ReviewOS

stacks/stx

fix(serve): fragment extraction is hardcoded to the first `<main>`…last `</main>`, so `router.container` is only honoured client-side and page structure silently decides whether SPA nav works

#1853
Closed glennmichael123 opened this 22 days ago · 1 comment
22 days ago

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 shouldIntercept

The option is public and documented — packages/stx/src/site-builder/types.ts:180:

/** DOM selector for the SPA swap target. Defaults to `main`. */
container?: string

and 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

  1. Make fragment extraction read the same container selector the client does. Thread the resolved router.container from getRouterInjectOptions() into the extraction block at serve.ts:2926-2960 instead of the hardcoded <main> regex + lastIndexOf('</main>').
  2. 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.ts already has findElementEnd() doing exactly this (with comment/raw-text skipping); reuse it.
  3. Ship an explicit outlet: <StxOutlet /> (or honour data-stx-content on the server side as a first-class marker), so a layout can mark the swap region without spending its <main> element on it.
  4. 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.warn from shouldIntercept when getContainer() is null), instead of the current silent return false at client.ts:1220.
  5. Add a regression test for a page with two <main> elements and for a page with container: '[data-stx-content]', asserting the emitted X-STX-Fragment body is the container's inner HTML in both cases.

Related: #1789, #1833

Sign in to comment on this issue.