@braidlabs/core 0.1.1 → 0.2.0

package/src/elements/fragment-slot.js

@@ -1,9 +1,28 @@
 import { BraidError } from '../errors.js';
-import { braidDocumentUrl, BRAID_FRAGMENT_ID_HEADER } from '../protocol.js';
+import { braidDocumentUrl, BRAID_FRAGMENT_ID_HEADER, BRAID_REDIRECT_LOCATION_HEADER, BRAID_RETURN_URL_HEADER, } from '../protocol.js';
 import { createRealm } from '../realm/realm-manager.js';
+import { contractAdapter } from '../adapters/contract-adapter.js';
 import { resolveAdapter } from '../adapters/adapter.js';
+import { parseFragmentContent } from '../adapters/compat-adapter.js';
 import { createFragmentEnv } from '../env/create-env.js';
-import { isDevMode } from '../config.js';
+import { getBraidConfig, isDevMode } from '../config.js';
+import { braidContext } from '../context/context-bus.js';
+import { createBoundaryChannel } from '../weave/channel.js';
+import { createSameRealmBackingPair } from '../weave/same-realm-backing.js';
+import { weaveId } from '../weave/envelope.js';
+import { performHostHandshake } from '../weave/handshake.js';
+import { attachContextRouter } from '../weave/context-bridge.js';
+import { FRAGMENT_EVENT, PROPS_CHANGED } from '../weave/messages.js';
+import { startFragmentBeats, startHostLiveness } from '../weave/liveness.js';
+import { DIRTY, closeAndDispose } from '../weave/closing.js';
+import { negotiateContract } from '../weave/contract.js';
+import { createSandboxRealm } from '../realm/sandbox-realm.js';
+import { createPortBacking } from '../weave/port-backing.js';
+import { readCapabilities, resolveCapabilities } from '../weave/capabilities.js';
+/** `connecting` is reported as `ready`; every other liveness state carries its own name. */
+export function slotStateFor(liveness) {
+    return liveness === 'connecting' ? 'ready' : liveness;
+}
 /**
  * Finds server-rendered fragment content the gateway pierced into a slot.
  *
@@ -21,6 +40,42 @@ export function findPiercedContentRoot(shadowRoot) {
     }
     return null;
 }
+/**
+ * The slot's own styles, including the fallback rules.
+ *
+ * `gone` and `error` hide the fragment's content and reveal whatever the host put in the fallback
+ * slot. Note what is *not* hidden: `suspect`. A fragment that is merely slow keeps its rendered
+ * content on screen, because replacing a working-if-sluggish UI with an apology is a worse outcome
+ * than a moment of unresponsiveness — and suspicion is designed to be recoverable.
+ */
+export const SLOT_STYLES = ':host, braid-document, braid-html, braid-body { display: block; } braid-head { display: none; }' +
+    'slot[name="fallback"] { display: none; }' +
+    ':host([state="gone"]) braid-document, :host([state="error"]) braid-document { display: none; }' +
+    ':host([state="gone"]) slot[name="fallback"], :host([state="error"]) slot[name="fallback"] { display: block; }';
+/**
+ * Ensures the shadow root can present host-provided fallback content:
+ *
+ * ```html
+ * <fragment-slot name="checkout"><p slot="fallback">Checkout is unavailable.</p></fragment-slot>
+ * ```
+ *
+ * Added separately from the styles because pierced fragments arrive with a shadow root the gateway
+ * wrote, which has content but no fallback slot — and a fallback that only worked for
+ * client-rendered fragments would be missing from exactly the pages that server-render because
+ * their first paint matters.
+ */
+export function ensureFallbackSlot(shadowRoot) {
+    if (shadowRoot.querySelector('slot[name="fallback"]'))
+        return;
+    if (!shadowRoot.querySelector('style')) {
+        const styleSheet = document.createElement('style');
+        styleSheet.textContent = SLOT_STYLES;
+        shadowRoot.prepend(styleSheet);
+    }
+    const fallback = document.createElement('slot');
+    fallback.name = 'fallback';
+    shadowRoot.append(fallback);
+}
 /**
  * `<fragment-slot>` — the custom element a host renders to mount a fragment.
  *
@@ -44,8 +99,22 @@ export class FragmentSlot extends HTMLElement {
     }
     #state = 'idle';
     #props = {};
-    #propsListeners = new Set();
+    /** Host end of this instance's boundary channel; undefined between teardown and the next boot. */
+    #channel;
+    #liveness;
     #abortController;
+    /**
+     * The in-flight close, if any.
+     *
+     * Teardown became asynchronous when it became a negotiation, and `disconnectedCallback` is not.
+     * So a close runs on after the element has left the DOM, and the next boot waits for it — which
+     * is also what stops a completing close from clearing a shadow root the *next* instance has
+     * already rendered into.
+     */
+    #closing;
+    /** Identifies which close is current, so a superseded one does not clear the DOM on its way out. */
+    #closingToken;
+    #dirty = null;
     #booted = false;
     #bootScheduled = false;
     /** Set by reload(): a reload must re-fetch, never re-adopt the pierced content. */
@@ -53,15 +122,48 @@ export class FragmentSlot extends HTMLElement {
     get state() {
         return this.#state;
     }
+    /**
+     * Sets the state, reflects it to the `state` attribute, and announces the transition.
+     *
+     * The attribute is what lets a host show fallback content in CSS alone — `:host([state="gone"])`
+     * — which matters because the page most in need of a fallback is the one whose JavaScript is
+     * already in trouble.
+     */
+    #setState(next) {
+        if (this.#state === next)
+            return;
+        const previous = this.#state;
+        this.#state = next;
+        this.setAttribute('state', next);
+        this.dispatchEvent(new CustomEvent('braid:state', { detail: { state: next, previous, fragmentId: this.name } }));
+    }
     get name() {
         return this.getAttribute('name') ?? '';
     }
+    /**
+     * The fragment's unsaved-work declaration, or null.
+     *
+     * Readable synchronously because the only place a host can act on it — a `beforeunload`
+     * handler — cannot await anything. Braid never installs that handler itself:
+     *
+     * ```ts
+     * addEventListener('beforeunload', (event) => {
+     *   if (slot.dirty) event.preventDefault();
+     * });
+     * ```
+     */
+    get dirty() {
+        return this.#dirty;
+    }
     get props() {
         return this.#props;
     }
     set props(value) {
         this.#props = structuredClone(value ?? {});
-        this.#propsListeners.forEach((listener) => listener(this.#props));
+        // Cloned again on the way out. The slot's copy is the host's to mutate; a fragment holding a
+        // live reference to it would see changes the host never announced — the asymmetry that made
+        // props behave unlike context before Weave.
+        this.#channel?.send(PROPS_CHANGED, { props: structuredClone(this.#props) });
     }
     attributeChangedCallback(attribute, oldValue, newValue) {
         if (attribute === 'props') {
@@ -104,38 +206,109 @@ export class FragmentSlot extends HTMLElement {
     }
     disconnectedCallback() {
         this.#bootScheduled = false;
-        this.#teardown();
+        // Not awaited, because `disconnectedCallback` cannot be. The close runs on after the element
+        // has left the DOM — which is exactly the window a flush needs, and the reason the fragment's
+        // realm is not disposed until the negotiation finishes.
+        void this.#teardown('unmount');
         this.#booted = false;
     }
     async reload() {
-        this.#teardown();
+        await this.#teardown('reload');
         this.#forceFetch = true;
         await this.#boot();
     }
-    #teardown() {
-        this.#abortController?.abort();
+    /**
+     * Closes the current instance: ask, wait for the deadline at most, then dispose.
+     *
+     * Resolves once the instance is fully gone, so `reload()` and the next `#boot()` can wait on it.
+     */
+    #teardown(reason) {
+        const channel = this.#channel;
+        const abortController = this.#abortController;
+        this.#liveness?.stop();
+        this.#liveness = undefined;
+        this.#channel = undefined;
         this.#abortController = undefined;
-        this.shadowRoot?.replaceChildren();
-        this.#state = 'idle';
+        // Nothing mounted: the pre-Weave synchronous path, still the right one for an idle slot.
+        if (!channel || !abortController) {
+            abortController?.abort();
+            this.shadowRoot?.replaceChildren();
+            this.#setState('idle');
+            return Promise.resolve();
+        }
+        this.#setState('closing');
+        const token = Symbol('braid:closing');
+        this.#closingToken = token;
+        const closed = (async () => {
+            const result = await closeAndDispose({
+                channel,
+                fragmentId: this.name,
+                reason,
+                // Runs only after the fragment has acknowledged, or the deadline has passed. Aborting any
+                // earlier would cut off the flush this negotiation exists to allow.
+                dispose: () => {
+                    abortController.abort();
+                    channel.close();
+                },
+            });
+            this.#setDirty(null);
+            this.dispatchEvent(new CustomEvent('braid:closed', {
+                detail: { fragmentId: this.name, reason, ...result },
+            }));
+            // Only the close that is still the current one clears the DOM. A boot that overtook this
+            // close has already rendered into the shadow root, and wiping it here would blank a fragment
+            // that had just successfully mounted.
+            if (this.#closingToken === token) {
+                this.shadowRoot?.replaceChildren();
+                this.#setState('idle');
+                this.#closing = undefined;
+                this.#closingToken = undefined;
+            }
+        })();
+        this.#closing = closed;
+        return closed;
+    }
+    #setDirty(reason) {
+        if (this.#dirty === reason)
+            return;
+        this.#dirty = reason;
+        this.dispatchEvent(new CustomEvent('braid:dirty', { detail: { fragmentId: this.name, reason } }));
     }
     async #boot() {
         const fragmentId = this.name;
+        // A close still negotiating owns the shadow root until it finishes. Booting into it first
+        // would render content that the completing close would then clear.
+        await this.#closing;
         try {
             if (!fragmentId) {
+                /**
+                 * Every tier needs a name, but only one of them needs a *registry entry*.
+                 *
+                 * The name is this fragment's identity to the runtime: it appears in every `BraidError`, it
+                 * is what capability grants are looked up by, and it is what distinguishes two instances in
+                 * a trace. Contract and untrusted fragments have no gateway registration at all, so a hint
+                 * that told their authors to register one sent them looking for a file that should not
+                 * exist.
+                 */
+                const registered = this.getAttribute('adapter') !== 'contract' && this.getAttribute('trust') !== 'untrusted';
                 throw new BraidError('the <fragment-slot> element is missing its name attribute', {
                     fragmentId: '<unnamed>',
                     stage: 'slot-config',
-                    fixHint: '<fragment-slot name="..."> must name a fragment registered in the gateway',
+                    fixHint: registered
+                        ? '<fragment-slot name="..."> must name a fragment registered in the gateway'
+                        : '<fragment-slot name="..."> needs a name to identify this fragment in errors and ' +
+                            'capability grants — it is not looked up in a registry on this tier',
                 });
             }
+            this.#setState('loading');
             if (this.getAttribute('trust') === 'untrusted') {
-                throw new BraidError('the untrusted tier is not available in this build', {
-                    fragmentId,
-                    stage: 'slot-config',
-                    fixHint: 'this build of @braidlabs/core ships the trusted compat tier only',
-                });
+                await this.#bootUntrusted(fragmentId);
+                return;
+            }
+            if (this.getAttribute('adapter') === 'contract') {
+                await this.#bootContract(fragmentId);
+                return;
             }
-            this.#state = 'loading';
             const abortController = new AbortController();
             this.#abortController = abortController;
             const signal = abortController.signal;
@@ -161,11 +334,11 @@ export class FragmentSlot extends HTMLElement {
             else {
                 shadowRoot = this.shadowRoot ?? this.attachShadow({ mode: 'open' });
                 const styleSheet = document.createElement('style');
-                styleSheet.textContent =
-                    ':host, braid-document, braid-html, braid-body { display: block; } braid-head { display: none; }';
+                styleSheet.textContent = SLOT_STYLES;
                 contentRoot = document.createElement('braid-document');
                 shadowRoot.replaceChildren(styleSheet, contentRoot);
             }
+            ensureFallbackSlot(shadowRoot);
             /**
              * Boot the realm and fetch the fragment's document at the same time, unless it was
              * already pierced in. Both go through the gateway's namespaces, addressed by id.
@@ -175,41 +348,139 @@ export class FragmentSlot extends HTMLElement {
              * an adapter that builds its own UI from an entry module (a lone custom element, say) has
              * no document to fetch, and must not be reported as broken for not serving one.
              */
+            /**
+             * Painted as soon as it arrives, without waiting for the realm.
+             *
+             * The gateway prepared it exactly as it prepares pierced content — scripts inert, urls
+             * re-rooted — so it is safe on screen before anything runs, and from here on it *is* pierced
+             * content: already in the DOM, activated in place by the adapter. Realm boot is a round trip
+             * plus a handshake, and the user has nothing to look at in the meantime otherwise.
+             */
+            let painted = false;
+            const paint = (html, isHtml) => {
+                if (signal.aborted || !isHtml || !html.trim())
+                    return;
+                contentRoot.appendChild(parseFragmentContent(html, document));
+                painted = true;
+            };
             const [htmlResult, realm] = await Promise.all([
                 piercedContentRoot
                     ? Promise.resolve({ ok: true, html: null })
-                    : this.#fetchFragmentHtml(fragmentId, routeSrcUrl, signal).then((html) => ({ ok: true, html }), (error) => ({ ok: false, error })),
+                    : fetchFragmentHtml(fragmentId, routeSrcUrl, signal).then(({ html, isHtml }) => {
+                        paint(html, isHtml);
+                        return { ok: true, html };
+                    }, (error) => ({ ok: false, error })),
                 createRealm('compat-http', { fragmentId, routeUrl, bound, signal }),
             ]);
             // The gateway stamps the manifest-declared adapter onto the realm stub; unknown adapters
             // fail as a named error, and an undeclared adapter resolves to the default (compat).
             const adapter = resolveAdapter(realm.manifestAdapter, fragmentId);
-            if (!htmlResult.ok && adapter.needsDocument !== false)
+            if (!htmlResult.ok && adapter.needsDocument !== false) {
+                // The fragment sent the user somewhere else — a login, almost always — and the gateway has
+                // said the host allows following it. The slot stays `loading`: the page is about to be
+                // replaced, and flashing an error or a fallback in the meantime would only be noise.
+                if (htmlResult.error instanceof FragmentRedirectError) {
+                    // a slot that was removed or rebooted while the realm was loading must not move the page
+                    if (signal.aborted)
+                        return;
+                    const refusal = followFragmentRedirect(htmlResult.error, browserRedirectDeps());
+                    if (!refusal)
+                        return;
+                    throw refusal;
+                }
                 throw htmlResult.error;
+            }
             const html = htmlResult.ok ? htmlResult.html : null;
-            const env = createFragmentEnv({
+            // An adapter that builds its own UI never reads a document; one painted for it is taken down
+            // rather than left under whatever the adapter mounts.
+            if (painted && adapter.needsDocument === false) {
+                contentRoot.replaceChildren();
+                painted = false;
+            }
+            /**
+             * The boundary channel for this instance.
+             *
+             * Both ends live in the host realm on the trusted tier — the "fragment end" is the object
+             * graph the realm holds — so the same-realm backing dispatches directly with no clone. The
+             * shape is nonetheless identical to what Phase 5 will run over a `MessagePort`, which is the
+             * only reason building the transport before the tier that needs it is worth anything.
+             */
+            const instance = weaveId();
+            const backings = createSameRealmBackingPair();
+            const hostChannel = createBoundaryChannel({ backing: backings.host, fragmentId, instance, signal });
+            const fragmentChannel = createBoundaryChannel({ backing: backings.fragment, fragmentId, instance, signal });
+            this.#channel = hostChannel;
+            hostChannel.on(DIRTY, (payload) => {
+                this.#setDirty((payload ?? {}).reason ?? null);
+            });
+            hostChannel.on(FRAGMENT_EVENT, (payload) => {
+                const { type, detail } = (payload ?? {});
+                this.dispatchEvent(new CustomEvent('braid:event', { detail: { type, detail }, bubbles: true }));
+            });
+            const { env, opened } = createFragmentEnv({
                 contentRoot,
                 shadowRoot,
                 routeUrl,
-                getProps: () => this.#props,
-                onPropsChanged: (listener) => {
-                    this.#propsListeners.add(listener);
-                    const unsubscribe = () => this.#propsListeners.delete(listener);
-                    signal.addEventListener('abort', unsubscribe, { once: true });
-                    return unsubscribe;
+                channel: fragmentChannel,
+                fragmentId,
+                signal,
+            });
+            /**
+             * Terms are agreed before the adapter mounts, not after.
+             *
+             * A fragment that cannot be given the context it declared should never have been booted, and
+             * discovering that after its framework has rendered means tearing down a live UI instead of
+             * showing a fallback in an empty slot.
+             */
+            const hostContract = getBraidConfig().contract;
+            const capabilities = this.#capabilitiesFor(fragmentId, readCapabilities(realm.adapterOptions));
+            await performHostHandshake({
+                channel: hostChannel,
+                fragmentId,
+                instance,
+                ...(hostContract === undefined ? {} : { hostContract }),
+                negotiate: (host, fragment) => negotiateContract({ host, fragment, schemaFor: (key) => braidContext.schemaFor(key) }),
+                onBridged: (bridges) => {
+                    /**
+                     * A bridged connection is a working one, so this is an event and not an error — but it is
+                     * announced rather than logged quietly, because `discards` names fields this fragment
+                     * will never see, and a screen rendered confidently without them looks correct.
+                     */
+                    this.dispatchEvent(new CustomEvent('braid:bridged', { detail: { fragmentId, bridges } }));
+                    if (isDevMode()) {
+                        for (const bridge of bridges) {
+                            console.debug(`[braid:${fragmentId}] context "${bridge.key}" bridged v${bridge.from} → v${bridge.to}` +
+                                (bridge.discards.length > 0 ? `, discarding ${bridge.discards.join(', ')}` : ''));
+                        }
+                    }
                 },
-                emit: (type, detail) => {
-                    this.dispatchEvent(new CustomEvent('braid:event', { detail: { type, detail }, bubbles: true }));
+                assertReachable: (versions) => {
+                    for (const [key, as] of Object.entries(versions))
+                        braidContext.assertReachable(key, as, fragmentId);
                 },
-                signal,
+                openWith: (contextVersions) => ({
+                    context: attachContextRouter({
+                        bus: braidContext,
+                        channel: hostChannel,
+                        fragmentId,
+                        contextVersions,
+                        ...(capabilities === undefined ? {} : { capabilities }),
+                        signal,
+                    }),
+                    props: structuredClone(this.#props),
+                }),
             });
+            await opened;
+            if (signal.aborted)
+                return;
             await adapter.boot({
                 fragmentId,
                 shadowRoot,
                 contentRoot,
                 realm,
-                html,
-                pierced: Boolean(piercedContentRoot),
+                // painted content is in the DOM already, which is all `pierced` tells the adapter
+                html: painted ? null : html,
+                pierced: Boolean(piercedContentRoot) || painted,
                 routeUrl,
                 bound,
                 env,
@@ -217,8 +488,28 @@ export class FragmentSlot extends HTMLElement {
             });
             if (signal.aborted)
                 return;
-            this.#state = 'ready';
+            this.#setState('ready');
             this.dispatchEvent(new CustomEvent('braid:ready', { detail: { fragmentId } }));
+            /**
+             * Liveness starts only once the adapter has mounted.
+             *
+             * Starting it at handshake would put a deadline on a fragment that is still evaluating its
+             * framework bundle, and the honest name for that state is `loading` — the host knows exactly
+             * what it is waiting for, so it has nothing to be suspicious about yet.
+             */
+            this.#liveness = startHostLiveness({
+                channel: hostChannel,
+                instance,
+                signal,
+                onState: (liveness) => this.#setState(slotStateFor(liveness)),
+            });
+            // Scheduled on the realm's own event loop, never the host's — a beat is only evidence if it
+            // had to be produced by the thing being asked about. See `BeatScheduler`.
+            startFragmentBeats({
+                channel: fragmentChannel,
+                scheduler: realm.window,
+                signal,
+            });
             if (isDevMode()) {
                 console.debug(`[braid:${fragmentId}] ready`, { slot: this });
             }
@@ -226,7 +517,7 @@ export class FragmentSlot extends HTMLElement {
         catch (error) {
             if (this.#abortController?.signal.aborted)
                 return;
-            this.#state = 'error';
+            this.#setState('error');
             const braidError = error instanceof BraidError
                 ? error
                 : new BraidError(error instanceof Error ? error.message : String(error), {
@@ -245,37 +536,429 @@ export class FragmentSlot extends HTMLElement {
             }));
         }
     }
-    async #fetchFragmentHtml(fragmentId, routeSrcUrl, signal) {
-        // the document namespace: the gateway prepares this exactly as it prepares pierced content
-        const documentUrl = braidDocumentUrl(fragmentId, routeSrcUrl.pathname, routeSrcUrl.search);
-        let response;
-        try {
-            response = await fetch(documentUrl, {
-                headers: {
-                    accept: 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8',
-                    [BRAID_FRAGMENT_ID_HEADER]: fragmentId,
-                },
-                signal,
-            });
-        }
-        catch (error) {
-            throw new BraidError(`fetching the fragment's html from "${documentUrl}" failed`, {
+    /**
+     * Mounts a contract fragment, with **no gateway involved at all**.
+     *
+     * ```html
+     * <fragment-slot name="checkout" adapter="contract" entry="https://checkout.example.com/main.js">
+     * ```
+     *
+     * The host declares the entry in markup because a gateway-free host has nowhere else to declare
+     * it — there is no registry to read and no realm stub to stamp. That is the whole point: no
+     * middleware on the host origin, no namespace routing, no HTML rewriting, no document fetch. A
+     * statically hosted SPA can compose contract fragments.
+     *
+     * Everything else is shared with the trusted compat path — the same handshake, contract
+     * negotiation, capabilities, liveness and teardown — because all of it was built against the
+     * boundary rather than against compat's machinery.
+     */
+    async #bootContract(fragmentId) {
+        const entry = this.getAttribute('entry');
+        if (!entry) {
+            throw new BraidError('a contract fragment needs an entry module', {
                 fragmentId,
-                stage: 'fragment-fetch',
-                cause: error,
-                fixHint: 'ensure the braid gateway is mounted in front of this app and reachable from the browser',
+                stage: 'slot-config',
+                fixHint: '<fragment-slot adapter="contract" entry="https://checkout.example.com/main.js">',
             });
         }
-        if (!response.ok) {
-            throw new BraidError(`the gateway responded with HTTP ${response.status} for "${documentUrl}"`, {
+        const abortController = new AbortController();
+        this.#abortController = abortController;
+        const signal = abortController.signal;
+        const src = this.getAttribute('src');
+        const routeUrl = src ?? location.pathname + location.search;
+        const shadowRoot = this.shadowRoot ?? this.attachShadow({ mode: 'open' });
+        const styleSheet = document.createElement('style');
+        styleSheet.textContent = SLOT_STYLES;
+        const contentRoot = document.createElement('braid-document');
+        shadowRoot.replaceChildren(styleSheet, contentRoot);
+        ensureFallbackSlot(shadowRoot);
+        // The realm's base is the entry's own directory, not a gateway namespace: a contract fragment
+        // fetches its assets from wherever it is hosted, directly.
+        const entryUrl = new URL(entry, document.baseURI);
+        const realm = await createRealm('contract-blob', {
+            fragmentId,
+            routeUrl,
+            bound: !src,
+            signal,
+            baseHref: new URL('./', entryUrl).href,
+        });
+        const instance = weaveId();
+        const backings = createSameRealmBackingPair();
+        const hostChannel = createBoundaryChannel({ backing: backings.host, fragmentId, instance, signal });
+        const fragmentChannel = createBoundaryChannel({ backing: backings.fragment, fragmentId, instance, signal });
+        this.#channel = hostChannel;
+        hostChannel.on(DIRTY, (payload) => this.#setDirty((payload ?? {}).reason ?? null));
+        hostChannel.on(FRAGMENT_EVENT, (payload) => {
+            const { type, detail } = (payload ?? {});
+            this.dispatchEvent(new CustomEvent('braid:event', { detail: { type, detail }, bubbles: true }));
+        });
+        const { env, opened } = createFragmentEnv({
+            contentRoot,
+            shadowRoot,
+            routeUrl,
+            channel: fragmentChannel,
+            fragmentId,
+            signal,
+        });
+        const hostContract = getBraidConfig().contract;
+        const capabilities = this.#capabilitiesFor(fragmentId, undefined);
+        await performHostHandshake({
+            channel: hostChannel,
+            fragmentId,
+            instance,
+            ...(hostContract === undefined ? {} : { hostContract }),
+            negotiate: (host, fragment) => negotiateContract({ host, fragment, schemaFor: (key) => braidContext.schemaFor(key) }),
+            onBridged: (bridges) => void this.dispatchEvent(new CustomEvent('braid:bridged', { detail: { fragmentId, bridges } })),
+            assertReachable: (versions) => {
+                for (const [key, as] of Object.entries(versions))
+                    braidContext.assertReachable(key, as, fragmentId);
+            },
+            openWith: (contextVersions) => ({
+                context: attachContextRouter({
+                    bus: braidContext,
+                    channel: hostChannel,
+                    fragmentId,
+                    contextVersions,
+                    ...(capabilities === undefined ? {} : { capabilities }),
+                    signal,
+                }),
+                props: structuredClone(this.#props),
+            }),
+        });
+        await opened;
+        await contractAdapter.boot({
+            fragmentId,
+            shadowRoot,
+            contentRoot,
+            realm,
+            html: null,
+            pierced: false,
+            routeUrl,
+            bound: !src,
+            // Resolved against the document, so a relative `entry` works for a fragment served from the
+            // host's own origin — the static-host case, where there is no gateway *and* no second origin.
+            entry: entryUrl.href,
+            env,
+            signal,
+        });
+        if (signal.aborted)
+            return;
+        this.#setState('ready');
+        this.dispatchEvent(new CustomEvent('braid:ready', { detail: { fragmentId } }));
+        this.#liveness = startHostLiveness({
+            channel: hostChannel,
+            instance,
+            signal,
+            onState: (liveness) => this.#setState(slotStateFor(liveness)),
+        });
+        startFragmentBeats({ channel: fragmentChannel, scheduler: realm.window, signal });
+    }
+    /**
+     * Mounts an untrusted fragment: a visible cross-origin frame, and a port.
+     *
+     * Almost nothing from the trusted path applies here, and the shape of this method is the honest
+     * expression of that. There is no gateway namespace, no document fetch, no HTML rewriting, no
+     * pierced content to adopt, no adapter, and no realm to evaluate a module in — the fragment is a
+     * whole application at its own origin, and the only things that cross are the ones Weave carries.
+     *
+     * What it shares with the trusted path is everything built in Phases 1–4: the same handshake, the
+     * same contract negotiation, the same liveness, the same negotiated teardown. That is the return
+     * on having built the transport before the tier that needed it.
+     */
+    async #bootUntrusted(fragmentId) {
+        const src = this.getAttribute('src');
+        if (!src) {
+            throw new BraidError('an untrusted fragment needs an explicit cross-origin src', {
                 fragmentId,
-                stage: 'fragment-fetch',
-                fixHint: response.status === 404
-                    ? `register a manifest for fragment id "${fragmentId}" in the gateway registry`
-                    : `check the gateway logs for fragment id "${fragmentId}"`,
+                stage: 'slot-config',
+                fixHint: '<fragment-slot trust="untrusted" src="https://vendor.example.com/widget">',
             });
         }
-        return response.text();
+        const abortController = new AbortController();
+        this.#abortController = abortController;
+        const signal = abortController.signal;
+        const shadowRoot = this.shadowRoot ?? this.attachShadow({ mode: 'open' });
+        const styleSheet = document.createElement('style');
+        styleSheet.textContent = SLOT_STYLES;
+        shadowRoot.replaceChildren(styleSheet);
+        ensureFallbackSlot(shadowRoot);
+        /**
+         * On this tier the capability block is not advisory: `sandbox` and `permissions` become real
+         * iframe attributes that the browser enforces, and `context.read` decides what enters the
+         * fragment's mirror at all.
+         */
+        // No realm stub on this tier — there is no gateway — so `initBraid({ capabilities })` is the
+        // registry, and the slot's own attributes are the least authoritative source.
+        const capabilities = this.#capabilitiesFor(fragmentId, undefined, {
+            ...(this.#sandboxTokens() === undefined ? {} : { sandbox: this.#sandboxTokens() }),
+            ...(this.#permissions() === undefined ? {} : { permissions: this.#permissions() }),
+        });
+        const { promise: mounted, resolve: markMounted } = Promise.withResolvers();
+        const realm = await createSandboxRealm({
+            fragmentId,
+            src,
+            container: shadowRoot,
+            signal,
+            ...(capabilities?.sandbox === undefined ? {} : { sandboxTokens: capabilities.sandbox }),
+            ...(capabilities?.permissions === undefined ? {} : { permissions: capabilities.permissions }),
+        });
+        const instance = weaveId();
+        const hostChannel = createBoundaryChannel({
+            backing: createPortBacking(realm.port),
+            fragmentId,
+            instance,
+            signal,
+        });
+        this.#channel = hostChannel;
+        hostChannel.on(DIRTY, (payload) => {
+            this.#setDirty((payload ?? {}).reason ?? null);
+        });
+        hostChannel.on(FRAGMENT_EVENT, (payload) => {
+            const { type, detail } = (payload ?? {});
+            this.dispatchEvent(new CustomEvent('braid:event', { detail: { type, detail }, bubbles: true }));
+        });
+        /**
+         * Listening starts *before* the handshake; judging starts at `mounted`.
+         *
+         * A cross-origin guest begins beating the moment it is open, and nothing orders that against the
+         * host finishing its own work — so registering the handler afterwards drops the opening beat and
+         * leaves a healthy fragment in `connecting` for a full interval. Arming the deadline this early
+         * would be the opposite mistake, which is exactly what `armAfter` separates.
+         */
+        this.#liveness = startHostLiveness({
+            channel: hostChannel,
+            instance,
+            signal,
+            armAfter: mounted,
+            onState: (liveness) => this.#setState(slotStateFor(liveness)),
+        });
+        const hostContract = getBraidConfig().contract;
+        await performHostHandshake({
+            channel: hostChannel,
+            fragmentId,
+            instance,
+            ...(hostContract === undefined ? {} : { hostContract }),
+            negotiate: (host, fragment) => negotiateContract({ host, fragment, schemaFor: (key) => braidContext.schemaFor(key) }),
+            onBridged: (bridges) => {
+                this.dispatchEvent(new CustomEvent('braid:bridged', { detail: { fragmentId, bridges } }));
+            },
+            assertReachable: (versions) => {
+                for (const [key, as] of Object.entries(versions))
+                    braidContext.assertReachable(key, as, fragmentId);
+            },
+            openWith: (contextVersions) => ({
+                context: attachContextRouter({
+                    bus: braidContext,
+                    channel: hostChannel,
+                    fragmentId,
+                    contextVersions,
+                    ...(capabilities === undefined ? {} : { capabilities }),
+                    signal,
+                }),
+                props: structuredClone(this.#props),
+            }),
+        });
+        if (signal.aborted)
+            return;
+        this.#setState('ready');
+        this.dispatchEvent(new CustomEvent('braid:ready', { detail: { fragmentId } }));
+        /**
+         * No `startFragmentBeats` here. The guest schedules its own, in its own document, on its own
+         * event loop — which is stronger evidence than the trusted tier can offer, where the beat comes
+         * from a hidden frame rather than from the application itself.
+         */
+        markMounted();
+    }
+    /** Resolves this fragment's capabilities. See `resolveCapabilities` for the precedence. */
+    #capabilitiesFor(fragmentId, fromStub, fromSlot) {
+        return resolveCapabilities([fromStub, getBraidConfig().capabilities?.[fragmentId], fromSlot]);
+    }
+    /** `sandbox="allow-popups allow-downloads"` on the slot: additive tokens, host-declared. */
+    #sandboxTokens() {
+        const value = this.getAttribute('sandbox');
+        return value ? value.split(/\s+/).filter(Boolean) : undefined;
+    }
+    /** `allow="clipboard-write"` on the slot: Permissions-Policy features delegated into the frame. */
+    #permissions() {
+        const value = this.getAttribute('allow');
+        return value ? value.split(/;/).map((entry) => entry.trim()).filter(Boolean) : undefined;
+    }
+}
+/**
+ * A redirect target for an error message: origin and path only. The query string is where login
+ * redirects carry tokens and return-urls, and an error message ends up in the console and in the
+ * `braid:error` event.
+ */
+function redactedLocation(location, base) {
+    if (!location)
+        return null;
+    try {
+        const url = new URL(location, new URL(base, 'http://localhost'));
+        return `${url.origin === 'http://localhost' ? '' : url.origin}${url.pathname}`;
+    }
+    catch {
+        return null;
     }
 }
+/**
+ * Fetches the fragment's document from the gateway's document namespace.
+ *
+ * Redirects are refused rather than followed. Followed, a cross-origin one (an auth redirect to an
+ * identity provider, say) dies as an opaque CORS error that hides the status that caused it, and a
+ * relative one resolves against the gateway's origin — outside the namespace — so the shell's or a
+ * login page's html would be injected as the fragment's document without any error at all.
+ *
+ * A browser hands back an `opaqueredirect` for `redirect: 'manual'` (status 0, no readable
+ * `Location`); other runtimes expose the real 3xx, so the target is named when it can be read.
+ *
+ * A fragment that opted in to `redirect: 'navigate'` is the exception: the gateway answers with a
+ * `409` carrying the target, which becomes a {@link FragmentRedirectError} for the slot to follow.
+ *
+ * Resolves with the document and whether it arrived as HTML — which, through the gateway, is the one
+ * kind of document it prepares (scripts inert, handlers stripped). Anything else is not safe to put
+ * on screen ahead of the adapter.
+ */
+export async function fetchFragmentHtml(fragmentId, routeSrcUrl, signal) {
+    // the document namespace: the gateway prepares this exactly as it prepares pierced content
+    const documentUrl = braidDocumentUrl(fragmentId, routeSrcUrl.pathname, routeSrcUrl.search, getBraidConfig().basePath);
+    let response;
+    try {
+        response = await fetch(documentUrl, {
+            headers: {
+                accept: 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8',
+                [BRAID_FRAGMENT_ID_HEADER]: fragmentId,
+                // Where a login should send the user back to. Sent on every document fetch, because
+                // whether the fragment will redirect is not known until it answers.
+                ...(typeof location === 'undefined' ? {} : { [BRAID_RETURN_URL_HEADER]: location.href }),
+            },
+            redirect: 'manual',
+            signal,
+        });
+    }
+    catch (error) {
+        throw new BraidError(`fetching the fragment's html from "${documentUrl}" failed`, {
+            fragmentId,
+            stage: 'fragment-fetch',
+            cause: error,
+            fixHint: 'ensure the braid gateway is mounted in front of this app and reachable from the browser',
+        });
+    }
+    if (response.type === 'opaqueredirect' || (response.status >= 300 && response.status < 400 && response.status !== 304)) {
+        const location = redactedLocation(response.headers.get('location'), documentUrl);
+        throw new BraidError(`the fragment redirected "${documentUrl}"` +
+            (response.status > 0 ? ` with HTTP ${response.status}` : '') +
+            (location ? ` to "${location}"` : ' (the target is not visible to the browser)'), {
+            fragmentId,
+            stage: 'fragment-fetch',
+            fixHint: `a fragment's document must not redirect — it is fetched, not navigated to. Usually the request is ` +
+                `missing authentication and the fragment is sending it to a login page: handle auth inside ` +
+                `fragment "${fragmentId}" instead of redirecting, and check the Network tab for the redirect's target`,
+        });
+    }
+    // The gateway's answer for a fragment that opted in to `redirect: 'navigate'`: a 409 that carries
+    // where the fragment wanted to go. A 409 without the header is an ordinary failure, and the header
+    // on any other status is ignored — a fragment can set headers too, and only this pair is the
+    // gateway speaking.
+    if (response.status === 409) {
+        const target = response.headers.get(BRAID_REDIRECT_LOCATION_HEADER);
+        if (target)
+            throw new FragmentRedirectError(fragmentId, target, documentUrl);
+    }
+    if (!response.ok) {
+        throw new BraidError(`the gateway responded with HTTP ${response.status} for "${documentUrl}"`, {
+            fragmentId,
+            stage: 'fragment-fetch',
+            fixHint: response.status === 404
+                ? `register a manifest for fragment id "${fragmentId}" in the gateway registry`
+                : `check the gateway logs for fragment id "${fragmentId}"`,
+        });
+    }
+    const isHtml = response.headers.get('content-type')?.toLowerCase().includes('text/html') ?? false;
+    return { html: await response.text(), isHtml };
+}
+/**
+ * The gateway relayed a redirect from the fragment and vouched for its target. Carries the full
+ * target; the message does not, because a login's query string is where its tokens live and an
+ * error message ends up in the console and in the `braid:error` event.
+ */
+export class FragmentRedirectError extends BraidError {
+    target;
+    constructor(fragmentId, target, documentUrl) {
+        super(`the fragment redirected "${documentUrl}" to "${redactedLocation(target, documentUrl)}"`, {
+            fragmentId,
+            stage: 'fragment-fetch',
+            fixHint: `the redirect was not followed. ` +
+                `Check the Network tab for the redirect's target`,
+        });
+        this.name = 'FragmentRedirectError';
+        this.target = target;
+    }
+}
+/** How long a second redirect from the same fragment is treated as a loop rather than a new one. */
+export const REDIRECT_LOOP_WINDOW_MS = 30_000;
+const redirectsInFlight = new Set();
+/** The real thing, for the browser. Kept out of `followFragmentRedirect` so that is testable. */
+function browserRedirectDeps() {
+    return {
+        assign: (url) => location.assign(url),
+        storage: () => sessionStorage,
+        now: () => Date.now(),
+        baseHref: location.href,
+        inFlight: redirectsInFlight,
+    };
+}
+/**
+ * Sends the page where the fragment's redirect asked, once.
+ *
+ * @returns `null` when the page is navigating, or the error to report when it is not.
+ *
+ * Two things stop it. The scheme must be http(s) — the gateway already checks, and this is the one
+ * line between a `javascript:` URL and `location.assign`. And a fragment that redirects again
+ * within {@link REDIRECT_LOOP_WINDOW_MS} is a loop: login succeeded, the user came back, and the
+ * fragment still cannot tell who they are. A page reload loses all in-memory state, so the only
+ * thing that can remember the last redirect is `sessionStorage`; if that is unavailable, the answer
+ * is no — an unbounded loop is worse than an error.
+ */
+export function followFragmentRedirect(error, deps) {
+    const { fragmentId } = error;
+    if (deps.inFlight.has(fragmentId))
+        return null;
+    const refuse = (message, fixHint) => new BraidError(message, { fragmentId, stage: 'fragment-fetch', fixHint, cause: error });
+    let url;
+    try {
+        url = new URL(error.target, deps.baseHref);
+    }
+    catch {
+        return refuse('the fragment redirected to a URL that cannot be parsed', `check the gateway logs for fragment "${fragmentId}"`);
+    }
+    if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+        return refuse(`the fragment redirected to a "${url.protocol}" URL, which is not followed`, `check the gateway logs for fragment "${fragmentId}"`);
+    }
+    // A path the gateway vouched for is a path on this origin. If it resolves anywhere else — a
+    // protocol-relative `//host` is the way — something upstream is wrong, and following it would be
+    // an open redirect.
+    if (!/^[a-z][a-z0-9+.-]*:/i.test(error.target) && url.origin !== new URL(deps.baseHref).origin) {
+        return refuse('the fragment redirected to a path that resolves to another origin, which is not followed', `check the gateway logs for fragment "${fragmentId}"`);
+    }
+    const key = `braid:redirect:${fragmentId}`;
+    try {
+        const storage = deps.storage();
+        const last = Number(storage.getItem(key));
+        const now = deps.now();
+        const age = now - last;
+        // a stamp from the future (a clock that moved) is stale, not a reason to refuse for the tab's lifetime
+        if (last > 0 && age >= 0 && age < REDIRECT_LOOP_WINDOW_MS) {
+            return refuse(`fragment "${fragmentId}" redirected again straight after the last redirect, so it was not followed`, `the fragment cannot see who the user is after login, so it keeps redirecting: forward their ` +
+                `identity to it with forwardCredentials or additionalHeaders on the gateway`);
+        }
+        storage.setItem(key, String(now));
+    }
+    catch {
+        return refuse(`the fragment redirected to "${redactedLocation(error.target, deps.baseHref)}", but there is no way to ` +
+            `stop a redirect loop here (sessionStorage is unavailable), so it was not followed`, 'allow sessionStorage for this page, or handle authentication inside the fragment');
+    }
+    deps.inFlight.add(fragmentId);
+    deps.assign(url.href);
+    return null;
+}
 //# sourceMappingURL=fragment-slot.js.map