Warning

This is an internal project, and is not intended for public use. No support or stability guarantees are provided.

Use Stream

useStream is the client-loading layer: it streams a list of chunks in on the client and coordinates their swaps so the page settles as one update. It sits above a single coordinated-lazy piece and is the client-driven sibling of abstractCreateStream (server/build loading). It is the streaming half of the Coordinated Streaming pattern.

useStream

Streams the chunk list on the client, accumulating snapshots into state, and owns a controller scoped to the rendered chunks. Render the returned chunks inside the returned Controller; loading stays true until the stream ends and every rendered chunk has settled.

function Chart() {
  const { chunks, Controller, loading } = useStream({ source: listSource });
  return (
    <Controller>
      {chunks.map((chunk, index) => (
        <ChartChunk key={index} preloaded={chunk} />
      ))}
    </Controller>
  );
}

A streaming source pushes chunks over time; loading stays true until the stream ends:

streaming… 0/6

'use client';
import * as React from 'react';
import { useStream } from '@mui/internal-docs-infra/useStream';
import type { StreamSource } from '@mui/internal-docs-infra/useStream';
import { DemoButton } from '@/components/DemoButton/DemoButton';

interface Point {
  x: number;
  y: number;
}

const COUNT = 6;

// Each stream run shifts the curve, so a refresh visibly brings in new data.
let streamRun = 0;
const makePoints = (run: number): Point[] =>
  Array.from({ length: COUNT }, (_unused, index) => ({
    x: index,
    y: 50 + 32 * Math.sin((index / (COUNT - 1)) * Math.PI * 2 + run),
  }));

const delay = (ms: number, signal: AbortSignal) =>
  new Promise<void>((resolve) => {
    const id = setTimeout(resolve, ms);
    signal.addEventListener('abort', () => clearTimeout(id), { once: true });
  });

// A streaming source: pushes one point at a time with an artificial delay so the
// chart visibly fills in. Re-invoked on every refresh with a fresh dataset.
const source: StreamSource<Point, void> = {
  mode: 'stream',
  async *stream(chunks, _options, signal) {
    streamRun += 1;
    const points = makePoints(streamRun);
    for (const point of points) {
      await delay(450, signal);
      if (signal.aborted) {
        return;
      }
      chunks.push(point);
      yield;
    }
  },
};

const WIDTH = 260;
const HEIGHT = 100;
const toXY = (point: Point) => `${(point.x / (COUNT - 1)) * WIDTH},${HEIGHT - point.y}`;

export function StreamingChart() {
  const { chunks, Controller, loading, revalidating, refresh } = useStream<Point, void>({ source });

  return (
    <Controller>
      <div style={{ display: 'flex', flexDirection: 'column', gap: 8, alignItems: 'flex-start' }}>
        <svg
          width={WIDTH}
          height={HEIGHT}
          style={{ border: '1px solid #d0cdd7', borderRadius: 8, background: '#faf9fc' }}
        >
          <polyline
            points={chunks.map(toXY).join(' ')}
            fill="none"
            stroke="#7c3aed"
            strokeWidth={2}
          />
          {chunks.map((point) => (
            <circle
              key={point.x}
              cx={(point.x / (COUNT - 1)) * WIDTH}
              cy={HEIGHT - point.y}
              r={3}
              fill="#7c3aed"
            />
          ))}
        </svg>
        <div style={{ font: '13px monospace', color: loading ? '#7c3aed' : '#3f8f3f' }}>
          {loading
            ? `streaming… ${chunks.length}/${COUNT}`
            : `done — ${chunks.length} points${revalidating ? ' · revalidating…' : ''}`}
        </div>
        {/* `refresh()` re-streams in the background: the current chart stays up
            (stale-while-revalidate) and swaps once the new data finishes. */}
        <DemoButton onClick={() => refresh()}>Refresh</DemoButton>
      </div>
    </Controller>
  );
}

ExpandCollapse

The same applies to any progressively-revealed content — for example source streamed line by line:

▍

'use client';
import * as React from 'react';
import { useStream } from '@mui/internal-docs-infra/useStream';
import type { StreamSource } from '@mui/internal-docs-infra/useStream';
import { DemoButton } from '@/components/DemoButton/DemoButton';

const SNIPPETS = [
  [
    'export function greet(name) {',
    "  const message = 'Hello, ' + name;",
    '  console.log(message);',
    '  return message;',
    '}',
  ],
  [
    'export function total(items) {',
    '  return items.reduce(',
    '    (sum, item) => sum + item.price,',
    '    0,',
    '  );',
    '}',
  ],
];

// Alternate the snippet on each stream run, so a refresh streams in new source.
let streamRun = 0;

const delay = (ms: number, signal: AbortSignal) =>
  new Promise<void>((resolve) => {
    const id = setTimeout(resolve, ms);
    signal.addEventListener('abort', () => clearTimeout(id), { once: true });
  });

// Streams the source one line at a time, accumulating into the rendered block.
const source: StreamSource<string, void> = {
  mode: 'stream',
  async *stream(chunks, _options, signal) {
    const lines = SNIPPETS[streamRun % SNIPPETS.length];
    streamRun += 1;
    for (const line of lines) {
      await delay(350, signal);
      if (signal.aborted) {
        return;
      }
      chunks.push(line);
      yield;
    }
  },
};

export function StreamingCode() {
  const { chunks, Controller, loading, revalidating, refresh } = useStream<string, void>({
    source,
  });

  // Build the text as a single node. A leading newline inside `<pre>` is stripped
  // by the HTML parser, so the cursor's newline is only added when there is
  // preceding content — otherwise SSR and hydration would disagree.
  const body = chunks.join('\n');
  const cursor = loading ? `${body ? '\n' : ''}▍` : '';

  return (
    <Controller>
      <div style={{ display: 'flex', flexDirection: 'column', gap: 8, alignItems: 'flex-start' }}>
        <pre
          style={{
            margin: 0,
            width: 320,
            boxSizing: 'border-box',
            padding: '10px 12px',
            minHeight: 96,
            border: '1px solid #d0cdd7',
            borderRadius: 8,
            background: '#faf9fc',
            font: '13px monospace',
            whiteSpace: 'pre-wrap',
          }}
        >
          {body + cursor}
        </pre>
        {/* `refresh()` re-streams in the background (stale-while-revalidate): the
            current source stays up and swaps once the next snippet finishes. */}
        <DemoButton onClick={() => refresh()}>
          {revalidating ? 'Revalidating…' : 'Refresh'}
        </DemoButton>
      </div>
    </Controller>
  );
}

ExpandCollapse

Coarse-to-detailed chunks

Each streamed chunk can be a coordinated-lazy piece rather than a finished value: its fallback paints a cheap sketch of the chunk and hoists the full slice, and its content draws the detail from that same slice — no reload. Here the graph is 1500 points in 15 chunks of 100; each chunk's fallback downsamples its slice to a coarse line, and the detail swaps in right-to-left over that baseline.

When the whole list is available at once, every coarse slice paints immediately and the detail then sweeps in from the right:

detailing… 0/15 chunks

'use client';
import * as React from 'react';
import { useStream } from '@mui/internal-docs-infra/useStream';
import type { StreamSource } from '@mui/internal-docs-infra/useStream';
import { Replayable } from '@/components/Replayable/Replayable';
import {
  CHUNK_COUNT,
  CHUNK_SIZE,
  ChartFrame,
  Segment,
  buildChunk,
  useSweepFront,
  type Chunk,
} from './sweepChart';

// Yields all 15 chunks at once, so every coarse sketch is on screen immediately —
// the full baseline is up before any detail loads.
const source: StreamSource<Chunk, void> = {
  mode: 'stream',
  async *stream(chunks, _options, signal) {
    if (signal.aborted) {
      return;
    }
    for (let index = 0; index < CHUNK_COUNT; index += 1) {
      chunks.push(buildChunk(index));
    }
    yield;
  },
};

function DetailSweepChartView() {
  const { chunks, Controller, loading } = useStream<Chunk, void>({ source });

  // The baseline is up instantly; detail then sweeps in from the right edge. A
  // chunk swaps once the front passes it, so the highest indices detail first.
  const front = useSweepFront(CHUNK_COUNT, 130);

  return (
    <Controller>
      <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
        <ChartFrame>
          {chunks.map((chunk) => (
            <Segment key={chunk.index} chunk={chunk} ready={chunk.index >= CHUNK_COUNT - front} />
          ))}
        </ChartFrame>
        <div style={{ font: '13px monospace', color: loading ? '#7c3aed' : '#3f8f3f' }}>
          {loading
            ? `detailing… ${front}/${CHUNK_COUNT} chunks`
            : `done — ${CHUNK_COUNT * CHUNK_SIZE} points`}
        </div>
      </div>
    </Controller>
  );
}

export function DetailSweepChart() {
  return (
    <Replayable>
      <DetailSweepChartView />
    </Replayable>
  );
}

ExpandCollapse

When the list streams instead, the coarse baseline draws itself across the chart as chunks arrive, and the detail follows a beat behind — both right-to-left:

streaming 0/15 · detailed 0

'use client';
import * as React from 'react';
import { useStream } from '@mui/internal-docs-infra/useStream';
import type { StreamSource } from '@mui/internal-docs-infra/useStream';
import { Replayable } from '@/components/Replayable/Replayable';
import {
  CHUNK_COUNT,
  CHUNK_SIZE,
  ChartFrame,
  Segment,
  buildChunk,
  delay,
  useSweepFront,
  type Chunk,
} from './sweepChart';

// Streams the chunks right-to-left (the rightmost segment first), one every
// 220ms, so the coarse baseline draws itself across the chart over time.
const source: StreamSource<Chunk, void> = {
  mode: 'stream',
  async *stream(chunks, _options, signal) {
    for (let step = 0; step < CHUNK_COUNT; step += 1) {
      const index = CHUNK_COUNT - 1 - step;
      await delay(220, signal);
      if (signal.aborted) {
        return;
      }
      chunks.push(buildChunk(index));
      yield;
    }
  },
};

function StreamSweepChartView() {
  const { chunks, Controller, loading } = useStream<Chunk, void>({ source });

  // Detail trails the baseline: a second front sweeps the same right-to-left order
  // a beat later, and never outruns the chunks that have actually streamed in.
  const front = useSweepFront(CHUNK_COUNT, 220, 360);
  const detailedFront = Math.min(front, chunks.length);

  return (
    <Controller>
      <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
        <ChartFrame>
          {chunks.map((chunk) => (
            <Segment
              key={chunk.index}
              chunk={chunk}
              ready={chunk.index >= CHUNK_COUNT - detailedFront}
            />
          ))}
        </ChartFrame>
        <div style={{ font: '13px monospace', color: loading ? '#7c3aed' : '#3f8f3f' }}>
          {loading
            ? `streaming ${chunks.length}/${CHUNK_COUNT} · detailed ${detailedFront}`
            : `done — ${CHUNK_COUNT * CHUNK_SIZE} points`}
        </div>
      </div>
    </Controller>
  );
}

export function StreamSweepChart() {
  return (
    <Replayable>
      <StreamSweepChartView />
    </Replayable>
  );
}

ExpandCollapse

The reveal needn't cascade. Here four small bar charts fill in one bar per tick — each bar grows from zero as a loading placeholder that hoists its value — and the swap to the full content is held until the whole list arrives, so every bar gains its interactive error bar in a single coordinated commit. Only the value rides the fallback→content hoist channel; the error bounds and sample size reach the content alone, where hovering a bar reveals them:

Alpha

Beta

Gamma

Delta

streaming… 0/12

'use client';
import * as React from 'react';
import { useStream } from '@mui/internal-docs-infra/useStream';
import { Replayable } from '@/components/Replayable/Replayable';
import { CHARTS, ChartCard, SETTLE_MS, TOTAL, source, type Bar } from './barChart';

function StreamingBarsView() {
  const { chunks, Controller, streamComplete } = useStream<Bar, void>({ source });

  // Hold every swap in its loading state until the whole list has streamed in,
  // then flip one shared flag a beat later (so the last bar finishes growing) —
  // all the error bars reveal together rather than as a cascade.
  const [reveal, setReveal] = React.useState(false);
  React.useEffect(() => {
    if (!streamComplete) {
      return undefined;
    }
    const id = setTimeout(() => setReveal(true), SETTLE_MS);
    return () => clearTimeout(id);
  }, [streamComplete]);

  return (
    <Controller>
      <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
        <div style={{ display: 'flex', gap: 10 }}>
          {CHARTS.map((chart) => (
            <ChartCard key={chart.title} chart={chart} arrived={chunks.length} ready={reveal} />
          ))}
        </div>
        <div style={{ font: '13px monospace', color: reveal ? '#3f8f3f' : '#7c3aed' }}>
          {reveal
            ? `done — ${TOTAL} bars across ${CHARTS.length} charts · hover for value ± error`
            : `streaming… ${chunks.length}/${TOTAL}`}
        </div>
      </div>
    </Controller>
  );
}

export function StreamingBars() {
  return (
    <Replayable>
      <StreamingBarsView />
    </Replayable>
  );
}

ExpandCollapse

Scrolling, multi-resolution streams

A real instance of this is multi-resolution loading: a fast, coarse feed places each new slice on a fixed cadence, and a higher-resolution feed backfills the detail a beat behind — so the live edge stays a sketch and refines as it ages while the window scrolls. A live metrics monitor over a known range — each tick's coarse chord refines into the jittery detail just behind the edge:

live · 0/26

'use client';
import * as React from 'react';
import { useStream } from '@mui/internal-docs-infra/useStream';
import { Replayable } from '@/components/Replayable/Replayable';
import {
  DETAIL_LAG_MS,
  HEIGHT,
  RefiningSlice,
  SLICE_WIDTH,
  SUBSAMPLES,
  ScrollFrame,
  TICK_MS,
  TOTAL,
  createTickSource,
  scrollOffset,
} from './oscilloscope';

interface Point {
  x: number;
  y: number;
}

interface MetricsSlice {
  index: number;
  points: Point[];
}

const SAMPLE_COUNT = TOTAL * SUBSAMPLES;

// A latency-like signal: a slow swell with fine jitter the coarse feed can't see.
const metric = (globalIndex: number) => {
  const t = globalIndex / SAMPLE_COUNT;
  return 60 + 30 * Math.sin(t * Math.PI * 2 * 3) + 10 * Math.sin(t * Math.PI * 2 * 29);
};

// One slice spans `SUBSAMPLES` steps plus the shared boundary point, so adjacent
// columns' lines meet.
function buildSlice(index: number): MetricsSlice {
  const start = index * SUBSAMPLES;
  const points = Array.from({ length: SUBSAMPLES + 1 }, (_unused, sub) => {
    const globalIndex = start + sub;
    return { x: (sub / SUBSAMPLES) * SLICE_WIDTH, y: HEIGHT - metric(globalIndex) };
  });
  return { index, points };
}

const toPath = (points: Point[]) => points.map((point) => `${point.x},${point.y}`).join(' ');

// Coarse feed: just the slice's endpoints — a straight chord, the rollup's-eye view.
function CoarseLine({ slice }: { slice: MetricsSlice }) {
  const ends = [slice.points[0], slice.points[slice.points.length - 1]];
  return (
    <svg width={SLICE_WIDTH} height={HEIGHT} style={{ overflow: 'visible' }}>
      <polyline
        points={toPath(ends)}
        fill="none"
        stroke="#cdbef0"
        strokeWidth={1.5}
        strokeDasharray="4 3"
      />
    </svg>
  );
}

// Detailed feed: every sub-sample, so the jitter shows.
function DetailLine({ slice }: { slice: MetricsSlice }) {
  return (
    <svg width={SLICE_WIDTH} height={HEIGHT} style={{ overflow: 'visible' }}>
      <polyline points={toPath(slice.points)} fill="none" stroke="#7c3aed" strokeWidth={2} />
    </svg>
  );
}

const ITEMS = Array.from({ length: TOTAL }, (_unused, index) => buildSlice(index));
const source = createTickSource(ITEMS, TICK_MS);

function LiveMetricsMonitorView() {
  const { chunks, Controller, loading } = useStream<MetricsSlice, void>({ source });

  return (
    <Controller>
      <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
        <ScrollFrame offset={scrollOffset(chunks.length)}>
          {chunks.map((slice) => (
            <RefiningSlice
              key={slice.index}
              data={slice}
              lagMs={DETAIL_LAG_MS}
              coarse={(data) => <CoarseLine slice={data} />}
              detail={(data) => <DetailLine slice={data} />}
            />
          ))}
        </ScrollFrame>
        <div style={{ font: '13px monospace', color: loading ? '#7c3aed' : '#3f8f3f' }}>
          {loading ? `live · ${chunks.length}/${TOTAL}` : `done — ${SAMPLE_COUNT} samples`}
        </div>
      </div>
    </Controller>
  );
}

export function LiveMetricsMonitor() {
  return (
    <Replayable>
      <LiveMetricsMonitorView />
    </Replayable>
  );
}

ExpandCollapse

The chunk count needn't be known up front. This waveform records for an unknown length — the stream signals its own end when the generator returns (last-chunk completion, not a knownCount) — and older slices scroll off the left as it grows. Each slice enters as an instant peak envelope, then the decoded samples fill in:

recording · 0 slices

'use client';
import * as React from 'react';
import { useStream } from '@mui/internal-docs-infra/useStream';
import { Replayable } from '@/components/Replayable/Replayable';
import {
  DETAIL_LAG_MS,
  HEIGHT,
  RefiningSlice,
  SLICE_WIDTH,
  SUBSAMPLES,
  ScrollFrame,
  TICK_MS,
  createTickSource,
  scrollOffset,
} from './oscilloscope';

interface WaveSlice {
  index: number;
  samples: number[];
}

// The stream just runs until the generator returns — the consumer never declares
// a count, so this stands in for an open-ended recording.
const SLICE_COUNT = 44;
const SAMPLE_COUNT = SLICE_COUNT * SUBSAMPLES;
const CENTER = HEIGHT / 2;
const SCALE = HEIGHT / 2 - 8;

// A carrier under a slowly swelling amplitude envelope, so the peak heights vary.
const sample = (globalIndex: number) => {
  const t = globalIndex / SAMPLE_COUNT;
  const envelope = 0.32 + 0.52 * Math.abs(Math.sin(t * Math.PI * 2 * 1.3));
  return envelope * Math.sin(t * Math.PI * 2 * 33);
};

function buildSlice(index: number): WaveSlice {
  const start = index * SUBSAMPLES;
  const samples = Array.from({ length: SUBSAMPLES }, (_unused, sub) => sample(start + sub));
  return { index, samples };
}

// Coarse feed: one min/max peak bar for the whole slice — the instant envelope.
function Envelope({ slice }: { slice: WaveSlice }) {
  const peak = Math.max(...slice.samples.map((value) => Math.abs(value)));
  return (
    <svg width={SLICE_WIDTH} height={HEIGHT}>
      <rect
        x={4}
        width={SLICE_WIDTH - 8}
        y={CENTER - peak * SCALE}
        height={Math.max(peak * SCALE * 2, 1)}
        rx={2}
        fill="#cdbef0"
      />
    </svg>
  );
}

// Detailed feed: a mirrored bar per sample — the decoded waveform.
function Waveform({ slice }: { slice: WaveSlice }) {
  return (
    <svg width={SLICE_WIDTH} height={HEIGHT}>
      {slice.samples.map((value, sampleIndex) => {
        const x = ((sampleIndex + 0.5) / SUBSAMPLES) * SLICE_WIDTH;
        const amplitude = Math.abs(value) * SCALE;
        return (
          <line
            key={sampleIndex}
            x1={x}
            x2={x}
            y1={CENTER - amplitude}
            y2={CENTER + amplitude}
            stroke="#7c3aed"
            strokeWidth={2}
            strokeLinecap="round"
          />
        );
      })}
    </svg>
  );
}

const ITEMS = Array.from({ length: SLICE_COUNT }, (_unused, index) => buildSlice(index));
const source = createTickSource(ITEMS, TICK_MS);

function LiveWaveformView() {
  const { chunks, Controller, loading } = useStream<WaveSlice, void>({ source });

  // No total: the count is unknown up front, so the caption only reports what has
  // arrived. Older slices scroll off the left as the recording grows.
  return (
    <Controller>
      <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
        <ScrollFrame offset={scrollOffset(chunks.length)}>
          {chunks.map((slice) => (
            <RefiningSlice
              key={slice.index}
              data={slice}
              lagMs={DETAIL_LAG_MS}
              coarse={(data) => <Envelope slice={data} />}
              detail={(data) => <Waveform slice={data} />}
            />
          ))}
        </ScrollFrame>
        <div style={{ font: '13px monospace', color: loading ? '#7c3aed' : '#3f8f3f' }}>
          {loading ? `recording · ${chunks.length} slices` : `stopped — ${chunks.length} slices`}
        </div>
      </div>
    </Controller>
  );
}

export function LiveWaveform() {
  return (
    <Replayable>
      <LiveWaveformView />
    </Replayable>
  );
}

ExpandCollapse

Streaming compressed content

The chunks can also be text. A commented document streams in with each chunk's comments shipped as compressed HAST decoded against the plaintext as a dictionary — so only the comment delta crosses the wire. Each chunk is outlined in black once its plaintext is present and gains a purple inner outline once its comments decode; the bars beside it are width-coded bytes — black plaintext, purple compressed comments, and a red hatched bar for the same content shipped uncompressed — with the per-chunk and total savings.

Two arrangements trade off differently. First, load the entire plaintext up front, then stream the comment chunks compressed against that one whole-document dictionary — the bigger the dictionary, the better the comments compress:

plaintext 778 B — sent up front for hydration

The team gathers feedback before each release.

Small fixes ship the same day they land.

Larger proposals wait for a second reviewer.

Every change is paired with a short rationale.

Rationales are kept in the shared log.

plaintext 218 B

comments 240 B

uncompressed 715 B

Reviewers focus on intent over style.

Style is handled by the formatter on commit.

Comments should suggest, not block.

Threads close once the author replies.

Unresolved threads surface in the digest.

plaintext 199 B

comments 136 B

uncompressed 534 B

Releases are cut on a weekly cadence.

A draft note collects the week’s changes.

Each entry credits its author.

The note is published with the tag.

Hotfixes are noted out of band.

plaintext 180 B

comments 228 B

uncompressed 623 B

Feedback from users is triaged weekly.

Themes are grouped before they are scheduled.

Quick wins jump the queue.

Everything else is sized first.

The backlog is pruned every month.

plaintext 178 B

comments 136 B

uncompressed 493 B

totals

plaintext 778 B

comments 0 B

uncompressed 778 B · −0%

plaintext ready · comments 0/4

'use client';
import * as React from 'react';
import { useStream } from '@mui/internal-docs-infra/useStream';
import type { StreamSource } from '@mui/internal-docs-infra/useStream';
import { decompressString } from '@mui/internal-docs-infra/pipeline/hastUtils';
import { Replayable } from '@/components/Replayable/Replayable';
import {
  BYTE_SCALE,
  ChunkRow,
  DOCUMENT,
  Totals,
  byteLength,
  compressLines,
  linesText,
  type Line,
} from './proseComments';

const ALL_LINES = DOCUMENT.flatMap((chunk) => chunk.lines);
const FULL_PLAINTEXT = linesText(ALL_LINES);
const PLAINTEXT_BYTES = byteLength(FULL_PLAINTEXT);
const RAW_TOTAL = DOCUMENT.reduce((sum, chunk) => sum + byteLength(JSON.stringify(chunk.lines)), 0);
// Final total baseline, so the totals bars grow against a fixed scale.
const TOTAL_REFERENCE = PLAINTEXT_BYTES + RAW_TOTAL;

// Each comment chunk is compressed against the WHOLE document's plaintext — the
// big shared dictionary the upfront plaintext block already paid for.
interface CommentChunk {
  index: number;
  compressed: string;
  plaintextBytes: number;
  compressedBytes: number;
  rawBytes: number;
}

const ITEMS: CommentChunk[] = DOCUMENT.map((chunk) => {
  const compressed = compressLines(chunk.lines, FULL_PLAINTEXT);
  return {
    index: chunk.index,
    compressed,
    plaintextBytes: byteLength(linesText(chunk.lines)),
    compressedBytes: byteLength(compressed),
    rawBytes: byteLength(JSON.stringify(chunk.lines)),
  };
});

const delay = (ms: number, signal: AbortSignal) =>
  new Promise<void>((resolve) => {
    const id = setTimeout(resolve, ms);
    signal.addEventListener('abort', () => clearTimeout(id), { once: true });
  });

const source: StreamSource<CommentChunk, void> = {
  mode: 'stream',
  async *stream(chunks, _options, signal) {
    for (const item of ITEMS) {
      await delay(700, signal);
      if (signal.aborted) {
        return;
      }
      chunks.push(item);
      yield;
    }
  },
};

function EntirePlaintextProseView() {
  const { chunks, Controller, loading } = useStream<CommentChunk, void>({ source });

  // The plaintext is on screen instantly; each comment chunk decodes against the
  // whole-document dictionary as it arrives, lighting up that chunk's purple outline.
  const decodedByChunk = React.useMemo(() => {
    const decoded = new Map<number, Line[]>();
    for (const chunk of chunks) {
      decoded.set(
        chunk.index,
        JSON.parse(decompressString(chunk.compressed, FULL_PLAINTEXT)) as Line[],
      );
    }
    return decoded;
  }, [chunks]);

  const compressedTotal = chunks.reduce((sum, chunk) => sum + chunk.compressedBytes, 0);
  const rawTotal = chunks.reduce((sum, chunk) => sum + chunk.rawBytes, 0);

  return (
    <Controller>
      <div style={{ display: 'flex', flexDirection: 'column', gap: 12, width: 'fit-content' }}>
        {/* The whole plaintext is one payload sent up front for hydration — shown
            centered above the black box that outlines it. */}
        <div
          style={{
            alignSelf: 'center',
            display: 'flex',
            flexDirection: 'column',
            alignItems: 'center',
            gap: 4,
            font: '11px monospace',
            color: '#2c2838',
          }}
        >
          <div>plaintext {PLAINTEXT_BYTES} B — sent up front for hydration</div>
          <div
            style={{
              width: PLAINTEXT_BYTES * BYTE_SCALE,
              height: 11,
              borderRadius: 3,
              background: '#2c2838',
            }}
          />
        </div>
        {/* The entire plaintext arrived as one payload, so the whole box gets a
            single black outline; comments light up each chunk's purple outline. */}
        <div
          style={{
            display: 'flex',
            flexDirection: 'column',
            gap: 8,
            width: 'fit-content',
            padding: 8,
            borderRadius: 10,
            border: '2px solid #2c2838',
          }}
        >
          {ITEMS.map((item) => {
            const decoded = decodedByChunk.get(item.index);
            const lines =
              decoded ?? DOCUMENT[item.index].lines.map((line) => ({ text: line.text }));
            return (
              <ChunkRow
                key={item.index}
                lines={lines}
                plaintextBytes={item.plaintextBytes}
                compressedBytes={item.compressedBytes}
                rawBytes={item.rawBytes}
                richLoaded={Boolean(decoded)}
                blackBox={false}
              />
            );
          })}
        </div>
        {/* Totals accumulate live (fixed scale, so the bars grow) and stay put. */}
        <Totals
          plaintextBytes={PLAINTEXT_BYTES}
          compressedBytes={compressedTotal}
          rawBytes={rawTotal}
          referenceBytes={TOTAL_REFERENCE}
        />
        <div style={{ font: '13px monospace', color: loading ? '#7c3aed' : '#3f8f3f' }}>
          {loading
            ? `plaintext ready · comments ${chunks.length}/${ITEMS.length}`
            : 'commented — full document'}
        </div>
      </div>
    </Controller>
  );
}

export function EntirePlaintextProse() {
  return (
    <Replayable>
      <EntirePlaintextProseView />
    </Replayable>
  );
}

ExpandCollapse

Or progressively, like the chart: stream five lines at a time, each chunk's comments compressed against just that chunk's plaintext. The plaintext arrives incrementally, but each smaller dictionary compresses its comments a little less:

totals

plaintext 0 B

comments 0 B

uncompressed 0 B · −0%

streaming · 0/4 chunks

'use client';
import * as React from 'react';
import { useStream } from '@mui/internal-docs-infra/useStream';
import type { StreamSource } from '@mui/internal-docs-infra/useStream';
import {
  CoordinatedLazy,
  useCoordinatedContent,
  useCoordinatedFallback,
} from '@mui/internal-docs-infra/CoordinatedLazy';
import { decompressString } from '@mui/internal-docs-infra/pipeline/hastUtils';
import { Replayable } from '@/components/Replayable/Replayable';
import {
  ChunkRow,
  DOCUMENT,
  Totals,
  byteLength,
  compressLines,
  linesText,
  type Line,
} from './proseComments';

// Each 5-line chunk carries its own plaintext and a comment payload compressed
// against just that chunk's plaintext — a smaller, per-chunk dictionary.
interface WireChunk {
  index: number;
  plaintext: string;
  compressed: string;
  plaintextBytes: number;
  compressedBytes: number;
  rawBytes: number;
}

const ITEMS: WireChunk[] = DOCUMENT.map((chunk) => {
  const plaintext = linesText(chunk.lines);
  const compressed = compressLines(chunk.lines, plaintext);
  return {
    index: chunk.index,
    plaintext,
    compressed,
    plaintextBytes: byteLength(plaintext),
    compressedBytes: byteLength(compressed),
    rawBytes: byteLength(JSON.stringify(chunk.lines)),
  };
});

// The final total baseline (plaintext + raw comments), so the totals bars grow
// against a fixed scale as chunks stream in.
const TOTAL_REFERENCE = ITEMS.reduce((sum, item) => sum + item.plaintextBytes + item.rawBytes, 0);

const delay = (ms: number, signal: AbortSignal) =>
  new Promise<void>((resolve) => {
    const id = setTimeout(resolve, ms);
    signal.addEventListener('abort', () => clearTimeout(id), { once: true });
  });

const source: StreamSource<WireChunk, void> = {
  mode: 'stream',
  async *stream(chunks, _options, signal) {
    for (const item of ITEMS) {
      await delay(800, signal);
      if (signal.aborted) {
        return;
      }
      chunks.push(item);
      yield;
    }
  },
};

function ChunkFallback({ chunk }: { chunk: WireChunk }) {
  // Paint the plain five lines and hoist them as the per-chunk dictionary.
  useCoordinatedFallback(React.useMemo(() => ({ plaintext: chunk.plaintext }), [chunk.plaintext]));
  return (
    <ChunkRow
      lines={chunk.plaintext.split('\n').map((text) => ({ text }))}
      plaintextBytes={chunk.plaintextBytes}
      compressedBytes={chunk.compressedBytes}
      rawBytes={chunk.rawBytes}
      richLoaded={false}
      blackBox
    />
  );
}

function ChunkContent({ chunk }: { chunk: WireChunk }) {
  // Decode the comment payload against the plaintext the fallback hoisted.
  const { plaintext } = useCoordinatedContent() as { plaintext: string };
  const lines = React.useMemo<Line[]>(
    () => JSON.parse(decompressString(chunk.compressed, plaintext)),
    [chunk.compressed, plaintext],
  );
  return (
    <ChunkRow
      lines={lines}
      plaintextBytes={chunk.plaintextBytes}
      compressedBytes={chunk.compressedBytes}
      rawBytes={chunk.rawBytes}
      richLoaded
      blackBox
    />
  );
}

// A chunk expands its height in as it streams (via the grid 0fr→1fr trick, which
// transitions to an auto height), then swaps from plain to commented a beat later.
function ChunkPiece({ chunk }: { chunk: WireChunk }) {
  const [ready, setReady] = React.useState(false);
  const [expanded, setExpanded] = React.useState(false);
  React.useEffect(() => {
    const frame = requestAnimationFrame(() => setExpanded(true));
    const id = setTimeout(() => setReady(true), 450);
    return () => {
      cancelAnimationFrame(frame);
      clearTimeout(id);
    };
  }, []);
  return (
    <div
      style={{
        display: 'grid',
        gridTemplateRows: expanded ? '1fr' : '0fr',
        transition: 'grid-template-rows 0.3s ease',
      }}
    >
      <div style={{ overflow: 'hidden' }}>
        <CoordinatedLazy
          ready={ready}
          requireHoist
          fallback={<ChunkFallback chunk={chunk} />}
          content={<ChunkContent chunk={chunk} />}
        />
      </div>
    </div>
  );
}

function ProgressiveProseView() {
  const { chunks, Controller, loading } = useStream<WireChunk, void>({ source });

  const plaintextBytes = chunks.reduce((sum, chunk) => sum + chunk.plaintextBytes, 0);
  const compressedBytes = chunks.reduce((sum, chunk) => sum + chunk.compressedBytes, 0);
  const rawBytes = chunks.reduce((sum, chunk) => sum + chunk.rawBytes, 0);

  return (
    <Controller>
      <div style={{ display: 'flex', flexDirection: 'column', gap: 12 }}>
        {/* A fixed-height viewport (~2.5 chunk cards tall). New chunks append below
            the fold; the scroll position stays put so reading isn't interrupted. */}
        <div
          style={{
            boxSizing: 'border-box',
            width: 620,
            height: 400,
            overflowY: 'auto',
            overflowX: 'hidden',
            display: 'flex',
            flexDirection: 'column',
            gap: 8,
            padding: 8,
            borderRadius: 8,
            border: '1px solid #e0dde8',
            background: '#fff',
          }}
        >
          {chunks.map((chunk) => (
            <ChunkPiece key={chunk.index} chunk={chunk} />
          ))}
        </div>
        {/* Totals accumulate live as chunks stream in (fixed scale, so the bars
            grow); shown throughout so nothing shifts. */}
        <Totals
          plaintextBytes={plaintextBytes}
          compressedBytes={compressedBytes}
          rawBytes={rawBytes}
          referenceBytes={TOTAL_REFERENCE}
        />
        <div style={{ font: '13px monospace', color: loading ? '#7c3aed' : '#3f8f3f' }}>
          {loading
            ? `streaming · ${chunks.length}/${ITEMS.length} chunks`
            : 'commented — full document'}
        </div>
      </div>
    </Controller>
  );
}

export function ProgressiveProse() {
  return (
    <Replayable>
      <ProgressiveProseView />
    </Replayable>
  );
}

ExpandCollapse

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.

Property	Type	Description
source	`StreamSource<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`.
loaderOptions	`O \| undefined`	Options passed to the source loaders.
channelKey	`string \| null \| undefined`	Coordination channel forwarded to the owned controller.
revalidateOnIdle	`boolean \| undefined`	Opt into stale-while-revalidate: once the list has finished streaming, automatically it once on the first idle period (via `requestIdleCallback`). Client-only; the current list stays visible while the background re-stream runs.

Return Type

UseStreamResult

Key	Type	Required
chunks	`P[]`	Yes
Controller	`React.ComponentType<{ children: React.ReactNode }>`	Yes
loading	`boolean`	Yes
streamComplete	`boolean`	Yes
revalidating	`boolean`	Yes
refresh	`() => void`	Yes

useStreamController

Scopes a group of chunks so the page can tell when they have all loaded — via a known count (knownCount) or a last-chunk flag (streaming + markLast). Returns { Controller, loading, gate, markLast, setKnownCount }. The Controller supplies the controller's gate as the ambient gate, so chunks rendered inside register their swap with it through CoordinatedLazy — no gate prop to thread through each one.

Scope a group of chunks so the page can tell when they have all loaded.

Returns a Controller provider to wrap the chunks in — it supplies the controller’s gate as the ambient gate (via CoordinatedGateContext), so chunks rendered inside register their swap with it through CoordinatedLazy without a gate prop — and a reactive loading flag that stays true until every registered chunk settles. Completion resolves via the gate’s known-count (knownCount) or last-chunk (streaming + markLast) signals; with neither, it opens as soon as the chunks present in the initial commit all settle. Each chunk also registers with the page-global gate (via CoordinatedLazy), so a page-wide coordinated commit waits for them too.

Property	Type	Description
knownCount	`number \| undefined`	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.
streaming	`boolean \| undefined`	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.
channelKey	`string \| null \| undefined`	Coordination channel forwarded to chunks for cross-instance commits (e.g. a later page-wide change landing together). `null` opts out.
safetyTimeoutMs	`number \| undefined`	Override the gate’s safety timeout (ms).

Return Type

UseStreamControllerResult

Key	Type	Required
Controller	`React.ComponentType<{ children: React.ReactNode }>`	Yes
loading	`boolean`	Yes
gate	`SettleGate`	Yes
markLast	`() => void`	Yes
setKnownCount	`(count: number) => void`	Yes

streamChunks

The isomorphic async-generator driver behind useStream: it walks a StreamSource (any mode) and yields accumulating snapshots with a lastChunk flag. useStream consumes it on the client with incremental setState; the same driver is what a server render awaits, so streaming behaves identically in both environments.

Drive any StreamSource mode and yield an accumulating snapshot after each chunk lands. Isomorphic: the client (useStream) iterates it and setStates 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.

Parameter	Type	Description
source	`StreamSource<P, O>`
options	`O`
signal	`AbortSignal`

Return Type

AsyncGenerator<ChunkSnapshot<P>, void, void>

Additional types

ChunkSnapshot

A snapshot emitted by streamChunks after each chunk lands.

type ChunkSnapshot<P> = {
  /** All chunks loaded so far, in order. */
  chunks: P[];
  /** `true` on the snapshot that completes the stream (last-chunk signal). */
  lastChunk: boolean;
}

StreamSource

Where a chunk’s data comes from — a discriminated union on mode, so each strategy is strongly typed with no overloads or runtime return-type sniffing:

'data' — load the chunk’s data directly (optionally with a quick initial value first).
'urls' — split into per-chunk URLs (loadUrls), then load each URL’s data (loadChunk); supports an initial pass.
'stream' — push chunks into the passed array over time and yield after each, for progressive reveal (the generator’s return is the last-chunk signal).

type StreamSource<P = unknown, O = unknown> =
  | {
      mode: 'data';
      load: (options: O, signal: AbortSignal) => Promise<P>;
      initial?: (options: O) => P;
    }
  | {
      mode: 'urls';
      loadUrls: (options: O, signal: AbortSignal) => Promise<StreamUrlsResult>;
      loadChunk: (url: URL, options: O, signal: AbortSignal) => Promise<P>;
      initialUrls?: (options: O) => StreamUrlsResult;
      initialChunk?: (url: URL, options: O) => P;
    }
  | {
      mode: 'stream';
      stream: (chunks: P[], options: O, signal: AbortSignal) => AsyncGenerator<void, void, void>;
    }

StreamUrlsResult

Result of a urls-mode loader: the chunk URLs to load individually, rather than the data itself. lastChunk marks the final URL for last-chunk completion when the total isn’t known up front.

type StreamUrlsResult = { chunks: URL[]; lastChunk?: boolean }

UseStreamControllerOptions

Options for useStreamController.

type 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;
}

UseStreamControllerResult

Result of useStreamController.

type 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;
}

UseStreamOptions

Options for useStream.

type 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  it once on the first idle
   * period (via `requestIdleCallback`). Client-only; the current list stays
   * visible while the background re-stream runs.
   */
  revalidateOnIdle?: boolean;
}

UseStreamResult

Result of useStream.

type 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;
}

Benchmarking

For performance benchmarks of useStream, see the Benchmarking useStream page.

Coordinated Lazy — the single piece each list item renders
abstractCreateStream — the server/build-loading sibling
Coordinated Lazy — the swap each chunk uses
Coordinated Streaming — the pattern

Use Stream

useStream

Coarse-to-detailed chunks

Scrolling, multi-resolution streams

Streaming compressed content

useStreamController

streamChunks

Additional types

Benchmarking

Related