Streaming a Web Page, Explained at a Restaurant Table

A genuinely tricky piece of web architecture, explained with nothing but a restaurant, a waiter, and a busser. No jargon required.

We recently worked through a dense engineering design document — an architecture proposal for how a web page's pieces should be delivered to your browser, faster and with zero waste. Instead of reading it the usual way (nodding along and forgetting it), we used a simple technique: ask the AI to teach it back using only analogies, and to quiz you after each one until you can explain it yourself. We wrote up that technique separately:

→ Teach Me With Analogies: The AI Prompt That Makes Hard Things Actually Click

This post is the result of running that prompt on a real problem. By the end you'll understand — in plain words — what "scroll-priority streaming" is and why it's hard. We'll stay at one dinner table the whole way.

It's an edited transcript of that session, so after each analogy you'll see the exact check-in question the AI asked me and how I answered. That back-and-forth — a question after every step, then an adjustment based on my answer — is the technique working. It's the part that turns nodding along into actually understanding.

The restaurant that serves each dish as it's ready

Imagine you sit down and, instead of waiting until your entire meal is cooked, the kitchen sends out each dish the moment it's ready. Bread and salad show up almost instantly. The slow-roasted main takes longer — so in its place they set down a little card: "Your main course is on its way." You're never staring at an empty table, and the slow stuff fills in as it finishes.

That card does two jobs: it tells you more is coming, and it saves the exact spot on the table where the dish will land. When the main is ready, the waiter just swaps the card for the plate.

In web terms: A page doesn't have to arrive all at once. It streams in pieces — fast parts appear immediately, and slow parts get a temporary "loading…" placeholder that holds their spot until the real content is ready to drop in.

Check-in: here the AI stopped and asked me what that "on its way" card really stands in for, and why the kitchen doesn't just leave the spot empty. I said: "so I can start eating sooner and be happy." It confirmed that was the main point — then added the piece I'd glossed over: the card also saves the exact spot, so the real dish drops straight in when it's ready.

The waiter who notices you reaching

Now suppose some dishes are cooked in a back kitchen far away, and it takes a while to walk them over. The ordinary waiter brings them out in whatever order they happen to finish. But there's a smarter waiter: one who watches which way you're leaning. If you start reaching toward the spot where your dessert card sits — clearly that's what you want next — the waiter hurries to grab that dish first and get it in front of you before you're annoyed.

In web terms: A long page has many "loading…" spots further down. As you scroll toward one, the system notices "they're heading here" and rushes to deliver that section first — instead of making you wait for it in the default order. That's scroll-priority: prioritize whatever the reader is moving toward.

Check-in: it asked why this "watch which way you're reaching" waiter beats the one who just brings dishes whenever they happen to be ready. I answered that if I'm reaching toward the fish or the dessert, I get that one sooner — and the waiter doesn't push dishes I'm not asking for yet. It confirmed, adding the nuance that the other dishes still come; they're just no longer the priority.

Rush the dessert — but don't waste a crumb

Here's where it gets hard. A lazy way to rush your dessert would be wasteful in one of two ways:

• The double-plate mistake: in the rush, the waiter also brings a second copy of the bread and salad you already have. Now your table is piling up with duplicate food.
• The re-cook-everything mistake: to get one dessert out faster, the kitchen throws out the whole meal-in-progress and starts the entire dinner over. You get your dessert, but every other table is now delayed because the kitchen is redoing work it already did.

The rule is: rush only the one dish you're reaching for, bring exactly that — no duplicate plates, no re-cooking — and don't disrupt the kitchen's normal flow for everyone else.

In web terms: Every piece of a page costs data to send and effort to produce. Zero-waste means when we hurry a section to you, we send only the new bytes for that section — nothing you already received gets sent twice, and the server doesn't redo work it already finished. Wasted data is wasted money and time on both sides: the site pays more to send it, and your page gets slower and heavier.

Check-in: it asked why the team is so strict about no duplicate plates and no re-cooking — what actually goes wrong if a little waste slips through each time. I said wasted food costs more and slows everything down: the kitchen backs up, the owner loses money, and diners wait longer overall. That's the whole economic argument, it said — wasted bytes are wasted money and time on both sides.

The pre-stocked counter near your table

The far-away kitchen is slow, so the restaurant does something clever: it prepares its most popular dishes ahead of time and keeps them at a little serving counter right next to the dining room. Any table can be served those dishes almost instantly, and the far kitchen isn't bothered at all.

But there's a catch. Because these dishes are pre-packaged and handed out to lots of different customers, they're all identical copies. You can't ask the counter to make yours special on the spot. And a shared package can't know that it's you, right now, reaching toward the dessert.

In web terms: That nearby counter is a cache — popular page-pieces prepared once and stored on machines physically close to users all over the world, so they load fast without a round-trip to the origin server. The catch is real: because a cached piece is identical for everyone, the brain that decides "this particular reader needs this piece next" can't live inside the piece. It has to live somewhere else.

Check-in: it asked why pre-made, identical, shared-by-everyone dishes make the "rush the exact dish" trick harder than plates cooked fresh just for me. I reasoned that each copy needs a precise name, that changing the recipe means a new name, and that too many variations would overflow the counter. It confirmed all three map to real caching problems — then sharpened the point I was circling: a shared package can't know that it's me, reaching right now.

Your own personal busser

So the restaurant gives each table its own little helper — a busser standing right at your side. The pre-made dishes still come from the shared counter (fast, identical for all), but your busser is the one who watches you, notices you're reaching toward the dessert, grabs that package off the counter, and sets it down in the right spot — swapping the "coming soon" card for the real plate.

Why put the smarts in a personal busser instead of the shared counter? Because a counter trying to serve everyone would have to constantly poll every customer and shove plates at people who don't want them yet — wasteful and slow. Far better to let the counter stay simple and let each table's busser pull only the plate that customer actually needs, exactly when they need it.

In web terms: That busser is a small program running inside your own browser that watches your scrolling, fetches the right cached pieces, and slots them into the page — no round-trip to the far server, no duplicate plates, and all the per-reader smarts kept right next to the reader. Pull what this person needs; don't push everything at everyone.

Check-in: it asked why the smarts belong in a personal busser rather than being built into the shared counter. I said a counter serving everyone would have to keep polling all the diners and pushing out plates nobody ordered yet — while a busser handles one diner and grabs the shared plate only when it's actually needed. That's the recommendation exactly, it said: pull, don't push, and keep the per-person smarts at the table.

The dish has to be edible — and not upset your table

Two easy-to-miss demands when the busser swaps that card for the real dessert:

1. It must be actually edible, right away — not a gorgeous plastic display model of a dessert that looks perfect but you can't eat. It arrives with its fork, ready to dig into.
2. Rushing it mustn't disturb what you already had going. If you'd poured your wine, tucked your napkin, and started your salad, sliding in the dessert must not knock over your glass or reset your whole table.

Get either wrong and it's maddening: the busser moves your salad to make room and you lose your place; or brings your fries with no ketchup, there but useless.

In web terms: A delivered section isn't just a picture — it has buttons that click and boxes you can type in. When it drops in, it has to actually work immediately (not just look right), and it must not wipe out what you'd already done — your scroll position, or text you'd half-typed into a form higher up the page.

Check-in: it asked me to picture how it would feel wrong if the restaurant botched either demand. I rattled off: the busser moves my salad to make room and I lose my place; it interrupts my conversation; it brings fries with no ketchup, or fajitas with no tortillas; it clears my silverware for the next dish. It confirmed those split cleanly into the two failure modes — clobbering what I was already doing, and delivering something I can't actually use.

So what is the document actually proposing?

Here's the thing to keep in mind: the restaurant hasn't been built yet. The proposal is a plan — it carefully writes down the problem (everything above), compares several different ways to pull it off (a few flavors of "personal busser," a "smart local dispatcher," and others), recommends a combination (the personal-busser-at-your-table approach as the default), rejects a crude idea (the equivalent of "to rush the dessert, just scream at the kitchen to freeze everything" — too disruptive), and lays out a step-by-step test plan: build a little, prove it works, then build the next bit.

It's the blueprint and the taste-test schedule, argued carefully, before anyone builds the real thing.

Why this matters for React on Rails

Faster pages that cost less to deliver, that stay interactive the instant they appear, that don't waste a single byte re-sending what you already have — that's the whole game for teams serving real traffic. Getting streaming, caching, and interactivity to cooperate is one of the harder problems in modern web rendering, and it's exactly the kind of thing React on Rails exists to make practical for Rails teams.

If you want to see the real engineering behind the analogy, the design investigation lives here:

• Design proposal: Scroll-priority streaming: architecture investigation and recommendation
• Related: selective hydration prototype (#4740) and the original question (#4385)

And if you want to understand your own next hard thing this way, grab the prompt from the companion post: Teach Me With Analogies.