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

package/useCoordinated/useCoordinatedLazy.mjs

@@ -0,0 +1,38 @@
+'use client';
+
+import * as React from 'react';
+import { registerLayoutShiftSource } from "./layoutShiftGate.mjs";
+
+/**
+ * Declares the calling component as a source of an initial, post-hydration
+ * layout shift — e.g. a code block that swaps from its plain fallback to
+ * highlighted (and focus-collapsed) output once it hydrates.
+ *
+ * While any registered source is unsettled, {@link useCoordinated} holds its
+ * layout-shifting commits, so a page-wide transform/variant change lands as a
+ * single unified update instead of a cascade as blocks swap in at staggered
+ * idle times. The host doesn't wire anything into its coordinated hooks — this
+ * registration is the only opt-in.
+ *
+ * Pass `settled: true` once the component has reached its stable
+ * post-hydration layout. Registration happens on mount and is released on
+ * unmount, so a component that unmounts before it settles can't hold the gate
+ * open for the rest of the page.
+ */
+export function useCoordinatedLazy(settled) {
+  const settleRef = React.useRef(null);
+  React.useEffect(() => {
+    settleRef.current = registerLayoutShiftSource();
+    return () => {
+      // Idempotent — doubles as a release when the component unmounts before
+      // it ever settled.
+      settleRef.current?.();
+      settleRef.current = null;
+    };
+  }, []);
+  React.useEffect(() => {
+    if (settled) {
+      settleRef.current?.();
+    }
+  }, [settled]);
+}

package/useCoordinated/useCoordinatedLocalStorage.d.mts

@@ -0,0 +1,16 @@
+import type * as React from 'react';
+import { type UseCoordinatedExtras, type UseCoordinatedOptions } from "./useCoordinated.mjs";
+/**
+ * `useLocalStorageState` + coordination in one call. Cross-tab sync
+ * happens via the underlying storage events; the coordinator handles
+ * within-tab peers (sibling demos on the same page) so their visible
+ * value flips land in a single layout pass.
+ *
+ * @param storageKey - localStorage key, or `null` to disable storage
+ *   (falls back to regular `useState` semantics).
+ * @param initializer - Initial value, identical to
+ *   `useLocalStorageState`.
+ * @param options - Coordination options. Pass `channelKey: null` to
+ *   skip the coordinator entirely.
+ */
+export declare function useCoordinatedLocalStorage<TPreload = void>(storageKey: string | null, initializer: string | null | (() => string | null), options: UseCoordinatedOptions<string | null, TPreload>): [string | null, React.Dispatch<React.SetStateAction<string | null>>, UseCoordinatedExtras<string | null>];

package/useCoordinated/useCoordinatedLocalStorage.mjs

@@ -0,0 +1,22 @@
+'use client';
+
+import useLocalStorageState from "../useLocalStorageState/index.mjs";
+import { useCoordinated } from "./useCoordinated.mjs";
+
+/**
+ * `useLocalStorageState` + coordination in one call. Cross-tab sync
+ * happens via the underlying storage events; the coordinator handles
+ * within-tab peers (sibling demos on the same page) so their visible
+ * value flips land in a single layout pass.
+ *
+ * @param storageKey - localStorage key, or `null` to disable storage
+ *   (falls back to regular `useState` semantics).
+ * @param initializer - Initial value, identical to
+ *   `useLocalStorageState`.
+ * @param options - Coordination options. Pass `channelKey: null` to
+ *   skip the coordinator entirely.
+ */
+export function useCoordinatedLocalStorage(storageKey, initializer, options) {
+  const underlying = useLocalStorageState(storageKey, initializer);
+  return useCoordinated(underlying, options);
+}

package/useCoordinated/useCoordinatedPreference.d.mts

@@ -0,0 +1,20 @@
+import type * as React from 'react';
+import { type UseCoordinatedExtras, type UseCoordinatedOptions } from "./useCoordinated.mjs";
+/**
+ * `usePreference` + {@link useCoordinated} in one call.
+ *
+ * Cross-tab sync happens through the underlying `localStorage` /
+ * `storage` event flow that `usePreference` already provides; the
+ * coordinator handles within-tab peers so demos that share the same
+ * preference key commit their visible flip together rather than
+ * cascading layout shifts.
+ *
+ * @param type - Preference type, identical to `usePreference`.
+ * @param name - Variant/transform name(s), identical to
+ *   `usePreference`.
+ * @param initializer - Initial value or initializer, identical to
+ *   `usePreference`.
+ * @param options - Coordination options. Pass `channelKey: null` to
+ *   skip the coordinator entirely.
+ */
+export declare function useCoordinatedPreference<TPreload = void>(type: 'variant' | 'transform', name: string | string[], initializer: string | null | (() => string | null) | undefined, options: UseCoordinatedOptions<string | null, TPreload>): [string | null, React.Dispatch<React.SetStateAction<string | null>>, UseCoordinatedExtras<string | null>];

package/useCoordinated/useCoordinatedPreference.mjs

@@ -0,0 +1,26 @@
+'use client';
+
+import { usePreference } from "../usePreference/usePreference.mjs";
+import { useCoordinated } from "./useCoordinated.mjs";
+
+/**
+ * `usePreference` + {@link useCoordinated} in one call.
+ *
+ * Cross-tab sync happens through the underlying `localStorage` /
+ * `storage` event flow that `usePreference` already provides; the
+ * coordinator handles within-tab peers so demos that share the same
+ * preference key commit their visible flip together rather than
+ * cascading layout shifts.
+ *
+ * @param type - Preference type, identical to `usePreference`.
+ * @param name - Variant/transform name(s), identical to
+ *   `usePreference`.
+ * @param initializer - Initial value or initializer, identical to
+ *   `usePreference`.
+ * @param options - Coordination options. Pass `channelKey: null` to
+ *   skip the coordinator entirely.
+ */
+export function useCoordinatedPreference(type, name, initializer, options) {
+  const underlying = usePreference(type, name, initializer ?? null);
+  return useCoordinated(underlying, options);
+}

package/useCoordinated/useSettleGate.d.mts

@@ -0,0 +1,11 @@
+import type { SettleGate } from "./createSettleGate.mjs";
+/**
+ * Register the calling component as a source on a settle gate and release it
+ * once `settled` is `true`. Generalizes `useCoordinatedLazy`: registration
+ * happens on mount and the release is idempotent, so a component that unmounts
+ * before settling can't hold the gate open. Defaults to the page-global
+ * {@link pageSettleGate}; pass `null` to opt out of registration entirely (used
+ * when a swap conditionally registers with a controller gate that may be
+ * absent).
+ */
+export declare function useSettleGate(settled: boolean, gate?: SettleGate | null): void;

package/useCoordinated/useSettleGate.mjs

@@ -0,0 +1,34 @@
+'use client';
+
+import * as React from 'react';
+import { pageSettleGate } from "./pageSettleGate.mjs";
+
+/**
+ * Register the calling component as a source on a settle gate and release it
+ * once `settled` is `true`. Generalizes `useCoordinatedLazy`: registration
+ * happens on mount and the release is idempotent, so a component that unmounts
+ * before settling can't hold the gate open. Defaults to the page-global
+ * {@link pageSettleGate}; pass `null` to opt out of registration entirely (used
+ * when a swap conditionally registers with a controller gate that may be
+ * absent).
+ */
+export function useSettleGate(settled, gate = pageSettleGate) {
+  const settleRef = React.useRef(null);
+  React.useEffect(() => {
+    if (!gate) {
+      return undefined;
+    }
+    settleRef.current = gate.register();
+    return () => {
+      // Idempotent - doubles as a release when the component unmounts before it
+      // ever settled, so it can't hold the gate open for the rest of the page.
+      settleRef.current?.();
+      settleRef.current = null;
+    };
+  }, [gate]);
+  React.useEffect(() => {
+    if (settled) {
+      settleRef.current?.();
+    }
+  }, [settled]);
+}

package/useDemo/exportVariant.d.mts

@@ -140,12 +140,19 @@ export interface ExportConfig {
     rootFile: string;
   };
   /**
-   * Transform function that runs at the very start of the export process
-   * Can modify the variant code and metadata before any other processing happens
+   * Transform function that runs at the very start of the export process.
+   * Can modify the variant code and metadata before any other processing happens.
+   *
+   * Every source handed to this hook — `variant.source`, each
+   * `variant.extraFiles[*].source`, and each `globals[*].source` — is decoded to
+   * either a plain string or a live HAST tree (`HastRoot`); the serialized
+   * `hastCompressed` / `hastJson` shapes never reach it. Read a source as text
+   * with `stringOrHastToString`, or inspect / transform the HAST directly.
+   * Decoded trees are clones you own, so mutating them is safe.
    * @example
-   * transformVariant: (variant, globals, variantName) => ({
-   *   variant: { ...variant, source: modifiedSource },
-   *   globals: { ...globals, extraFiles: { ...globals.extraFiles, 'theme.css': { source: '.new {}', metadata: true } } }
+   * transformVariant: (variant, variantName, globals) => ({
+   *   variant: { ...variant, source: `// ${variantName}\n${stringOrHastToString(variant.source)}` },
+   *   globals: { ...globals, 'theme.css': { source: '.new {}', metadata: true } },
    * })
    */
   transformVariant?: (variant: VariantCode, variantName?: string, globals?: VariantExtraFiles) => {

package/useDemo/exportVariant.mjs

@@ -6,6 +6,7 @@
 import { externalsToPackages } from "../pipeline/loaderUtils/index.mjs";
 import { getFileNameFromUrl } from "../pipeline/loaderUtils/getFileNameFromUrl.mjs";
 import { examineCodeVariant } from "../pipeline/loadIsomorphicCodeVariant/examineCodeVariant.mjs";
+import { decodeSource } from "../pipeline/loadIsomorphicCodeVariant/decodeSource.mjs";
 import { mergeCodeMetadata, extractCodeMetadata } from "../pipeline/loadIsomorphicCodeVariant/mergeCodeMetadata.mjs";
 
 /**
@@ -33,6 +34,47 @@ function mergeFiles(...fileSets) {
   return merged;
 }
 
+/**
+ * Decode every `source` in an extra-files map to `string | HastRoot` (never a
+ * serialized `hastJson` / `hastCompressed` payload), reusing the shared decode
+ * cache. Each file's own `fallback` is the DEFLATE dictionary for a
+ * `hastCompressed` source. URL-only string entries are passed through untouched.
+ */
+function decodeExtraFilesSources(files) {
+  const decoded = {};
+  for (const [name, fileData] of Object.entries(files)) {
+    if (typeof fileData === 'string' || fileData.source === undefined) {
+      decoded[name] = fileData;
+    } else {
+      decoded[name] = {
+        ...fileData,
+        source: decodeSource(fileData.source, fileData.fallback)
+      };
+    }
+  }
+  return decoded;
+}
+
+/**
+ * Decode a variant's main `source` and all of its extra-file sources to
+ * `string | HastRoot` (see {@link decodeExtraFilesSources}), so downstream
+ * consumers — most notably the user-supplied `transformVariant` hook — never
+ * have to handle serialized `hastCompressed` / `hastJson` payloads or thread
+ * their dictionaries.
+ */
+function decodeVariantSources(variant) {
+  const decoded = {
+    ...variant
+  };
+  if (variant.source !== undefined) {
+    decoded.source = decodeSource(variant.source, variant.fallback);
+  }
+  if (variant.extraFiles) {
+    decoded.extraFiles = decodeExtraFilesSources(variant.extraFiles);
+  }
+  return decoded;
+}
+
 /**
  * Extract filename from URL or return undefined if not available
  */
@@ -155,13 +197,23 @@ export function exportVariant(variantCode, config = {}) {
     metadata: processedGlobals
   } = extractCodeMetadata(variantCode);
 
-  // Run optional transform hook to modify variant and globals before processing
+  // Run optional transform hook to modify variant and globals before processing.
   if (transformVariant) {
-    const transformed = transformVariant(processedVariantCode, variantName, processedGlobals);
+    // Decode sources before handing them to the hook so it only ever sees a
+    // plain string or a live `HastRoot`, never a serialized `hastJson` /
+    // `hastCompressed` payload. Precomputed / SSR variants can still carry
+    // serialized sources here; the co-located `fallback` is the dictionary
+    // needed to decode them. `decodeSource` reuses the shared decode cache (so a
+    // source already decoded for rendering is not inflated again) and clones the
+    // tree so the hook owns what it receives. Decoding lazily here keeps it off
+    // the no-transform path, where `flattenCodeVariant` decodes at the end.
+    const decodedVariant = decodeVariantSources(processedVariantCode);
+    const decodedGlobals = decodeExtraFilesSources(processedGlobals);
+    const transformed = transformVariant(decodedVariant, variantName, decodedGlobals);
     if (transformed) {
       // Re-extract metadata after transformation
       const result = transformed.variant && extractCodeMetadata(transformed.variant);
-      processedVariantCode = result?.variant || processedVariantCode;
+      processedVariantCode = result?.variant || decodedVariant;
 
       // Start fresh with only the new metadata and explicitly transformed globals
       // Do NOT merge with the original processedGlobals to avoid duplication
@@ -278,8 +330,10 @@ export function exportVariant(variantCode, config = {}) {
     },
     devDependencies: {
       ...(!isFramework && {
-        '@vitejs/plugin-react': 'latest',
-        vite: 'latest'
+        // Pinned to major versions instead of `latest` to work around
+        // https://github.com/stackblitz/webcontainer-core/issues/2104
+        '@vitejs/plugin-react': '^5',
+        vite: '^7'
       }),
       ...(useTypescript && {
         typescript: 'latest',

package/useDemo/useDemo.d.mts

@@ -58,6 +58,7 @@ export declare function useDemo<T extends {} = {}>(contentProps: ContentProps<T>
   selectedFileLines: number;
   selectedFileName: string | undefined;
   selectedFileUrl: string | undefined;
+  selectedFileSlug: string | undefined;
   selectFileName: (fileName: string) => void;
   allFilesSlugs: Array<{
     fileName: string;
@@ -67,13 +68,15 @@ export declare function useDemo<T extends {} = {}>(contentProps: ContentProps<T>
   expanded: boolean;
   expand: () => void;
   setExpanded: (expanded: boolean) => void;
-  copy: (event: React.MouseEvent<Element>) => Promise<void>;
-  copyMarkdown: (event: React.MouseEvent<Element>) => Promise<void>;
+  copy: (event: React.MouseEvent<Element, MouseEvent>) => Promise<void>;
+  copyMarkdown: (event: React.MouseEvent<Element, MouseEvent>) => Promise<void>;
   availableTransforms: string[];
   selectedTransform: string | null | undefined;
   selectTransform: (transformName: string | null) => void;
+  pendingTransform: string | null | undefined;
   setSource?: (source: string, fileName?: string) => void;
   reset?: () => void;
+  refresh?: () => void;
   userProps: T & {
     name?: string;
     slug?: string;

package/useScrollAnchor/useScrollAnchor.mjs

@@ -42,10 +42,16 @@ export function useScrollAnchor() {
     activeSessionCleanupRef.current = null;
 
     // Snapshot the scroll target at session start so a later ref change
-    // doesn't redirect compensation mid-flight.
-    const scrollTarget = scrollContainerRef.current ?? window;
+    // doesn't redirect compensation mid-flight. `scrollElement` is the attached
+    // container (if any); `scrollTarget` is what receives the user-interaction
+    // listeners (the container or the window).
+    const scrollElement = scrollContainerRef.current;
+    const scrollTarget = scrollElement ?? window;
     const interactionTarget = scrollTarget;
-    const initialTop = anchor.getBoundingClientRect().top;
+
+    // Mutable so it can be re-baselined when an attached container can't yet
+    // absorb a delta (see below).
+    let initialTop = anchor.getBoundingClientRect().top;
     let active = true;
     let cleanupTimer;
 
@@ -58,8 +64,25 @@ export function useScrollAnchor() {
         return;
       }
       const delta = anchor.getBoundingClientRect().top - initialTop;
-      if (Math.abs(delta) > 0.5) {
-        scrollTarget.scrollBy(0, delta);
+      if (Math.abs(delta) <= 0.5) {
+        return;
+      }
+      if (!scrollElement) {
+        window.scrollBy(0, delta);
+        return;
+      }
+      const before = scrollElement.scrollTop;
+      scrollElement.scrollBy(0, delta);
+      const remainder = delta - (scrollElement.scrollTop - before);
+      if (Math.abs(remainder) > 0.5) {
+        // The container couldn't absorb this part — it isn't scrollable yet
+        // (its content hasn't exceeded its `max-height`). Re-baseline instead
+        // of forcing the difference elsewhere: scrolling the page would shift
+        // the surrounding layout, and carrying the delta forward would snap the
+        // anchor back the instant the container becomes scrollable. Accepting
+        // the small drift now keeps the surrounding layout still and lets the
+        // container hold the anchor smoothly from here on.
+        initialTop += remainder;
       }
     });
     function cleanup() {

package/useStream/index.d.mts

@@ -0,0 +1,6 @@
+export { useStream } from "./useStream.mjs";
+export { useStreamController } from "./useStreamController.mjs";
+export { streamChunks } from "./streamChunks.mjs";
+export type { UseStreamOptions, UseStreamResult } from "./useStream.mjs";
+export type { ChunkSnapshot } from "./streamChunks.mjs";
+export type { UseStreamControllerOptions, UseStreamControllerResult, StreamSource, StreamUrlsResult } from "./types.mjs";

package/useStream/index.mjs

@@ -0,0 +1,6 @@
+// Client loading: stream a list of chunks in on the client and coordinate their
+// swaps. Sits above `Chunk` (a single piece) and is the client-driven sibling of
+// `abstractCreateStream` (server/build loading).
+export { useStream } from "./useStream.mjs";
+export { useStreamController } from "./useStreamController.mjs";
+export { streamChunks } from "./streamChunks.mjs";

package/useStream/streamChunks.d.mts

@@ -0,0 +1,23 @@
+import type { StreamSource } from "./types.mjs";
+/** A snapshot emitted by {@link streamChunks} after each chunk lands. */
+export interface ChunkSnapshot<P> {
+  /** All chunks loaded so far, in order. */
+  chunks: P[];
+  /** `true` on the snapshot that completes the stream (last-chunk signal). */
+  lastChunk: boolean;
+}
+/**
+ * Drive any {@link StreamSource} `mode` and yield an accumulating snapshot after
+ * each chunk lands. Isomorphic: the client (`useStream`) iterates it and
+ * `setState`s each snapshot for progressive reveal; the server awaits it to
+ * completion for non-incremental modes.
+ *
+ * - `'data'` - one `load`, one terminal snapshot.
+ * - `'urls'` - `loadUrls`, then `loadChunk` per URL, one snapshot each; the
+ *   final URL is the last chunk unless `loadUrls` returned `lastChunk: false`.
+ * - `'stream'` - runs the generator (which pushes into the array and yields),
+ *   surfacing a snapshot per yield, then a terminal snapshot on return.
+ *
+ * Stops early (without a terminal snapshot) if `signal` aborts.
+ */
+export declare function streamChunks<P, O>(source: StreamSource<P, O>, options: O, signal: AbortSignal): AsyncGenerator<ChunkSnapshot<P>, void, void>;

package/useStream/streamChunks.mjs

@@ -0,0 +1,85 @@
+/** A snapshot emitted by {@link streamChunks} after each chunk lands. */
+
+/**
+ * Drive any {@link StreamSource} `mode` and yield an accumulating snapshot after
+ * each chunk lands. Isomorphic: the client (`useStream`) iterates it and
+ * `setState`s each snapshot for progressive reveal; the server awaits it to
+ * completion for non-incremental modes.
+ *
+ * - `'data'` - one `load`, one terminal snapshot.
+ * - `'urls'` - `loadUrls`, then `loadChunk` per URL, one snapshot each; the
+ *   final URL is the last chunk unless `loadUrls` returned `lastChunk: false`.
+ * - `'stream'` - runs the generator (which pushes into the array and yields),
+ *   surfacing a snapshot per yield, then a terminal snapshot on return.
+ *
+ * Stops early (without a terminal snapshot) if `signal` aborts.
+ */
+export async function* streamChunks(source, options, signal) {
+  if (source.mode === 'data') {
+    const data = await source.load(options, signal);
+    if (signal.aborted) {
+      return;
+    }
+    yield {
+      chunks: [data],
+      lastChunk: true
+    };
+    return;
+  }
+  if (source.mode === 'urls') {
+    const result = await source.loadUrls(options, signal);
+    if (signal.aborted) {
+      return;
+    }
+    const urls = result.chunks;
+    const accumulated = [];
+    for (let index = 0; index < urls.length; index += 1) {
+      // Sequential by design: chunks stream in and yield in order for
+      // progressive reveal - loading in parallel would defeat that.
+      // eslint-disable-next-line no-await-in-loop
+      const data = await source.loadChunk(urls[index], options, signal);
+      if (signal.aborted) {
+        return;
+      }
+      accumulated.push(data);
+      const isLast = index === urls.length - 1 && result.lastChunk !== false;
+      yield {
+        chunks: [...accumulated],
+        lastChunk: isLast
+      };
+    }
+    if (urls.length === 0) {
+      // Nothing to load - still signal completion so a controller can settle.
+      yield {
+        chunks: [],
+        lastChunk: result.lastChunk !== false
+      };
+    }
+    return;
+  }
+
+  // stream mode: the generator pushes into `accumulated` and yields after each.
+  const accumulated = [];
+  const generator = source.stream(accumulated, options, signal);
+  let step = await generator.next();
+  while (!step.done) {
+    if (signal.aborted) {
+      return;
+    }
+    yield {
+      chunks: [...accumulated],
+      lastChunk: false
+    };
+    // Sequential by design: a generator is driven one step at a time.
+    // eslint-disable-next-line no-await-in-loop
+    step = await generator.next();
+  }
+  if (signal.aborted) {
+    return;
+  }
+  // Generator returned -> the stream is complete.
+  yield {
+    chunks: [...accumulated],
+    lastChunk: true
+  };
+}

package/useStream/types.d.mts

@@ -0,0 +1,45 @@
+import type * as React from 'react';
+import type { SettleGate } from "../useCoordinated/createSettleGate.mjs";
+export type { StreamSource, StreamUrlsResult } from "../CoordinatedLazy/types.mjs";
+/** Options for `useStreamController`. */
+export interface UseStreamControllerOptions {
+  /**
+   * Total number of chunks that will register. The controller stays `loading`
+   * until that many have registered and all have settled - **known-count**
+   * completion. Use when the chunk count is known up front.
+   */
+  knownCount?: number;
+  /**
+   * Hold the controller `loading` for an unknown-count stream until `markLast`
+   * is called - **last-chunk** completion. Ignored when `knownCount` is set.
+   * Use for a streaming loader that pushes chunks over time and signals the end
+   * when its generator returns.
+   */
+  streaming?: boolean;
+  /**
+   * Coordination channel forwarded to chunks for cross-instance commits (e.g.
+   * a later page-wide change landing together). `null` opts out.
+   */
+  channelKey?: string | null;
+  /** Override the gate's safety timeout (ms). */
+  safetyTimeoutMs?: number;
+}
+/** Result of `useStreamController`. */
+export interface UseStreamControllerResult {
+  /**
+   * Provider that scopes chunk registration to this controller: it supplies the
+   * controller's gate as the ambient gate, so chunks rendered inside register
+   * their swap with it (via `CoordinatedLazy`) without a `gate` prop.
+   */
+  Controller: React.ComponentType<{
+    children: React.ReactNode;
+  }>;
+  /** `true` while any registered chunk is still loading; `false` once all settle. */
+  loading: boolean;
+  /** The controller's settle gate (also provided as the ambient gate). */
+  gate: SettleGate;
+  /** Mark the last chunk as arrived - terminal for a streaming controller. */
+  markLast: () => void;
+  /** Declare/adjust the total chunk count (known-count completion). */
+  setKnownCount: (count: number) => void;
+}

package/useStream/types.mjs

@@ -0,0 +1 @@
+export {};

package/useStream/useStream.d.mts

@@ -0,0 +1,57 @@
+import * as React from 'react';
+import type { StreamSource } from "./types.mjs";
+/** Options for {@link useStream}. */
+export interface UseStreamOptions<P, O> {
+  /**
+   * The source that produces the chunk list, by `mode`: `urls` resolves the
+   * chunk URLs then loads each, `stream` pushes chunks over time, `data` yields
+   * a single chunk. Streamed snapshots accumulate into `chunks`.
+   */
+  source: StreamSource<P, O>;
+  /** Options passed to the source loaders. */
+  loaderOptions?: O;
+  /** Coordination channel forwarded to the owned controller. */
+  channelKey?: string | null;
+  /**
+   * Opt into stale-while-revalidate: once the list has finished streaming,
+   * automatically {@link UseStreamResult.refresh} it once on the first idle
+   * period (via `requestIdleCallback`). Client-only; the current list stays
+   * visible while the background re-stream runs.
+   */
+  revalidateOnIdle?: boolean;
+}
+/** Result of {@link useStream}. */
+export interface UseStreamResult<P> {
+  /** The chunks loaded so far, accumulating as they stream in. */
+  chunks: P[];
+  /** Controller provider that scopes the rendered chunks' coordination. */
+  Controller: React.ComponentType<{
+    children: React.ReactNode;
+  }>;
+  /** `true` until the list has finished streaming and every chunk has settled. */
+  loading: boolean;
+  /** `true` once the list has finished streaming (the last chunk arrived). */
+  streamComplete: boolean;
+  /** `true` while a background re-stream (revalidation) is in flight; the current list stays. */
+  revalidating: boolean;
+  /**
+   * Re-stream the list in the background and swap the fresh list in atomically
+   * once it completes, keeping the current list visible meanwhile
+   * (stale-while-revalidate). Aborts any prior in-flight refresh.
+   */
+  refresh: () => void;
+}
+/**
+ * Stream a list of chunks on the client and own a `StreamController` that scopes
+ * their coordination. Render the returned `chunks` as chunk components inside
+ * the returned `Controller`; each chunk registers its swap with the controller,
+ * and the list's completion (`markLast`) plus those swaps drive `loading`.
+ *
+ * The controller runs in `streaming` mode, so it stays `loading` until the list
+ * finishes streaming - at which point the chunks present can settle it.
+ *
+ * `refresh()` (and the opt-in `revalidateOnIdle`) re-stream the list in the
+ * background and swap the result in atomically when it completes, without a
+ * loading flash — the current list stays visible the whole time.
+ */
+export declare function useStream<P, O>(options: UseStreamOptions<P, O>): UseStreamResult<P>;