@braidlabs/core 0.6.0 → 0.7.0

package/src/config.d.ts

@@ -8,7 +8,9 @@
  * names itself, which trusted fragments may then read and write.
  */
 import type { HostContract } from './weave/contract.js';
+import { type RecoveryPolicy } from './elements/recovery.js';
 import type { FragmentCapabilities } from './weave/capabilities.js';
+import type { PrerequisiteResolver } from './elements/prerequisites.js';
 export interface BraidOptions {
     /**
      * What this host offers fragments, as a contract they can require a range of.
@@ -91,6 +93,29 @@ export interface BraidOptions {
      * fragment documents from `/manage/__braid/…`. Call `initBraid` before any slot connects.
      */
     basePath?: string;
+    /**
+     * Resolvers for mount prerequisites: named things that must be ready before a fragment's code
+     * runs, such as a warm session for its authorization server. Keyed by exact key or by a
+     * `prefix*` pattern. A fragment declares the keys it needs with `<fragment-slot requires="…">`
+     * or its manifest's `requires`. See `elements/prerequisites.ts`.
+     *
+     * ```ts
+     * initBraid({ prerequisites: { 'session:*': (key, { signal }) => sessions.ensure(key, { signal }) } });
+     * ```
+     */
+    prerequisites?: Record<string, PrerequisiteResolver>;
+    /** How long a prerequisite may take before its fragment fails. Defaults to 15 seconds. */
+    prerequisiteTimeoutMs?: number;
+    /**
+     * Reboot a fragment that fails for a reason a retry can fix — its fetch, its realm, its
+     * handshake or mount failed, or it stopped answering (`gone`) — up to three times per mount, after
+     * 1, 4 and 16 seconds. Off by default. `true` takes those defaults; an object sets them. See
+     * `elements/recovery.ts` for what is and is not retried.
+     */
+    recover?: boolean | {
+        attempts?: number;
+        delayMs?: number;
+    };
 }
 /** See {@link BraidOptions.realmGlobals}. */
 export type RealmGlobalsHook = (fragment: {
@@ -106,6 +131,9 @@ interface ResolvedBraidConfig {
     sharedGlobals?: string[];
     realmGlobals?: RealmGlobalsHook;
     onHostNavigation?: (notify: () => void) => void;
+    prerequisites?: Record<string, PrerequisiteResolver>;
+    prerequisiteTimeoutMs?: number;
+    recover?: RecoveryPolicy;
 }
 export declare function setBraidConfig(options?: BraidOptions): void;
 export declare function getBraidConfig(): Readonly<ResolvedBraidConfig>;

package/src/config.js

@@ -7,6 +7,7 @@
  * own realm and shadow DOM subtree. The one channel back is `sharedGlobals`: host globals the host
  * names itself, which trusted fragments may then read and write.
  */
+import { DEFAULT_RECOVERY, MAX_RECOVERY_ATTEMPTS } from './elements/recovery.js';
 const config = {
     dev: false,
     basePath: '',
@@ -30,6 +31,29 @@ export function setBraidConfig(options = {}) {
     if (options.onHostNavigation) {
         config.onHostNavigation = options.onHostNavigation;
     }
+    if (options.prerequisites) {
+        config.prerequisites = options.prerequisites;
+    }
+    if (options.prerequisiteTimeoutMs !== undefined) {
+        if (!Number.isFinite(options.prerequisiteTimeoutMs) || options.prerequisiteTimeoutMs <= 0) {
+            throw new Error(`braid: prerequisiteTimeoutMs must be a positive number of milliseconds`);
+        }
+        config.prerequisiteTimeoutMs = options.prerequisiteTimeoutMs;
+    }
+    if (options.recover !== undefined) {
+        if (options.recover === false) {
+            delete config.recover;
+        }
+        else {
+            const given = options.recover === true ? {} : options.recover;
+            const attempts = given.attempts ?? DEFAULT_RECOVERY.attempts;
+            const delayMs = given.delayMs ?? DEFAULT_RECOVERY.delayMs;
+            if (!Number.isInteger(attempts) || attempts < 1 || attempts > MAX_RECOVERY_ATTEMPTS || !Number.isFinite(delayMs) || delayMs < 0) {
+                throw new Error(`braid: recover needs 1 to ${MAX_RECOVERY_ATTEMPTS} attempts and a delayMs of zero or more`);
+            }
+            config.recover = { attempts, delayMs };
+        }
+    }
     // Kept in sync with the gateway's normalizeBasePath: a path the URL parser would rewrite (`/café`,
     // a dot segment) could never match the parsed pathnames the gateway compares it to.
     if (options.basePath !== undefined) {

package/src/config.js.map

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

package/src/elements/boot-gate.d.ts

@@ -0,0 +1,47 @@
+/**
+ * When a slot boots its fragment: at once (`eager`, the default), or on intent.
+ *
+ * - `idle` — once the page has loaded and the browser next has nothing better to do, or two
+ *   seconds after load regardless.
+ * - `visible` — when the slot comes within one viewport of being on screen.
+ * - `interaction` — on the first hover, pointer, key, or focus inside a pierced slot. The content
+ *   is already painted, so the user has something to interact with; the fragment's code is what
+ *   waits. A slot that was not pierced has nothing on screen to interact with, so it boots when
+ *   visible instead.
+ *
+ * Deferring a boot defers all of it — the realm iframe, the document fetch, the fragment's
+ * framework and app — which is more than lazy hydration can defer inside one framework.
+ */
+export type BootMode = 'eager' | 'idle' | 'visible' | 'interaction';
+export declare function parseBootMode(value: string | null, fragmentId: string): BootMode;
+export interface BootGate {
+    /** Resolves when the slot should boot. Never rejects; never resolves after `dispose()`. */
+    readonly triggered: Promise<void>;
+    /**
+     * Re-dispatches the clicks and submits that arrived before the fragment could handle them, on
+     * their original targets, one per task, and stops holding. Called once the fragment is ready.
+     */
+    replay(): void;
+    /** Stops waiting and holding, and drops anything held — the fragment will not be handling it. */
+    dispose(): void;
+}
+/**
+ * Waits for a slot's boot trigger, holding what the user did in the meantime.
+ *
+ * Clicks and submits inside the slot are the events whose default action goes wrong without the
+ * fragment's code — a link followed, a form posted — so until the fragment is ready they are
+ * cancelled, kept, and replayed. At most one per element is kept, so three anxious clicks on "Pay"
+ * become one. Every other event is left alone, and listened to passively: typed text and focus are
+ * already in the DOM, which the fragment adopts in place.
+ *
+ * A replay is a synthetic event, some time after the real one, so what needs a fresh user gesture —
+ * `window.open`, a file picker, the clipboard — will not work from it.
+ *
+ * The listeners are on the slot's own shadow root, never on the host's `window` or `document`. The
+ * one exception is `idle`, which waits for the host window's `load` once, if the page has not
+ * loaded yet.
+ */
+export declare function createBootGate(slot: HTMLElement, mode: BootMode, options: {
+    pierced: boolean;
+    fragmentId: string;
+}): BootGate;

package/src/elements/boot-gate.js

@@ -0,0 +1,207 @@
+import { isDevMode } from '../config.js';
+const BOOT_MODES = ['eager', 'idle', 'visible', 'interaction'];
+/** Events that start an `interaction` boot. Only `click` and `submit` are ever cancelled. */
+const PASSIVE_INTENT_EVENTS = ['pointerover', 'pointerdown', 'touchstart', 'keydown', 'focusin'];
+const HELD_EVENTS = ['click', 'submit'];
+/** Held at most this many, so a user hammering a dead button cannot queue an avalanche. */
+const MAX_HELD = 10;
+/**
+ * How far outside the viewport a `visible` slot starts booting. A boot is a network round trip and
+ * an iframe, so it needs more lead than an image does; a smaller margin shows the skeleton on any
+ * brisk scroll.
+ */
+const VISIBLE_MARGIN = '100%';
+/** The longest an `idle` boot waits, after load, for the browser to go idle. */
+const IDLE_TIMEOUT_MS = 2_000;
+export function parseBootMode(value, fragmentId) {
+    if (value === null || value === '')
+        return 'eager';
+    if (BOOT_MODES.includes(value))
+        return value;
+    console.warn(`[braid:${fragmentId}] unknown boot="${value}", booting eagerly; expected one of ${BOOT_MODES.join(', ')}`);
+    return 'eager';
+}
+/**
+ * Waits for a slot's boot trigger, holding what the user did in the meantime.
+ *
+ * Clicks and submits inside the slot are the events whose default action goes wrong without the
+ * fragment's code — a link followed, a form posted — so until the fragment is ready they are
+ * cancelled, kept, and replayed. At most one per element is kept, so three anxious clicks on "Pay"
+ * become one. Every other event is left alone, and listened to passively: typed text and focus are
+ * already in the DOM, which the fragment adopts in place.
+ *
+ * A replay is a synthetic event, some time after the real one, so what needs a fresh user gesture —
+ * `window.open`, a file picker, the clipboard — will not work from it.
+ *
+ * The listeners are on the slot's own shadow root, never on the host's `window` or `document`. The
+ * one exception is `idle`, which waits for the host window's `load` once, if the page has not
+ * loaded yet.
+ */
+export function createBootGate(slot, mode, options) {
+    const held = [];
+    let stopTrigger = () => undefined;
+    let stopHolding = () => undefined;
+    let done = false;
+    let fire;
+    const triggered = new Promise((resolve) => {
+        fire = () => {
+            if (done)
+                return;
+            stopTrigger();
+            stopTrigger = () => undefined;
+            resolve();
+        };
+    });
+    const root = slot.shadowRoot;
+    const effective = mode === 'interaction' && !(options.pierced && root) ? 'visible' : mode;
+    if (effective === 'eager') {
+        fire();
+    }
+    else if (effective === 'idle') {
+        let cancel = () => undefined;
+        const whenIdle = () => {
+            if (typeof requestIdleCallback === 'function') {
+                const handle = requestIdleCallback(() => fire(), { timeout: IDLE_TIMEOUT_MS });
+                cancel = () => cancelIdleCallback(handle);
+            }
+            else {
+                // Safari has no requestIdleCallback: a moment after load is the closest equivalent
+                const handle = setTimeout(() => fire(), 200);
+                cancel = () => clearTimeout(handle);
+            }
+        };
+        // idle during page load is time the page's own content needs
+        if (document.readyState === 'complete')
+            whenIdle();
+        else {
+            addEventListener('load', whenIdle, { once: true });
+            cancel = () => removeEventListener('load', whenIdle);
+        }
+        stopTrigger = () => cancel();
+    }
+    else if (effective === 'visible') {
+        if (typeof IntersectionObserver !== 'function') {
+            fire();
+        }
+        else {
+            const observer = new IntersectionObserver((entries) => {
+                if (entries.some((entry) => entry.isIntersecting))
+                    fire();
+            }, { rootMargin: VISIBLE_MARGIN });
+            observer.observe(slot);
+            stopTrigger = () => observer.disconnect();
+        }
+    }
+    else {
+        const shadow = root;
+        // After the next paint, so the boot's work does not land in the frame that answers the
+        // interaction that started it — which is the frame INP measures.
+        const fireAfterPaint = () => {
+            if (typeof requestAnimationFrame === 'function')
+                requestAnimationFrame(() => setTimeout(fire, 0));
+            else
+                setTimeout(fire, 0);
+        };
+        const onIntent = () => fireAfterPaint();
+        const onHeld = (event) => {
+            hold(event);
+            fireAfterPaint();
+        };
+        for (const type of PASSIVE_INTENT_EVENTS)
+            shadow.addEventListener(type, onIntent, { capture: true, passive: true });
+        // Kept until replay, not only until the trigger: a click while the fragment boots needs
+        // holding as much as the first.
+        for (const type of HELD_EVENTS)
+            shadow.addEventListener(type, onHeld, { capture: true });
+        stopHolding = () => {
+            for (const type of PASSIVE_INTENT_EVENTS)
+                shadow.removeEventListener(type, onIntent, { capture: true });
+            for (const type of HELD_EVENTS)
+                shadow.removeEventListener(type, onHeld, { capture: true });
+        };
+    }
+    function hold(event) {
+        const target = event.composedPath()[0];
+        if (!target)
+            return;
+        event.preventDefault();
+        // The fragment's own handlers do not exist yet, and the host's bubbling listeners should see
+        // this action once — when it is replayed — rather than once cancelled and again for real.
+        event.stopPropagation();
+        if (held.length >= MAX_HELD || held.some((entry) => entry.target === target))
+            return;
+        held.push(event.type === 'submit'
+            ? { target, submitter: event.submitter ?? null }
+            : { target, click: mouseInit(event) });
+    }
+    function finish() {
+        done = true;
+        stopTrigger();
+        stopHolding();
+    }
+    function replayOne(entry) {
+        if (!entry.target.isConnected) {
+            if (isDevMode()) {
+                console.warn(`[braid:${options.fragmentId}] an action taken before boot was dropped: its element left the ` +
+                    `DOM while the fragment booted, so the fragment re-rendered instead of adopting its markup`);
+            }
+            return;
+        }
+        try {
+            if (entry.click) {
+                entry.target.dispatchEvent(new MouseEvent('click', entry.click));
+            }
+            else {
+                const form = entry.target;
+                // a submitter the fragment replaced is no longer this form's, and requestSubmit would throw
+                const submitter = entry.submitter?.isConnected && entry.submitter.form === form ? entry.submitter : undefined;
+                form.requestSubmit(submitter);
+            }
+        }
+        catch (error) {
+            console.warn(`[braid:${options.fragmentId}] replaying an action taken before boot failed`, error);
+        }
+    }
+    return {
+        triggered,
+        replay() {
+            if (done)
+                return;
+            finish();
+            const queue = held.splice(0);
+            // One per task, so each handler's own re-render — a button disabling itself — lands first.
+            const next = () => {
+                const entry = queue.shift();
+                if (!entry)
+                    return;
+                replayOne(entry);
+                if (queue.length)
+                    setTimeout(next, 0);
+            };
+            next();
+        },
+        dispose() {
+            finish();
+            held.length = 0;
+        },
+    };
+}
+function mouseInit(event) {
+    return {
+        bubbles: true,
+        cancelable: true,
+        composed: true,
+        detail: event.detail,
+        clientX: event.clientX,
+        clientY: event.clientY,
+        screenX: event.screenX,
+        screenY: event.screenY,
+        button: event.button,
+        buttons: event.buttons,
+        ctrlKey: event.ctrlKey,
+        shiftKey: event.shiftKey,
+        altKey: event.altKey,
+        metaKey: event.metaKey,
+    };
+}
+//# sourceMappingURL=boot-gate.js.map

package/src/elements/boot-gate.js.map

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

package/src/elements/fragment-slot.d.ts

@@ -17,6 +17,11 @@ import { LivenessState } from '../weave/liveness.js';
 export type FragmentSlotState = 'idle' | 'loading' | 'ready' | 'error' | 'closing' | 'healthy' | 'unobservable' | 'suspect' | 'gone';
 /** `connecting` is reported as `ready`; every other liveness state carries its own name. */
 export declare function slotStateFor(liveness: LivenessState): FragmentSlotState;
+/**
+ * Whether a slot sits in another fragment's DOM: some shadow root above it belongs to a slot. A
+ * host's own components may keep slots in their shadow roots; those are the host's.
+ */
+export declare function insideAnotherFragment(slot: Element): boolean;
 /**
  * Finds server-rendered fragment content the gateway pierced into a slot.
  *
@@ -35,6 +40,12 @@ export declare function findPiercedContentRoot(shadowRoot: ShadowRoot | null): H
  * than a moment of unresponsiveness — and suspicion is designed to be recoverable.
  */
 export declare const SLOT_STYLES: string;
+/**
+ * Adds the slot a host's `slot="loading"` child projects into. Only on roots the client builds: a
+ * pierced fragment already has its content on screen. (After `reload()` a pierced slot's root is
+ * rebuilt by the client, and can show its loading state like any other.)
+ */
+export declare function ensureLoadingSlot(shadowRoot: ShadowRoot): void;
 /**
  * Ensures the shadow root can present host-provided fallback content:
  *
@@ -59,6 +70,8 @@ export declare function ensureFallbackSlot(shadowRoot: ShadowRoot): void;
  * - `src` — optional route url for the fragment. When absent, the fragment is *bound*: it
  *   follows the host page's location and participates in host navigation.
  * - `props` — JSON attribute (or the `props` property) passed to the fragment instance.
+ * - `boot` — `eager` (default), `idle`, `visible`, or `interaction`: when to boot. Read when the
+ *   slot connects, or when a deferred slot's late markup arrives. See `boot-gate.ts`.
  *
  * Events: `braid:ready`, `braid:error` (detail includes stage + fix hint), `braid:event`
  * (fragment → host).
@@ -90,6 +103,27 @@ export declare class FragmentSlot extends HTMLElement {
     disconnectedCallback(): void;
     reload(): Promise<void>;
 }
+/**
+ * Starts loading a fragment before its slot exists — from a link's hover, or a router's preload
+ * hook — so a navigation that is about to mount it finds the work already in flight.
+ *
+ * ```ts
+ * link.addEventListener('pointerenter', () => prefetchFragment('billing', '/billing/invoices'));
+ * ```
+ *
+ * `route` is what the slot will render: the destination page's path for a routed fragment, or the
+ * slot's `src` for a widget. Two things start:
+ *
+ * - the fragment's document, held for the next slot of that fragment and route to mount within
+ *   ten seconds (`PREFETCH_TTL_MS`) — so that slot makes no document request of its own;
+ * - the scripts the document names, in its own namespace, as `<link rel="prefetch">` the realm
+ *   then loads from the HTTP cache.
+ *
+ * Compat fragments only: contract and untrusted fragments load no Braid document. Calling it again
+ * for the same fragment and route while a prefetch is held does nothing. Call
+ * `clearPrefetchedFragments()` when the user signs out.
+ */
+export declare function prefetchFragment(fragmentId: string, route: string): void;
 /**
  * Fetches the fragment's document from the gateway's document namespace.
  *