Summary
The SPA swap region is located two different ways. On the client it is o.container (configurable, with [data-stx-content] and main as fallbacks). On the server, fragment extraction ignores the configured container entirely and string-slices from the first <main …> to the last </main>. Three things follow: setting router: { container: '[data-stx-content]' } produces a fragment the client then injects into the container (duplicating the chrome); a page with two <main> elements swaps the wrong span; and a page with no <main> silently disables SPA navigation for every link on it, at HTTP 200 with no warning.
Impact (real app)
analyticshq shipped the no-<main> case to production. resources/views/dashboard.stx:1138-1142, written when it was found:
<main>, not a<div>: this is the SPA router's swap container. router.container defaults to 'main', and getContainer() returning null makes shouldIntercept bail, so every link on this page was doing a full document load. The four sibling app pages already declare their own<main>; the dashboard was the only one that did not. Same element, same classes -- only the tag name changes.
Because the rule is structural and unenforced, it also had to be written into the layouts as prose. resources/layouts/marketing.stx:53-55:
The single router container. Pages must NOT declare their own
<main>: fragment extraction slices from the first<main>to the LAST</main>, so a second one makes the router swap the wrong span and duplicate the chrome.
resources/layouts/auth.stx:19-22 repeats it, and adds that pages must "yield their own width wrapper instead" — a layout decision forced by routing, because the two layouts disagree about max-width and neither can express that on the element the router owns.
So: one shipped regression where every link on the highest-traffic page did a full document load, three duplicated structural warnings across three files, and no page in the app can use <main> for its semantic meaning.
Evidence in stx
Server, packages/bun-plugin/src/serve.ts:
2928 const mainOpenMatch = fragment.match(/<main\b[^>]*>/i)
2929 const mainCloseIdx = fragment.lastIndexOf('</main>')
...
2957 const mainStart = mainOpenMatch.index! + mainOpenMatch[0].length
2960 fragment = fragment.slice(mainStart, mainCloseIdx).trim()No reference to the configured container anywhere in that block, and the whole thing is behind if (mainOpenMatch && mainCloseIdx !== -1) (:2927) — when it does not match, the full body ships as the "fragment".
Client, packages/router/src/client.ts:
45 var defaults={container:'main', …}
47 var containerSel=o.container;
252 function getContainer(){
253 return document.querySelector(containerSel)||document.querySelector('[data-stx-content]')||document.querySelector('main');
254 }
848 var newContent=doc.querySelector(containerSel)||doc.querySelector('[data-stx-content]')||doc.querySelector('main');
1220 if(!getContainer())return false; // inside shouldInterceptThe option is public and documented — packages/stx/src/site-builder/types.ts:180:
/** DOM selector for the SPA swap target. Defaults to `main`. */
container?: stringand it is merged into the injected config at packages/bun-plugin/src/serve.ts:2303-2305. stx's own app-shell already relies on the non-main form — packages/stx/src/app-shell.ts:232 emits window.__stxRouterConfig={container:'[data-stx-content]'} around <div data-stx-content> at :245 — which the fragment path cannot extract.
Prior art
None of these infer the swap region from the document's tag names:
- Vue Router —
<router-view>is an explicit component. - Nuxt —
<NuxtPage>. - Angular —
<router-outlet>. - React Router —
<Outlet />. - Turbo/Hotwire —
<turbo-frame id="…">, an explicit element with an id.
All of them let a page contain any number of <main> elements, and none make the router silently no-op when a tag is missing.
Ask
- Make fragment extraction read the same container selector the client does. Thread the resolved
router.containerfromgetRouterInjectOptions()into the extraction block atserve.ts:2926-2960instead of the hardcoded<main>regex +lastIndexOf('</main>'). - Locate the region by matching the element, not by slicing to the last close tag — track tag depth from the opening tag so a nested same-tag element cannot terminate the slice early or late.
packages/stx/src/signal-processing.tsalready hasfindElementEnd()doing exactly this (with comment/raw-text skipping); reuse it. - Ship an explicit outlet:
<StxOutlet />(or honourdata-stx-contenton the server side as a first-class marker), so a layout can mark the swap region without spending its<main>element on it. - Warn loudly when a rendered page yields no container — both at render time ("page X declares no
<container>; SPA navigation is disabled for this route") and in the client (console.warnfromshouldInterceptwhengetContainer()is null), instead of the current silentreturn falseatclient.ts:1220. - Add a regression test for a page with two
<main>elements and for a page withcontainer: '[data-stx-content]', asserting the emittedX-STX-Fragmentbody is the container's inner HTML in both cases.