ReviewOS

stacks/stx

The #1809 runtime handoff guard is fragment-path only — a full-document swap still lands on a page whose runtime never runs

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

Verified against 9ccbd4e46c.

#1809 added the guard that hands off to a real page load when a fetched fragment needs a runtime the current page has not loaded. It sits inside the fragment branch and nowhere else:

packages/router/src/client.ts:588:    if(isFragment){
packages/router/src/client.ts:592:      if(!window.stx&&fragmentNeedsRuntime(html,declaredRuntime)){

:592 is the only call site of fragmentNeedsRuntime in the file. The full-document swap path has no equivalent check.

Nor is the store bundle re-executed on that path:

$ grep -rn 'data-stx-stores\|data-stx-composables' packages/router/
0

Symptom

Navigating from a runtime-free page to a runtime-needing one via the full-document path leaves the destination's client script dead. In a real app (stacksjs/analyticshq) that is /compare → /dashboard: the destination throws defineStore is not defined, its onMount never runs, so the /api/me call never fires and the auth redirect never happens. The page renders and is quietly inert. No error surfaces to the user.

I have a solid reproduction of the symptom and the source read above; I have not isolated the exact mechanism by which the document path skips the runtime, so treat the trace as "guard is missing here" rather than a full diagnosis.

Why it is about to matter more

The same app has five pages whose layout group is contradicted by a hand-written stx-layout meta, which routes ordinary in-app navigation down the full-document path rather than the fragment path — i.e. straight into the unguarded branch. See stacksjs/analyticshq#35.

Suggested fix

Apply the same fragmentNeedsRuntime-style handoff before a full-document swap, and re-execute the store/composable bundles when the destination declares them.

#1809 (the fragment-path fix this extends).

22 days ago

Fixed in 260c4ce. Your read was right — the guard was fragment-only — and I isolated the mechanism you'd left open.

Why the document path loses a runtime it actually has

A document is not a fragment: it genuinely carries the destination's runtime. This path then throws it away, in two places, before anything can run it:

// prepareRoutedBodyScripts
if(s.hasAttribute('src')){s.remove();return}                                   // :915
if(isSignalsRuntimeScript(s,text)||text.indexOf('__stxRouter')!==-1){s.remove();return}  // :918

Both are correct when the current page already has a runtime — the incoming copy is redundant. When it has none, nothing puts one back. Note the serve-mode runtime is <script data-stx-runtime src="/_stx/runtime.js">, so it is dropped by the first line, before the runtime check is even reached.

That is exactly your defineStore is not defined: defineStore lives on window.stx, so it is the runtime that is missing, not the store bundle.

The fix

Same hand-off as the fragment branch, placed before the swap and before _cleanupContainer — so we neither dispose the outgoing page's scopes nor half-replace the document and then reload.

Unlike a fragment, the document holds the answer directly, so there is nothing to infer from markers or ask the server for:

function documentShipsRuntime(doc,html){
  if(doc&&doc.querySelector&&doc.querySelector('script[data-stx-runtime]'))return true;
  return html.indexOf("'use strict';var cloakStyle")!==-1
    ||(html.indexOf('_cleanupContainer')!==-1&&html.indexOf('signals runtime loading')!==-1);
}

The attribute covers both emitted shapes; the content sniff behind it covers a document rendered by a server too old to stamp it.

On the store bundles

You were right that they are not re-executed here — process.ts anchors both data-stx-stores and data-stx-composables immediately after the runtime, so they sit in <head> while prepareRoutedBodyScripts only walks the body.

But that is not what caused your symptom, and I left it alone rather than fixing it blind: getStoreScript bundles the whole stores directory, so every page carries the same bundle — a page that has a runtime already has the stores. It would only bite if bundles ever became per-page. Worth its own issue if you want it tracked.

A testing note

The tests assert on the hand-off itself rather than on a completed swap, because no full-document swap can complete under very-happy-dom: its attributes collection yields entries with no name, so the router's body-attribute copy throws setAttribute(undefined) and the router's own catch falls back to location.href — which would have made both outcomes look identical. The fixture also keeps <body> bare for the same reason. Real browsers return proper Attr nodes, so this is a harness limit, not an stx bug.

Verified against the parent commit: all four hand-off tests fail there, and both must-keep-working tests pass — so the guard is doing the work, and it is not just firing on everything.

Full suite 10664 pass in a clean worktree; the two failures are the pre-existing crosswind-arbitrary-values case and a package-exports timeout that passes in isolation.

Sign in to comment on this issue.