The Softshell Log.

Everything softshell does is a change to one journey: a URL goes in, a Response comes out. Pick a request and watch the real pipeline decisions replay — matching, parallel loaders, framework signals, boundaries, and streaming. Each behavior below was added by a numbered chapter.

The motivation. File-based routing is the visible part of Next.js, but it is not the deepest idea. The deeper idea is that a framework owns the journey from an incoming request to a delivered application. React, by itself, describes UI — it does not answer the full application question: someone requested this URL; what should happen now?

The kernel is the smallest useful framework idea, and everything later attaches to it:

Layouts attach before render. Data loading enriches the context. Caching wraps the work. Streaming changes how render produces the body. Hydration adds browser JavaScript to the shell. If we understand this kernel, every later feature has a place to land — skip it and the project becomes a pile of features with no spine.

The motivation. Two traps: build on Express/Fastify and you learn their request objects instead of framework internals; build inside a serverless platform and you add hosting concerns before the mental model is stable. The middle path — the core speaks the Web Fetch API:

src/core/handle.ts — the shape everything keys offhandle(request: Request): Promise<Response>

Route matching needs a URL. Rendering needs context. Headers fit Headers. Nothing framework-shaped is inherently Node-shaped — so the core uses the least surprising standard, and adapters translate at the edges. That one decision is why the serverless adapter (Entry 011) ends up nearly empty, and why streaming (Entry 022) later slots in without friction: a Web Response body was always allowed to be a stream.

Day 1 shipped a deliberately tiny set: project config, a route module type, a route table, a render function, a core handler, a Node dev adapter, a serverless-shaped fetch adapter, and one route component. No bundler, no watcher, no hydration, no file routing — each was postponed until it became the concept being studied. (The bundler's day finally arrived in Entry 024.)

• tsx runs TypeScript directly — no build pipeline before the runtime pipeline is understood
• DOM libs in tsconfig — not for browser code, but because the core uses Web-standard Request/Response/ReadableStream types
• dependencies: react, react-dom — that's all Day 1 needs

The motivation. A framework needs a way to talk about a route before it can render one. A route is not a file — a file is where a route comes from. A route is executable UI associated with a URL pattern. The type came before the discovery mechanism on purpose:

src/core/types.ts — grown by nearly every chapter sinceexport type RouteModule = {
  path: string;
  filePath: string;            // 024: so the client bundler can re-import it
  segments: RouteSegment[];    // 017: parsed pattern, not just a label
  layouts: LayoutModule[];     // 018: the shells that wrap the page
  component: ComponentType<RouteProps>;
  errorBoundary?: ErrorModule;      // 021
  notFoundBoundary?: NotFoundModule;// 021
  loadingBoundary?: LoadingModule;  // 022
  load?: RouteLoader;               // 019
  title?: string | ((ctx: RenderContext) => string | Promise<string>);
};

Components receive a prepared RenderContext — request, url, params — because routes should not parse requests from scratch. The framework normalizes raw request information; the app receives a clean interface.

Before file-based routing, softshell had a hardcoded table and a matcher that was string equality. Less exciting than glob scanning — and exactly the point: the runtime path had to exist before file discovery became a way of generating the table automatically (Entry 016).

src/core/routes.ts — Day 1, the whole routing systemexport const routes: RouteModule[] = [
  {
    path: "/",
    component: Page,
    title: "Softshell",
  },
];

export function matchRoute(pathname: string): RouteModule | undefined {
  return routes.find((route) => route.path === pathname);
}

Watch what happens to these seven lines across the log: the array gets generated from the filesystem (016), find by equality becomes segment matching with params (017), and the list gains a specificity sort (017). The question never changes.

Without a React component, the framework could return a hardcoded HTML string and prove only that we can write an HTTP server. The first page displays the current pathname from the render context — a small detail proving the request crossed the framework boundary into React. The page handles no sockets, writes no headers. It is just UI:

Day 1 used renderToString: direct, buffered, perfect for the first lesson (Entry 022 replaces it with a stream). Three ideas hide in one line:

const appHtml = renderToString(createElement(route.component, { ctx }));

The framework creates the element (components don't render because they exist); request-derived information enters React through a controlled prop; react-dom turns the tree into markup. Then a document shell wraps it — browsers receive documents, not components. The shell is tiny but it is the right conceptual slot: metadata, stylesheets, client bundles, and hydration payloads all attach there in later chapters.

src/core/render.tsx (Day 1 shape) — the document shellfunction createDocument(input: { appHtml: string; title: string }): string {
  return `<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>${escapeHtml(input.title)}</title>
  </head>
  <body style="margin:0">
    <div id="root">${input.appHtml}</div>
  </body>
</html>`;
}

function escapeHtml(value: string): string {
  return value
    .replaceAll("&", "&amp;")
    .replaceAll("<", "&lt;")
    .replaceAll(">", "&gt;")
    .replaceAll('"', "&quot;")
    .replaceAll("'", "&#39;");
}

That escapeHtml on the title is the first appearance of a recurring truth: once the framework owns document generation, it owns the safety boundaries. Titles can carry dynamic, user-influenced values (Entry 017's dynamic titles prove it: Blog: ${params.slug}); unescaped, a slug could inject markup into the head. Entry 024 applies the identical rule to hydration data.

One explicit function owns the application-level journey. Every future feature will be a change to this exact function, so it is worth reading in its original, complete Day-1 form:

src/core/handle.ts — Day 1, in full (compare with today's version in Entries 020–024)export async function handle(request: Request): Promise<Response> {
  const url = new URL(request.url);            // 1. parse
  const route = matchRoute(url.pathname);      // 2. match

  if (!route) {
    return new Response("Not found", {         // 3. own the failure path
      status: 404,
      headers: { "content-type": "text/plain; charset=utf-8" },
    });
  }

  const ctx: RenderContext = { request, url, params: {} };   // 4. context

  const html = await renderRoute(route, ctx);  // 5. render

  return new Response(html, {                  // 6. respond
    status: 200,
    headers: { "content-type": "text/html; charset=utf-8" },
  });
}

Step 3 deserves its own sentence: a framework is not just happy-path rendering; it owns failure paths too. That one plain-text 404 grows into an entire arc — Entry 020 gives it vocabulary, Entry 021 gives it UI, Entry 023 gives it subtree semantics.

Node's HTTP server speaks IncomingMessage/ServerResponse; the core wants Request/Response. The adapter bridges — including the stream boundary, where request bodies exist only for methods that carry one:

src/adapters/node.tsreturn new Request(url, {
  method,
  headers,
  body: hasBody ? Readable.toWeb(req) : undefined,   // GET/HEAD have no body
  duplex: hasBody ? "half" : undefined,
} as RequestInit);

The TypeScript casts at the stream boundary are exactly the kind of edge case that belongs in an adapter, not in the framework core. The core does not need to know Node exists.

The executable entrypoint contains no route or render logic — if it did, the core would be leaking outward. The whole architecture reads in one loop:

src/dev.tsconst server = createServer(async (req, res) => {
  const request = nodeRequestToWebRequest(req, origin);
  const response = await handle(request);
  await writeWebResponse(res, response);
});

Many modern runtimes call a handler shaped fetch(Request) → Response. Because the core already has that shape, the serverless-facing adapter is almost nothing:

src/adapters/fetch.tsimport { handle } from "../core/handle.js";
export default { fetch: handle };

The first working page creates false confidence unless the missing pieces are named. Day 1's gap list became the curriculum — and this page's later chapters are that list getting crossed off:

• file-based routing → Entry 016
• dynamic route params → Entry 017
• layouts → Entry 018
• streaming → Entry 022
• hydration → Entry 024
• Server/Client component split — future
• caching — future
• dev module graph / HMR — future

As the code grows more complicated, the model must stay simple:

Everything else — all eleven chapters that follow — is an elaboration of those four lines.

Next.js is productive precisely because it hides enormous machinery — which is what makes it hard to understand deeply. Creating one file in a Next app touches route trees, compiler graphs, server/client boundaries, payload formats, and deployment targets all at once. Softshell isolates one layer at a time, and each future feature gets motivated from the pain of the current implementation instead of arriving as magic.

Adding a page meant editing the hardcoded table — fine for one route, un-framework-like for two. The chapter-selection principle used ever since: the next problem is the smallest one that naturally follows from what exists. Hence: a route manifest.

The motivation. Without file routing, adding an About page takes two steps: create the component, then remember to edit the framework's route table. That second step is the smell — the developer's intent is already present in the file they created.

Discovery is allowed to care about files; serving should care about routes. Discovery runs once at startup, producing matchable metadata the request world consumes:

Discovery is three honest jobs: find the files, translate locations into URLs, and turn files into executable route metadata. The scanner is a plain recursive walk —

src/core/file-routes.ts — a route file is only a CANDIDATE, not yet a routeasync function findPageFiles(dir: string): Promise<string[]> {
  const entries = await readdir(dir, { withFileTypes: true });
  const files = await Promise.all(
    entries.map(async (entry) => {
      const fullPath = join(dir, entry.name);
      if (entry.isDirectory()) return findPageFiles(fullPath);
      return entry.isFile() && entry.name === "page.tsx" ? [fullPath] : [];
    }),
  );
  return files.flat();
}

— the path translation is where the convention lives (note the POSIX normalization: route paths must be URL-shaped even on filesystems with other separators) —

src/core/file-routes.ts — file location becomes URLfunction filePathToRoutePath(appDir: string, filePath: string): string {
  const routeFilePath = relative(appDir, filePath).split(sep).join(posix.sep);
  const routeDir = posix.dirname(routeFilePath);

  if (routeDir === ".") return "/";      // src/app/page.tsx is the root
  return `/${routeDir}`;
}

— and the import is the moment a filename becomes executable code, with the framework's first contract enforced loudly at startup instead of mysteriously at request time:

src/core/file-routes.ts — a file becomes a routeconst module = (await import(pathToFileURL(filePath).href)) as PageModule;

if (!module.default) {
  throw new Error(`${filePath} must default export a React component`);
}

return {
  path: routePath,
  segments: routePathToSegments(routePath),
  component: module.default,
  ...
};

The handler stopped importing a global table and became a factory — a closure that receives its routes. Setup work happens once; request-time work stays focused. A function that accepts dependencies beats a function that imports global state: tomorrow the manifest can come from a build step, a watcher, or a test, and handle never changes.

src/core/handle.tsexport function createHandler(routes: RouteManifest): RequestHandler {
  return async function handle(request: Request): Promise<Response> { ... };
}

The motivation. /blog/hello-softshell and /blog/routing-internals are the same kind of page; only one segment varies. One file should serve them all:

The manifest evolved from "path as string" to "path plus parsed segments" — brackets are parsed once at discovery, never re-interpreted per request:

src/core/routes.tsexport function routePathToSegments(path: string): RouteSegment[] {
  return splitPathname(path).map((segment) => {
    const dynamicMatch = /^\[([A-Za-z0-9_]+)\]$/.exec(segment);
    if (dynamicMatch) return { kind: "dynamic", name: dynamicMatch[1] };
    return { kind: "static", value: segment };
  });
}

Matching now produces information. Comparing segment lists is a walk where static segments demand equality and dynamic segments capture — the first time the matcher's job is extraction, not just selection:

src/core/routes.ts — matchSegments, where params are bornfunction matchSegments(routeSegments, pathnameSegments): RouteParams | undefined {
  if (routeSegments.length !== pathnameSegments.length) return undefined;

  const params: RouteParams = {};

  for (const [index, routeSegment] of routeSegments.entries()) {
    const pathnameSegment = pathnameSegments[index];

    if (routeSegment.kind === "dynamic") {
      params[routeSegment.name] = decodeURIComponent(pathnameSegment);  // capture
      continue;
    }
    if (routeSegment.value !== pathnameSegment) return undefined;       // demand
  }

  return params;   // matching PRODUCED data: { route, params } flows to ctx
}

Two details worth noticing: segments are URL-decoded here (hello%20world arrives in the page as "hello world" — the framework normalizes raw request text before the app sees it), and pathnames are normalized before matching so /about/ and /about are the same route. Dynamic routes also created an ordering problem: /blog/new could fit /blog/[slug], so the manifest is sorted once at discovery:

src/core/routes.ts — sortRoutesBySpecificityreturn [...routes].sort((left, right) => {
  const lengthDifference = right.segments.length - left.segments.length;
  if (lengthDifference !== 0) return lengthDifference;      // more segments first

  const staticDifference =
    countStaticSegments(right.segments) - countStaticSegments(left.segments);
  if (staticDifference !== 0) return staticDifference;      // static beats dynamic

  return left.path.localeCompare(right.path);               // stable tie-break
});

Once routes are patterns, match order matters — the literal route always beats the pattern that could swallow it.

The motivation. Real apps want shared UI around pages — the same nav on every page, the same section chrome on every blog page. Without layouts, every page repeats it, and ownership blurs: does the page own the whole screen, or only the leaf content?

What makes wrapping possible at all is one prop. A page receives the route context; a layout receives the context plus whatever route content belongs inside it:

src/core/types.ts — children is the whole trickexport type LayoutProps = {
  ctx: RenderContext;
  children: ReactNode;   // the wrapped subtree — page, or another layout
};

In React terms a layout is not special — just a component rendering children. In framework terms it is special because softshell decides which layouts wrap which page, and that decision is filesystem interpretation — so it belongs to discovery, not to the request handler. For each page, walk root → page directory and keep the layout.tsx files that exist:

src/core/file-routes.ts — the chain of directories a page lives underfunction directoriesFromAppRoot(appDir: string, routeDir: string): string[] {
  const routeDirPath = relative(appDir, routeDir);
  if (!routeDirPath) return [appDir];

  const directories = [appDir];
  let currentDir = appDir;

  for (const segment of routeDirPath.split(sep)) {
    currentDir = join(currentDir, segment);
    directories.push(currentDir);      // root -> … -> page dir, in order
  }
  return directories;
}

// for src/app/blog/[slug]/page.tsx this checks, in order:
//   src/app/layout.tsx          ✓ exists -> kept
//   src/app/blog/layout.tsx     ✓ exists -> kept
//   src/app/blog/[slug]/layout.tsx  ✗ doesn't -> skipped

The manifest stores that chain parent → child (natural reading order); the renderer builds the tree leaf-first, so a single .reverse() puts the root layout outermost:

src/core/render.tsx — the wrap that everything later reuseslet element = createElement(route.component, { ctx, data });
for (const layout of [...route.layouts].reverse()) {
  element = createElement(layout.component, { ctx, children: element });
}
// RootLayout( BlogLayout( BlogPostPage ) )

The rendered result for /blog/hello-softshell shows three regions from three files on one screen — root nav, blog heading, post content. That is the feature. And it is the App Router's biggest idea: not file-based routing, tree-based routing.

The motivation. A blog page doesn't want to render a slug; it wants the post the slug points to. The slug is a lookup key, not content. Without a framework convention, every page invents its own data story. The pipeline gained a slot — after matching, before rendering:

src/app/blog/[slug]/page.tsxexport async function load({ params }: RouteProps["ctx"]) {
  return { post: getPost(params.slug) };
}
// the page receives it as a prop:
export default function BlogPostPage({ ctx, data }: RouteProps<BlogPostData>) { ... }

Softshell doesn't care what the loader does — file read, database, API. The contract is only: if the route exports load, call it with ctx; the return value becomes page data. On the wire that contract is two lines in the handler and one widened prop type:

src/core/handle.ts + src/core/types.ts — the entire v1 mechanism// the handler owns the pipeline, so it runs the route's request-specific work:
const data = route.load ? await route.load(ctx) : undefined;
const html = await renderRoute(route, ctx, data);

// and the page's contract gains a second prop:
export type RouteProps<TData = unknown> = {
  ctx: RenderContext;   // framework context: request, url, params — always there
  data: TData;          // route-specific app data — whatever load() returned
};

The split between those two props matters: ctx is supplied by softshell for every route; data is supplied by this route's declaration. Pages without loaders get undefined and stay simple. Deliberately absent in v1, each with its future chapter: layout loaders (023), caching, typed inference from load's return type to the page's data prop. Once this slot existed, the real framework questions became askable: what if it throws? can layouts load too? can data stream in late? Entries 020–023 are those questions, answered.

The motivation. Data loading created a second kind of failure. /blog matches no route — a plain 404. But /blog/missing-post matches /blog/[slug]; the loader runs; only then does the app discover the resource doesn't exist. Different failure modes deserve different vocabulary:

src/app/blog/[slug]/page.tsx — the loader speaks framework verbsif (requestedSlug === "latest") {
  redirect("/blog/hello-softshell");   // -> 307 + Location, no render
}
const post = getPost(requestedSlug);
if (!post) {
  notFound();                          // -> 404, no render
}
post.title;   // TypeScript allows this: notFound() returns `never`

Both helpers throw — and that's the deep lesson. Why throwing, and not returning a special object? Because a return value must be inspected by every caller up the chain, and the page would have to stay typed as "post might be missing" even after the loader already decided. A throw escapes the entire nested call stack in one move, and the framework catches it at the one place that owns responses:

src/core/navigation.ts — the whole moduleexport class NotFoundSignal extends Error {
  readonly kind = "notFound";
  constructor() { super("Softshell notFound()"); }
}

export class RedirectSignal extends Error {
  readonly kind = "redirect";
  constructor(
    readonly location: string,
    readonly status: RedirectStatus = 307,
  ) { super(`Softshell redirect(${location})`); }
}

export function notFound(): never {
  throw new NotFoundSignal();
}

export function redirect(location: string, status: RedirectStatus = 307): never {
  throw new RedirectSignal(location, status);
}

export function isNavigationSignal(error: unknown): error is NavigationSignal {
  return error instanceof NotFoundSignal || error instanceof RedirectSignal;
}

Note the deliberate privacy: the signal classes exist, but app code never constructs them — it says what it wants (notFound()) and the framework owns the mechanism. The never return type is doing real work too: TypeScript knows that branch cannot return, so after if (!post) notFound(); the compiler narrows post to defined — a thrown signal became type information. The catch side is one discriminating question:

src/core/handle.ts — the line between signal and bug} catch (error) {
  // Framework-owned control flow signals are not bugs.
  if (isNavigationSignal(error)) {
    if (error instanceof RedirectSignal) {
      return redirectResponse(error);       // -> 3xx + Location header
    }
    return renderNotFoundResponse(...);     // -> 404
  }
  // Anything else is an unexpected failure — a REAL bug. It must not be
  // swallowed by the framework's own catch.
  return renderErrorResponse(...);          // -> 500 (Entry 021)
}

A redirect is an HTTP decision, not a render result — the response is status: 307, headers: { location } with no body at all. Try /blog/latest and /blog/missing-post in the simulator and watch the two signals take different exits.

The motivation. Entry 020 could decide not to render, but couldn't render the decision — 404s were plain text, and unexpected bugs fell through to a generic 500. The nav and chrome that wrapped every healthy page simply vanished. But because the route matched, the framework already knows the layout chain, so it can keep the surviving shells and replace only the failed leaf:

Two files, one machinery — a notFound() signal renders the nearest not-found.tsx (404); any unexpected throw renders the nearest error.tsx (500), receiving the Error as a prop. Boundaries differ from layouts in a crucial way, and the difference is visible as two different directory walks:

src/core/file-routes.ts — nearest-boundary walk (vs. the collect-all layout walk)async function findNearestBoundaryForPage(appDir, pageFilePath, filename) {
  const directories = directoriesFromAppRoot(appDir, dirname(pageFilePath));

  // directoriesFromAppRoot is ordered root -> page, so iterate from the END
  // to reach the page's closest ancestor boundary first.
  for (let index = directories.length - 1; index >= 0; index -= 1) {
    const candidate = join(directories[index], filename);
    if (await fileExists(candidate)) return candidate;
  }
  return undefined;
}

The render side reuses Entry 018's layout wrap wholesale — a fallback is just a different leaf riding the same chain. That generalization (wrap any leaf, not only the page) is the entire refactor this chapter required of the renderer:

src/core/render.tsx — renderFallbackDocumentexport function renderFallbackDocument(input: {
  layouts: LayoutModule[];
  layoutData: unknown[];
  ctx: RenderContext;
  leaf: ReactElement;        // an error OR not-found component — any leaf
  title: string;
}): string {
  const appHtml = renderToString(
    wrapWithLayouts(input.layouts, input.layoutData, input.ctx, input.leaf),
  );
  return documentPrefix(input.title) + appHtml + DOCUMENT_SUFFIX;
}

And the handler branch, including the trap most first implementations miss — what if the fallback itself throws? Rendering an error boundary for the error boundary would loop forever; the framework must bottom out at plain text. Softshell's escape hatch was verified by deliberately breaking error.tsx and watching /blog/boom degrade to a text 500 instead of hanging:

src/core/handle.ts — renderErrorResponse, with the escape hatchfunction renderErrorResponse(route, ctx, cause, layouts, layoutData): Response {
  const boundary = route.errorBoundary;
  const error = toError(cause);

  if (!boundary) {
    throw error;   // no boundary: rethrow so the raw error still surfaces as a 500
  }

  try {
    const html = renderFallbackDocument({
      layouts, layoutData, ctx,
      leaf: createElement(boundary.component, { ctx, error }),
      title: "Something went wrong",
    });
    return new Response(html, { status: 500, headers: HTML_HEADERS });
  } catch {
    // Escape hatch: if the boundary (or a surviving layout) throws while
    // rendering the fallback, degrade to plain text instead of looping.
    return new Response("Internal Server Error", {
      status: 500,
      headers: TEXT_HEADERS,
    });
  }
}

The motivation. Look at what renderToString actually is: a function that cannot return until the entire tree has rendered. The header finished in a microsecond. The nav finished. The layouts finished. And all of it sits in a server-side string, going nowhere, because one stats query needs 1.2 more seconds. The user stares at a blank tab — not because the server is slow, but because the slowest part of the page holds every finished part hostage:

The fix required no new transport. An HTTP body was never required to be a single buffer — it is bytes over time. And softshell's core has spoken Web Response since Entry 002, whose body may be a ReadableStream. The boundary drawn on Day 1 was already streaming-shaped; only the renderer wasn't.

Streaming only matters if something can say "I'm not ready." Mechanically, that is all Suspense is: a component, mid-render, hands React a promise instead of returning UI. In React 19 the verb is use():

src/app/blog/[slug]/page.tsx — a component that suspendsfunction StatsPanel({ stats }: { stats: Promise<PostStats> }) {
  const resolved = use(stats);   // pending? -> React SUSPENDS this subtree
  return (
    <div>
      <span>{resolved.views.toLocaleString()} plays</span>
      ...
    </div>
  );
}

// and in the page body, the boundary that catches it:
<Suspense fallback={<StatsSkeleton />}>
  <StatsPanel stats={data.stats} />
</Suspense>

When use() meets a pending promise, React abandons that subtree's render, walks up to the nearest <Suspense>, renders its fallback instead, and subscribes to the promise. Everything outside the boundary keeps rendering. When the promise settles, React re-renders just the abandoned subtree — and on the server, ships the result as a late chunk into the same response (§3). Where does a pending promise come from? The loader stops awaiting things on purpose:

src/app/blog/[slug]/page.tsx + src/app/slow/page.tsx — the deferring pattern// blog: post blocks, stats deliberately do not
return {
  post,                                  // awaited chain: getPost() already ran
  stats: loadPostStats(requestedSlug),   // a promise, NOT awaited — 1.2s away
};

// slow: the WHOLE page defers
export function load(): SlowPageData {
  return {
    report: new Promise((resolve) => {
      setTimeout(() => resolve({ batches: 7, unitsPacked: 2140, ... }), 2000);
    }),
  };
}
export default function SlowPage({ ctx, data }: RouteProps<SlowPageData>) {
  const report = use(data.report);   // top-level suspension: loading.tsx holds the spot
  ...
}

This quietly redefined the loader. Its question is no longer "what data does this page need?" but "which data must block the first byte, and which may arrive later?" Await it in load() = blocking. Return the raw promise = deferred. That split is a real API decision the app author makes per field.

HTTP writes the status line first — HTTP/1.1 200 OK — before any body bytes. Once the first chunk leaves, the number is spoken for. This single constraint explains the pipeline's entire ordering, including why loaders that can notFound() are awaited rather than deferred:

React's API is built around exactly this moment. renderToReadableStream returns a promise of a stream, and that promise resolves when the shell — everything outside Suspense boundaries — has rendered:

src/core/render.tsx — the shell contract// This promise resolves when the SHELL is ready. If the shell itself throws
// (a layout, or a page with no loading boundary), the promise REJECTS and the
// handler can still pick a real status code — no bytes have been sent yet.
const appStream = await renderToReadableStream(element, {
  onError(error) {
    // Errors inside an already-flushed Suspense boundary land here. The
    // status code is spoken for by then, so all we can do is log.
    console.error("softshell: error while streaming", error);
  },
});

That one await is why Entry 021's boundaries survived streaming untouched: a shell failure rejects into the handler's existing catch, and the error page goes out with a genuine 500. The two onError comments are the deadline stated twice — before the first byte, errors choose status codes; after it, they can only be logged.

View-source on /slow while it loads and the whole trick is legible. The shell arrives with the boundary rendered as its fallback, wrapped in markers:

view-source, first flush (~4ms) — the boundary is a fallback + a promise of more<!--$?--><template id="B:0"></template>
  <!-- loading.tsx skeleton HTML: the stamp, the bars … -->
<!--/$-->

Two seconds later, into the same open response, React emits the real content — hidden — plus a one-line script that swaps it in:

view-source, late chunk (~2.0s) — content + the swap<div hidden id="S:0">
  <!-- the real page: "This page took two seconds. The shell didn't." … -->
</div>
<script>$RC("B:0","S:0")</script>

$RC ("replace content") is a few hundred bytes of vanilla JavaScript React inlines once per response: find the template's boundary, remove the fallback, move the hidden nodes into place. No bundle, no hydration, no framework runtime — the swap works on a page with zero client JavaScript of its own, which is what made this chapter buildable a full chapter before hydration existed. The measured result:

Entry 007's document shell was a template string around a finished app string. It could not survive contact with a stream — there is no finished string to wrap. It became a streaming envelope: emit the head immediately, pump React's chunks through untouched, close the document when React's stream ends:

src/core/render.tsx — wrapAppStreamInDocument, the pumpreturn new ReadableStream<Uint8Array>({
  async start(controller) {
    controller.enqueue(encoder.encode(documentPrefix(input.title, ...)));

    const reader = input.appStream.getReader();
    for (;;) {
      const { done, value } = await reader.read();
      if (done) break;
      controller.enqueue(value);          // React's chunks pass through untouched
    }

    controller.enqueue(encoder.encode(ROOT_CLOSE));      // </div>
    // (Entry 024 later slots the hydration payload exactly here)
    controller.enqueue(encoder.encode(DOCUMENT_TAIL));   // </body></html>
  },
});

Buffered rendering did not disappear — it retreated to where it is correct. renderFallbackDocument (error/not-found pages) still uses renderToString: fallbacks are small, and their status codes must precede their bytes anyway.

With all the machinery above in place, the marquee feature costs almost nothing. Discovery finds the nearest loading.tsx with Entry 021's boundary walk — literally the same function, third filename:

src/core/file-routes.ts — one added line of discoveryconst [layouts, errorBoundary, notFoundBoundary, loadingBoundary] =
  await Promise.all([
    discoverLayoutsForPage(appDir, filePath),
    discoverBoundary<ErrorProps>(appDir, filePath, "error.tsx"),
    discoverBoundary<NotFoundProps>(appDir, filePath, "not-found.tsx"),
    discoverBoundary<LoadingProps>(appDir, filePath, "loading.tsx"),   // new
  ]);

…and the renderer wraps the page leaf in a framework-owned boundary. When Next's docs say "loading.tsx automatically wraps your page in Suspense," this is the literal, complete mechanism:

src/core/render.tsx — the entire featurelet leaf: ReactElement = createElement(route.component, { ctx, data });

if (route.loadingBoundary) {
  leaf = createElement(Suspense, {
    fallback: createElement(route.loadingBoundary.component, { ctx }),
    children: leaf,
  });
}

Layouts sit outside that boundary — so they stream immediately while the page streams in behind its skeleton. Pages keep declaring inner boundaries by hand for finer grain, exactly like the blog's stats panel in §1.

• Post-shell errors can't change the status. An error inside an already-flushed boundary lands in onError, gets logged, and the client keeps the fallback. Every streaming framework hits this wall; there is no fix, only the discipline of putting status-deciding work before the shell.
• Signals lose power inside boundaries. A notFound() thrown from a component inside Suspense after first flush is just another post-shell error — which is why softshell keeps interrupts in loaders, where they run before the deadline.
• The pump ignores backpressure. The envelope pushes chunks as fast as React produces them instead of honoring pull(). Fine at teaching scale; a production pump would respect the consumer.

Give a page several boundaries on different clocks — say related posts (0.5s), stats (1.2s), comments (2.5s) — and the wire teaches two lessons at once:

Completion order is safe because every swap targets its boundary by id — $RC("B:2","S:2") doesn't care who finished first. Three ovens, one waiter, dishes served as they're done. The second lesson is about hydration: in softshell there is no per-boundary hydration schedule. The payload is the trailer, so the module can't execute until the stream closes — meaning the page looks progressively done but becomes alive all at once, at the end. Every click before that moment hits markup with no listeners and dies — even on shell UI whose markup existed from millisecond four.

That dead-click window is exactly what React's selective hydration exists to fix: hydrate the shell while boundaries still stream, hydrate each island as its chunk lands, and if the user clicks a not-yet-hydrated island, prioritize it and replay the click. Softshell can't do any of that, and the blocker is our own wire format — the trailer requires the whole stream before the client knows its props. Simple protocol, late interactivity: a priced trade-off, and a candidate future chapter.

The motivation. The blog layout wants the archive's post count — layout-owned data that belongs to every page under /blog. Without layout loaders the options were repetition (each page fetches it) or buried I/O (the layout reaches into data during render, invisible to the framework). Same move as Entry 019, one level up: layouts export load(ctx).

src/core/handle.ts — parallel, not waterfallconst [layoutOutcomes, pageOutcome] = await Promise.all([
  Promise.all(route.layouts.map((layout) => runLoader(layout.load, ctx))),
  runLoader(route.load, ctx),
]);

Parallelism is safe by construction: every loader receives only ctx, never another loader's result — the chain shares a request, not a data pipeline. But naive Promise.all has a flaw for this job: it rejects on the first failure and throws away the information of which one failed and what the others returned. So every loader runs through a wrapper that converts throws into values:

src/core/handle.ts — outcomes, not exceptions// Every loader (layout or page) either produced data or captured its throw.
// Capturing keeps two properties: all loaders run to completion in parallel,
// and we know exactly WHICH one failed.
type LoaderOutcome =
  | { ok: true; data: unknown }
  | { ok: false; error: unknown };

async function runLoader(load, ctx): Promise<LoaderOutcome> {
  if (!load) return { ok: true, data: undefined };
  try {
    return { ok: true, data: await load(ctx) };
  } catch (error) {
    return { ok: false, error };
  }
}

Knowing which segment failed is what enables the failure semantics:

The truncation itself is almost anticlimactic — the outermost failure wins, and one slice() expresses "everything below it could never have rendered":

src/core/handle.ts — the subtree cutconst failedLayoutIndex = layoutOutcomes.findIndex((outcome) => !outcome.ok);

if (failedLayoutIndex !== -1) {
  const failed = layoutOutcomes[failedLayoutIndex] as { ok: false; error: unknown };

  return failureToResponse(
    route,
    ctx,
    failed.error,
    route.layouts.slice(0, failedLayoutIndex),                      // surviving shells
    layoutOutcomes.slice(0, failedLayoutIndex).map(outcomeData),    // …and their data
  );
}

The demo layout carries both the data and the trap in one loader:

src/app/blog/layout.tsx — a layout that loads (and can be detonated)export function load({ url }: RenderContext): BlogLayoutData {
  // A deliberate trap: a layout loader failure poisons the whole blog
  // subtree. Try /blog/hello-softshell?break-layout=1
  if (url.searchParams.has("break-layout")) {
    throw new Error("Intentional explosion in the blog layout loader…");
  }

  return {
    postCount: listPosts().length,
    archiveLabel: "cassette archive",
  };
}

export default function BlogLayout({ data, children }: LayoutProps<BlogLayoutData>) {
  // data belongs to THIS layout — the page never sees it
  ...
}

Try ?break-layout=1 in the simulator. A correctness fix fell out for free: fallback documents now receive surviving layouts' data — under Entry 021 they re-rendered layouts data-blind, harmless then, a crash once the blog layout actually read data.postCount. The 404 page still shows the post-count chip because that loader genuinely succeeded on that request.

The motivation, stated as bluntly as possible: put an onClick anywhere in the app and nothing happens. Here is the actual component that now lives on the home page:

src/app/page.tsx — HydrationCounterfunction HydrationCounter() {
  const [count, setCount] = useState(0);

  return (
    <div>
      <button
        type="button"
        onClick={() => setCount((current) => current + 1)}
      >
        Press me
      </button>
      <span>
        pressed {count} times ·{" "}
        {count > 0
          ? "this page is hydrated and alive"
          : "dead until the client bundle hydrates"}
      </span>
    </div>
  );
}

Before this chapter, the server rendered it happily. useState works in a server render — it returns the initial value; there is no update loop because a server render is a single pass, so setCount is created and simply never called. Then renderToReadableStream serialized the tree, and this — exactly this — is what reached the browser:

view-source: what the wire actually carried<button type="button" style="border:1.5px solid #3A2516;...">Press me</button>
<span style="...">pressed 0 times · dead until the client bundle hydrates</span>

Look at what is missing. No onclick attribute. No reference to a handler. Nothing. And this is not React being lazy — it is a fact about the medium. onClick={() => setCount(...)} is a closure: a function object in the server's memory holding a reference to a state cell in the server's memory. HTML is text. There is no HTML syntax that can represent "a function, closed over live memory, on another machine." (React could emit onclick="..." strings, but a string can't close over setCount — that whole idea collapses immediately.) Markup can carry the result of behavior, never behavior itself. Until this chapter, softshell was a very elegant HTML printer.

Why "rendered twice" and not "shipped once"? Because the click handler must live in browser memory as a real closure over a real state cell. The only way to get it there is to run the code that creates it — HydrationCounter itself — in the browser. And if the browser is going to re-run components anyway, running them with the same props means React computes the same tree the server did — and hydrateRoot can then adopt the DOM that already exists instead of rebuilding it. No pixels change; the page switches from printed to alive. That single principle dictates the entire chapter's shopping list:

Requirement one: the browser needs HydrationCounter. That function lives in src/app/page.tsx. So the naive plan is: serve that file and let the browser import it. Entry 003 postponed bundling "until bundling is the concept we are actually studying" — this is that day, so let's actually study it: walk the naive plan into every wall it hits, because a bundler is nothing more than the machine that removes these four walls.

Wall 1 — the browser cannot read our disk. The dev server serves responses, not a filesystem. Before anything else, every module the page needs must be reachable over HTTP. Fine — we could add a static route per source file. Keep going.

Wall 2 — bare specifiers. Look at the first line of the page module:

src/app/page.tsx, line 1 — legal in Node, illegal in a browserimport { useState } from "react";
// Browser: TypeError — Failed to resolve module specifier "react".
// Relative references must start with "/", "./", or "../".

"react" is a bare specifier. Node resolves it with an algorithm: walk up the directory tree probing node_modules/react, read its package.json, interpret the "exports" map, pick a file. Browsers implement none of that — a browser import must be a URL. Something has to resolve every bare specifier to a real file before the browser ever sees the code.

Wall 3 — the source is not JavaScript. Even resolved, the file can't execute: browsers speak neither TypeScript nor JSX. Types can be erased, but JSX is a real syntax transform — what you write is not what runs:

the jsx transform — what "<button onClick={...}>" actually is// what you wrote:
<button onClick={() => setCount((c) => c + 1)}>Press me</button>

// what must execute (jsx: "automatic" targets react/jsx-runtime):
import { jsx } from "react/jsx-runtime";
jsx("button", { onClick: () => setCount((c) => c + 1), children: "Press me" });

Wall 4 — the module graph fans out. page.tsx imports react; hydration needs react-dom/client; react-dom imports scheduler; the blog page imports posts.ts and navigation.ts… Loading modules natively means the browser discovers each import only after downloading its importer — a waterfall of serial round trips, hundreds deep for React alone.

When does it run? At build time — for softshell, once at dev-server startup, exactly like route discovery and for exactly the same reason (Entry 016: interpret the filesystem before requests arrive, never during them). Requests are served from memory. This is the same phase boundary the manifest taught, applied to code instead of metadata:

Softshell uses esbuild — one function call, no config file. Every option below is one of the four walls being removed:

src/core/client-bundle.ts — the entire bundler integrationconst result = await build({
  stdin: {
    contents: entrySource,        // the entry is a STRING — see §2; never touches disk
    resolveDir: process.cwd(),    // where bare-specifier resolution starts (Wall 2)
    loader: "ts",
    sourcefile: "softshell-client-entry.ts",
  },
  bundle: true,                   // follow the whole import graph (Walls 1 + 4)
  write: false,                   // keep the output in memory; the kernel serves it
  format: "esm",
  platform: "browser",            // pick "browser" fields when packages offer both
  jsx: "automatic",               // the transform from Wall 3, targeting react/jsx-runtime
  define: { "process.env.NODE_ENV": '"development"' },
  logLevel: "silent",
});

return result.outputFiles[0].text;

Two lines deserve extra attention. define exists because React's own entry point is written for Node:

node_modules/react-dom/index.js (paraphrased) — why `define` is not optionalif (process.env.NODE_ENV === "production") {
  module.exports = require("./cjs/react-dom.production.js");
} else {
  module.exports = require("./cjs/react-dom.development.js");
}
// Browsers have no `process` — this line would throw at runtime.
// `define` textually replaces the expression at BUILD time, so the
// condition becomes "development" === "production": statically false,
// and the dead branch is eliminated from the bundle entirely.

And one resolution wrinkle: softshell's imports end in .js (import ... from "../core/types.js") even though the files are .ts — the NodeNext convention from Entry 003. esbuild mirrors TypeScript's rule: when ./types.js doesn't exist, it tries ./types.ts. Without that, not one file in the repo would bundle.

esbuild needs an entry point. What is it? It can't be a single page — the bundle is built once but must serve every route. So the entry must import all pages and layouts and expose them keyed by route. The tempting shortcut is a hand-written registry file… and that is Entry 016's smell in a new costume: create page.tsx, then remember to also register it for the client. The developer's intent is already in the filesystem; the framework already extracts it — discoverRoutes(). So the entry is generated from the manifest. The only missing ingredient was that discovery threw file paths away after importing modules; now every module type records where it came from:

src/core/types.ts — the one-field change that makes generation possibleexport type RouteModule = {
  path: string;
  // Absolute path of the page source file. Discovery keeps it so the client
  // bundler can re-import the same module for the browser.
  filePath: string;
  ...
};

The generator walks the manifest, emits one import per distinct file (the root layout appears in every route's chain but must be imported once — same module identity matters for React), and builds the registry:

src/core/client-bundle.ts — generateEntrySource, the dedup coreconst identifiers = new Map<string, string>();

const identifierFor = (filePath: string): string => {
  let id = identifiers.get(filePath);
  if (!id) {
    id = `m${identifiers.size}`;
    identifiers.set(filePath, id);
    imports.push(`import ${id} from ${JSON.stringify(filePath)};`);
  }
  return id;
};

for (const route of routes) {
  const componentId = identifierFor(route.filePath);
  const layoutIds = route.layouts.map((l) => identifierFor(l.filePath));
  const loadingId = route.loadingBoundary
    ? identifierFor(route.loadingBoundary.filePath)
    : "undefined";

  registryEntries.push(
    `  ${JSON.stringify(route.path)}: { component: ${componentId}, ` +
    `layouts: [${layoutIds.join(", ")}], loading: ${loadingId} },`,
  );
}

For the app as it exists today, the generated module — the string handed to esbuild's stdin — is this:

the actual generated entry (paths shortened)import { hydrate } from ".../src/client/hydrate.ts";
import m0 from ".../src/app/blog/[slug]/page.tsx";
import m1 from ".../src/app/layout.tsx";        // imported ONCE, used by all four routes
import m2 from ".../src/app/blog/layout.tsx";
import m3 from ".../src/app/about/page.tsx";
import m4 from ".../src/app/slow/page.tsx";
import m5 from ".../src/app/slow/loading.tsx";  // loading.tsx ships too — see §4 for why
import m6 from ".../src/app/page.tsx";

hydrate({
  "/blog/[slug]": { component: m0, layouts: [m1, m2], loading: undefined },
  "/about":       { component: m3, layouts: [m1],     loading: undefined },
  "/slow":        { component: m4, layouts: [m1],     loading: m5 },
  "/":            { component: m6, layouts: [m1],     loading: undefined },
});

Note what is absent: error.tsx and not-found.tsx. Fallback documents don't hydrate (they carry no bundle and no payload — verified by grepping the 404/500 responses for client references: zero), so their components never ship. The kernel serves the finished bundle like any other framework-owned response:

src/core/handle.ts — the bundle is just another Responseif (options.clientBundle && url.pathname === CLIENT_BUNDLE_PATH) {
  return new Response(options.clientBundle, {
    status: 200,
    headers: { "content-type": "text/javascript; charset=utf-8" },
  });
}

Two honest observations, both recorded as future chapters rather than fixed quietly. Everything ships. The 1,091 KB dev bundle (unminified development React is most of it) contains every loader and even posts.ts — open the bundle and the blog "database" is legible inside it. Today that's demo data; in a real app this exact mechanism would ship connection strings. Which modules may reach the client? is the question React Server Components exists to answer, and softshell now owns the evidence for why it must be asked. And no code splitting — visiting /about downloads the blog page too.

Requirement two: the same props. The components are now in the browser, but props live in server memory — data.post came out of a loader that ran on the server and will not run again in the browser. The only bridge between the two memories is bytes in the document. So: embed the props. The naive plan is one line — JSON.stringify(data) — and like §1, the honest move is to walk it into its walls:

what JSON.stringify silently does to loader dataJSON.stringify({
  post:  { slug: "hello-softshell" },   // ✓ plain data survives
  stats: loadPostStats(slug),           // ✗ a Promise -> {}   (silently!)
  fn:    () => {},                      // ✗ a function -> key dropped (silently!)
})
// -> '{"post":{"slug":"hello-softshell"},"stats":{}}'

That empty {} is a bomb. The blog page's stats panel calls use(data.stats) — Entry 022's deferred-streaming pattern — and use() requires a thenable. Hand it {} and hydration throws. The general lesson arrives before the fix:

Softshell's wire format is one tagged marker. The serializer walks the data; plain values pass through; a thenable becomes { $softshell: "promise", value }:

src/core/payload.ts — serializeForClient, the whole protocolexport async function serializeForClient(value: unknown): Promise<unknown> {
  if (value === null || value === undefined) return value;

  if (typeof value === "function") {
    console.warn("softshell: loader data contained a function; dropped");
    return undefined;                       // loudly, not silently like JSON
  }

  if (typeof value !== "object") return value;

  if (isThenable(value)) {
    const outcome = await settledWithin(value, 25);

    if (outcome.state === "pending")  return { $softshell: "pending-promise" };
    if (outcome.state === "rejected") return { $softshell: "rejected-promise" };

    return {
      $softshell: "promise",
      value: await serializeForClient(outcome.value),   // recurse: nested promises work
    };
  }

  if (Array.isArray(value)) {
    return Promise.all(value.map((entry) => serializeForClient(entry)));
  }

  const out: Record<string, unknown> = {};
  for (const [key, entry] of Object.entries(value)) {
    out[key] = await serializeForClient(entry);
  }
  return out;
}

But wait — serializing a promise's resolved value requires the promise to have resolved. When is that guaranteed? This is the chapter's most elegant timing fact. Recall Entry 022's envelope: the document is prefix → React's chunks → suffix. React's stream does not end until every Suspense boundary has streamed its content — meaning every promise a component consumed via use() has settled by the time the stream closes. So the payload is built exactly there, as the final chunk:

src/core/render.tsx — the trailer rides the stream's clockconst trailer = options.hydrate
  ? async () => {
      const payload: HydrationPayload = {
        routePath: route.path,
        params: ctx.params,
        data: await serializeForClient(data),          // promises are settled NOW
        layoutData: (await serializeForClient(layoutData)) as unknown[],
      };
      return payloadScriptTag(payload);
    }
  : undefined;

// ...inside the envelope, after React's chunks finish:
controller.enqueue(encoder.encode(ROOT_CLOSE));                    // </div> — #root closes
if (input.trailer) {
  controller.enqueue(encoder.encode(`\n    ${await input.trailer()}`));
}
controller.enqueue(encoder.encode(DOCUMENT_TAIL));                 // </body></html>

The settledWithin race covers the one case the stream's clock does not: a loader deferred a promise that no component ever consumed. Nothing awaited it, so it may still be pending — and the payload must never hold the response open waiting for it:

src/core/payload.ts — never let the payload block the streamconst pending = Symbol("pending");
const timeout = new Promise<typeof pending>((resolve) => {
  setTimeout(() => resolve(pending), timeoutMs);
});

try {
  const value = await Promise.race([promise, timeout]);
  return value === pending ? { state: "pending" } : { state: "fulfilled", value };
} catch {
  return { state: "rejected" };
}

What actually rides the wire on /blog/hello-softshell — captured from the real response:

view-source, last chunk of the stream</div>    <!-- #root closed; the container's children stay pristine -->
<script>window.__SOFTSHELL__ = {
  "routePath": "/blog/[slug]",       // registry key — the client never re-matches
  "params": { "slug": "hello-softshell" },
  "data": {
    "post": { "slug": "hello-softshell", "title": "Hello from Softshell data loading", ... },
    "stats": { "$softshell": "promise",
               "value": { "views": 1755, "rewinds": 3, "tapeWear": "well loved" } }
  },
  "layoutData": [null, { "postCount": 2, "archiveLabel": "cassette archive" }]
};</script>
</body>

Three placement decisions are visible in that capture, and each one prevents a specific bug:

• Outside #root. hydrateRoot matches the container's children one-to-one against the tree it computes. A foreign <script> node inside the container is a guaranteed mismatch — so the envelope closes the root div first, then emits the payload.
• Escaped. A post titled </script><script>steal() would otherwise terminate the payload script early and execute. payloadScriptTag rewrites every < to < — identical bytes to JSON's parser, inert to the HTML parser. Entry 007 escaped the title; the rule generalizes: data is now part of the document, so data is now an injection surface.
• Ordered by platform semantics. The bundle's <script type="module"> sits in the <head> — but module scripts are deferred by default: fetched during streaming (a free head start), executed only after parsing completes, which is after the payload chunk ran. No DOMContentLoaded listener, no callback dance.

Requirement three: the same shape. The bundle's generated entry calls hydrate(registry), and the runtime is a point-by-point transcription of server decisions — every line below answers "how did the server do it?":

src/client/hydrate.ts — the browser half, nearly in fullexport function hydrate(registry: ClientRegistry): void {
  const payload = window.__SOFTSHELL__;
  if (!payload) return;                       // no payload -> stay a static page

  const entry = registry[payload.routePath];  // server matched; client just looks up
  if (!entry) return;

  // Rebuild the render context. The URL comes from the browser itself;
  // params come from the payload. The Request cannot cross the wire, so the
  // client fabricates an equivalent one.
  const ctx: RenderContext = {
    request: new Request(window.location.href),
    url: new URL(window.location.href),
    params: payload.params,
  };

  const data = revive(payload.data);
  const layoutData = payload.layoutData.map((entryData) => revive(entryData));

  // Entry 018's wrap order + Entry 022's loading-Suspense + Entry 023's
  // per-layout data. Any difference in shape here is a hydration mismatch.
  let element: ReactElement = createElement(entry.component, { ctx, data });

  if (entry.loading) {
    element = createElement(Suspense, {
      fallback: createElement(entry.loading, { ctx }),
      children: element,
    });
  }

  for (let index = entry.layouts.length - 1; index >= 0; index -= 1) {
    element = createElement(entry.layouts[index], {
      ctx,
      data: layoutData[index],
      children: element,
    });
  }

  hydrateRoot(document.getElementById("root")!, element);
}

Read it against the server renderer and the mirroring is total — including loading.tsx: even on a page whose content long since streamed in, the client must recreate the <Suspense> wrapper, because the server rendered one and the shape must match. That is why loading components ship in the bundle. The reviver is the protocol's other half:

src/client/hydrate.ts — revive, marker by markerfunction revive(value: unknown): unknown {
  if (value === null || typeof value !== "object") return value;
  if (Array.isArray(value)) return value.map((entry) => revive(entry));

  const record = value as Record<string, unknown>;

  if (record.$softshell === "promise") {
    return Promise.resolve(revive(record.value));   // use() works again
  }
  if (record.$softshell === "rejected-promise") {
    const rejected = Promise.reject(new Error("softshell: rejected on the server"));
    rejected.catch(() => {});   // pre-handle: no unhandledrejection console spam,
    return rejected;            // but use() still observes the rejection
  }
  if (record.$softshell === "pending-promise") {
    return new Promise(() => {});                   // honest: it never settled there either
  }

  const out: Record<string, unknown> = {};
  for (const [key, entry] of Object.entries(record)) out[key] = revive(entry);
  return out;
}

What hydrateRoot then actually does, since this chapter should not treat it as magic: React renders the element tree in memory, then walks the container's existing DOM in lockstep with it — for each fiber, instead of createElement-ing a DOM node, it claims the node that's already there and records it as the fiber's stateNode. Text and attributes are trusted, not rewritten (that's why nothing flickers). Listeners were never per-node to begin with — React attaches one delegated listener set at the root and routes events to fibers — so "attaching behavior" is mostly bookkeeping. If the walk desynchronizes — the computed tree says <span>, the DOM has a <div> — that is a hydration mismatch: React 19 recovers by throwing the server DOM away and client-rendering, correct but wasteful, and the console says so. The framework now makes a promise it never made before — the second render will equal the first — and mismatches are the cost of breaking it.

The deferred stats were this chapter's real mismatch test. During hydration, StatsPanel calls use() on the revived promise — technically a different, already-resolved promise object. React suspends the boundary, the microtask delivers the value, the retry renders exactly what the server streamed, the DOM matches. One prop needed a judgment call: ctx.request is streams-and-state, not data — it cannot cross. The client fabricates new Request(location.href), which is honest in spirit because components only ever read ctx.url and ctx.params. The code that actually consumes requests — loaders — never runs in the browser at all. Sit with that asymmetry: loaders are server code; components are shared code. Two kinds of functions living in one file, separated only by convention — and "only by convention" is precisely the weakness the RSC chapter will exist to fix.

What does the ignition actually change? hydrate() runs exactly once per document load, returns nothing, and alters almost nothing you can see:

Hydration buys the capability to alter, not the alteration. And one loaded gun sits in the last line: hydrateRoot returns a Root object with a .render(newTree) method — and softshell currently drops it on the floor. Client-side navigation is, mechanically, "keep that Root and call .render() with the next route's tree instead of letting the browser reload." The handle the next chapter needs is already being returned to us.

Verified, case by case: the counter clicked alive in a real browser (state update, re-render). Zero hydration warnings on / (plain page), /blog/hello-softshell (inline Suspense + revived promise), and /slow — the maximal case: an entire page inside a Suspense boundary whose content arrived two seconds into the stream, hydrating against a revived two-second-old promise. The payload's wire format was inspected byte-for-byte ($softshell markers carrying the settled values), the payload confirmed outside #root, and the 404/500 fallback documents grepped clean of any client reference. The full Entry 020–023 status matrix and the streaming timings were re-run unchanged.

• No code splitting — one bundle, every route, downloaded on first visit.
• No server/client module split — loaders and the "database" ship to every visitor. The RSC motivation now lives in the repo as a grep-able fact, not a slogan.
• No client-side navigation — links still tear down a living app to rebuild an identical shell. But notice the inventory: the browser holds every route's components, a tree-building runtime, and a wire format for route data. Soft navigation lacks exactly one ingredient — the next route's payload — and the protocol that serializes it already exists.
• No rebuild-on-change — the bundle is startup-frozen like the manifest; both await the dev-module-graph / HMR chapter.
• Wire-format gaps — Date, Map, Set, cyclic references: none survive. Real flight formats handle these; softshell documents the line it drew.
• The fetch adapter passes no bundle — serverless-shaped deployments serve pure HTML, unchanged since Entry 011 and honest about it.

Where is the code that waits to run the bundle until the deferred promises resolve? Nowhere. Three facts in three places, none aware of the other two:

Grep the repo for the coordination you'd expect — an event, a readiness flag, a Promise.all — and you find nothing. Each link is purely local; the design is the absence of that code. Two spec facts make it airtight, and neither is a network race: an inline classic <script> executes at its parse position (nothing to fetch), and a module script executes after parsing completes, always — the bundle finishes downloading at ~0.6s and then sits idle for ~1.4s while the stream is open, because "downloaded" and "eligible to run" are different states. The counterfactual proves the mechanism: had the payload itself been a module script, deferred modules run in document order — the head bundle first — and the whole design breaks. The payload being a boring inline classic script is load-bearing.

Hypothesis (Interlude 001): moving the payload from trailer to <head> should destroy streaming, because in a sequential channel anything placed before the shell must be computed before the shell can leave. Implementation: a temporary ?payload-in-head=1 trap that emitted the payload in the head and gave the serializer a 10s promise budget — genuinely waiting was the experiment. The trap was scaffolding, removed right after the measurement; the number was the point, not the feature. Measured:

First byte collapsed to exactly total time — renderToString reinvented by one placement decision. Two findings we didn't predict: the head payload carries real resolved values and hydration stays clean, so this is a slow but correct configuration — the more damning result, since nothing errors and Entry 022's entire value silently evaporates. And React still "streams" into the firehose: the skeleton and $RC swap are still in the wire, born and replaced in the same network burst — a movie fully downloaded, then played at 1000×. (The trap has since been removed — replay the experiment in the simulator.)

The general principle, now measured instead of asserted: order in a stream is a dependency schedule — head-of-line blocking, the same phenomenon that killed HTTP/1.1 pipelining, reproduced with a template string. And it only equals time because the browser is an incremental parser: a consumer that waited for complete files would render at 2.0s in either mode. The whole streaming chapter compresses to one rule:

The motivation. Click "Blog example" before this entry and watch the browser destroy a perfectly good application: a hydrated app — fibers, state, listeners — obliterated; a new document streamed and parsed; the same 1.1 MB bundle re-executed; hydration re-run from zero; and an identical root layout rebuilt from nothing. The framework has known both pages share that shell since Entry 018; the navigation model just couldn't use the knowledge. Interlude 001 took the inventory — all routes' components in the bundle, a tree-building runtime, a wire format for props, a discarded Root — and this chapter spends it.

1 — the marker is a header, not a query param. The same URL must answer as pixels or as props. A query param writes the request into the address — but the address is data the app reads (?break-layout proves loaders consume ctx.url.searchParams), so the framework would forever strip its own marker before building ctx. A header is the envelope's sticky note — a channel app code never reads:

src/core/payload.tsexport const PAYLOAD_REQUEST_HEADER = "softshell-payload";

2 — signals ride inside the envelope. HTTP redirects don't survive fetch() — the browser follows a 307 transparently and hands the runtime the target's HTML instead of saying "go elsewhere." So Entry 020's signals gain a JSON-level serialization, and title joins the payload (no new <head> will set the tab title for us):

src/core/payload.ts — the four answers a data request can getexport type NavigationEnvelope =
  | ({ kind: "render" } & HydrationPayload)
  | { kind: "redirect"; location: string }
  | { kind: "notFound" }
  | { kind: "error" };

3 — deferred promises are awaited fully, and the regression is priced. No stream ends to guarantee settlement, so the serializer's budget goes 25ms → 10s and deferred data is genuinely awaited. Measured cost: soft-navigating to /slow blocks 2.003s — worse than a hard load's 4ms shell. Mitigation: a progress bar over a still-interactive old page. Fix: the next two chapters, named now — the matcher goes isomorphic, payloads learn to stream. This entry's worst behavior is the next entries' reason to exist.

4 — plain <a> tags, upgraded by delegation. One document-level listener; the browser's default is selectively substituted, never removed:

5 — keep the Root, reconcile the tree. hydrateRoot's return value — discarded since Entry 024 — is stored, and navigation becomes one call: root.render(nextTree). React diffs against the mounted tree; the root layout is the same component in the same position, so it is not remounted — its DOM and state survive the crossing. 6 — two guards: a navigation ticket counter (rapid clicks race; a stale response must never win) and the escape hatch — anything unrecognized → window.location.assign(). The browser is always the correct fallback.

The point is what doesn't change: same matching, same parallel loaders. The data branch sits after the shared loader phase and only changes the output format:

src/core/handle.ts — outcomes become an envelope instead of a documentif (isPayloadRequest) {
  return payloadResponse(route, ctx, layoutOutcomes, pageOutcome);
}

// inside payloadResponse:
const failed = layoutOutcomes.find((o) => !o.ok) ?? (!pageOutcome.ok ? pageOutcome : undefined);
if (failed && !failed.ok) {
  return envelopeResponse(envelopeForFailure(failed.error));   // signals -> kinds
}

return envelopeResponse({
  kind: "render",
  routePath: route.path,
  params: ctx.params,
  data: await serializeForClient(pageOutcome.data, DATA_REQUEST_PROMISE_BUDGET_MS),
  layoutData: (await serializeForClient(layoutOutcomes.map(outcomeData), ...)) as unknown[],
  title: title ?? "Softshell",
});

src/client/hydrate.ts — navigate(), the whole transitionconst ticket = ++navigationSequence;
showProgress();

const response = await fetch(href, { headers: { [PAYLOAD_REQUEST_HEADER]: "1" } });
const envelope = (await response.json()) as NavigationEnvelope;

if (ticket !== navigationSequence) return;      // a newer navigation superseded us

if (envelope.kind === "redirect") {
  return navigate(envelope.location, options);  // JSON-level redirect (max 5 hops)
}
if (envelope.kind !== "render") {
  window.location.assign(href);                 // escape hatch: browser takes over
  return;
}

root.render(assembleTree(envelope, url));       // RECONCILE — the whole chapter
history.pushState({}, "", url.pathname + url.search);
document.title = envelope.title ?? "Softshell";

First hydration and every navigation share one assembleTree() — the payload-to-tree assembly from Entry 024, factored. Back/forward is the popstate event: pushState-created entries don't reload; the browser says "you handled forward, you handle back," and navigate() re-runs without pushing.

The proof is a session-clicks counter living in the root layout's header. Clicked to 3, then: home → blog → back → redirect link → back. After five soft transitions the count read 3 — and stronger, the check returned sameDomNode: true: the literal button element survived every crossing. URL and title updated per hop; /blog/latest soft-followed its JSON redirect and pushed the final location; the not-found link triggered a real hard fallback (fonts re-fetched, counter wiped to 0, server-rendered 404 boundary). The network log tells it in one glance:

• No payload caching — every soft nav re-fetches, even back/forward. The cache chapter finally has a concrete thing to cache.
• No instant skeletons — Decision 3's regression stands until the matcher goes isomorphic (026) and payloads stream (027).
• No prefetching, no scroll restoration on back — and navigating to the current page re-renders instead of short-circuiting.
• Dev-server-only — the fetch adapter ships no client runtime, so it never navigates softly.

The motivation. The registry is keyed by patterns — registry["/blog/hello-softshell"] is undefined; only "/blog/[slug]" is a key. The bridge from concrete URL to pattern is matching, and it lived only on the server: the browser held a phone book it couldn't read. The workaround was already shipping — the envelope's routePath is the server doing the lookup and mailing the answer back, one round trip per navigation, partly just to learn the destination's own identity.

The insight that made it tiny: nothing new crosses the wire. The registry's keys ARE the route patterns, and routePathToSegments is the pure parser — so the client derives its own manifest from what it already holds. Zero generator changes:

src/client/hydrate.ts — the manifest, derived at hydrate() timeclientManifest = sortRoutesBySpecificity(
  Object.keys(clientRegistry).map((path) => ({
    path,
    segments: routePathToSegments(path),
  })),
);
// the sort is NOT optional — specificity order is the matching algorithm;
// skip it and /blog/new vs /blog/[slug] could disagree with the server

The refactor: types that tell the truth. matchRoute demanded full RouteModule[] and read exactly one field. The generic bound states the real requirement — and the body did not change by one character:

src/core/routes.ts — the matcher's honest contractexport type MatchableRoute = {
  path: string;
  segments: RouteSegment[];
};

export function matchRoute<T extends MatchableRoute>(
  routes: T[],
  pathname: string,
): RouteMatch<T> | undefined { /* body: unchanged */ }

Server-side, inference picks T = RouteModule and handle.ts compiles untouched — proof the refactor changed what the types claim, not what the code does. Client-side, T = MatchableRoute. Same function, two inferred shapes; RouteModule satisfies the bound structurally, no declaration anywhere. One trap for the record: importing the type without the type modifier typechecks fine and then kills the server at startup — esbuild goes looking for a runtime export that type-erasure deleted. The compiler and the bundler disagree about what an import means; import { type MatchableRoute } keeps them aligned. (Found in review — the one real bug in this entry's diff.)

What navigate() does with it — gate before chrome, warn after truth:

src/client/hydrate.ts — three usesconst localMatch = clientManifest
  ? matchRoute(clientManifest, targetUrl.pathname)
  : undefined;

if (!localMatch) {
  window.location.assign(href);   // unknown route: zero fetch, straight out
  return;                          // (sits BEFORE the ticket and progress bar)
}

// …fetch, envelope arrives…

if (envelope.routePath !== localMatch.route.path) {
  console.warn("softshell: client manifest disagrees with server — trusting the server");
}
// warn-and-continue: the tree still assembles from envelope.routePath.
// The server stays the authority; the local answer is advisory.

Drift — what two copies of the truth costs. A matched-but-missing resource is not drift: both matchers agree /blog/missing-post fits [slug]; the loader's notFound() is a data decision (Entry 020's structure-vs-existence distinction, resurfacing). Real drift is identical functions fed different data — and the mechanism is time:

The moment the manifest crossed the wire it became two copies with independent lifetimes. The warn detects; the 025 escape hatches already recover (unknown either way → hard navigation → the reload IS the manifest update). That's Next.js's buildId strategy in embryo.

Honest billing. A normal navigation feels byte-for-byte identical to 025 — the matcher produces identity, not data; loaders are server code; the fetch wait is untouched. Even 027's skeletons will key off frame 1 of the streamed payload, not local matching. Today's yield: the unknown-route skip and the drift check. The structural yield: this is the Pages-Router architecture (which Remix, React Router, SvelteKit, Nuxt, and TanStack Router all ship today — the App Router is the outlier, not the trend), and the chapter that comes to collect is code splitting: when registry values become "chunk, go fetch it," URL → route → which chunk must be answered before any network, because that answer is the fetch being started.

Verified: typecheck with handle.ts untouched; server startup doubling as the bundle test (matcher confirmed inside the served bundle); the 025 matrix unchanged (counter survived nav + Back at 3, redirect chain pushed the final URL, titles updated); /nope produced exactly one network entry — a document navigation, no preceding payload fetch; zero drift warnings in normal operation. Code by the log's author; review found the esbuild type-import trap.

Words the log leans on as if everyone already knows them. Each card is one unit of understanding: a tight definition, then something concrete — a diagram, the raw bytes, or a knob to turn. Dotted-underlined words like this throughout the log jump down here.