@braidlabs/core 0.1.1 → 0.3.0

package/src/weave/handshake.d.ts

@@ -0,0 +1,124 @@
+import { BoundaryChannel } from './channel.js';
+import { ContextBridge, FragmentContract, HostContract } from './contract.js';
+/**
+ * The connect-time handshake: HELLO → ACCEPT → OPEN.
+ *
+ * Braid has always verified a version at boot — the gateway stamps `BRAID_PROTOCOL_VERSION` onto
+ * the realm stub and the client checks the `<meta>`. That check answers "did these two ship
+ * together?" and nothing else. It cannot answer the questions the phases above this one ask:
+ * *which instance* am I talking to, *what* does it declare it can parse, and *when* did it become
+ * ready to hear from me.
+ *
+ * Three steps rather than two, because ACCEPT and OPEN carry different things in different
+ * directions and collapsing them would force the host to send the context snapshot before it has
+ * seen what the fragment can parse — which is precisely the information that decides how the
+ * snapshot must be projected.
+ */
+export declare const HELLO = "weave/hello";
+export declare const OPEN = "weave/open";
+/** Host → fragment. What the host is, and what it is prepared to speak. */
+export interface HelloPayload {
+    weave: number;
+    /** The client ↔ gateway composition protocol version, echoed for diagnosis only. */
+    protocol: string;
+    fragmentId: string;
+    instance: string;
+    /** What the host offers, so a fragment can refuse from its own side too. */
+    contract?: HostContract;
+}
+/** Fragment → host, as the reply to HELLO. What the fragment is, and what it can parse. */
+export interface AcceptPayload {
+    weave: number;
+    /**
+     * Per-key context contract versions this fragment speaks.
+     *
+     * A fragment built months ago reads a context published today, so it declares what it can parse
+     * and every delivery is projected down to it. The registry manifest is the authority where it has
+     * an opinion — see `resolveContextVersions` — because a compromised or merely stale fragment
+     * should not be able to talk its way into a projection the host did not sanction.
+     */
+    contextVersions?: Record<string, number>;
+    /**
+     * What this fragment requires and provides.
+     *
+     * The registry manifest overrides it where it has an opinion, for the same reason it overrides
+     * `contextVersions` — on the untrusted tier this half of the handshake is attacker-controlled,
+     * and a fragment that could state its own requirements could state them away.
+     */
+    contract?: FragmentContract;
+}
+/** Host → fragment. The opening state, sent once terms are agreed. */
+export interface OpenPayload {
+    /** Every context key, already projected to this fragment's declared versions. */
+    context: Record<string, unknown>;
+    props: Record<string, unknown>;
+}
+export interface HostHandshakeOptions {
+    channel: BoundaryChannel;
+    fragmentId: string;
+    instance: string;
+    /**
+     * Context versions from the fragment's registry manifest, where the registry has an opinion.
+     * Merged over whatever the fragment declares in ACCEPT.
+     */
+    manifestContextVersions?: Readonly<Record<string, number>>;
+    /** What this host offers. Absent when the host declares no contract. */
+    hostContract?: HostContract;
+    /** The fragment's contract from its registry manifest, overriding what it declares in ACCEPT. */
+    manifestContract?: FragmentContract;
+    /**
+     * Compares the two contracts. Injected so the handshake carries no contract logic of its own —
+     * negotiation is a policy question and this module is a protocol.
+     */
+    negotiate?(host: HostContract | undefined, fragment: FragmentContract | undefined): {
+        outcome: 'compatible' | 'bridged' | 'incompatible';
+        bridges: ContextBridge[];
+        reason?: string;
+        fixHint?: string;
+    };
+    /** Reports a connection opened across a version gap, with what it costs. */
+    onBridged?(bridges: ContextBridge[]): void;
+    /** Builds the opening state once terms are agreed and versions are known to be reachable. */
+    openWith(contextVersions: Readonly<Record<string, number>>): OpenPayload;
+    /**
+     * Raises if a declared version cannot be projected to from what the host publishes.
+     *
+     * Checked here, at the handshake, rather than at first delivery. That is where the context bus
+     * already argues it belongs — "refusing the subscription makes it a start-up error with a
+     * fragment's name on it" — and this moves it one step earlier still, to before the fragment has
+     * been handed any state at all.
+     */
+    assertReachable(contextVersions: Readonly<Record<string, number>>): void;
+    timeoutMs?: number;
+}
+export interface HandshakeResult {
+    contextVersions: Readonly<Record<string, number>>;
+    bridges: ContextBridge[];
+}
+/** Drives the host end. Resolves once the fragment has been sent its opening state. */
+export declare function performHostHandshake(options: HostHandshakeOptions): Promise<HandshakeResult>;
+export interface FragmentHandshakeOptions {
+    channel: BoundaryChannel;
+    /** What this fragment declares it can parse, per context key. */
+    contextVersions?: Readonly<Record<string, number>>;
+    /** What this fragment requires and provides. */
+    contract?: FragmentContract;
+    /** Called once the host sends the opening state. */
+    onOpen(payload: OpenPayload): void;
+}
+/**
+ * Answers the host end. Registers its handlers synchronously and returns a promise that resolves
+ * at OPEN, so a caller may either await readiness or ignore it — the handlers are live either way,
+ * which matters because HELLO can arrive in the same turn this is called.
+ */
+export declare function answerHandshake(options: FragmentHandshakeOptions): Promise<OpenPayload>;
+/**
+ * Merges the fragment's declaration with the registry's, with the registry winning.
+ *
+ * Not an arbitrary tie-break. The manifest is host-side configuration describing a fragment; the
+ * ACCEPT payload is the fragment describing itself. On the untrusted tier the second of those is
+ * attacker-controlled, and a fragment that could name its own context version could ask to be
+ * served a shape the host never intended to project. Letting the registry win costs nothing when
+ * the two agree, which is every honest case.
+ */
+export declare function resolveContextVersions(declared: Readonly<Record<string, number>> | undefined, fromManifest: Readonly<Record<string, number>> | undefined): Readonly<Record<string, number>>;

package/src/weave/handshake.js

@@ -0,0 +1,109 @@
+import { BraidError } from '../errors.js';
+import { BRAID_PROTOCOL_VERSION } from '../protocol.js';
+import { WEAVE_VERSION } from './envelope.js';
+/**
+ * The connect-time handshake: HELLO → ACCEPT → OPEN.
+ *
+ * Braid has always verified a version at boot — the gateway stamps `BRAID_PROTOCOL_VERSION` onto
+ * the realm stub and the client checks the `<meta>`. That check answers "did these two ship
+ * together?" and nothing else. It cannot answer the questions the phases above this one ask:
+ * *which instance* am I talking to, *what* does it declare it can parse, and *when* did it become
+ * ready to hear from me.
+ *
+ * Three steps rather than two, because ACCEPT and OPEN carry different things in different
+ * directions and collapsing them would force the host to send the context snapshot before it has
+ * seen what the fragment can parse — which is precisely the information that decides how the
+ * snapshot must be projected.
+ */
+export const HELLO = 'weave/hello';
+export const OPEN = 'weave/open';
+/**
+ * Ten seconds, and deliberately not the channel's default five.
+ *
+ * HELLO is the one request sent while the fragment is still booting — its realm may be parsing a
+ * framework bundle on a cold cache over a slow connection. Every other request happens against a
+ * fragment that has already proven it can answer, which is why they get a tighter deadline.
+ */
+const HANDSHAKE_TIMEOUT_MS = 10_000;
+/** Drives the host end. Resolves once the fragment has been sent its opening state. */
+export async function performHostHandshake(options) {
+    const { channel, fragmentId, instance } = options;
+    const hello = {
+        weave: WEAVE_VERSION,
+        protocol: BRAID_PROTOCOL_VERSION,
+        fragmentId,
+        instance,
+        ...(options.hostContract === undefined ? {} : { contract: options.hostContract }),
+    };
+    const accept = await channel.request(HELLO, hello, {
+        timeoutMs: options.timeoutMs ?? HANDSHAKE_TIMEOUT_MS,
+    });
+    if (accept?.weave !== WEAVE_VERSION) {
+        throw new BraidError(`the fragment answered with weave protocol v${String(accept?.weave)}, and this host speaks v${WEAVE_VERSION}`, {
+            fragmentId,
+            stage: 'handshake',
+            fixHint: 'the host and the fragment are running different major versions of @braidlabs/core — align them',
+        });
+    }
+    /**
+     * Terms before state.
+     *
+     * The negotiation runs between ACCEPT and OPEN because that is the only point where both halves
+     * are known and nothing has crossed yet. A fragment refused here has been handed no context, no
+     * props, and no reason to have started rendering.
+     */
+    const fragmentContract = options.manifestContract ?? accept.contract;
+    const negotiation = options.negotiate?.(options.hostContract, fragmentContract) ?? {
+        outcome: 'compatible',
+        bridges: [],
+    };
+    if (negotiation.outcome === 'incompatible') {
+        throw new BraidError(negotiation.reason ?? 'the fragment’s contract is not compatible with this host', {
+            fragmentId,
+            stage: 'contract',
+            ...(negotiation.fixHint === undefined ? {} : { fixHint: negotiation.fixHint }),
+        });
+    }
+    if (negotiation.bridges.length > 0)
+        options.onBridged?.(negotiation.bridges);
+    const contextVersions = resolveContextVersions(accept.contextVersions, options.manifestContextVersions);
+    options.assertReachable(contextVersions);
+    // Fire and forget: OPEN carries state, not a question. Making it a request would mean the host
+    // blocks its own mount on a fragment acknowledging state it has already been given, and a
+    // fragment slow to acknowledge would look identical to one that never got it.
+    channel.send(OPEN, options.openWith(contextVersions));
+    return { contextVersions, bridges: negotiation.bridges };
+}
+/**
+ * Answers the host end. Registers its handlers synchronously and returns a promise that resolves
+ * at OPEN, so a caller may either await readiness or ignore it — the handlers are live either way,
+ * which matters because HELLO can arrive in the same turn this is called.
+ */
+export function answerHandshake(options) {
+    const { channel } = options;
+    const { promise, resolve } = Promise.withResolvers();
+    channel.on(HELLO, () => ({
+        weave: WEAVE_VERSION,
+        ...(options.contextVersions === undefined ? {} : { contextVersions: { ...options.contextVersions } }),
+        ...(options.contract === undefined ? {} : { contract: options.contract }),
+    }));
+    channel.on(OPEN, (payload) => {
+        const open = (payload ?? { context: {}, props: {} });
+        options.onOpen(open);
+        resolve(open);
+    });
+    return promise;
+}
+/**
+ * Merges the fragment's declaration with the registry's, with the registry winning.
+ *
+ * Not an arbitrary tie-break. The manifest is host-side configuration describing a fragment; the
+ * ACCEPT payload is the fragment describing itself. On the untrusted tier the second of those is
+ * attacker-controlled, and a fragment that could name its own context version could ask to be
+ * served a shape the host never intended to project. Letting the registry win costs nothing when
+ * the two agree, which is every honest case.
+ */
+export function resolveContextVersions(declared, fromManifest) {
+    return { ...(declared ?? {}), ...(fromManifest ?? {}) };
+}
+//# sourceMappingURL=handshake.js.map

package/src/weave/handshake.js.map

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

package/src/weave/liveness.d.ts

@@ -0,0 +1,90 @@
+import { BoundaryChannel } from './channel.js';
+/**
+ * Liveness — the fragment as a session rather than a mount.
+ *
+ * Before this, `<fragment-slot>` had four states and `ready` was terminal: a fragment whose realm
+ * wedged in a `while (true)` reported `ready` forever, and the only symptom was a region of the page
+ * that had quietly stopped being an application. The host had no way to tell "finished rendering"
+ * from "stopped existing".
+ *
+ * ```
+ * idle → connecting → healthy ⇄ unobservable
+ *                        ↓           ↓
+ *                     suspect  →   gone
+ * ```
+ *
+ * The state that makes this correct rather than merely present is **`unobservable`**. Browsers
+ * throttle timers in hidden tabs — to once a second, then far less after a few minutes — so a naive
+ * heartbeat reports mass death the moment a user switches tabs, and a team that has seen that once
+ * will turn the whole feature off. `unobservable` is not a fault: it is the host saying it has
+ * stopped being able to tell, which is a different claim from the fragment being unwell.
+ */
+export declare const BEAT = "weave/beat";
+export type LivenessState = 'connecting' | 'healthy' | 'unobservable' | 'suspect' | 'gone';
+/**
+ * Where "can the fragment be observed right now?" is answered from.
+ *
+ * An interface rather than a direct `document.visibilityState` read so the two ends can be driven
+ * from the same source in a test. Both ends must agree — the fragment stops beating and the host
+ * suspends its deadline — and they agree by consulting the same document, which holds on the
+ * trusted tier (one document) and on the untrusted one (an iframe's visibility follows its top
+ * level).
+ */
+export interface VisibilitySource {
+    isHidden(): boolean;
+    onChange(listener: () => void): () => void;
+}
+export declare function documentVisibility(): VisibilitySource;
+/**
+ * The timer source a fragment's beats are scheduled on.
+ *
+ * This is the whole point of the fragment half, and the easiest thing to get wrong: scheduling
+ * beats on the *host's* `setInterval` would produce a perfectly steady heartbeat from a realm that
+ * had stopped executing. The beat has to be scheduled on the realm's own event loop — pass
+ * `realm.window` — so that a fragment spinning in a synchronous loop stops beating, because its
+ * timers stop firing. A beat proves the realm's task queue is turning; nothing else here does.
+ */
+export interface BeatScheduler {
+    setInterval(handler: () => void, ms: number): number;
+    clearInterval(id: number): void;
+    /** Used for the opening beat, which must be evidence on the same terms as every other beat. */
+    setTimeout(handler: () => void, ms: number): number;
+}
+export interface HostLivenessOptions {
+    channel: BoundaryChannel;
+    /** The instance whose beats count. Beats stamped with any other instance are ignored. */
+    instance: string;
+    signal: AbortSignal;
+    onState(state: LivenessState, previous: LivenessState): void;
+    beatIntervalMs?: number;
+    graceBeats?: number;
+    goneAfterMs?: number;
+    visibility?: VisibilitySource;
+    /**
+     * Listen now, judge later: the beat handler is registered immediately, and the first deadline is
+     * armed only once this settles.
+     *
+     * The two have to be separable. Registering late loses the opening beat — the guest schedules it
+     * as soon as it is open, and on a cross-origin port nothing orders that against the host finishing
+     * its own mount — which leaves a perfectly healthy fragment sitting in `connecting` for a full
+     * interval. Arming early is the opposite mistake: it puts a deadline on a fragment that is still
+     * evaluating its framework bundle, and the honest name for that state is `loading`.
+     */
+    armAfter?: Promise<unknown>;
+}
+export interface HostLiveness {
+    readonly state: LivenessState;
+    stop(): void;
+}
+/** Host side: watches for beats and reports what it can and cannot conclude from their absence. */
+export declare function startHostLiveness(options: HostLivenessOptions): HostLiveness;
+export interface FragmentBeatOptions {
+    channel: BoundaryChannel;
+    /** The realm's timer source — see `BeatScheduler`. */
+    scheduler: BeatScheduler;
+    signal: AbortSignal;
+    beatIntervalMs?: number;
+    visibility?: VisibilitySource;
+}
+/** Fragment side: beats while it can be observed, and stays quiet while it cannot. */
+export declare function startFragmentBeats(options: FragmentBeatOptions): () => void;

package/src/weave/liveness.js

@@ -0,0 +1,189 @@
+/**
+ * Liveness — the fragment as a session rather than a mount.
+ *
+ * Before this, `<fragment-slot>` had four states and `ready` was terminal: a fragment whose realm
+ * wedged in a `while (true)` reported `ready` forever, and the only symptom was a region of the page
+ * that had quietly stopped being an application. The host had no way to tell "finished rendering"
+ * from "stopped existing".
+ *
+ * ```
+ * idle → connecting → healthy ⇄ unobservable
+ *                        ↓           ↓
+ *                     suspect  →   gone
+ * ```
+ *
+ * The state that makes this correct rather than merely present is **`unobservable`**. Browsers
+ * throttle timers in hidden tabs — to once a second, then far less after a few minutes — so a naive
+ * heartbeat reports mass death the moment a user switches tabs, and a team that has seen that once
+ * will turn the whole feature off. `unobservable` is not a fault: it is the host saying it has
+ * stopped being able to tell, which is a different claim from the fragment being unwell.
+ */
+export const BEAT = 'weave/beat';
+export function documentVisibility() {
+    return {
+        isHidden: () => document.visibilityState === 'hidden',
+        onChange(listener) {
+            document.addEventListener('visibilitychange', listener);
+            return () => document.removeEventListener('visibilitychange', listener);
+        },
+    };
+}
+/** Two seconds: three missed beats is six, comfortably under a person's patience for a dead panel. */
+const BEAT_INTERVAL_MS = 2_000;
+/** Three, so one dropped beat under load is not a diagnosis. */
+const GRACE_BEATS = 3;
+/** Fifteen seconds of silence from a fragment that should be running is not a slow fragment. */
+const GONE_AFTER_MS = 15_000;
+/** Host side: watches for beats and reports what it can and cannot conclude from their absence. */
+export function startHostLiveness(options) {
+    const { channel, instance, signal } = options;
+    const beatIntervalMs = options.beatIntervalMs ?? BEAT_INTERVAL_MS;
+    const graceBeats = options.graceBeats ?? GRACE_BEATS;
+    const goneAfterMs = options.goneAfterMs ?? GONE_AFTER_MS;
+    const visibility = options.visibility ?? documentVisibility();
+    let state = 'connecting';
+    let deadline;
+    let goneTimer;
+    let stopped = false;
+    const transition = (next) => {
+        if (stopped || next === state)
+            return;
+        const previous = state;
+        state = next;
+        options.onState(next, previous);
+    };
+    const clearDeadline = () => {
+        if (deadline !== undefined)
+            clearTimeout(deadline);
+        deadline = undefined;
+    };
+    const clearGone = () => {
+        if (goneTimer !== undefined)
+            clearTimeout(goneTimer);
+        goneTimer = undefined;
+    };
+    const armDeadline = () => {
+        clearDeadline();
+        if (stopped || visibility.isHidden())
+            return;
+        deadline = setTimeout(() => {
+            transition('suspect');
+            // Suspicion is reported but not acted on. A fragment doing a long synchronous render is
+            // indistinguishable from one that has died, right up until it finishes — so the host says
+            // what it observes and waits before it says what it concludes.
+            clearGone();
+            goneTimer = setTimeout(() => transition('gone'), goneAfterMs);
+        }, beatIntervalMs * graceBeats);
+    };
+    channel.on(BEAT, (_payload, meta) => {
+        /**
+         * A beat only counts for the instance it came from.
+         *
+         * Without this, a fragment torn down mid-flight could have its last in-flight beat credited to
+         * the instance that replaced it, and a replacement that never booted would look healthy for one
+         * interval. (Today both ends of a trusted channel are stamped with the same instance by the
+         * slot; Phase 5 binds this to the instance the fragment reports in ACCEPT.)
+         */
+        if (meta.instance !== instance)
+            return;
+        if (stopped)
+            return;
+        clearGone();
+        transition(visibility.isHidden() ? 'unobservable' : 'healthy');
+        armDeadline();
+    });
+    const detachVisibility = visibility.onChange(() => {
+        if (stopped)
+            return;
+        if (visibility.isHidden()) {
+            clearDeadline();
+            clearGone();
+            // Only a running fragment becomes unobservable. One already suspect or gone stays that way:
+            // hiding the tab is not evidence of recovery.
+            if (state === 'healthy' || state === 'connecting')
+                transition('unobservable');
+            return;
+        }
+        // Back in view: the deadline restarts from now rather than resuming, because the fragment has
+        // only just been told it may beat again and has not had a chance to.
+        armDeadline();
+    });
+    /**
+     * Starting state depends on whether the fragment can be observed *right now*.
+     *
+     * `armDeadline()` alone is not enough, and the gap is easy to miss: it declines to arm while
+     * hidden but transitions nothing, so a fragment that mounts into an already-hidden tab sits in
+     * `connecting` indefinitely — indistinguishable, to a host, from one that never booted. Only the
+     * `visibilitychange` handler below said `unobservable`, and a tab that was hidden before the
+     * fragment existed never fires one.
+     *
+     * This is exactly the case a test that toggles visibility cannot reach, because toggling starts
+     * from visible. It took a real browser — a backgrounded tab — to surface it.
+     */
+    const begin = () => {
+        if (visibility.isHidden())
+            transition('unobservable');
+        else
+            armDeadline();
+    };
+    if (options.armAfter) {
+        // Settled either way: a mount that failed still stops this from arming, because the slot tears
+        // the instance down and the abort below runs.
+        void options.armAfter.then(begin, begin);
+    }
+    else {
+        begin();
+    }
+    const stop = () => {
+        if (stopped)
+            return;
+        stopped = true;
+        clearDeadline();
+        clearGone();
+        detachVisibility();
+    };
+    signal.addEventListener('abort', stop, { once: true });
+    return {
+        get state() {
+            return state;
+        },
+        stop,
+    };
+}
+/** Fragment side: beats while it can be observed, and stays quiet while it cannot. */
+export function startFragmentBeats(options) {
+    const { channel, scheduler, signal } = options;
+    const beatIntervalMs = options.beatIntervalMs ?? BEAT_INTERVAL_MS;
+    const visibility = options.visibility ?? documentVisibility();
+    const beat = () => {
+        // Suppressed rather than merely ignored by the host: a hidden tab's throttled beats would
+        // arrive at unpredictable intervals, and a host that had to distinguish "throttled" from
+        // "dying" from timing alone would guess wrong in both directions.
+        if (visibility.isHidden())
+            return;
+        channel.send(BEAT);
+    };
+    const timer = scheduler.setInterval(beat, beatIntervalMs);
+    /**
+     * An opening beat as well as the interval, so `connecting → healthy` costs one message rather
+     * than one interval — a fragment that appears unwell for its first two seconds reads as a slow
+     * fragment, and that impression is very hard to undo.
+     *
+     * Scheduled on the realm rather than called directly, even though calling it would be simpler and
+     * would look identical in every passing test. A beat sent from host code is not evidence about
+     * the realm, and one exception to that rule is all it takes for a realm that wedged during mount
+     * to report `healthy` on the strength of a beat it never produced.
+     */
+    scheduler.setTimeout(beat, 0);
+    const detachVisibility = visibility.onChange(() => {
+        if (!visibility.isHidden())
+            scheduler.setTimeout(beat, 0);
+    });
+    const stop = () => {
+        scheduler.clearInterval(timer);
+        detachVisibility();
+    };
+    signal.addEventListener('abort', stop, { once: true });
+    return stop;
+}
+//# sourceMappingURL=liveness.js.map

package/src/weave/liveness.js.map

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

package/src/weave/messages.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Message types that are not the handshake and not context.
+ *
+ * Both of these crossed the boundary before Weave existed, and both crossed it *unevenly*: the
+ * context bus cloned, while props and events handed live host-realm objects to fragment code. That
+ * asymmetry was invisible on the trusted tier and is unshippable on the untrusted one, so both are
+ * corrected here rather than carried forward.
+ */
+/** Host → fragment. A complete props snapshot, cloned. Never a patch — see below. */
+export declare const PROPS_CHANGED = "props/changed";
+/** Fragment → host. Surfaced on the slot element as `braid:event`. */
+export declare const FRAGMENT_EVENT = "frag/event";
+export interface PropsChangedPayload {
+    /**
+     * The whole props object, every time.
+     *
+     * A diff would be smaller and would also require both ends to agree on how to apply one — which
+     * is a second protocol, with its own skew problem, protecting a payload that is a handful of
+     * fields on every real page. Sending the whole thing keeps "what does this fragment think its
+     * props are" answerable by looking at one message.
+     */
+    props: Record<string, unknown>;
+}
+export interface FragmentEventPayload {
+    type: string;
+    detail?: unknown;
+}

package/src/weave/messages.js

@@ -0,0 +1,13 @@
+/**
+ * Message types that are not the handshake and not context.
+ *
+ * Both of these crossed the boundary before Weave existed, and both crossed it *unevenly*: the
+ * context bus cloned, while props and events handed live host-realm objects to fragment code. That
+ * asymmetry was invisible on the trusted tier and is unshippable on the untrusted one, so both are
+ * corrected here rather than carried forward.
+ */
+/** Host → fragment. A complete props snapshot, cloned. Never a patch — see below. */
+export const PROPS_CHANGED = 'props/changed';
+/** Fragment → host. Surfaced on the slot element as `braid:event`. */
+export const FRAGMENT_EVENT = 'frag/event';
+//# sourceMappingURL=messages.js.map

package/src/weave/messages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.js","sourceRoot":"","sources":["../../../../../libs/core/src/weave/messages.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,qFAAqF;AACrF,MAAM,CAAC,MAAM,aAAa,GAAG,eAAe,CAAC;AAE7C,sEAAsE;AACtE,MAAM,CAAC,MAAM,cAAc,GAAG,YAAY,CAAC"}

package/src/weave/port-backing.d.ts

@@ -0,0 +1,19 @@
+import { ChannelBacking } from './channel.js';
+/**
+ * The cross-origin transport: one `MessagePort`, structured clone, nothing else.
+ *
+ * Nothing here is used by the trusted tier — it exists now, and is tested now, so that Phase 5 is
+ * the act of *choosing* this backing rather than the act of inventing it. A transport written after
+ * the protocol has shipped is a transport that inherits every same-origin assumption the protocol
+ * accumulated in the meantime.
+ *
+ * Two rules this backing enforces that the same-realm one gets for free:
+ *
+ * 1. **Everything inbound is untrusted.** A port is reachable by whatever holds the other end.
+ *    Malformed messages are dropped silently — an untrusted peer must not be able to fill the
+ *    host's console by posting garbage in a loop.
+ * 2. **Nothing unclonable goes out.** `postMessage` throws `DataCloneError` on a function or a DOM
+ *    node, and the throw surfaces at the *sender*, far from whoever put the value in the payload.
+ *    Converting it here names the offending message type while that context still exists.
+ */
+export declare function createPortBacking(port: MessagePort): ChannelBacking;

package/src/weave/port-backing.js

@@ -0,0 +1,54 @@
+import { isEnvelope } from './envelope.js';
+/**
+ * The cross-origin transport: one `MessagePort`, structured clone, nothing else.
+ *
+ * Nothing here is used by the trusted tier — it exists now, and is tested now, so that Phase 5 is
+ * the act of *choosing* this backing rather than the act of inventing it. A transport written after
+ * the protocol has shipped is a transport that inherits every same-origin assumption the protocol
+ * accumulated in the meantime.
+ *
+ * Two rules this backing enforces that the same-realm one gets for free:
+ *
+ * 1. **Everything inbound is untrusted.** A port is reachable by whatever holds the other end.
+ *    Malformed messages are dropped silently — an untrusted peer must not be able to fill the
+ *    host's console by posting garbage in a loop.
+ * 2. **Nothing unclonable goes out.** `postMessage` throws `DataCloneError` on a function or a DOM
+ *    node, and the throw surfaces at the *sender*, far from whoever put the value in the payload.
+ *    Converting it here names the offending message type while that context still exists.
+ */
+export function createPortBacking(port) {
+    let closed = false;
+    return {
+        post(envelope) {
+            if (closed)
+                return;
+            try {
+                port.postMessage(envelope);
+            }
+            catch (error) {
+                throw new Error(`braid: a "${envelope.type}" payload could not cross the boundary — ` +
+                    `values sent to a cross-origin fragment must be structured-cloneable ` +
+                    `(no functions, DOM nodes, or class instances with methods)`, { cause: error });
+            }
+        },
+        receive(handler) {
+            const listener = (event) => {
+                if (closed)
+                    return;
+                if (!isEnvelope(event.data))
+                    return;
+                handler(event.data);
+            };
+            port.addEventListener('message', listener);
+            port.start();
+            return () => port.removeEventListener('message', listener);
+        },
+        close() {
+            if (closed)
+                return;
+            closed = true;
+            port.close();
+        },
+    };
+}
+//# sourceMappingURL=port-backing.js.map

package/src/weave/port-backing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"port-backing.js","sourceRoot":"","sources":["../../../../../libs/core/src/weave/port-backing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,UAAU,EAAE,MAAM,eAAe,CAAC;AAGrD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAiB;IACjD,IAAI,MAAM,GAAG,KAAK,CAAC;IAEnB,OAAO;QACL,IAAI,CAAC,QAAkB;YACrB,IAAI,MAAM;gBAAE,OAAO;YACnB,IAAI,CAAC;gBACH,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;YAC7B,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,IAAI,KAAK,CACb,aAAa,QAAQ,CAAC,IAAI,2CAA2C;oBACnE,sEAAsE;oBACtE,4DAA4D,EAC9D,EAAE,KAAK,EAAE,KAAK,EAAE,CACjB,CAAC;YACJ,CAAC;QACH,CAAC;QAED,OAAO,CAAC,OAAO;YACb,MAAM,QAAQ,GAAG,CAAC,KAAmB,EAAE,EAAE;gBACvC,IAAI,MAAM;oBAAE,OAAO;gBACnB,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC;oBAAE,OAAO;gBACpC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YACtB,CAAC,CAAC;YACF,IAAI,CAAC,gBAAgB,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;YAC3C,IAAI,CAAC,KAAK,EAAE,CAAC;YACb,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,mBAAmB,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;QAC7D,CAAC;QAED,KAAK;YACH,IAAI,MAAM;gBAAE,OAAO;YACnB,MAAM,GAAG,IAAI,CAAC;YACd,IAAI,CAAC,KAAK,EAAE,CAAC;QACf,CAAC;KACF,CAAC;AACJ,CAAC"}