Route Metadata & Head

## Head entries are data, not markup you write A document's `<head>` carries statements *about* the page rather than the content of it: the `<title>`, `<meta>` entries, `<link>` relations, and inline configuration a browser or a machine consumer reads before it reaches the body. In a meta-framework you rarely hand-write that block per URL. Each **route segment** — the root shell, every layout between it and the page, and the page itself — **declares the head entries it is responsible for, as data**, and the framework turns the collected declarations into markup. "As data" is the load-bearing part. A segment does not emit `<meta ...>` markup wherever it happens to sit in the component tree; it supplies a structure the framework owns: a title value, a list of `meta` entries, a list of `link` entries. Because the framework holds them as values it can compare entries across segments, collapse duplicates, let a deeper segment override a shallower one, apply a title pattern, and control the order in which they are written. Markup emitted from somewhere inside the body gives it none of that. ## How one URL's head is assembled For a request, a typical meta-framework does four things in order: 1. **Match** the URL against the route table, producing a chain of segments from the root down to the leaf. 2. **Collect** each matched segment's head declaration; a segment that declares nothing contributes nothing. 3. **Merge** the collected declarations into a single set, resolving the cases where two segments describe the same entry. 4. **Serialise** the merged set into the `<head>` of the document, ahead of the body. The consequence worth internalising is that **the head belongs to the matched chain, not to the page alone**. A root shell owns what every URL needs — a character set, a viewport entry, a site-wide title pattern, a default description. A section layout owns what its pages share. The leaf contributes only what is genuinely specific to this URL. The same page reached under a different parent can legitimately end up with a different head. ## Declarations are static or computed Two shapes appear across frameworks: - **Static values** — the segment supplies a fixed structure known without running anything per request: a title for an about page, a default description for a section. - **Computed values** — the segment supplies a function the framework calls with the matched route parameters and, where supported, the data that route loaded. A detail route builds its title from the record it is about. Computed entries are what make per-URL metadata possible on a dynamic route, and they are also what put the head on the critical path, because nothing can be serialised until its inputs resolve. ## Why it happens on the server, ahead of the body The head is emitted at the top of the document, so it has to be resolved before the body is written. That ordering is what makes the served bytes self-describing: | approach | what the served HTML contains | who sees the right values | |---|---|---| | one shared static template | the same head for every URL | everyone, but it is never URL-specific | | per-segment declarations rendered on the server | this URL's merged head | every consumer, including ones that never run scripts | | values assigned by client code after load | the pre-change head | only consumers that execute scripts | The third row is the common mistake. Assigning the document title from client code does update the browser tab, and for an in-app concern that is fine. But the HTML actually served still carries the old values, so anything that reads the document without executing JavaScript — many crawlers, link-preview fetchers, feed and archive tools, a plain HTTP client in your terminal — sees them. The way to check is to fetch the URL as a plain request and read the returned bytes, not to inspect the live document in a browser, where the client has already repaired it. ## What holding entries as data buys the framework - **Deduplication** — an entry declared at two levels is emitted once rather than twice. - **Patterns** — a parent can wrap whatever title a descendant supplies, so pages declare only their own part. - **Deterministic order** — the emitted block does not shuffle between renders. - **Reuse across rendering modes** — the same declarations produce the head whether the page is built ahead of time or rendered per request. - **Feeding other outputs** — a generated preview image or a listing file can read the same values instead of restating them. ## The mental model to carry into an interview URL → matched chain of segments → each segment's declaration → merged → serialised into the head before the body. Everything else in this area hangs off that one pipeline: the precedence rules when two segments collide, what happens when an entry is computed from loaded data, why a page built ahead of time keeps the head it was built with, and what streaming does to the whole arrangement. If you can draw the pipeline, you can reason your way to the rest.