useSyncExternalStore as the sanctioned escape hatch

The last lesson left you with two copies of the same text. The ref holds the truth, updated on every chunk. The state holds a snapshot of it, updated on a tick. Everything renders from the snapshot, and the obvious question follows: why not read the buffer directly?

Because a render that reads an untracked mutable value is unsound, and React knows this comes up often enough to ship a supported way to do it. One hook, three arguments, and a contract that is not optional.

React tells you not to reach for this first

Start with the sentence people skip. The reference recommends preferring useState and useReducer, and reaching for this hook only when you need to integrate with existing non-React code. It is an integration hook, not a performance hook.

Your case qualifies, and it is worth being precise about why. A token buffer that a network handler mutates outside React’s knowledge is existing non-React state. It is not React state that you have decided to hide in a ref for speed. If you cannot say that sentence honestly about your own store, use useState.

The three arguments

const listeners = new Set()
let snapshot = ''          // the cached value getSnapshot returns
let buffer = ''            // the mutable accumulator

function subscribe(callback) {
  listeners.add(callback)
  return () => listeners.delete(callback)
}

function getSnapshot() {
  return snapshot          // must be Object.is-stable when nothing changed
}

function flush() {
  if (buffer === snapshot) return
  snapshot = buffer        // publish a new value, once
  listeners.forEach((l) => l())
}

// in the component
const text = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot)

subscribe registers a callback React will invoke when the store changes, and returns a function that unregisters it. getSnapshot reads the current value. getServerSnapshot supplies the value used during server-rendering and hydration, and is required if your surface renders on the server at all.

Notice where the throttle now lives. Chunks still append to buffer with no notification. flush is what publishes, and calling it once a frame gives you the same decoupling as the previous lesson, with the tree reading the store rather than a copy of it.

The contract, and the exact way it breaks

getSnapshot must return the same value while the store has not changed, and React compares with Object.is. The reference is explicit that the snapshot must be immutable and that a cached last snapshot should be returned when the data has not changed.

Get it wrong and the failure is not subtle. React names it in its own error text: the result of getSnapshot should be cached. What happens underneath is an infinite loop. React calls getSnapshot, gets a value that is not Object.is-equal to the last one, concludes the store changed, re-renders, calls getSnapshot again, and gets another new value.

// Wrong: a new object every call, so Object.is always fails
function getSnapshot() {
  return { text: buffer, length: buffer.length }
}

// Right: publish a new object only when the data actually changed
let snapshot = { text: '', length: 0 }
function flush() {
  if (buffer === snapshot.text) return
  snapshot = { text: buffer, length: buffer.length }
  listeners.forEach((l) => l())
}
function getSnapshot() {
  return snapshot
}

The wrong version looks correct in review. It is a pure function of the buffer, it has no side effects, and it reads exactly like the kind of selector people write everywhere else. That is what makes this the one rule to internalise: the snapshot is a value you publish, not a value you compute on demand. Anything derived — a message count, a formatted string, a sliced array — is derived at publish time, once, or in the component from a stable snapshot.

The caveat that hands off to the next lesson

One more line from the reference matters for what comes next. If the store is mutated during a non-blocking Transition update, React falls back to performing that update as blocking: it re-reads getSnapshot before committing, and if the value changed since the render started, it restarts the update as a blocking one.

Read that against a stream. A store that is mutated continuously is a store that is very likely to have changed mid-render. Marking your transcript update as low-priority and then publishing to the store on every frame can cancel out the priority you asked for. Whether that is acceptable is the subject of the transitions lesson, and it is the reason this module ends there rather than here.

What this does not cover

The store now publishes on a cadence you set. The remaining question is priority rather than cadence: whether the transcript update should yield to a click that arrives mid-render, and what happens when the low-priority work is restarted by the next chunk before it ever commits. The transitions lesson closes this module on that, and it starts from the Transition caveat quoted above.

This lesson does not cover state management libraries. Several implement their React bindings on top of this hook, and if you already use one, reading its store implementation is a better use of an hour than rewriting it. The reason to build the store by hand once is to be able to review theirs.

And it does not touch the amount of DOM the published snapshot turns into. A perfectly correct store still renders an unbounded transcript; the payload module handles that, and the stream’s own transport and lifecycle belong to the Streaming interfaces course.