@braidlabs/core 0.1.1 → 0.3.0

package/src/context/context-bus.js

@@ -1,8 +1,34 @@
 import { BraidError } from '../errors.js';
-const values = new Map();
-const subscriptions = new Map();
-const schemas = new Map();
-export const braidContext = {
+/**
+ * A context bus.
+ *
+ * State moved from module scope to instance fields so that a page can hold more than one — see
+ * `createContextBus`. Every method body below is unchanged by that move; the semantics that make
+ * this a bus rather than an event emitter are the versioning ones, and they are per-bus by nature.
+ */
+class ContextBus {
+    #values = new Map();
+    #subscriptions = new Map();
+    #schemas = new Map();
+    /**
+     * Firehose listeners: notified of *which* key changed, never of the value.
+     *
+     * This exists for the boundary router, which mirrors the whole bus into a fragment realm and
+     * therefore has to learn about keys that did not exist when it attached. It carries no value
+     * because every observer needs the value projected to a different version, so handing one out here
+     * would be handing out the wrong one.
+     */
+    #observers = new Set();
+    #notifyObservers(key) {
+        for (const observer of [...this.#observers]) {
+            try {
+                observer(key);
+            }
+            catch (error) {
+                console.error(`braid: a context observer threw for "${key}"`, error);
+            }
+        }
+    }
     /**
      * Declares the contract a context key carries.
      *
@@ -11,12 +37,17 @@ export const braidContext = {
      * real page.
      */
     register(key, schema) {
-        schemas.set(key, schema);
-    },
+        this.#schemas.set(key, schema);
+        // A schema registered after a value was published changes how that value projects, and a
+        // mirror holding the pre-registration shape would stay wrong until the next `set` — which for
+        // a slow-moving key like the signed-in user may be never.
+        if (this.#values.has(key))
+            this.#notifyObservers(key);
+    }
     /** The schema registered for a key, if any. */
     schemaFor(key) {
-        return schemas.get(key);
-    },
+        return this.#schemas.get(key);
+    }
     /**
      * Publishes a context value to every fragment (and host code) subscribed to the key.
      *
@@ -26,10 +57,10 @@ export const braidContext = {
      * 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) ?? [])]) {
+        this.#values.set(key, value);
+        for (const subscription of [...(this.#subscriptions.get(key) ?? [])]) {
             try {
-                subscription.listener(project(key, value, subscription.as));
+                subscription.listener(this.#project(key, value, subscription.as));
             }
             catch (error) {
                 // Reported rather than swallowed: a subscriber that never hears anything again is worth
@@ -37,23 +68,24 @@ export const braidContext = {
                 console.error(`braid: a "${key}" context subscriber threw; other subscribers were unaffected`, error);
             }
         }
-    },
+        this.#notifyObservers(key);
+    }
     get(key, options) {
-        const value = values.get(key);
+        const value = this.#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);
-    },
+        this.#assertReachable(key, options?.as, options?.fragmentId);
+        return this.#project(key, value, options?.as);
+    }
     subscribe(key, listener, options) {
-        assertReachable(key, options?.as, options?.fragmentId);
-        let keySubscriptions = subscriptions.get(key);
+        this.#assertReachable(key, options?.as, options?.fragmentId);
+        let keySubscriptions = this.#subscriptions.get(key);
         if (!keySubscriptions) {
             keySubscriptions = new Set();
-            subscriptions.set(key, keySubscriptions);
+            this.#subscriptions.set(key, keySubscriptions);
         }
         const subscription = {
             listener,
@@ -63,55 +95,109 @@ export const braidContext = {
         const unsubscribe = () => void keySubscriptions.delete(subscription);
         options?.signal?.addEventListener('abort', unsubscribe, { once: true });
         return unsubscribe;
-    },
+    }
+    /** Every key that currently holds a value. Used to seed a fragment's mirror at handshake. */
+    keys() {
+        return [...this.#values.keys()];
+    }
+    /**
+     * Observes *which* keys change, including keys that do not exist yet.
+     *
+     * `subscribe` cannot serve this: it binds to one key by name, so a mirror built from it would
+     * silently miss every key first published after the fragment mounted.
+     */
+    observe(listener) {
+        this.#observers.add(listener);
+        return () => void this.#observers.delete(listener);
+    }
+    /**
+     * Raises if `as` cannot be projected to from the published version.
+     *
+     * The check `subscribe` runs, exposed so it can be run *earlier* — at the boundary handshake,
+     * before a fragment has been handed any state. Decided from the declared chain rather than from
+     * a stored value, so a fragment that mounts before the first broadcast gets the same answer as
+     * one that mounts after it.
+     */
+    assertReachable(key, as, fragmentId) {
+        this.#assertReachable(key, as, fragmentId);
+    }
     /** Exposed for tests. */
     clear() {
-        values.clear();
-        subscriptions.clear();
-        schemas.clear();
-    },
-};
+        this.#values.clear();
+        this.#subscriptions.clear();
+        this.#schemas.clear();
+        this.#observers.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.
+     */
+    #project(key, value, as) {
+        const schema = this.#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.
+     */
+    #assertReachable(key, as, fragmentId) {
+        const schema = this.#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}`);
+        }
+    }
+}
 /**
- * Projects a published value to one subscriber's version.
+ * The page-level context bus: what `<fragment-slot>` routes to unless a fragment is scoped elsewhere.
  *
- * `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.
+ * Still a singleton, still the default, and every existing import of it behaves exactly as before.
+ * What changed is that it is now *an instance of something*, which is what makes a second bus
+ * possible at all.
  */
-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);
-}
+export const braidContext = new ContextBus();
 /**
- * Refuses a subscriber whose version cannot be reached from the publisher's.
+ * Creates a bus a fragment owns, rather than one it merely subscribes to.
+ *
+ * Keys published here never reach the page bus and are never visible to any other fragment — not
+ * their values, not their names, not the timing of their changes. Two uses, and they are the two
+ * readings the plan left open:
+ *
+ * - **A private namespace.** A fragment that wants durable, versioned, cross-realm state that is
+ *   nobody else's business gets it without inventing a second storage mechanism, and without the
+ *   host having to grant or withhold anything.
+ * - **A subtree bus**, once nested fragments exist: a parent fragment hands its own bus to the
+ *   fragments it composes, and they coordinate below the host's notice.
  *
- * 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.
+ * The first works today. The second needs nested fragments to be a first-class concept, which is a
+ * larger commitment and is not made here — but nothing about this signature has to change when it
+ * is, because the routing already addresses buses by `scope` rather than by position.
  */
-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}`);
-    }
+export function createContextBus() {
+    return new ContextBus();
 }
 //# sourceMappingURL=context-bus.js.map

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

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

@@ -1,4 +1,22 @@
-export type FragmentSlotState = 'idle' | 'loading' | 'ready' | 'error';
+import { BraidError } from '../errors.js';
+import { LivenessState } from '../weave/liveness.js';
+/**
+ * What the slot reports about its fragment.
+ *
+ * The original four are all still here and still mean what they meant — `ready` in particular is
+ * kept as the name for "mounted, first beat not yet observed", which the liveness machine calls
+ * `connecting`. Renaming it would have broken every host checking `slot.state === 'ready'` in
+ * exchange for a word.
+ *
+ * The new three are the ones `ready` used to have to cover on its own:
+ *
+ * - `healthy` — beating.
+ * - `unobservable` — the tab is hidden, so the host has stopped being able to tell. Not a fault.
+ * - `suspect` → `gone` — beats stopped while the fragment should have been running.
+ */
+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;
 /**
  * Finds server-rendered fragment content the gateway pierced into a slot.
  *
@@ -8,6 +26,28 @@ export type FragmentSlotState = 'idle' | 'loading' | 'ready' | 'error';
  * and replaces identical content — so it is worth a named helper and a test.
  */
 export declare function findPiercedContentRoot(shadowRoot: ShadowRoot | null): HTMLElement | 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 declare const SLOT_STYLES: string;
+/**
+ * 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 declare function ensureFallbackSlot(shadowRoot: ShadowRoot): void;
 /**
  * `<fragment-slot>` — the custom element a host renders to mount a fragment.
  *
@@ -30,6 +70,19 @@ export declare class FragmentSlot extends HTMLElement {
     static get observedAttributes(): string[];
     get state(): FragmentSlotState;
     get name(): string;
+    /**
+     * 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(): string | null;
     get props(): Record<string, unknown>;
     set props(value: Record<string, unknown>);
     attributeChangedCallback(attribute: string, oldValue: string | null, newValue: string | null): void;
@@ -37,3 +90,63 @@ export declare class FragmentSlot extends HTMLElement {
     disconnectedCallback(): void;
     reload(): Promise<void>;
 }
+/**
+ * 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 declare function fetchFragmentHtml(fragmentId: string, routeSrcUrl: URL, signal: AbortSignal): Promise<{
+    html: string;
+    isHtml: boolean;
+}>;
+/**
+ * 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 declare class FragmentRedirectError extends BraidError {
+    readonly target: string;
+    constructor(fragmentId: string, target: string, documentUrl: string);
+}
+/** How long a second redirect from the same fragment is treated as a loop rather than a new one. */
+export declare const REDIRECT_LOOP_WINDOW_MS = 30000;
+export interface RedirectDeps {
+    /** Navigates the top-level page. */
+    assign(url: string): void;
+    /** `sessionStorage`, as a thunk: merely reaching for it throws in some privacy modes. */
+    storage(): Pick<Storage, 'getItem' | 'setItem'>;
+    now(): number;
+    /** What a relative target is relative to. */
+    baseHref: string;
+    /**
+     * Fragments whose redirect this page is already following. Two slots for one fragment hear the
+     * same redirect in the same tick; the second is not a loop, it is the same navigation.
+     */
+    inFlight: Set<string>;
+}
+/**
+ * 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 declare function followFragmentRedirect(error: FragmentRedirectError, deps: RedirectDeps): BraidError | null;