stx-router 0.2.152 → 0.2.154

package/dist/client.js

@@ -21,6 +21,28 @@ export function getRouterScript() {
   var containerSel=o.container;
   var debug=!!o.debug;
   function log(){if(debug&&typeof console!=='undefined'&&console.log)console.log.apply(console,arguments)}
+
+  // \u2500\u2500 Build skew (stacksjs/stx#1772) \u2500\u2500
+  // The build that rendered THIS document, and therefore the build the runtime
+  // executing right now came from. Under bun --watch a save restarts the server,
+  // so the next navigation can fetch a fragment produced by a newer build; when
+  // the scoped-script or binding format drifted between the two, the old runtime
+  // cannot hydrate the new fragment \u2014 literal moustaches, dead bindings, stale
+  // canvas. Sporadic, and never on a clean boot.
+  //
+  // Conservative on purpose: act only when BOTH ids are known. A missing id is
+  // "no information", never "mismatch", so statically hosted output (no headers)
+  // and older servers behave exactly as before.
+  var buildMeta=document.querySelector('meta[name="stx-build"]');
+  var loadedBuild=buildMeta?(buildMeta.getAttribute('content')||''):'';
+  window.__stxBuild=loadedBuild;
+  function isBuildSkew(incoming){
+    return !!(loadedBuild&&incoming&&incoming!==loadedBuild);
+  }
+  function reloadForSkew(url,incoming){
+    log('[router] build skew: page is',loadedBuild,'server is',incoming,'\u2014 full navigation');
+    location.href=url;
+  }
   function runViewTransition(callback){
     if(!o.viewTransitions||!document.startViewTransition)return false;
     try{
@@ -216,6 +238,44 @@ export function getRouterScript() {
   // Layout-level scripts (theme, nav setup) execute on initial page load and
   // should NOT re-execute when navigating to another page with the same layout.
   var executedScriptHashes={};
+
+  // \u2500\u2500 Re-execution contract (stacksjs/stx#1773) \u2500\u2500
+  // Whether a generated script may run again after an SPA swap used to be
+  // SNIFFED from its source: does it start with '(' or ';', or mention
+  // window.stx.mount. That is a property of the emitted shape, not of intent,
+  // so every change to how scripts are wrapped was one edit away from silently
+  // reclassifying them \u2014 and the symptom of getting it wrong is a component
+  // that renders completely dead (literal moustaches, stuck :show) only on a
+  // REVISIT, because nav-away already disposed its scope.
+  //
+  // Emitters now declare it: data-stx-run="always" on self-contained scope
+  // IIFEs and mount() wrappers, which own their scope and whose registration
+  // _cleanupContainer removed on the way out. Anything unstamped falls back to
+  // the old sniff, so a page rendered by an older server behaves exactly as
+  // before.
+  //
+  // The sniff itself now asks what the script REGISTERS rather than how it is
+  // spelled (#1828). cleanupContainer deletes window.stx._scopes entries,
+  // element disposers and destroy hooks on the way out, so the scripts that
+  // must run again are exactly the ones that put a scope back. That is
+  // detectable; a leading character is not.
+  //
+  // Deliberately NOT "strip leading comments, then test the first character",
+  // which is the obvious repair and is wrong in the expensive direction. Three
+  // emitters open with a comment and MUST NOT re-run: the animation scripts
+  // register matchMedia and DOMContentLoaded listeners plus an
+  // IntersectionObserver, and the STX lifecycle runtime owns a Map of live
+  // instances. Comment-stripping would flip all three to re-running on every
+  // navigation, leaking a listener and an observer each time and resetting the
+  // instance registry \u2014 trading a silent missing component for a silent leak.
+  var REGISTERS_SCOPE=/window\\.stx\\.mount|_scopes\\s*\\[|\\.initScope\\s*\\(|__stxComponentFactories\\s*\\[/;
+  function runsAlways(declared, code){
+    if(declared==='always')return true;
+    if(declared==='once')return false;
+    if(REGISTERS_SCOPE.test(code))return true;
+    var head=code.trimStart();
+    return head.charAt(0)==='('||head.charAt(0)===';';
+  }
   function hashScript(code){
     var h=0;for(var i=0;i<code.length;i++){h=((h<<5)-h)+code.charCodeAt(i);h|=0}
     return h;
@@ -227,11 +287,99 @@ export function getRouterScript() {
     var match=code.match(/function (__stx_setup_[A-Za-z0-9_]+)\\s*\\(/);
     return match?match[1]:'';
   }
+  // Does this fetched DOCUMENT carry the signals runtime?
+  //
+  // Unlike a fragment, a document holds the answer directly, so there is
+  // nothing to infer from markers or ask the server for: look for the script.
+  // Both emitted shapes carry data-stx-runtime \u2014 inline, and the serve-mode
+  // src="/_stx/runtime.js" \u2014 with the content sniff behind it for a document
+  // rendered by a server old enough not to stamp the attribute.
+  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);
+  }
   function isSignalsRuntimeScript(script,code){
     return !!(script&&script.hasAttribute&&script.hasAttribute('data-stx-runtime'))
       ||(code.indexOf('_cleanupContainer')!==-1&&code.indexOf('signals runtime loading')!==-1)
       ||code.indexOf("'use strict';var cloakStyle")!==-1;
   }
+  // A fragment never carries the signals runtime: the server strips the runtime
+  // IIFE out of it, and every re-execution path here filters it out again. So a
+  // page that never needed a runtime cannot hydrate a fragment that does \u2014 the
+  // setup function would be defined but never invoked, scope IIFEs throw while
+  // destructuring window.stx, and every x-cloak element stays display:none
+  // forever against the cloak style shipped on EVERY page. Hand those off to a
+  // real navigation, which loads the destination's own runtime (#1809).
+  //
+  // The SERVER decides this now, and says so in X-STX-Runtime, which travels
+  // into the fragment marker as rt=1 / rt=0 so it survives the prefetch cache.
+  // It is answering a question it knows the answer to exactly \u2014 did I put a
+  // runtime in this page \u2014 where the router could only guess from markup.
+  //
+  // Guessing missed a whole page shape (#1827). Every marker below originates in
+  // a client SCRIPT, so a page with reactive syntax and no script anywhere \u2014 a
+  // <script server>-only login form built from :if / x-model / :disabled \u2014 emits
+  // none of them, while the server ships it the runtime. Whatever root marker it
+  // does get lands on <body>, which a fragment excludes by construction. So
+  //   <p :if="error" x-cloak>Invalid credentials</p>
+  // swapped into a runtime-less page keeps the x-cloak the server stamped on it,
+  // and only the runtime ever removes that: server-rendered text, in the DOM, at
+  // display:none forever.
+  //
+  // The same held for x-data on the routed container, whose scope attribute is
+  // hoisted out of the fragment body into X-STX-Container-Attrs. Asking the
+  // server covers both without either being enumerated.
+  //
+  // The sniff stays as the fallback for a server too old to declare it. Its
+  // discriminators matter. x-cloak and data-stx-scoped are NOT usable: each
+  // fragment inlines the head styles, cloak rule included, and the appearance
+  // bootstrap emits a self-contained data-stx-scoped script on pages with no
+  // reactivity at all. A bare window.stx is not usable either \u2014 the server
+  // prepends a _latestSetup=null clear script to every fragment. Any of those
+  // would make this always true and disable SPA navigation everywhere.
+  function fragmentNeedsRuntime(frag,declared){
+    if(declared==='1')return true;
+    if(declared==='0')return false;
+    if(frag.indexOf('__stx_setup_')!==-1
+      ||frag.indexOf('data-stx-scope=')!==-1
+      ||frag.indexOf('data-stx-reactive')!==-1
+      ||/=\\s*window\\.stx\\s*;/.test(frag))return true;
+    var content=stripInertRegions(frag);
+    return BARE_DIRECTIVE.test(content)||content.indexOf('{{')!==-1;
+  }
+  // Documentation is both the largest population of runtime-less pages and the
+  // likeliest to contain directive syntax as literal CONTENT, so the fallback
+  // reads past the regions where that content lives. A page of stx examples must
+  // not full-reload on every hop through the docs \u2014 that is the regression
+  // #1809 existed to remove.
+  function stripInertRegions(frag){
+    return frag
+      .replace(new RegExp('<scr'+'ipt\\\\b[\\\\s\\\\S]*?<\\\\/scr'+'ipt>','gi'),'')
+      .replace(/<style\\b[\\s\\S]*?<\\/style>/gi,'')
+      .replace(/<pre\\b[\\s\\S]*?<\\/pre>/gi,'')
+      .replace(/<code\\b[\\s\\S]*?<\\/code>/gi,'')
+      .replace(/<!--[\\s\\S]*?-->/g,'');
+  }
+  // Anchored on the whitespace before an attribute name and the = that follows,
+  // so it reads attribute POSITIONS rather than characters. Bare ':' and '@' are
+  // everywhere in ordinary content \u2014 'xlink:href', 'background: red', '10:00',
+  // an email address \u2014 and none of those sit in that position.
+  //
+  // The x- arm is deliberately open rather than a list of known directives:
+  // x-attr is a GENERIC binding prefix, so x-href / x-src / x-value / x-alt bind
+  // exactly like x-text does. Measured over the 339 rendered docs pages, the
+  // open form costs nothing over an allowlist (3 matches either way, all three
+  // of them pages the CURRENT four-marker sniff already matches because they
+  // document its marker names) while covering directives an allowlist forgets.
+  var BARE_DIRECTIVE=/\\s(?::[a-z][\\w-]*|@[a-z][\\w.-]*|x-[a-z][\\w-]*)\\s*=\\s*["']/i;
+  // The fragment marker doubles as the carrier for the server's declaration.
+  // Encoding it in the HTML rather than threading a parameter keeps it inside
+  // the one value that already reaches swap() through every path, the prefetch
+  // cache included.
+  function fragmentMarker(declared){
+    return '<!--stx-fragment'+(declared==='true'?' rt=1':declared==='false'?' rt=0':'')+'-->';
+  }
   // Record scripts from the initial page load
   document.querySelectorAll('script').forEach(function(s){
     var text=s.textContent||'';
@@ -292,7 +440,20 @@ export function getRouterScript() {
     return containerSel==='main'||containerSel==='[data-stx-content]';
   }
 
+  // Write the address bar. The mode travels in the same slot as the legacy
+  // pushState boolean: false still means "do not touch history", true still
+  // pushes, and the string 'replace' replaces. Threading a fourth argument
+  // through swap() to each of the three history sites would have been the
+  // alternative (#1807).
+  function writeHistory(mode,href){
+    if(mode==='replace')history.replaceState({},'',href);
+    else history.pushState({},'',href);
+  }
+
+  // Second arg accepts the legacy pushState boolean OR an options object
+  // { replace }. Callers inside this file still pass the boolean.
   function navigate(url,pushState,force){
+    if(pushState&&typeof pushState==='object')pushState=pushState.replace?'replace':true;
     // Lang-picker passes force=true with an already-localized path (/en/...).
     // Re-localizing would map it back to the *current* locale and no-op.
     if(!force) url=withCurrentLocale(url);
@@ -308,7 +469,7 @@ export function getRouterScript() {
     if(t.origin!==location.origin){location.href=url;return Promise.resolve(false)}
 
     if(t.pathname===location.pathname&&t.hash){
-      if(pushState!==false)history.pushState({},'',t.href);
+      if(pushState!==false)writeHistory(pushState,t.href);
       var el=document.querySelector(t.hash);
       if(el)el.scrollIntoView({behavior:'smooth'});
       return Promise.resolve(true);
@@ -344,6 +505,7 @@ export function getRouterScript() {
           return r.text();
         }).then(function(html){
           log('[router] full page fetched from cache path, len:',html.length);
+          pendingLayoutDecl={layout:layoutCache[targetPath]||'',group:layoutGroupCache[targetPath]||''};
           return swap(html,targetPath,pushState,targetHash);
         }).catch(function(err){
           console.error('[router] full page fetch error:',err);
@@ -351,6 +513,7 @@ export function getRouterScript() {
         }).finally(done);
       }
       pendingContainerAttrs=attrsCache[targetPath]||'';
+      pendingLayoutDecl=null;
       return Promise.resolve(swap(cache[targetPath],targetPath,pushState,targetHash)).then(function(){
         applyTitle(titleCache[targetPath]);
         return true;
@@ -364,11 +527,16 @@ else {
       var wantsFragment=shouldUseFragmentResponse();
       return fetch(url,{headers:wantsFragment?{'X-STX-Router':'true','Accept':'text/html'}:{'Accept':'text/html'}}).then(function(r){
         if(!r.ok)throw new Error(r.status);
+        // Before anything is parsed or swapped: a fragment from a different
+        // build must not be handed to this page's runtime (#1772).
+        var incomingBuild=r.headers.get('X-STX-Build')||'';
+        if(isBuildSkew(incomingBuild)){reloadForSkew(url,incomingBuild);return null}
         var isFragment=wantsFragment&&r.headers.get('X-STX-Fragment')==='true';
         var newLayout=r.headers.get('X-STX-Layout')||'';
         var newGroup=r.headers.get('X-STX-Layout-Group')||'';
         var newTitle=r.headers.get('X-STX-Title')||'';
         var newCAttrs=r.headers.get('X-STX-Container-Attrs')||'';
+        var newRuntime=r.headers.get('X-STX-Runtime')||'';
         // Layout change? Fetch the FULL page (no X-STX-Router header) and do full document swap
         if(isFragment&&checkLayoutChange(newLayout,url,newGroup)){
           log('[router] layout change \u2014 fetching full page for document swap');
@@ -381,12 +549,13 @@ else {
             });
           });
         }
-        return r.text().then(function(html){return{html:html,isFragment:isFragment,layout:newLayout,layoutGroup:newGroup,title:newTitle,containerAttrs:newCAttrs}});
+        return r.text().then(function(html){return{html:html,isFragment:isFragment,layout:newLayout,layoutGroup:newGroup,title:newTitle,containerAttrs:newCAttrs,runtime:newRuntime}});
       }).then(function(result){
         if(!result)return;
-        if(result.isFragment)result.html='<!--stx-fragment-->'+result.html;
+        if(result.isFragment)result.html=fragmentMarker(result.runtime)+result.html;
         if(o.cache)setCache(targetPath,result.html,result.layout,result.layoutGroup,result.title,result.containerAttrs);
         pendingContainerAttrs=result.isFragment?(result.containerAttrs||''):'';
+        pendingLayoutDecl=result.isFragment?null:{layout:result.layout||'',group:result.layoutGroup||''};
         return Promise.resolve(swap(result.html,targetPath,pushState,targetHash)).then(function(){
           // Fragment swaps carry no <head>; apply the title from the header.
           // Full-document swaps already set document.title from the <title> tag.
@@ -411,9 +580,19 @@ else {
       ||html.indexOf('data-stx-content')!==-1;
   }
 
+  // The layout and group the SERVER declared for the document about to be
+  // swapped in. Set immediately before each swap() call by whichever path
+  // fetched it, and consumed once.
+  //
+  // Threaded this way rather than as a swap() parameter, matching
+  // pendingContainerAttrs \u2014 see the note above writeHistory about the cost of
+  // adding an argument to swap() and its three call sites (#1807).
+  var pendingLayoutDecl=null;
   function swap(html,url,pushState,hash){
-    var isFragment=html.indexOf('<!--stx-fragment-->')===0;
-    if(isFragment)html=html.slice('<!--stx-fragment-->'.length);
+    var fragMark=/^<!--stx-fragment(?: rt=([01]))?-->/.exec(html);
+    var isFragment=!!fragMark;
+    var declaredRuntime=fragMark&&fragMark[1]?fragMark[1]:'';
+    if(isFragment)html=html.slice(fragMark[0].length);
     if(!isFragment&&!isStxDocument(html)){log('[router] non-stx document \u2014 full navigation to:',url);location.href=url;return Promise.resolve(false)}
     var currentContent=getContainer();
     log('[router] swap: isFragment='+isFragment+' container='+!!currentContent+' tag='+(currentContent&&currentContent.tagName)+' selector='+containerSel+' htmlLen='+html.length);
@@ -421,6 +600,14 @@ else {
 
     // Fragment mode: server returned just the page content (no document wrapper)
     if(isFragment){
+      // Before _cleanupContainer, not after: handing off later would dispose
+      // the OUTGOING page's scopes and then reload anyway. Inside doFragSwap
+      // would be later still \u2014 innerHTML is already replaced by then.
+      if(!window.stx&&fragmentNeedsRuntime(html,declaredRuntime)){
+        log('[router] fragment needs the signals runtime and this page has none \u2014 full navigation to:',url);
+        location.href=url;
+        return Promise.resolve(false);
+      }
       if(window.stx&&window.stx._cleanupContainer)window.stx._cleanupContainer(currentContent);
       function doFragSwap(){
         // Extract scripts from fragment before injecting HTML
@@ -430,15 +617,34 @@ else {
         var fragCrosswindHrefs=[];
         var fragCrosswindCSS=null;
         var cleanFrag=html.replace(new RegExp('<scr'+'ipt\\\\b([^>]*)>([\\\\s\\\\S]*?)<\\\\/scr'+'ipt>','gi'),function(m,attrs,code){
+          // A data block is not code, and everything below this line assumes it
+          // is: the body gets stashed in fragScripts, re-emitted as a pending
+          // placeholder, then wrapped in braces and executed. Wrapping a JSON
+          // object in braces reparses it as a labelled block, so its first ':'
+          // is a SyntaxError on every single fragment swap
+          // (stacksjs/stx#1801). @structuredData renders at its call site,
+          // which inside a layout is @section('content') \u2014 i.e. in the routed
+          // container \u2014 so the natural way to write it hit this.
+          //
+          // Left exactly as found rather than stripped: crawlers read
+          // structured data wherever it sits, and the browser will not execute
+          // a non-JS type anyway. Mirrors prepareRoutedBodyScripts' notion of
+          // executable, which this path never had.
+          var typeMatch=attrs.match(/\\btype\\s*=\\s*(?:"([^"]*)"|'([^']*)'|([^\\s>]+))/i);
+          var scriptType=((typeMatch&&(typeMatch[1]||typeMatch[2]||typeMatch[3]))||'').trim().toLowerCase();
+          if(scriptType&&scriptType!=='text/javascript'&&scriptType!=='application/javascript'&&scriptType!=='module')return m;
           if(code&&code.trim()&&!isSignalsRuntimeScript({hasAttribute:function(name){return name==='data-stx-runtime'&&attrs.indexOf('data-stx-runtime')!==-1}},code)){
             var slot='fragment-'+(++fragScriptId);
             var scoped=/(?:^|\\s)data-stx-scoped(?:\\s|=|$)/i.test(attrs);
-            fragScripts.push({text:code,slot:slot,setupName:generatedSetupName(code),scoped:scoped});
+            var runDecl=(attrs.match(/data-stx-run\\s*=\\s*["']?(always|once)["']?/i)||[])[1];
+            fragScripts.push({text:code,slot:slot,setupName:generatedSetupName(code),scoped:scoped,run:runDecl?runDecl.toLowerCase():''});
             // Retain scoped setup code in its inert placeholder. A placeholder
             // inside template.content is unreachable through document, so the
             // repeated component runtime must execute it for each clone.
             return '<scr'+'ipt type="application/stx-pending" data-stx-route-script="'+slot+'"'
-              +(scoped?' data-stx-scoped':'')+'>'+code+'<\\/scr'+'ipt>';
+              +(scoped?' data-stx-scoped':'')
+              +(runDecl?' data-stx-run="'+runDecl.toLowerCase()+'"':'')
+              +'>'+code+'<\\/scr'+'ipt>';
           }
           return '';
         });
@@ -498,7 +704,7 @@ else {
         currentContent.innerHTML=cleanFrag;
         // Remove old page scripts
         document.querySelectorAll('script[data-stx-page]').forEach(function(s){s.remove()});
-        if(pushState!==false)history.pushState({},'',url+(hash||''));
+        if(pushState!==false)writeHistory(pushState,url+(hash||''));
         updateNav(url);
         updateActiveLinks();
         if(o.scrollToTop&&!hash)window.scrollTo({top:0,behavior:'instant'});
@@ -541,17 +747,14 @@ else {
           // re-execute because each page has its own setup.
           var h=hashScript(code);
           var isSetup=code.indexOf('__stx_setup_')!==-1;
-          // Compute isAlreadyScoped first so the dedup check can exempt
-          // self-contained IIFE scripts. data-stx-scoped scope IIFEs
-          // (the (function(){ ... })() shape) must re-execute on every
-          // navigation. They own their own scope and won't collide
-          // with prior runs, AND _cleanupContainer deleted their
-          // entry from window.stx._scopes on the way out. Without
-          // this exemption, navigating away and back leaves the page
-          // leaf with no scope registered: bindIf/@event never re-bind
-          // and all :if branches stay visible at once.
-          // Mirrors the full-doc swap path's runAlways escape below.
-          var isAlreadyScoped=code.trimStart().charAt(0)==='('||code.trimStart().charAt(0)===';'||code.indexOf('window.stx.mount')>-1;
+          // Self-contained scope scripts must re-execute on every navigation:
+          // they own their scope, won't collide with prior runs, and
+          // _cleanupContainer deleted their entry from window.stx._scopes on
+          // the way out. Skipping one leaves the page leaf with no scope
+          // registered \u2014 bindIf/@event never re-bind and every :if branch
+          // stays visible at once. Declared by the emitter via data-stx-run,
+          // sniffed only as a fallback (#1773).
+          var isAlreadyScoped=runsAlways(entry.run,code);
           if(!isSetup&&!isAlreadyScoped&&executedScriptHashes[h]){
             log('[router] skipping already-executed script (hash dedup)');
             return;
@@ -571,7 +774,12 @@ else {
             document.body.appendChild(ns);
           }
         });
-        log('[router] scripts done. _latestSetup:', !!window.stx._latestSetup);
+        // Guarded: the router ships on every page, the signals runtime only on
+        // pages that have a client script. log() is debug-gated but its
+        // ARGUMENTS are evaluated at the call site regardless, so an unguarded
+        // read here threw on every runtime-less page \u2014 aborting the swap and
+        // falling back to a full document load (#1809).
+        log('[router] scripts done. _latestSetup:', !!(window.stx&&window.stx._latestSetup));
         // THEN fire stx:load \u2014 now _latestSetup is set and processElement has the right scope
         window.dispatchEvent(new Event('stx:load'));
       }
@@ -590,6 +798,27 @@ else {
     // Full document mode: parse with DOMParser and extract container content
     var parser=new DOMParser();
     var doc=parser.parseFromString(html,'text/html');
+    // Full documents carry the build id as a meta rather than a header, and
+    // this path also serves cached HTML, so check here too (#1772).
+    var docBuildMeta=doc.querySelector('meta[name="stx-build"]');
+    var docBuild=docBuildMeta?(docBuildMeta.getAttribute('content')||''):'';
+    if(isBuildSkew(docBuild)){reloadForSkew(url,docBuild);return Promise.resolve(false)}
+    // Same hand-off as the fragment path, for the same reason (#1809, #1839).
+    // A full document DOES carry the destination's runtime \u2014 and this path
+    // throws it away: prepareRoutedBodyScripts drops every script[src] and
+    // everything isSignalsRuntimeScript matches, on the assumption that the
+    // current page already has one. When it does not, nothing puts a runtime
+    // back, so the destination's client code dies on its first line with
+    // "defineStore is not defined" (defineStore lives on window.stx) and the
+    // page renders quietly inert \u2014 no error reaches the user.
+    //
+    // Before the swap and before _cleanupContainer, so we neither dispose the
+    // outgoing page's scopes nor half-replace the document and then reload.
+    if(!window.stx&&documentShipsRuntime(doc,html)){
+      log('[router] document needs the signals runtime and this page has none \u2014 full navigation to:',url);
+      location.href=url;
+      return Promise.resolve(false);
+    }
     var newContent=doc.querySelector(containerSel)||doc.querySelector('[data-stx-content]')||doc.querySelector('main');
     if(!newContent){location.href=url;return Promise.resolve(false)}
 
@@ -676,14 +905,33 @@ else {
       // For same-layout: swap only the container (<main>)
       var newBody=doc.querySelector('body');
       var isLayoutChange=false;
+      var declaredLayout=pendingLayoutDecl;
+      pendingLayoutDecl=null;
       if(newBody){
         var newMeta=doc.querySelector('meta[name="stx-layout"]');
         var curMeta=document.querySelector('meta[name="stx-layout"]');
         var curLayout=curMeta?curMeta.getAttribute('content'):'';
-        var newLayout=newMeta?newMeta.getAttribute('content'):'';
+        // The server's answer wins over the document's metas. We are only here
+        // because checkLayoutChange already said the group changed, based on
+        // exactly these headers \u2014 re-deriving from metas and disagreeing meant
+        // paying for the full-document fetch and then discarding the reason we
+        // made it, so the destination's <main> was swapped into the previous
+        // page's chrome (#1833).
+        //
+        // They disagree more easily than they look. The bun-plugin serve path
+        // calls a layout-less page 'default' while the client's own fallback
+        // calls it 'app'; a <head> with attributes silently skips the meta
+        // injection entirely; and the i18n path rewrites every page's group to
+        // i18n:<locale>. Any one of those leaves the metas saying "unchanged"
+        // about a document the headers said had changed.
+        var newLayout=declaredLayout&&declaredLayout.layout
+          ? declaredLayout.layout
+          : (newMeta?newMeta.getAttribute('content'):'');
         var curGroup=getCurrentLayoutGroup();
-        var newGroup=getDocLayoutGroup(doc,newLayout);
-        isLayoutChange=curGroup!==newGroup||(curLayout&&newLayout&&curLayout!==newLayout);
+        var newGroup=declaredLayout&&declaredLayout.group
+          ? declaredLayout.group
+          : getDocLayoutGroup(doc,newLayout);
+        isLayoutChange=curGroup!==newGroup||!!(curLayout&&newLayout&&curLayout!==newLayout);
       }
       var incomingSetupName=newBody?(newBody.getAttribute('data-stx')||''):'';
       // Scripts assigned through innerHTML are inert. Preserve executable
@@ -703,7 +951,7 @@ else {
           var slot='document-'+(++routedBodyScriptId);
           var setupName=generatedSetupName(text);
           if(setupName)incomingSetupName=setupName;
-          routedBodyScripts.push({text:text,runAlways:true,slot:slot,setupName:setupName});
+          routedBodyScripts.push({text:text,runAlways:true,slot:slot,setupName:setupName,run:s.getAttribute('data-stx-run')||''});
           s.textContent='';
           s.setAttribute('type','application/stx-pending');
           s.setAttribute('data-stx-route-script',slot);
@@ -810,7 +1058,7 @@ else {
       }
 
       // Push history state (before active link updates so location.pathname is current)
-      if(pushState!==false)history.pushState({},'',url+(hash||''));
+      if(pushState!==false)writeHistory(pushState,url+(hash||''));
 
       // Update active nav links
       updateNav(url);
@@ -831,6 +1079,34 @@ else {
         document.documentElement.lang=doc.documentElement.lang;
       }
 
+      // \u2500\u2500 Reconcile <html> attributes (stacksjs/stx#1798) \u2500\u2500
+      // A layout that scopes its design tokens to the root element
+      // (html.marketing { --bg: \u2026 }) needs that class to LEAVE when you
+      // navigate to a layout that doesn't want it \u2014 otherwise both token sets
+      // match at once and the second layout paints with the first one's
+      // palette. Head stylesheets are additive across a swap, so the class is
+      // the only thing disambiguating them.
+      //
+      // Only what stx wrote is touched, per the markers emitted by
+      // document-shell.ts. Diffing the whole element against the incoming
+      // document would strip the color-mode boot's dark class and
+      // data-reduced-motion, which exist only on the live page.
+      if(doc.documentElement){
+        var curRoot=document.documentElement,incRoot=doc.documentElement;
+        var tokens=function(el,attr){var v=el.getAttribute(attr);return v?v.split(/\\s+/).filter(Boolean):[]};
+        var prevCls=tokens(curRoot,'data-stx-html-class'),nextCls=tokens(incRoot,'data-stx-html-class');
+        prevCls.forEach(function(c){if(nextCls.indexOf(c)===-1)curRoot.classList.remove(c)});
+        nextCls.forEach(function(c){curRoot.classList.add(c)});
+        if(nextCls.length)curRoot.setAttribute('data-stx-html-class',nextCls.join(' '));
+        else curRoot.removeAttribute('data-stx-html-class');
+
+        var prevNames=tokens(curRoot,'data-stx-html-attrs'),nextNames=tokens(incRoot,'data-stx-html-attrs');
+        prevNames.forEach(function(n){if(nextNames.indexOf(n)===-1)curRoot.removeAttribute(n)});
+        nextNames.forEach(function(n){var v=incRoot.getAttribute(n);if(v!==null)curRoot.setAttribute(n,v)});
+        if(nextNames.length)curRoot.setAttribute('data-stx-html-attrs',nextNames.join(' '));
+        else curRoot.removeAttribute('data-stx-html-attrs');
+      }
+
       window.dispatchEvent(new CustomEvent('stx:navigate',{detail:{url:url}}));
 
       // Execute page scripts FIRST \u2014 they define setup functions and set _latestSetup
@@ -860,7 +1136,7 @@ else {
           // Skip the wrap for module scripts \u2014 they get their own scope from
           // ESM, and top-level 'import' is illegal inside a block, which
           // would throw SyntaxError before the script ever runs.
-          var alreadyScoped=text.trimStart().charAt(0)==='('||text.trimStart().charAt(0)===';'||text.indexOf('window.stx.mount')>-1;
+          var alreadyScoped=runsAlways(typeof entry==='string'?'':entry.run,text);
           ns.textContent=(hasImport||alreadyScoped)?text:'{'+text+'}';
           ns.setAttribute('data-stx-page','');
           var placeholder=entry.slot?document.querySelector('script[data-stx-route-script="'+entry.slot+'"]'):null;
@@ -964,7 +1240,8 @@ else {
         var pLayout=r.headers.get('X-STX-Layout')||'';
         var pGroup=r.headers.get('X-STX-Layout-Group')||'';
         var pTitle=r.headers.get('X-STX-Title')||'';
-        return r.text().then(function(html){return{html:isFrag?'<!--stx-fragment-->'+html:html,layout:pLayout,layoutGroup:pGroup,title:pTitle}});
+        var pRuntime=r.headers.get('X-STX-Runtime')||'';
+        return r.text().then(function(html){return{html:isFrag?fragmentMarker(pRuntime)+html:html,layout:pLayout,layoutGroup:pGroup,title:pTitle}});
       }).then(function(result){
         if(o.cache)setCache(key,result.html,result.layout,result.layoutGroup,result.title);
       }).catch(function(){}).finally(function(){delete prefetching[key]});
@@ -1063,7 +1340,7 @@ else {
       var key=cacheKey(url);
       if(!cache[key]){
         var wantsFragment=shouldUseFragmentResponse();
-        fetch(url,{headers:wantsFragment?{'X-STX-Router':'true'}:{'Accept':'text/html'}}).then(function(r){var isFrag=wantsFragment&&r.headers.get('X-STX-Fragment')==='true';var pLayout=r.headers.get('X-STX-Layout')||'';var pGroup=r.headers.get('X-STX-Layout-Group')||'';var pTitle=r.headers.get('X-STX-Title')||'';return r.text().then(function(html){return{html:isFrag?'<!--stx-fragment-->'+html:html,layout:pLayout,layoutGroup:pGroup,title:pTitle}})}).then(function(result){setCache(key,result.html,result.layout,result.layoutGroup,result.title)}).catch(function(){});
+        fetch(url,{headers:wantsFragment?{'X-STX-Router':'true'}:{'Accept':'text/html'}}).then(function(r){var isFrag=wantsFragment&&r.headers.get('X-STX-Fragment')==='true';var pLayout=r.headers.get('X-STX-Layout')||'';var pGroup=r.headers.get('X-STX-Layout-Group')||'';var pTitle=r.headers.get('X-STX-Title')||'';var pRuntime=r.headers.get('X-STX-Runtime')||'';return r.text().then(function(html){return{html:isFrag?fragmentMarker(pRuntime)+html:html,layout:pLayout,layoutGroup:pGroup,title:pTitle}})}).then(function(result){setCache(key,result.html,result.layout,result.layoutGroup,result.title)}).catch(function(){});
       }
     },
     clearCache:function(){for(var k in cache)delete cache[k];for(var lk in layoutCache)delete layoutCache[lk];for(var gk in layoutGroupCache)delete layoutGroupCache[gk];cacheOrder.length=0},

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "stx-router",
   "type": "module",
-  "version": "0.2.152",
+  "version": "0.2.154",
   "description": "File-based router for STX — .stx template discovery, nested layouts, typed route params, middleware, and client-side SPA navigation.",
   "author": "Chris Breuer <chris@stacksjs.org>",
   "license": "MIT",