@mui/internal-docs-infra 0.11.1-canary.8 → 0.11.1

package/CoordinatedLazy/ChunkServerLoader.mjs

@@ -0,0 +1,97 @@
+import * as React from 'react';
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Server render path for a chunk: an async server component that produces the
+ * content on the server, to be rendered under a Suspense boundary so React
+ * streams the fallback until it resolves (per-chunk Suspense). It is a plain
+ * async render function (no Node-only imports), so it bundles harmlessly with
+ * the client surface - it just never runs there.
+ *
+ * With `initial`, it renders the server `InitialLoader` (the quick initial
+ * state). Otherwise it prefers the server `Loader` component (dynamically
+ * imported, never shipped to the client), falling back to a server-side
+ * `data`-mode `load`. When none applies it renders the loading placeholder (the
+ * client then takes over).
+ *
+ * Readiness/coordination is a client concern, so there is no gate here - the
+ * parent Suspense owns the fallback, and the streamed content hydrates into the
+ * client swap.
+ */
+export async function ChunkServerLoader(args) {
+  const {
+    config,
+    props = {},
+    initial = false
+  } = args;
+  const options = props.loaderOptions ?? config.loaderOptions;
+  const userProps = props.userProps ?? {};
+
+  // Server initial: render the InitialLoader's quick state (still `loading`, as
+  // the full data is not in yet - a client source can upgrade it afterwards).
+  if (initial && config.InitialLoader) {
+    const loaded = await config.InitialLoader();
+    const Loaded = loaded.default;
+    const loadingProps = {
+      ...userProps,
+      data: props.preloaded,
+      loading: true
+    };
+    return /*#__PURE__*/_jsx(Loaded, {
+      ...loadingProps
+    });
+  }
+
+  // Server initial from a `data`-mode source: compute the quick `initial()` value
+  // (synchronous, no await) on the server and render it into `ChunkContent` still
+  // marked `loading`. `source.initial()` must return serializable data, since
+  // `ChunkContent` may be a Client Component. `InitialLoader` above wins when both
+  // are present.
+  if (initial && config.source && config.source.mode === 'data' && config.source.initial) {
+    const data = config.source.initial(options);
+    const ChunkContent = config.ChunkContent;
+    const loadingProps = {
+      ...userProps,
+      data,
+      loading: true
+    };
+    return /*#__PURE__*/_jsx(ChunkContent, {
+      ...loadingProps
+    });
+  }
+  if (!initial && config.Loader) {
+    const loaded = await config.Loader();
+    const Loaded = loaded.default;
+    const contentProps = {
+      ...userProps,
+      data: props.preloaded,
+      loading: false
+    };
+    return /*#__PURE__*/_jsx(Loaded, {
+      ...contentProps
+    });
+  }
+  if (!initial && config.source && config.source.mode === 'data') {
+    const data = await config.source.load(options, new AbortController().signal);
+    const ChunkContent = config.ChunkContent;
+    const contentProps = {
+      ...userProps,
+      data,
+      loading: false
+    };
+    return /*#__PURE__*/_jsx(ChunkContent, {
+      ...contentProps
+    });
+  }
+  const ChunkLoading = config.ChunkLoading;
+  if (ChunkLoading) {
+    const loadingProps = {
+      ...userProps,
+      data: props.preloaded,
+      loading: true
+    };
+    return /*#__PURE__*/_jsx(ChunkLoading, {
+      ...loadingProps
+    });
+  }
+  return null;
+}

package/CoordinatedLazy/CoordinatedContentContext.d.mts

@@ -0,0 +1,15 @@
+import * as React from 'react';
+import type { CoordinatedContentContextValue } from "./types.mjs";
+/**
+ * Carries the data the fallback hoisted down into the full content. A
+ * `CoordinatedLazy` provides it around `content` after the swap; content reads
+ * it via {@link useCoordinatedContent}.
+ */
+export declare const CoordinatedContentContext: React.Context<CoordinatedContentContextValue>;
+/**
+ * Read the data the fallback hoisted, from inside the full content. Lets the
+ * content use what the fallback fetched (e.g. a decompression dictionary)
+ * without the consumer threading it through props. Returns an empty map when
+ * rendered outside a `CoordinatedLazy`.
+ */
+export declare function useCoordinatedContent(): Record<string, unknown>;

package/CoordinatedLazy/CoordinatedContentContext.mjs

@@ -0,0 +1,22 @@
+'use client';
+
+import * as React from 'react';
+/**
+ * Carries the data the fallback hoisted down into the full content. A
+ * `CoordinatedLazy` provides it around `content` after the swap; content reads
+ * it via {@link useCoordinatedContent}.
+ */
+export const CoordinatedContentContext = /*#__PURE__*/React.createContext({
+  hoisted: {}
+});
+
+/**
+ * Read the data the fallback hoisted, from inside the full content. Lets the
+ * content use what the fallback fetched (e.g. a decompression dictionary)
+ * without the consumer threading it through props. Returns an empty map when
+ * rendered outside a `CoordinatedLazy`.
+ */
+if (process.env.NODE_ENV !== "production") CoordinatedContentContext.displayName = "CoordinatedContentContext";
+export function useCoordinatedContent() {
+  return React.useContext(CoordinatedContentContext).hoisted;
+}

package/CoordinatedLazy/CoordinatedFallbackContext.d.mts

@@ -0,0 +1,11 @@
+import * as React from 'react';
+import type { CoordinatedFallbackContextValue } from "./types.mjs";
+/**
+ * Provided by a `CoordinatedLazy` to its fallback subtree while the fallback is
+ * shown. Carries the upward hoist channel and the nested-suppression flag.
+ *
+ * `undefined` outside a fallback subtree: a fallback reads it via
+ * `useCoordinatedFallback`, and a nested `CoordinatedLazy` detects its presence
+ * to know it is rendered inside an outer instance's still-loading fallback.
+ */
+export declare const CoordinatedFallbackContext: React.Context<CoordinatedFallbackContextValue | undefined>;

package/CoordinatedLazy/CoordinatedFallbackContext.mjs

@@ -0,0 +1,13 @@
+'use client';
+
+import * as React from 'react';
+/**
+ * Provided by a `CoordinatedLazy` to its fallback subtree while the fallback is
+ * shown. Carries the upward hoist channel and the nested-suppression flag.
+ *
+ * `undefined` outside a fallback subtree: a fallback reads it via
+ * `useCoordinatedFallback`, and a nested `CoordinatedLazy` detects its presence
+ * to know it is rendered inside an outer instance's still-loading fallback.
+ */
+export const CoordinatedFallbackContext = /*#__PURE__*/React.createContext(undefined);
+if (process.env.NODE_ENV !== "production") CoordinatedFallbackContext.displayName = "CoordinatedFallbackContext";

package/CoordinatedLazy/CoordinatedGateContext.d.mts

@@ -0,0 +1,14 @@
+import * as React from 'react';
+import type { SettleGate } from "../useCoordinated/createSettleGate.mjs";
+/**
+ * The ambient settle gate that a {@link CoordinatedLazy} swap registers with
+ * when it isn't given an explicit `gate` prop. A coordinator (e.g. the
+ * `useStream` controller) provides its gate here so every swap rendered beneath
+ * it reports into the same gate - that is how a group's `loading` reflects each
+ * piece's swap without threading a `gate` prop through every one. `null` outside
+ * any coordinator, in which case the swap registers only with the page-global
+ * gate.
+ */
+export declare const CoordinatedGateContext: React.Context<SettleGate | null>;
+/** Read the ambient settle gate, or `null` when there is no surrounding coordinator. */
+export declare function useCoordinatedGate(): SettleGate | null;

package/CoordinatedLazy/CoordinatedGateContext.mjs

@@ -0,0 +1,19 @@
+'use client';
+
+import * as React from 'react';
+/**
+ * The ambient settle gate that a {@link CoordinatedLazy} swap registers with
+ * when it isn't given an explicit `gate` prop. A coordinator (e.g. the
+ * `useStream` controller) provides its gate here so every swap rendered beneath
+ * it reports into the same gate - that is how a group's `loading` reflects each
+ * piece's swap without threading a `gate` prop through every one. `null` outside
+ * any coordinator, in which case the swap registers only with the page-global
+ * gate.
+ */
+export const CoordinatedGateContext = /*#__PURE__*/React.createContext(null);
+
+/** Read the ambient settle gate, or `null` when there is no surrounding coordinator. */
+if (process.env.NODE_ENV !== "production") CoordinatedGateContext.displayName = "CoordinatedGateContext";
+export function useCoordinatedGate() {
+  return React.useContext(CoordinatedGateContext);
+}

package/CoordinatedLazy/CoordinatedLazy.d.mts

@@ -0,0 +1,14 @@
+import * as React from 'react';
+import type { CoordinatedLazyProps } from "./types.mjs";
+/**
+ * Show `fallback` until `ready` (and the page-coordinated swap conditions) are
+ * met, then swap to `content`. The fallback is force-mounted once so its
+ * `useCoordinatedFallback` hoist runs even when the content is precomputed; the
+ * hoisted data is handed down to `content` via `useCoordinatedContent`.
+ *
+ * Generalizes the state-driven fallback<->content swap from
+ * `CodeHighlighterClient`. Advanced consumers that need to fold the hoisted data
+ * into their own `ready` computation should use {@link useCoordinatedSwap}
+ * directly instead of this component.
+ */
+export declare function CoordinatedLazy(props: CoordinatedLazyProps): React.ReactElement;

package/CoordinatedLazy/CoordinatedLazy.mjs

@@ -0,0 +1,86 @@
+'use client';
+
+import * as React from 'react';
+import { useCoordinatedSwap } from "./useCoordinatedSwap.mjs";
+import { CoordinatedFallbackContext } from "./CoordinatedFallbackContext.mjs";
+import { CoordinatedContentContext } from "./CoordinatedContentContext.mjs";
+
+/**
+ * Show `fallback` until `ready` (and the page-coordinated swap conditions) are
+ * met, then swap to `content`. The fallback is force-mounted once so its
+ * `useCoordinatedFallback` hoist runs even when the content is precomputed; the
+ * hoisted data is handed down to `content` via `useCoordinatedContent`.
+ *
+ * Generalizes the state-driven fallback<->content swap from
+ * `CodeHighlighterClient`. Advanced consumers that need to fold the hoisted data
+ * into their own `ready` computation should use {@link useCoordinatedSwap}
+ * directly instead of this component.
+ */
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+export function CoordinatedLazy(props) {
+  const {
+    content,
+    fallback,
+    ready,
+    defer,
+    holdGate,
+    skipFallback,
+    requireHoist,
+    awaitContent,
+    gate,
+    data,
+    preload
+  } = props;
+  const {
+    showFallback,
+    fallbackContext,
+    hoisted,
+    reportContentReady
+  } = useCoordinatedSwap({
+    ready,
+    defer,
+    holdGate,
+    hasFallback: fallback != null,
+    skipFallback,
+    requireHoist,
+    awaitContent,
+    gate,
+    data,
+    preload
+  });
+
+  // Forward `fallback` so a code-split `content` (e.g. `LazyContent`) can show
+  // the same placeholder via `useCoordinatedContent().fallback` while its
+  // dynamic import resolves - no empty flash on the content-side swap. In
+  // `awaitContent` mode the fallback is already rendered alongside the content,
+  // so the content must stay null while loading (no duplicate placeholder).
+  const contentContext = React.useMemo(() => ({
+    hoisted,
+    reportReady: reportContentReady,
+    fallback: awaitContent ? undefined : fallback
+  }), [hoisted, reportContentReady, fallback, awaitContent]);
+  const contentNode = /*#__PURE__*/_jsx(CoordinatedContentContext.Provider, {
+    value: contentContext,
+    children: content
+  });
+  const fallbackNode = showFallback ? /*#__PURE__*/_jsx(CoordinatedFallbackContext.Provider, {
+    value: fallbackContext,
+    children: fallback
+  }) : null;
+
+  // awaitContent: mount the content behind the fallback so a code-split content
+  // (e.g. `LazyContent`) loads in the background and reveals once it reports
+  // ready. The content returns `null` until then, so only the fallback shows.
+  if (awaitContent) {
+    return /*#__PURE__*/_jsxs(React.Fragment, {
+      children: [fallbackNode, contentNode]
+    });
+  }
+
+  // Default: show the fallback OR the content (the content only mounts once the
+  // swap commits to it).
+  return showFallback ? /*#__PURE__*/_jsx(CoordinatedFallbackContext.Provider, {
+    value: fallbackContext,
+    children: fallback
+  }) : contentNode;
+}

package/CoordinatedLazy/CoordinatedLazyClient.d.mts

@@ -0,0 +1,24 @@
+import * as React from 'react';
+import type { ChunkComponentProps, ClientChunkConfig } from "./types.mjs";
+/** Props for {@link CoordinatedLazyClient}. */
+export interface CoordinatedLazyClientProps<T extends {}, P, O> {
+  /**
+   * The chunk config with the server-only loader functions
+   * (`source`/`Loader`/`InitialLoader`) already stripped, so no function is ever
+   * serialized into this Client Component. Client loading comes from a
+   * {@link ChunkProvider} source in context (via {@link useChunk}).
+   */
+  config: ClientChunkConfig<T, P, O>;
+  props: ChunkComponentProps<T, P, O>;
+}
+/**
+ * The client-loading half of {@link createCoordinatedLazy}: loads the piece's
+ * data on the client via {@link useChunk}, shows `ChunkLoading` until it is
+ * ready, then swaps to `ChunkContent` through {@link CoordinatedLazy}. The
+ * isomorphic router renders this only for the client-driven render modes, so the
+ * content/loading components here are always client components.
+ */
+export declare function CoordinatedLazyClient<T extends {}, P, O>({
+  config,
+  props
+}: CoordinatedLazyClientProps<T, P, O>): React.ReactElement;

package/CoordinatedLazy/CoordinatedLazyClient.mjs

@@ -0,0 +1,65 @@
+'use client';
+
+import * as React from 'react';
+import { useChunk } from "./useChunk.mjs";
+import { CoordinatedLazy } from "./CoordinatedLazy.mjs";
+import { jsx as _jsx } from "react/jsx-runtime";
+function RenderNull() {
+  return null;
+}
+
+/** Props for {@link CoordinatedLazyClient}. */
+
+/**
+ * The client-loading half of {@link createCoordinatedLazy}: loads the piece's
+ * data on the client via {@link useChunk}, shows `ChunkLoading` until it is
+ * ready, then swaps to `ChunkContent` through {@link CoordinatedLazy}. The
+ * isomorphic router renders this only for the client-driven render modes, so the
+ * content/loading components here are always client components.
+ */
+export function CoordinatedLazyClient({
+  config,
+  props
+}) {
+  const ChunkContent = config.ChunkContent;
+  const ChunkLoading = config.ChunkLoading ?? RenderNull;
+  const {
+    data,
+    loading,
+    revalidating,
+    refresh
+  } = useChunk(config, props);
+  const userProps = props.userProps ?? {};
+
+  // Spreading the generic `T` alongside the fixed fields needs an assertion; the
+  // shape matches `ChunkContentProps<T, P>` / `ChunkLoadingProps<T, P>`. The
+  // content also receives `refresh`/`revalidating` so it can trigger a
+  // stale-while-revalidate reload.
+  const contentProps = {
+    ...userProps,
+    data,
+    loading: false,
+    refresh,
+    revalidating
+  };
+  const loadingProps = {
+    ...userProps,
+    data,
+    loading: true
+  };
+
+  // `gate` is left to `CoordinatedLazy`: an explicit `props.gate` wins, otherwise
+  // it registers with the ambient controller gate (if any).
+  return /*#__PURE__*/_jsx(CoordinatedLazy, {
+    ready: !loading,
+    defer: config.swap?.defer,
+    requireHoist: config.swap?.requireHoist,
+    gate: props.gate,
+    content: /*#__PURE__*/_jsx(ChunkContent, {
+      ...contentProps
+    }),
+    fallback: /*#__PURE__*/_jsx(ChunkLoading, {
+      ...loadingProps
+    })
+  });
+}

package/CoordinatedLazy/LazyContent.d.mts

@@ -0,0 +1,26 @@
+import * as React from 'react';
+import type { LazyContentProps } from "./types.mjs";
+/**
+ * Lazily import a component and render it once its chunk has loaded, reporting
+ * readiness to the settle gate - so the page can coordinate the swap and a
+ * `StreamController` can reflect it in `loading`.
+ *
+ * The import runs in an effect (not `React.lazy` + Suspense) on purpose: the swap
+ * that reveals this content mounts/unmounts the subtree around a pending `import()`,
+ * and a Suspense boundary that comes and goes around a pending promise trips React's
+ * async-info-on-boundary tracking ("cleaning up async info that was not on the
+ * parent Suspense boundary"). Loading in an effect avoids a Suspense boundary
+ * entirely, and renders only the fallback during SSR (effects don't run there).
+ *
+ * The import factory is captured once (via lazy `useState`), so an inline
+ * `content={() => import('./X')}` doesn't restart the import every render. While
+ * the module loads, the explicit `fallback` (or, if none, the coordinating swap's
+ * fallback from {@link CoordinatedContentContext}) is shown - so the same
+ * placeholder keeps covering the load, with no empty flash.
+ */
+export declare function LazyContent<T extends {} = {}>({
+  content,
+  props,
+  fallback,
+  gate
+}: LazyContentProps<T>): React.ReactElement;

package/CoordinatedLazy/LazyContent.mjs

@@ -0,0 +1,80 @@
+'use client';
+
+import * as React from 'react';
+import { CoordinatedContentContext } from "./CoordinatedContentContext.mjs";
+import { useSettleGate } from "../useCoordinated/useSettleGate.mjs";
+import { pageSettleGate } from "../useCoordinated/pageSettleGate.mjs";
+
+/**
+ * Lazily import a component and render it once its chunk has loaded, reporting
+ * readiness to the settle gate - so the page can coordinate the swap and a
+ * `StreamController` can reflect it in `loading`.
+ *
+ * The import runs in an effect (not `React.lazy` + Suspense) on purpose: the swap
+ * that reveals this content mounts/unmounts the subtree around a pending `import()`,
+ * and a Suspense boundary that comes and goes around a pending promise trips React's
+ * async-info-on-boundary tracking ("cleaning up async info that was not on the
+ * parent Suspense boundary"). Loading in an effect avoids a Suspense boundary
+ * entirely, and renders only the fallback during SSR (effects don't run there).
+ *
+ * The import factory is captured once (via lazy `useState`), so an inline
+ * `content={() => import('./X')}` doesn't restart the import every render. While
+ * the module loads, the explicit `fallback` (or, if none, the coordinating swap's
+ * fallback from {@link CoordinatedContentContext}) is shown - so the same
+ * placeholder keeps covering the load, with no empty flash.
+ */
+import { jsx as _jsx } from "react/jsx-runtime";
+export function LazyContent({
+  content,
+  props,
+  fallback = null,
+  gate
+}) {
+  // Capture the import thunk once - consumers pass an inline thunk (new identity
+  // each render), and we must not restart the import on every render.
+  const [importContent] = React.useState(() => content);
+  const [Loaded, setLoaded] = React.useState(null);
+  const coordinated = React.useContext(CoordinatedContentContext);
+  const reportReady = coordinated.reportReady;
+  React.useEffect(() => {
+    let active = true;
+    importContent().then(mod => {
+      if (active) {
+        // Function form: the stored value is itself a component (a function),
+        // so a bare `setLoaded(mod.default)` would be treated as an updater.
+        setLoaded(() => mod.default);
+      }
+    }).catch(() => {
+      // Leave the fallback in place on a failed import (network error, missing
+      // chunk); a parent error boundary can handle a hard failure if needed.
+    });
+    return () => {
+      active = false;
+    };
+  }, [importContent]);
+
+  // Signal the coordinating swap (and settle gate) that the content has loaded.
+  const loaded = Loaded !== null;
+  React.useEffect(() => {
+    if (loaded) {
+      reportReady?.();
+    }
+  }, [loaded, reportReady]);
+
+  // Pending until the module loads; report to the page-global gate and, when
+  // given, an additional controller gate.
+  useSettleGate(loaded, pageSettleGate);
+  useSettleGate(loaded, gate ?? null);
+  if (Loaded) {
+    const componentProps = props ?? {};
+    return /*#__PURE__*/_jsx(Loaded, {
+      ...componentProps
+    });
+  }
+
+  // While loading, show the explicit `fallback` prop if given, otherwise the
+  // coordinating swap's fallback (e.g. CodeHighlighter's `ContentLoading`).
+  return /*#__PURE__*/_jsx(React.Fragment, {
+    children: fallback ?? coordinated.fallback ?? null
+  });
+}

package/CoordinatedLazy/LazyContentServer.d.mts

@@ -0,0 +1,18 @@
+import * as React from 'react';
+import type { LazyContentProps } from "./types.mjs";
+/**
+ * Server variant of {@link LazyContent}: an async server component that awaits
+ * the dynamic import and renders the component. Render it under a Suspense
+ * boundary so React streams the `fallback` until the import resolves, then
+ * streams the resolved component in. It is a plain async render function (no
+ * Node-only imports), so it bundles harmlessly with the client surface - it
+ * just never runs there.
+ *
+ * Readiness is a client-side concern (the swap and gate live on the client), so
+ * there is no gate here - `fallback`/`gate` on the shared props are ignored by
+ * the server path (the parent Suspense owns the fallback).
+ */
+export declare function LazyContentServer<T extends {} = {}>({
+  content,
+  props
+}: LazyContentProps<T>): Promise<React.ReactElement>;

package/CoordinatedLazy/LazyContentServer.mjs

@@ -0,0 +1,25 @@
+import * as React from 'react';
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Server variant of {@link LazyContent}: an async server component that awaits
+ * the dynamic import and renders the component. Render it under a Suspense
+ * boundary so React streams the `fallback` until the import resolves, then
+ * streams the resolved component in. It is a plain async render function (no
+ * Node-only imports), so it bundles harmlessly with the client surface - it
+ * just never runs there.
+ *
+ * Readiness is a client-side concern (the swap and gate live on the client), so
+ * there is no gate here - `fallback`/`gate` on the shared props are ignored by
+ * the server path (the parent Suspense owns the fallback).
+ */
+export async function LazyContentServer({
+  content,
+  props
+}) {
+  const loaded = await content();
+  const Component = loaded.default;
+  const componentProps = props ?? {};
+  return /*#__PURE__*/_jsx(Component, {
+    ...componentProps
+  });
+}

package/CoordinatedLazy/buildChunkRenderInputs.d.mts

@@ -0,0 +1,8 @@
+import type { ChunkComponentProps, ChunkRenderInputs, CreateChunkConfig } from "./types.mjs";
+/**
+ * Evaluate a chunk's config + per-instance props into the already-resolved
+ * {@link ChunkRenderInputs} that `resolveChunkRender` consumes. Pure, so
+ * the same inputs drive the render decision identically on the server and the
+ * client's first render. Mirrors the `isLoaded` rule {@link useChunk} uses.
+ */
+export declare function buildChunkRenderInputs<T extends {}, P, O>(config: CreateChunkConfig<T, P, O>, props: ChunkComponentProps<T, P, O>): ChunkRenderInputs;

package/CoordinatedLazy/buildChunkRenderInputs.mjs

@@ -0,0 +1,35 @@
+/**
+ * Evaluate a chunk's config + per-instance props into the already-resolved
+ * {@link ChunkRenderInputs} that `resolveChunkRender` consumes. Pure, so
+ * the same inputs drive the render decision identically on the server and the
+ * client's first render. Mirrors the `isLoaded` rule {@link useChunk} uses.
+ */
+export function buildChunkRenderInputs(config, props) {
+  const {
+    preloaded,
+    controlled,
+    forceClient,
+    skipInitialLoad
+  } = props;
+  const isLoaded = Boolean(controlled) || (config.isLoaded ? config.isLoaded(preloaded) : preloaded !== undefined);
+  // A per-render `props.isInitial` override wins over the config predicate, for
+  // consumers whose initial-readiness depends on context they cannot express as
+  // a pure `config.isInitial(preloaded)`.
+  const isInitial = props.isInitial ?? (config.isInitial ? config.isInitial(preloaded) : false);
+
+  // A `data`-mode `source` is a SERVER loader (run by `ChunkServerLoader`), so it
+  // folds into the server flags alongside `Loader`/`InitialLoader` - it never
+  // drives a client mode. (`urls`/`stream` sources have no server-execution branch
+  // yet, so they set no server flag; supply them via a `ChunkProvider` to load on
+  // the client.) `forceClient` opts a source out of the server path too, exactly
+  // like `Loader`/`InitialLoader`; such a chunk falls to the client path and loads
+  // via a `ChunkProvider`. `skipInitialLoad` drops the initial stage.
+  const source = config.source;
+  const dataSource = source && source.mode === 'data' ? source : undefined;
+  return {
+    isLoaded,
+    isInitial,
+    hasServerInitial: !forceClient && !skipInitialLoad && Boolean(config.InitialLoader || dataSource?.initial),
+    hasServerLoader: !forceClient && Boolean(config.Loader || dataSource)
+  };
+}

package/CoordinatedLazy/createCoordinatedLazy.d.mts

@@ -0,0 +1,32 @@
+import * as React from 'react';
+import type { ChunkComponentProps, CreateChunkConfig } from "./types.mjs";
+/**
+ * Build a self-loading {@link CoordinatedLazy} component. The returned component
+ * is **isomorphic**: per render it evaluates {@link buildChunkRenderInputs} and
+ * routes via `resolveChunkRender`, so one component covers build, server,
+ * and client loading, and server or client rendering:
+ *
+ * - **content** (preloaded/controlled) - renders `ChunkContent` directly, so
+ *   build-precomputed data lands in the server HTML. `ChunkContent` may be a
+ *   server OR client component here.
+ * - **server-loader / server-initial** - renders the server `ChunkServerLoader`
+ *   under a Suspense boundary (server `Loader`/`InitialLoader` or a server-side
+ *   `data`-mode load), so content loads and renders on the server and streams
+ *   in. Requires a server (RSC) render context; supports server-component content.
+ * - **client modes** (async/initial/null) - delegates to the `'use client'`
+ *   {@link CoordinatedLazyClient}, which loads on the client and swaps the
+ *   fallback to content. `ChunkContent` here must be a client component.
+ *
+ * The client-mode branch hands the (function-bearing) `config` to a `'use client'`
+ * component, so a client-loaded chunk must render inside a client subtree - call
+ * `createCoordinatedLazy` from a client module, or wrap it in a client provider
+ * (e.g. `abstractCreateStream`'s `ClientProvider`). Server-loaded and
+ * preloaded/precomputed chunks have no such constraint - they render entirely on
+ * the server path.
+ *
+ * The user's generic props `T` flow through to both components; `data` (type
+ * `P`) is the loaded value (or the initial value while loading). Use it
+ * standalone for any deferred piece (a demo, a chart, a code frame); `useStream`
+ * renders a streamed list of them.
+ */
+export declare function createCoordinatedLazy<T extends {} = {}, P = unknown, O = unknown>(config: CreateChunkConfig<T, P, O>): React.ComponentType<ChunkComponentProps<T, P, O>>;