@tinvar/react 0.0.0-stage → 0.4.1

package/src/deferred-boundary.js

@@ -0,0 +1,646 @@
+'use client';
+
+// The browser half of <Deferred>: a client component that renders the
+// fallback until its trigger fires, then the fragment, through Suspense.
+//
+// The boundary used to be a custom element the server emitted and an
+// imperative runtime found, attached and mounted into from outside React.
+// That made every lifecycle question the runtime's to answer by hand --
+// attaching on each navigation, tearing down on each page left, keeping a
+// boundary whose element React reused, telling a re-issued token from new
+// content -- and each answer had defects. As a component, React answers
+// them: a boundary mounts with its page, unmounts with it, and is kept
+// across re-renders like any other component.
+//
+// Turning the fragment's RSC stream into elements needs the app's own
+// client bundle -- the module instance that hydrated the page -- so this
+// module cannot import a decoder. The app supplies one through
+// <FragmentProvider>.
+
+import {
+  Component,
+  Suspense,
+  createContext,
+  createElement,
+  startTransition,
+  use,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  useSyncExternalStore,
+} from 'react';
+import { FragmentError, FragmentHandle, serverFailure, tokenIdentity } from './fragment-client.js';
+import { installTrigger } from './deferred-triggers.js';
+import { AT_REST as NOT_REVALIDATING, onRevalidation, revalidationState } from './deferred-revalidation.js';
+import { FragmentGroups } from './deferred-groups.js';
+import { revokeSession } from './router.js';
+import { reloadUnlessLoading } from './document-load.js';
+import { useOptionalRouter } from './link.js';
+import { subscribeLive } from './live.js';
+
+/** A revalidation's load has been asked for, and not started yet. */
+const AWAITED = Symbol('awaiting a revalidation load');
+
+/** Dispatched on a boundary's element to load it; see loadDeferred(). */
+export const LOAD_EVENT = 'tinvar:load';
+
+const FragmentContext = createContext(null);
+
+/** What useDeferred() answers outside any boundary: nothing is happening. */
+const AT_REST = Object.freeze({ fetching: false, reloading: false, rescued: null, retry: () => {} });
+
+const DeferredContext = createContext(AT_REST);
+
+/**
+ * The state of the <Deferred> boundary a client component is rendered in --
+ * its fallback, its content, or its `fetching` or `rescue` slot.
+ *
+ * A hook rather than a render prop. <Deferred> is a server component, and a
+ * function cannot cross from the server to the client tree, so a slot that
+ * needs to know what its boundary is doing asks for it here. It is the
+ * `{ fetching }` Inertia's <WhenVisible> hands its children.
+ *
+ *   fetching   a load is in flight, from the trigger until what it brought
+ *              is on screen: the first load, an `always` refetch, a retry.
+ *              The element carries `data-fetching` meanwhile.
+ *   reloading  the content on screen is about to be replaced: an action is
+ *              revalidating the page, or the boundary is fetching the fresh
+ *              content it brought back. Content dims by it; the boundary's
+ *              element carries `data-reloading` meanwhile, for styles that
+ *              would rather select on that.
+ *   rescued    `{ digest }` once the server's render threw and the boundary
+ *              shows its `rescue` slot; the digest is what the failure was
+ *              logged under, when the server said.
+ *   retry      loads the boundary again -- the way forward a rescue slot
+ *              offers.
+ *
+ * @returns {{
+ *   fetching: boolean,
+ *   reloading: boolean,
+ *   rescued: { digest: string | null } | null,
+ *   retry: () => void,
+ * }}
+ */
+export function useDeferred() {
+  return useContext(DeferredContext);
+}
+
+/**
+ * Gives every <Deferred> below it what it needs to load.
+ *
+ * `hardNavigate` is the full page load a 401 calls for, injectable as the
+ * router's is.
+ *
+ * @param {{
+ *   decode: (stream: ReadableStream<Uint8Array>) => Promise<unknown>,
+ *   fetch?: typeof fetch,
+ *   onError?: (error: unknown, element: Element) => void,
+ *   hardNavigate?: (url: string) => void,
+ *   children?: unknown,
+ * }} props
+ */
+export function FragmentProvider({ decode, fetch, onError, hardNavigate, children }) {
+  // The page's <Deferred group>s, kept for the provider's life: a request in
+  // flight belongs to the group, not to whichever render started it. The
+  // decoder is read when a group's request is made, as a boundary reads it.
+  const decoder = useRef(decode);
+  decoder.current = decode;
+
+  // The once-shared values the page holds, claimed by their holds as a
+  // navigation claims them, so a deferred component reading one is handed
+  // it as held (ADR 0074). Read from the router when each request is made:
+  // the page on screen, and its session, may have changed since.
+  const router = useOptionalRouter();
+  const routed = useRef(router);
+  routed.current = router;
+  const claims = useRef(() => {
+    const current = /** @type {{ sharedClaims?: () => Record<string, string> } | null} */ (routed.current);
+    return typeof current?.sharedClaims === 'function' ? current.sharedClaims() : {};
+  }).current;
+
+  const [groups] = useState(() => new FragmentGroups(() => decoder.current, claims));
+
+  const value = useMemo(
+    () => ({ decode, fetch, onError, hardNavigate, groups, claims }),
+    [decode, fetch, onError, hardNavigate, groups, claims],
+  );
+  return createElement(FragmentContext.Provider, { value }, children);
+}
+
+/**
+ * Loads a `load="manual"` boundary -- or any boundary, early.
+ *
+ * @param {string | Element} target the boundary's `id`, or its element
+ */
+export function loadDeferred(target) {
+  const element = typeof target === 'string' ? globalThis.document?.getElementById(target) : target;
+  element?.dispatchEvent(new CustomEvent(LOAD_EVENT));
+}
+
+/**
+ * `rescue` is what the boundary shows once the server's render of its
+ * fragment throws -- "the client boundary renders its `rescue` slot instead
+ * of failing the page" (tinvar-spec.md, "Rescue and reloading"). Without
+ * one, such a boundary keeps its fallback and retries, as any failed load
+ * does. With one, it stops: the server has answered and reported it, and
+ * running a render that throws again on a timer only logs it again. The
+ * slot's own way forward is useDeferred().retry.
+ *
+ * `fetching` is shown beside the content while the boundary fetches it
+ * again -- an `always` refetch, a revalidation -- since the content stays up
+ * meanwhile and the fallback is for a boundary with nothing to show yet.
+ *
+ * Boundaries sharing a `group` load together: whichever is triggered first
+ * loads every one that has something to load, in one request (ADR 0018).
+ *
+ * @param {{
+ *   token: string,
+ *   load?: 'visible' | 'idle' | 'interaction' | 'manual',
+ *   buffer?: number,
+ *   always?: boolean,
+ *   group?: string,
+ *   id?: string,
+ *   fallback?: unknown,
+ *   fetching?: unknown,
+ *   rescue?: unknown,
+ * }} props
+ */
+export function DeferredBoundary({
+  token,
+  load = 'visible',
+  buffer,
+  always = false,
+  group,
+  id,
+  fallback = null,
+  fetching: refreshing = null,
+  rescue,
+}) {
+  const context = useContext(FragmentContext);
+  const host = useRef(null);
+
+  // The provider's callbacks, read when they are needed rather than
+  // subscribed to: an app passing an inline onError or fetch re-ran the
+  // effect on every render, aborting the load in flight and refetching.
+  const provided = useRef(context);
+  provided.current = context;
+
+  // What the token is FOR, without when it was issued. Every render mints a
+  // fresh token, so a poll or a reload hands a kept boundary a new one for
+  // the same content: that keeps the handle -- its backoff, its rotation --
+  // and what is on screen. Different claims are a different boundary.
+  //
+  // In a ref, not a memo: React may discard a memo, and this one owns state
+  // -- the backoff, the rotated token, whether the content has loaded.
+  const identity = tokenIdentity(token);
+  const entry = useRef(null);
+  if (entry.current === null || entry.current.identity !== identity) {
+    entry.current = {
+      identity,
+      handle: new FragmentHandle(token, context?.fetch),
+      loaded: false,
+      pending: null,
+      last: null,
+      // The revalidation this boundary has caught up with, and the load it
+      // started to catch up -- reloading until that load is on screen.
+      revalidated: revalidationState().generation,
+      // The quiet refresh this boundary has answered: see refreshDeferred().
+      refreshed: revalidationState().quiet,
+      // The next repeat load is a quiet refresh: not a refetch to read
+      // reloading for. Set by the refresh, cleared by the load it asks for.
+      quiet: false,
+      refetch: null,
+      // Showing its rescue slot: a group request another boundary starts
+      // leaves it be, since only its own slot's retry asks again.
+      rescued: false,
+    };
+  }
+
+  // Server renders read AT_REST: nothing is revalidated before hydration.
+  const revalidation = useSyncExternalStore(onRevalidation, revalidationState, () => NOT_REVALIDATING);
+
+  // Starts a load past the "loaded once" rule, for a revalidation; set by
+  // the effect that owns the trigger, which owns the request's lifetime.
+  const refresh = useRef(null);
+
+  /** @type {[{ identity: string | null, result: Promise<{ node?: unknown }> } | null, Function]} */
+  const [shown, setShown] = useState(null);
+
+  // The load in flight, set as it starts -- urgently, where `shown` is set
+  // in a transition -- so the boundary says it is fetching at once, and
+  // stops saying so when that same load has settled and is the one on
+  // screen.
+  /** @type {[{ identity: string | null, result: Promise<unknown>, settled: boolean } | null, Function]} */
+  const [started, setStarted] = useState(null);
+
+  // Bumped after a failure to install the trigger again: `visible` and
+  // `interaction` fire once and tear down, so without it a failed boundary
+  // never retried.
+  const [armed, setArmed] = useState(0);
+
+  // Set once the server's render threw and the `rescue` slot is up; what
+  // useDeferred() hands that slot.
+  const [rescued, setRescued] = useState(null);
+
+  // The live token the content on screen came with: what its render read,
+  // which the live module listens for changes to (see the effect below).
+  const [live, setLive] = useState(null);
+
+  // Read by the load when it fails, not subscribed to, as the provider's
+  // callbacks are: a slot given or taken away must not abort a load.
+  const rescuable = useRef(false);
+  rescuable.current = rescue !== undefined;
+
+  useEffect(() => {
+    const { handle } = entry.current;
+    if (handle.token === token) return;
+
+    const gaveUp = handle.terminal;
+    handle.adopt(token);
+
+    // A handle that had given up is not re-armed after its last failure, so
+    // its trigger was gone: the fresh token adopt() clears the way for was
+    // never sent, and the boundary stayed on its fallback until a reload.
+    if (gaveUp) setArmed((n) => n + 1);
+  }, [token]);
+
+  const hasProvider = context !== null;
+  const groups = group ? (context?.groups ?? null) : null;
+
+  // What the trigger's effect knows how to do, for the group to call: it
+  // owns the load's lifetime, the group decides when it runs.
+  const loader = useRef(null);
+
+  // Joined before the trigger is installed, so a trigger that fires as it
+  // is installed already has a group to ask.
+  const member = useRef(null);
+  useEffect(() => {
+    if (groups === null) return undefined;
+    const joined = {
+      get handle() {
+        return entry.current.handle;
+      },
+      ready: (again, asked) => loader.current?.ready(again, asked) ?? false,
+      start: (again, loading) => void loader.current?.begin(again, loading),
+      skip: (again) => {
+        if (!again) return;
+        // Behind a load in flight, a revalidation waits for it rather than
+        // being dropped: see the catch-up below.
+        if (entry.current.refetch === AWAITED && entry.current.pending === null) entry.current.refetch = null;
+        // A quiet refresh its group did not start is spent all the same, or
+        // the next revalidation's load would be taken for a quiet one.
+        entry.current.quiet = false;
+      },
+    };
+    member.current = joined;
+    const leave = groups.join(group, joined);
+    return () => {
+      member.current = null;
+      leave();
+    };
+  }, [groups, group, identity]);
+
+  useEffect(() => {
+    const element = host.current;
+    const boundary = entry.current;
+    if (!element) return undefined;
+
+    if (!hasProvider) {
+      console.error('[tinvar:client] A <Deferred> boundary needs a <FragmentProvider> above it to load.');
+      return undefined;
+    }
+
+    const aborter = new AbortController();
+
+    /**
+     * @param {boolean} again load even what has loaded, for a revalidation
+     * @param {boolean} [asked] triggered itself, rather than by its group
+     */
+    const ready = (again, asked = true) => {
+      // One load at a time. The handle shares its request, so a second
+      // trigger while one is in flight decoded the SAME stream again --
+      // "ReadableStream is locked" -- and the boundary fell back.
+      if (boundary.pending || boundary.handle.terminal) return false;
+      if (boundary.rescued && !asked) return false;
+
+      // `always` boundaries refetch on each trigger; the rest load once.
+      return !boundary.loaded || always || again;
+    };
+
+    /**
+     * @param {boolean} again
+     * @param {Promise<unknown>} [loading] its share of a group's request
+     */
+    const begin = (again, loading) => {
+      const quiet = again && boundary.quiet;
+      if (again) boundary.quiet = false;
+      if (!ready(again)) {
+        // A load in flight was asked for before the revalidation, and may
+        // bring back what the page held before the action -- so the
+        // revalidation stays awaited, and is started once that load settles.
+        // Dropping it left the pre-action content up for good.
+        if (again && boundary.refetch === AWAITED && boundary.pending === null) boundary.refetch = null;
+        return null;
+      }
+
+      const { decode, onError, hardNavigate, claims } = provided.current ?? {};
+
+      // Decoded by the handle, so a stream that cannot be decoded counts
+      // against its backoff and limit like any other failed load.
+      const result = (
+        loading ?? boundary.handle.load({ signal: aborter.signal, decode, headers: claims?.() ?? {} })
+      )
+        .then(
+          (node) => {
+            boundary.loaded = true;
+            boundary.last = { node };
+            boundary.rescued = false;
+            setRescued(null);
+            setLive(boundary.handle.liveToken);
+            return boundary.last;
+          },
+          (error) => {
+            // Unmounted -- the page moved on -- is not a failure.
+            if (aborter.signal.aborted) return boundary.last ?? {};
+
+            // The session is gone, and "session revocation, which the server
+            // signals with a 401", is cleared "with a full page load"
+            // (tinvar-spec.md, "Client-held data"). Reported as one more
+            // failed boundary, it left the protected page on screen. Before
+            // onError, so nothing the app's handler does can stop it.
+            if (error instanceof FragmentError && error.status === 401) {
+              // Wiped first: the reload alone left remembered drafts in the
+              // tab's storage for the next page to read back.
+              revokeSession();
+              // Loaded again -- unless a document load has begun: an action
+              // that ended the session sent the browser on, and this
+              // boundary fetched meanwhile. It is left to arrive
+              // (document-load.js).
+              reloadUnlessLoading(hardNavigate ?? ((u) => globalThis.location.assign(u)));
+            }
+
+            // A failed boundary must not take the page with it. It reports,
+            // keeps what it last showed -- an `always` refetch that fails
+            // leaves the loaded content up -- and is armed to try again
+            // unless the handle has given up. The handle's backoff paces it.
+            onError?.(error, element);
+
+            // The server's render threw, and there is nothing loaded to keep
+            // up: the rescue slot, and no retry on a timer -- see above.
+            const failure = rescuable.current && boundary.last === null ? serverFailure(error) : null;
+            if (failure !== null) {
+              boundary.rescued = true;
+              setRescued(failure);
+              return { rescued: failure };
+            }
+
+            if (!boundary.handle.terminal) setArmed((n) => n + 1);
+            return boundary.last ?? {};
+          },
+        )
+        .finally(() => {
+          if (boundary.pending === result) boundary.pending = null;
+          setStarted((load) => (load?.result === result ? { ...load, settled: true } : load));
+        });
+
+      boundary.pending = result;
+      // An awaited revalidation is answered by whichever load starts next,
+      // quiet or not: it was asked for after the action, so what it brings
+      // back is fresh. A quiet refresh and a revalidation gathered into one
+      // group request start a single load; taken for the quiet one, it left
+      // the revalidation awaited, and the boundary reloading until yet
+      // another load caught it up.
+      if (boundary.refetch === AWAITED || (again && !quiet)) boundary.refetch = result;
+      setStarted({ identity: boundary.identity, result, settled: false });
+
+      // A transition, so an `always` refetch keeps the current content on
+      // screen until the new content is ready, instead of flashing back to
+      // the fallback.
+      startTransition(() => setShown({ identity: boundary.identity, result }));
+      return result;
+    };
+
+    loader.current = { ready, begin };
+
+    // A member of a group asks its group, which loads every member that is
+    // ready, this one included; otherwise it loads on its own.
+    /** @param {boolean} again */
+    const ask = (again) => {
+      if (groups !== null && member.current !== null) groups.request(group, member.current, again);
+      else void begin(again);
+    };
+    const fire = () => ask(false);
+    refresh.current = () => ask(true);
+
+    const teardown = installTrigger(load, element, fire, { buffer, always });
+    element.addEventListener(LOAD_EVENT, fire);
+
+    return () => {
+      teardown();
+      element.removeEventListener(LOAD_EVENT, fire);
+      aborter.abort();
+      refresh.current = null;
+      loader.current = null;
+      // Abandoned, not pending: Strict Mode's remount -- or the effect
+      // re-running -- must be able to start its own.
+      boundary.pending = null;
+    };
+  }, [identity, load, buffer, always, armed, hasProvider, groups, group]);
+
+  // An action revalidated the page: what this boundary shows may be out of
+  // date, and the re-rendered page handed it a re-issued token for the same
+  // content, which it keeps -- so nothing else would fetch it again. One
+  // still on its fallback has nothing stale, and loads fresh on its own --
+  // unless its first load is already in flight, asked for before the action
+  // and as stale as any other.
+  useEffect(() => {
+    const boundary = entry.current;
+    if (boundary.revalidated === revalidation.generation) return;
+    boundary.revalidated = revalidation.generation;
+    if (refresh.current === null) return;
+    if (boundary.last === null && boundary.pending === null) return;
+
+    // Asked for, not yet started -- a group starts it on its next task --
+    // and reloading meanwhile; begin() replaces this with the load, leaves
+    // it behind a load already in flight, or clears it if it cannot start
+    // one.
+    boundary.refetch = AWAITED;
+    refresh.current();
+  }, [revalidation.generation]);
+
+  // A poll asked loaded boundaries to fetch again, quietly: the same load a
+  // revalidation starts, without `refetch` set, so nothing reads reloading
+  // and nothing dims -- the content is swapped when the new one is ready.
+  useEffect(() => {
+    const boundary = entry.current;
+    if (boundary.refreshed === revalidation.quiet) return;
+    boundary.refreshed = revalidation.quiet;
+    if (boundary.last === null || refresh.current === null) return;
+    boundary.quiet = true;
+    refresh.current();
+  }, [revalidation.quiet]);
+
+  // Something the content on screen read has changed, the server says --
+  // written in another tab, or by someone else (live.js). Fetched again as a
+  // poll's refresh is: quietly, nothing marked reloading, the content
+  // swapped once the new is ready, and paced by the handle's backoff. Each
+  // load brings the token for what it read, so the subscription follows it.
+  useEffect(() => {
+    if (live === null) return undefined;
+    return subscribeLive(live, () => {
+      const boundary = entry.current;
+      if (boundary.last === null || refresh.current === null) return;
+      boundary.quiet = true;
+      refresh.current();
+    });
+  }, [live]);
+
+  // A revalidation still awaited with nothing in flight: the load it waited
+  // behind has settled, so it starts now. After every commit, not in that
+  // load's own callbacks: a failed load re-arms the trigger, and a load
+  // started before that re-run would be aborted by it.
+  useEffect(() => {
+    const boundary = entry.current;
+    if (boundary.refetch !== AWAITED || boundary.pending !== null) return;
+    // A first load that failed: nothing stale is up, and its own trigger or
+    // retry loads fresh.
+    if (boundary.last === null) boundary.refetch = null;
+    else refresh.current?.();
+  });
+
+  const current = shown !== null && shown.identity === identity ? shown.result : null;
+
+  // Reloading from the moment an action starts revalidating the page until
+  // the content it brought back is on screen: while the action runs, in the
+  // render that learns it has settled (before the effect above has started
+  // the load), and while that load is in flight. Read from the COMMITTED
+  // result -- a transition keeps the old one until the new content renders,
+  // so the stale content stays marked for exactly as long as it is up.
+  const boundary = entry.current;
+  const reloading =
+    boundary.last !== null &&
+    (revalidation.active ||
+      revalidation.generation !== boundary.revalidated ||
+      (boundary.refetch !== null && current !== boundary.refetch));
+
+  // Done with once it is on screen, so a later `always` refetch is not
+  // mistaken for it.
+  useEffect(() => {
+    if (boundary.refetch !== null && current === boundary.refetch) boundary.refetch = null;
+  });
+
+  // From the trigger until what the load brought is on screen. Both halves
+  // are needed: a first load's transition commits at once, with Suspense's
+  // fallback up, so being committed is not being shown; and a refetch's
+  // settles before its transition commits the new content, so being settled
+  // is not either.
+  const fetching =
+    started !== null && started.identity === identity && (!started.settled || current !== started.result);
+
+  // A fragment that decoded but throws as it renders -- an error row below
+  // its root -- has nothing worth keeping: it is not loaded, so a retry or
+  // a trigger fetches it again.
+  const caught = (error) => {
+    provided.current?.onError?.(error, host.current);
+    const failure = rescuable.current ? serverFailure(error) : null;
+    if (failure === null) return;
+    entry.current.loaded = false;
+    entry.current.last = null;
+    entry.current.rescued = true;
+    setRescued(failure);
+  };
+
+  const state = useMemo(
+    () => ({
+      fetching,
+      reloading,
+      rescued,
+      retry: () => {
+        // Its own ask, which is what a rescued boundary waits for.
+        entry.current.rescued = false;
+        host.current?.dispatchEvent(new CustomEvent(LOAD_EVENT));
+      },
+    }),
+    [fetching, reloading, rescued],
+  );
+
+  return createElement(
+    'tinvar-deferred',
+    {
+      ref: host,
+      id,
+      'data-load': load,
+      'data-fetching': fetching ? '' : undefined,
+      'data-rescued': rescued === null ? undefined : '',
+      // The style hook, and what assistive technology is told: this region
+      // is being replaced, so wait for it rather than read it out now.
+      'data-reloading': reloading ? '' : undefined,
+      'aria-busy': reloading ? 'true' : undefined,
+    },
+    createElement(
+      DeferredContext.Provider,
+      { value: state },
+      current === null
+        ? fallback
+        : createElement(
+            Contained,
+            { result: current, fallback, rescue, onError: caught },
+            createElement(
+              Suspense,
+              { fallback },
+              createElement(Resolved, { result: current, fallback, rescue }),
+            ),
+          ),
+      // Only beside content: with nothing loaded yet, the fallback is what
+      // says a load is under way.
+      fetching && boundary.last !== null ? refreshing : null,
+    ),
+  );
+}
+
+/**
+ * Keeps a fragment's failure to the fragment.
+ *
+ * Promise rejections were already caught, but the decoded tree throws while
+ * React RENDERS it -- a component in the fragment that throws, an error row
+ * in the stream -- and that went to the nearest error boundary above, which
+ * is usually the page's. One failed boundary took the page with it.
+ *
+ * An error row is the server's render throwing, so it shows the boundary's
+ * `rescue` slot where there is one, and its fallback otherwise.
+ */
+class Contained extends Component {
+  constructor(props) {
+    super(props);
+    this.state = { failed: false, rescued: false, result: props.result };
+  }
+
+  // A new load gets a fresh chance: a refetch that renders after one that
+  // failed shows its content again. Reset here rather than by remounting,
+  // which would drop back to the fallback and lose the transition that
+  // keeps the old content up while the new loads.
+  static getDerivedStateFromProps(props, state) {
+    return props.result === state.result ? null : { failed: false, rescued: false, result: props.result };
+  }
+
+  static getDerivedStateFromError(error) {
+    return { failed: true, rescued: serverFailure(error) !== null };
+  }
+
+  componentDidCatch(error) {
+    this.props.onError(error);
+  }
+
+  render() {
+    if (!this.state.failed) return this.props.children;
+    return this.state.rescued && this.props.rescue !== undefined ? this.props.rescue : this.props.fallback;
+  }
+}
+
+function Resolved({ result, fallback, rescue }) {
+  const outcome = use(result);
+  if ('node' in outcome) return outcome.node;
+  return outcome.rescued && rescue !== undefined ? rescue : fallback;
+}

package/src/deferred-groups.d.ts

@@ -0,0 +1,24 @@
+/** The boundaries of one <Deferred group>, fetched together. See ADR 0018. */
+
+import type { FragmentHandle } from './fragment-client';
+
+/** FragmentEndpoint::MAX_GROUP: a longer group is sent in requests of at most this many. */
+export declare const MAX_GROUP: 16;
+
+export interface GroupMember {
+  handle: FragmentHandle;
+  /** Whether it would load now; `asked` says whether it was triggered itself. */
+  ready(again: boolean, asked: boolean): boolean;
+  /** Runs its load: its share of the group's request, or its own when it is the only one ready. */
+  start(again: boolean, load?: Promise<unknown>): void;
+  /** It asked and was not ready. */
+  skip(again: boolean): void;
+}
+
+export declare class FragmentGroups {
+  constructor(decode: () => ((stream: ReadableStream<Uint8Array>) => unknown) | undefined);
+  join(name: string, member: GroupMember): () => void;
+  /** How many groups have members: one that has none is forgotten. */
+  readonly size: number;
+  request(name: string, member: GroupMember, again: boolean): void;
+}