@braidlabs/core 0.6.0 → 0.7.1

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

@@ -1,22 +1,15 @@
 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.
- */
+/** The `settle-timeout` attribute as a delay: the default when absent, empty or not a number. */
+export declare function settleTimeoutMs(attribute: string | null): number;
 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 +28,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,9 +58,14 @@ 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`.
+ *
+ * - `settle-timeout` — milliseconds after `ready` before the slot reports `settled` on its own, for a
+ *   fragment that never says it has (default 10000). See {@link FragmentSlot.settled}.
  *
  * Events: `braid:ready`, `braid:error` (detail includes stage + fix hint), `braid:event`
- * (fragment → host).
+ * (fragment → host), `braid:settled` (detail: `{ fragmentId, timedOut }`).
  *
  * The slot uses only its own shadow root and its own elements — the host page is never patched.
  */
@@ -70,6 +74,28 @@ export declare class FragmentSlot extends HTMLElement {
     static get observedAttributes(): string[];
     get state(): FragmentSlotState;
     get name(): string;
+    /**
+     * Whether the fragment's first content has settled, reflected as the `settled` attribute.
+     *
+     * Not a slot state, because it answers a different question. `healthy` says the fragment's realm
+     * is running, which is true from its first beat — while the application inside may still be
+     * showing its own spinner. `settled` says the fragment has finished its own initial loading,
+     * which only the fragment can know: it reports it (`env.settled()`, `provideBraidFragment()` in
+     * Angular), and a host keeps its skeleton up until then. Not through `slot="loading"`, which is
+     * the slot's own boot-time state and gives way at first paint, but as a sibling the host styles:
+     *
+     * ```html
+     * <fragment-slot name="contact"></fragment-slot><div class="skeleton" hidden></div>
+     * ```
+     * ```css
+     * fragment-slot:not([settled], [state="error"]) + .skeleton { display: block; }
+     * ```
+     *
+     * A fragment that never reports is settled anyway `settle-timeout` milliseconds after `ready`, with
+     * `timedOut: true` on the event, so a skeleton cannot stick forever. One that fails never settles —
+     * it has nothing to show — so a skeleton keyed on `settled` gives way to `[state="error"]`, as above.
+     */
+    get settled(): boolean;
     /**
      * The fragment's unsaved-work declaration, or null.
      *
@@ -90,6 +116,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.
  *