@braidlabs/core 0.1.1

package/src/config.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Library-wide configuration for the Braid client runtime, set via `initBraid(options)`.
+ *
+ * Note there is no host-isolation mode switch: host purity is an invariant, not a mode.
+ * Braid never mutates a host-page global or prototype — in any mode, ever. The compat adapter
+ * achieves its interception with fragment-boundary techniques confined to each fragment's own
+ * realm and shadow DOM subtree.
+ */
+export interface BraidOptions {
+    /**
+     * Enables development-mode diagnostics: unaudited-API warnings from the compat document
+     * facade, boundary-bypass reports, and verbose boot logging. Defaults to false.
+     */
+    dev?: boolean;
+    /**
+     * Host navigation adapter. Bound fragments need to know when the host application navigates
+     * (e.g. the host router calls `history.pushState`). Braid never patches the host History API,
+     * so wire your router's after-navigation hook to the provided `notify` callback:
+     *
+     * ```ts
+     * initBraid({ onHostNavigation: (notify) => router.afterEach(() => notify()) });
+     * ```
+     *
+     * Where the Navigation API is available, host navigations are additionally observed
+     * automatically. Back/forward navigations (`popstate`) are always observed natively and need
+     * no adapter.
+     */
+    onHostNavigation?: (notify: () => void) => void;
+}
+interface ResolvedBraidConfig {
+    dev: boolean;
+    onHostNavigation?: (notify: () => void) => void;
+}
+export declare function setBraidConfig(options?: BraidOptions): void;
+export declare function getBraidConfig(): Readonly<ResolvedBraidConfig>;
+export declare function isDevMode(): boolean;
+export {};

package/src/config.js

@@ -0,0 +1,26 @@
+/**
+ * Library-wide configuration for the Braid client runtime, set via `initBraid(options)`.
+ *
+ * Note there is no host-isolation mode switch: host purity is an invariant, not a mode.
+ * Braid never mutates a host-page global or prototype — in any mode, ever. The compat adapter
+ * achieves its interception with fragment-boundary techniques confined to each fragment's own
+ * realm and shadow DOM subtree.
+ */
+const config = {
+    dev: false,
+};
+export function setBraidConfig(options = {}) {
+    if (options.dev !== undefined) {
+        config.dev = options.dev;
+    }
+    if (options.onHostNavigation) {
+        config.onHostNavigation = options.onHostNavigation;
+    }
+}
+export function getBraidConfig() {
+    return config;
+}
+export function isDevMode() {
+    return config.dev;
+}
+//# sourceMappingURL=config.js.map

package/src/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../../libs/core/src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AA8BH,MAAM,MAAM,GAAwB;IAClC,GAAG,EAAE,KAAK;CACX,CAAC;AAEF,MAAM,UAAU,cAAc,CAAC,UAAwB,EAAE;IACvD,IAAI,OAAO,CAAC,GAAG,KAAK,SAAS,EAAE,CAAC;QAC9B,MAAM,CAAC,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC;IAC3B,CAAC;IACD,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC;QAC7B,MAAM,CAAC,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IACrD,CAAC;AACH,CAAC;AAED,MAAM,UAAU,cAAc;IAC5B,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,SAAS;IACvB,OAAO,MAAM,CAAC,GAAG,CAAC;AACpB,CAAC"}

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

@@ -0,0 +1,67 @@
+import type { VersionedSchema } from '@braidlabs/skew';
+/**
+ * Context bus — host-published shared state, delivered at each subscriber's own contract version.
+ *
+ * Values are structured-cloned at the boundary: sharing live objects across realms creates
+ * cross-realm retention (GC leaks) and accidental coupling, and clone-at-the-boundary keeps fragment
+ * instances disposable.
+ *
+ * **Versioning is what makes this a bus rather than an event emitter.** A page composes fragments
+ * built at different times, so the publisher and a subscriber routinely disagree about what a
+ * context payload looks like. Register a `@braidlabs/skew` schema for a key and every delivery is
+ * projected to the version that subscriber asked for — older subscribers get the older shape, and
+ * neither side has to know the other exists.
+ *
+ * Two decisions worth stating, because both were tempting to get wrong:
+ *
+ * 1. **Reachability is checked when a fragment subscribes, not when a value is broadcast.**
+ *    Projecting down needs a `down` on every intervening step, and a chain missing one is a
+ *    programming error in your own contract rather than data skew. Discovering it mid-broadcast
+ *    would fail one delivery deep inside a fan-out with the other subscribers already served;
+ *    refusing the subscription makes it a start-up error with a fragment's name on it.
+ * 2. **An unregistered key passes through untouched.** A bus that demanded a schema for every value
+ *    is a bus nobody adopts incrementally. Untyped contexts are cloned and delivered as they are,
+ *    exactly as the v0 bus did.
+ */
+type ContextListener = (value: unknown) => void;
+export interface ContextSubscribeOptions {
+    signal?: AbortSignal;
+    /**
+     * The contract version this subscriber speaks. Defaults to the registered schema's current
+     * version — right for a fragment built from the same source, wrong for every fragment that was
+     * not, so a fragment that knows it is behind should say so.
+     */
+    as?: number;
+    /** Names the fragment in any error raised. Falls back to the context key. */
+    fragmentId?: string;
+}
+export interface ContextReadOptions {
+    as?: number;
+    fragmentId?: string;
+}
+export declare const braidContext: {
+    /**
+     * Declares the contract a context key carries.
+     *
+     * Registering after values have been published is allowed, and deliberately so: the host learns a
+     * fragment's contract when that fragment mounts, which is later than the first broadcast on every
+     * real page.
+     */
+    register<T>(key: string, schema: VersionedSchema<T>): void;
+    /** The schema registered for a key, if any. */
+    schemaFor(key: string): VersionedSchema<unknown> | undefined;
+    /**
+     * Publishes a context value to every fragment (and host code) subscribed to the key.
+     *
+     * **Every subscriber is isolated.** One fragment throwing in its listener — or declaring a version
+     * that became unreachable after it subscribed — must not stop delivery to the fragments after it
+     * in the set. Without that, a bad deploy of one app presents as a *different* app silently
+     * failing to update, which is the least debuggable shape a bug can take on a composed page.
+     */
+    set(key: string, value: unknown): void;
+    get(key: string, options?: ContextReadOptions): unknown;
+    subscribe(key: string, listener: ContextListener, options?: ContextSubscribeOptions): () => void;
+    /** Exposed for tests. */
+    clear(): void;
+};
+export {};

package/src/context/context-bus.js

@@ -0,0 +1,117 @@
+import { BraidError } from '../errors.js';
+const values = new Map();
+const subscriptions = new Map();
+const schemas = new Map();
+export const braidContext = {
+    /**
+     * Declares the contract a context key carries.
+     *
+     * Registering after values have been published is allowed, and deliberately so: the host learns a
+     * fragment's contract when that fragment mounts, which is later than the first broadcast on every
+     * real page.
+     */
+    register(key, schema) {
+        schemas.set(key, schema);
+    },
+    /** The schema registered for a key, if any. */
+    schemaFor(key) {
+        return schemas.get(key);
+    },
+    /**
+     * Publishes a context value to every fragment (and host code) subscribed to the key.
+     *
+     * **Every subscriber is isolated.** One fragment throwing in its listener — or declaring a version
+     * that became unreachable after it subscribed — must not stop delivery to the fragments after it
+     * in the set. Without that, a bad deploy of one app presents as a *different* app silently
+     * failing to update, which is the least debuggable shape a bug can take on a composed page.
+     */
+    set(key, value) {
+        values.set(key, value);
+        for (const subscription of [...(subscriptions.get(key) ?? [])]) {
+            try {
+                subscription.listener(project(key, value, subscription.as));
+            }
+            catch (error) {
+                // Reported rather than swallowed: a subscriber that never hears anything again is worth
+                // knowing about, and this is the only place that can see it happen.
+                console.error(`braid: a "${key}" context subscriber threw; other subscribers were unaffected`, error);
+            }
+        }
+    },
+    get(key, options) {
+        const value = values.get(key);
+        if (value === undefined)
+            return undefined;
+        // A read at an unreachable version is the same error as a subscription at one, and is raised
+        // rather than quietly answered at the publisher's version: handing a fragment a shape it cannot
+        // parse is how a context bus produces a stack trace in someone else's code.
+        assertReachable(key, options?.as, options?.fragmentId);
+        return project(key, value, options?.as);
+    },
+    subscribe(key, listener, options) {
+        assertReachable(key, options?.as, options?.fragmentId);
+        let keySubscriptions = subscriptions.get(key);
+        if (!keySubscriptions) {
+            keySubscriptions = new Set();
+            subscriptions.set(key, keySubscriptions);
+        }
+        const subscription = {
+            listener,
+            ...(options?.as === undefined ? {} : { as: options.as }),
+        };
+        keySubscriptions.add(subscription);
+        const unsubscribe = () => void keySubscriptions.delete(subscription);
+        options?.signal?.addEventListener('abort', unsubscribe, { once: true });
+        return unsubscribe;
+    },
+    /** Exposed for tests. */
+    clear() {
+        values.clear();
+        subscriptions.clear();
+        schemas.clear();
+    },
+};
+/**
+ * Projects a published value to one subscriber's version.
+ *
+ * `write({ as })` down-migrates and returns the older envelope — the polite move when the reader is
+ * known to be older than the publisher. Subscribers receive the payload rather than the envelope:
+ * the version they asked for is the version they get, so handing them a wrapper to unwrap would be
+ * ceremony without information.
+ */
+function project(key, value, as) {
+    const schema = schemas.get(key);
+    if (!schema)
+        return structuredClone(value);
+    const envelope = as === undefined || as === schema.version ? schema.write(value) : schema.write(value, { as });
+    return structuredClone(envelope.payload);
+}
+/**
+ * Refuses a subscriber whose version cannot be reached from the publisher's.
+ *
+ * Decided from the declared chain rather than by attempting a migration, so the answer does not
+ * depend on a value happening to have been published yet — a fragment that mounts before the first
+ * broadcast deserves the same error as one that mounts after it.
+ */
+function assertReachable(key, as, fragmentId) {
+    const schema = schemas.get(key);
+    if (!schema || as === undefined || as === schema.version)
+        return;
+    const raise = (message, fixHint) => {
+        throw new BraidError(message, { fragmentId: fragmentId ?? key, stage: 'context-version', fixHint });
+    };
+    if (as > schema.version) {
+        raise(`context "${key}" is published at v${schema.version}, and this subscriber asked for v${as}`, 'the publisher is older than the subscriber — deploy the host, or subscribe at a version it can produce');
+    }
+    if (as < 1)
+        raise(`context "${key}" has no v${as}`, 'contract versions start at 1');
+    // Every step between the subscriber's version and the publisher's has to walk back down.
+    const missing = schema.steps
+        .filter((step) => step.to > as && step.to <= schema.version && !step.down)
+        .map((step) => `v${step.to} (${step.description})`);
+    if (missing.length > 0) {
+        raise(`context "${key}" cannot be projected from v${schema.version} down to v${as}: ` +
+            `${missing.join(', ')} ${missing.length === 1 ? 'declares' : 'declare'} no down migration`, `add a down migration to the step that introduced ${missing[0]}, or subscribe at v${schema.version}`);
+    }
+}
+//# sourceMappingURL=context-bus.js.map

package/src/context/context-bus.js.map

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

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

@@ -0,0 +1,39 @@
+export type FragmentSlotState = 'idle' | 'loading' | 'ready' | 'error';
+/**
+ * Finds server-rendered fragment content the gateway pierced into a slot.
+ *
+ * Deliberately a direct-children scan rather than `querySelector(':scope > braid-document')`:
+ * `:scope` has no element to match against on a ShadowRoot, so that selector silently never
+ * matches. The failure mode is invisible from inside the page — the slot just quietly re-fetches
+ * and replaces identical content — so it is worth a named helper and a test.
+ */
+export declare function findPiercedContentRoot(shadowRoot: ShadowRoot | null): HTMLElement | null;
+/**
+ * `<fragment-slot>` — the custom element a host renders to mount a fragment.
+ *
+ * ```html
+ * <fragment-slot name="checkout"></fragment-slot>
+ * ```
+ *
+ * - `name` — the fragment id in the gateway registry (required).
+ * - `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.
+ *
+ * Events: `braid:ready`, `braid:error` (detail includes stage + fix hint), `braid:event`
+ * (fragment → host).
+ *
+ * The slot uses only its own shadow root and its own elements — the host page is never patched.
+ */
+export declare class FragmentSlot extends HTMLElement {
+    #private;
+    static get observedAttributes(): string[];
+    get state(): FragmentSlotState;
+    get name(): string;
+    get props(): Record<string, unknown>;
+    set props(value: Record<string, unknown>);
+    attributeChangedCallback(attribute: string, oldValue: string | null, newValue: string | null): void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    reload(): Promise<void>;
+}

package/src/elements/fragment-slot.js

@@ -0,0 +1,281 @@
+import { BraidError } from '../errors.js';
+import { braidDocumentUrl, BRAID_FRAGMENT_ID_HEADER } from '../protocol.js';
+import { createRealm } from '../realm/realm-manager.js';
+import { resolveAdapter } from '../adapters/adapter.js';
+import { createFragmentEnv } from '../env/create-env.js';
+import { isDevMode } from '../config.js';
+/**
+ * Finds server-rendered fragment content the gateway pierced into a slot.
+ *
+ * Deliberately a direct-children scan rather than `querySelector(':scope > braid-document')`:
+ * `:scope` has no element to match against on a ShadowRoot, so that selector silently never
+ * matches. The failure mode is invisible from inside the page — the slot just quietly re-fetches
+ * and replaces identical content — so it is worth a named helper and a test.
+ */
+export function findPiercedContentRoot(shadowRoot) {
+    if (!shadowRoot)
+        return null;
+    for (const child of shadowRoot.children) {
+        if (child.tagName === 'BRAID-DOCUMENT')
+            return child;
+    }
+    return null;
+}
+/**
+ * `<fragment-slot>` — the custom element a host renders to mount a fragment.
+ *
+ * ```html
+ * <fragment-slot name="checkout"></fragment-slot>
+ * ```
+ *
+ * - `name` — the fragment id in the gateway registry (required).
+ * - `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.
+ *
+ * Events: `braid:ready`, `braid:error` (detail includes stage + fix hint), `braid:event`
+ * (fragment → host).
+ *
+ * The slot uses only its own shadow root and its own elements — the host page is never patched.
+ */
+export class FragmentSlot extends HTMLElement {
+    static get observedAttributes() {
+        return ['name', 'src', 'props'];
+    }
+    #state = 'idle';
+    #props = {};
+    #propsListeners = new Set();
+    #abortController;
+    #booted = false;
+    #bootScheduled = false;
+    /** Set by reload(): a reload must re-fetch, never re-adopt the pierced content. */
+    #forceFetch = false;
+    get state() {
+        return this.#state;
+    }
+    get name() {
+        return this.getAttribute('name') ?? '';
+    }
+    get props() {
+        return this.#props;
+    }
+    set props(value) {
+        this.#props = structuredClone(value ?? {});
+        this.#propsListeners.forEach((listener) => listener(this.#props));
+    }
+    attributeChangedCallback(attribute, oldValue, newValue) {
+        if (attribute === 'props') {
+            try {
+                this.props = newValue ? JSON.parse(newValue) : {};
+            }
+            catch (error) {
+                console.warn(`[braid:${this.name}] ignoring unparsable props attribute`, error);
+            }
+        }
+        else if (attribute === 'name' && oldValue !== newValue) {
+            if (this.isConnected && this.#booted) {
+                void this.reload();
+            }
+            else if (this.isConnected && !this.#booted && !this.#bootScheduled) {
+                this.#bootScheduled = true;
+                queueMicrotask(() => {
+                    this.#bootScheduled = false;
+                    if (this.isConnected && !this.#booted) {
+                        this.#booted = true;
+                        void this.#boot();
+                    }
+                });
+            }
+        }
+    }
+    connectedCallback() {
+        if (this.#booted || this.#bootScheduled) {
+            return;
+        }
+        this.#bootScheduled = true;
+        queueMicrotask(() => {
+            this.#bootScheduled = false;
+            if (!this.isConnected || this.#booted) {
+                return;
+            }
+            this.#booted = true;
+            void this.#boot();
+        });
+    }
+    disconnectedCallback() {
+        this.#bootScheduled = false;
+        this.#teardown();
+        this.#booted = false;
+    }
+    async reload() {
+        this.#teardown();
+        this.#forceFetch = true;
+        await this.#boot();
+    }
+    #teardown() {
+        this.#abortController?.abort();
+        this.#abortController = undefined;
+        this.shadowRoot?.replaceChildren();
+        this.#state = 'idle';
+    }
+    async #boot() {
+        const fragmentId = this.name;
+        try {
+            if (!fragmentId) {
+                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',
+                });
+            }
+            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',
+                });
+            }
+            this.#state = 'loading';
+            const abortController = new AbortController();
+            this.#abortController = abortController;
+            const signal = abortController.signal;
+            // src present → standalone fragment pinned to that route; absent → bound to host location
+            const src = this.getAttribute('src');
+            const bound = !src;
+            const routeUrl = src ?? location.pathname + location.search;
+            const routeSrcUrl = new URL(routeUrl, document.baseURI);
+            /**
+             * Pierced fragments arrive with their content already in the DOM: the gateway wrote a
+             * declarative shadow root into this element, and the browser parsed it at the same time
+             * as the rest of the page. Adopting it is strictly better than fetching — the
+             * content is already painted, and re-fetching it would replace live DOM with identical
+             * DOM. `#forceFetch` is set by reload(), which must go back to the network.
+             */
+            const piercedContentRoot = this.#forceFetch ? null : findPiercedContentRoot(this.shadowRoot);
+            let shadowRoot;
+            let contentRoot;
+            if (piercedContentRoot) {
+                shadowRoot = this.shadowRoot;
+                contentRoot = piercedContentRoot;
+            }
+            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; }';
+                contentRoot = document.createElement('braid-document');
+                shadowRoot.replaceChildren(styleSheet, contentRoot);
+            }
+            /**
+             * 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.
+             *
+             * Which adapter a fragment uses is only known once the realm stub has loaded, so the
+             * document request is started optimistically and its failure is held rather than thrown:
+             * 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.
+             */
+            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 })),
+                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)
+                throw htmlResult.error;
+            const html = htmlResult.ok ? htmlResult.html : null;
+            const env = 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;
+                },
+                emit: (type, detail) => {
+                    this.dispatchEvent(new CustomEvent('braid:event', { detail: { type, detail }, bubbles: true }));
+                },
+                signal,
+            });
+            await adapter.boot({
+                fragmentId,
+                shadowRoot,
+                contentRoot,
+                realm,
+                html,
+                pierced: Boolean(piercedContentRoot),
+                routeUrl,
+                bound,
+                env,
+                signal,
+            });
+            if (signal.aborted)
+                return;
+            this.#state = 'ready';
+            this.dispatchEvent(new CustomEvent('braid:ready', { detail: { fragmentId } }));
+            if (isDevMode()) {
+                console.debug(`[braid:${fragmentId}] ready`, { slot: this });
+            }
+        }
+        catch (error) {
+            if (this.#abortController?.signal.aborted)
+                return;
+            this.#state = 'error';
+            const braidError = error instanceof BraidError
+                ? error
+                : new BraidError(error instanceof Error ? error.message : String(error), {
+                    fragmentId,
+                    stage: 'adapter-mount',
+                    cause: error,
+                });
+            console.error(braidError);
+            this.dispatchEvent(new CustomEvent('braid:error', {
+                detail: {
+                    fragmentId: braidError.fragmentId,
+                    stage: braidError.stage,
+                    fixHint: braidError.fixHint,
+                    error: braidError,
+                },
+            }));
+        }
+    }
+    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`, {
+                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.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}"`,
+            });
+        }
+        return response.text();
+    }
+}
+//# sourceMappingURL=fragment-slot.js.map

package/src/elements/fragment-slot.js.map

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

package/src/env/create-env.d.ts

@@ -0,0 +1,31 @@
+import { FragmentEnv } from './fragment-env.js';
+export interface CreateEnvOptions {
+    contentRoot: HTMLElement;
+    shadowRoot: ShadowRoot;
+    routeUrl: string;
+    /** Reads the slot's current props. */
+    getProps(): Readonly<Record<string, unknown>>;
+    /** Registers a props-change listener; returns an unsubscribe function. */
+    onPropsChanged(listener: (props: Readonly<Record<string, unknown>>) => void): () => void;
+    /** Fragment → host event dispatch (surfaced as `braid:event` on the slot element). */
+    emit(type: string, detail?: unknown): void;
+    signal: AbortSignal;
+    /** Names this fragment in context-version errors. */
+    fragmentId?: string;
+    /**
+     * The contract version this fragment speaks for each context key, from its manifest.
+     *
+     * A fragment built months ago reads a context published today, so it declares what it can parse
+     * and the bus projects each delivery down to it. Absent, a fragment is assumed current — right for
+     * one built from the same source, and the reason a fragment that knows it is behind must say so.
+     */
+    contextVersions?: Readonly<Record<string, number>>;
+}
+/**
+ * Builds the FragmentEnv for a fragment instance.
+ *
+ * Compat fragments never consume the env — the compat adapter installs the full illusion
+ * instead — but the runtime constructs one uniformly so the adapter interface is the same
+ * for every adapter, and contract adapters can land later without touching the slot.
+ */
+export declare function createFragmentEnv(options: CreateEnvOptions): FragmentEnv;