bun-plugin-stx 0.2.152 → 0.2.154

package/dist/{chunk-8nbccnre.js → chunk-5pnbtf0j.js}

@@ -621,6 +621,28 @@ 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{
@@ -816,6 +838,44 @@ 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;
@@ -827,11 +887,99 @@ 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||'';
@@ -892,7 +1040,20 @@ 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);
@@ -908,7 +1069,7 @@ 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);
@@ -944,6 +1105,7 @@ 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);
@@ -951,6 +1113,7 @@ 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;
@@ -964,11 +1127,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');
@@ -981,12 +1149,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.
@@ -1011,9 +1180,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);
@@ -1021,6 +1200,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
@@ -1030,15 +1217,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 '';
         });
@@ -1098,7 +1304,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'});
@@ -1141,17 +1347,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;
@@ -1171,7 +1374,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'));
       }
@@ -1190,6 +1398,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)}
 
@@ -1276,14 +1505,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
@@ -1303,7 +1551,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);
@@ -1410,7 +1658,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);
@@ -1431,6 +1679,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
@@ -1460,7 +1736,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;
@@ -1564,7 +1840,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]});
@@ -1663,7 +1940,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/dist/serve.d.ts

@@ -9,7 +9,39 @@ export declare function extractServerScriptsFromTemplate(content: string): {
   serverScripts: string[]
   templateContent: string
 };
+/**
+ * A token to mint for this request, or null to leave it alone.
+ *
+ * Safe methods only, and only when the request carries none already: anything
+ * else is somebody's live session, and rotating their token mid-flight would
+ * reject the very form they are about to submit.
+ */
+export declare function csrfTokenToMint(req: Request, cookies: Record<string, string>): string | null;
+/** The `Set-Cookie` value for a minted token. Readable by script, as double-submit requires. */
+export declare function csrfCookieHeader(token: string, secure: boolean): string;
 export declare function buildDynamicRouteRegexes(fileRouteBase: string): RegExp[];
+/**
+ * Rank a dynamic route file by specificity so the resolver can order candidates
+ * most-specific-first and never let a catch-all (`[...x]`) or a broad `[param]`
+ * shadow a more specific route (stacksjs/stx#1837).
+ *
+ * `discoverFiles` returns Bun glob order — where the catch-all frequently lands
+ * first — and `getRoute` takes the FIRST regex match. Without ordering, `/foo/15`
+ * matched `[...all].stx` (`^(.+)$`) before `foo/[id].stx`, so every dynamic
+ * detail route 404'd. Higher score = more specific = tried first:
+ *   - static segment       → +100   (strongly preferred)
+ *   - `[param]` segment     →   +1   (weakly preferred)
+ *   - `[...rest]` catch-all → -10000 (always last)
+ */
+export declare function routeSpecificity(fileRouteBase: string): number;
+/**
+ * True when a request path is for a STATIC ASSET (a non-page file extension like
+ * `.jpg`/`.css`/`.js`) rather than a page. Used so a catch-all page can never
+ * shadow an asset request that publicDir should serve — `getRoute` runs before
+ * the publicDir handler (stacksjs/stx#1841). Page extensions (`.stx`/`.md`/
+ * `.html`) return false; those are routable.
+ */
+export declare function isStaticAssetPath(requestPath: string): boolean;
 /**
  * Are we serving in production? In production the built-in 404 must not
  * enumerate the app's route list (information disclosure) and must not
@@ -65,6 +97,7 @@ export declare function render404Page(opts: {
   routes?: string[]
   isProduction: boolean
 }): string;
+export declare function resolveServeOpenUrl(port: number, openPath?: string): string;
 export declare function isRenderableCacheCandidate(html: string): boolean;
 export declare function bundleBrowserAsset(entrypoint: string): Promise<Response>;
 /**
@@ -72,6 +105,14 @@ export declare function bundleBrowserAsset(entrypoint: string): Promise<Response
  * @param options Server options with patterns and port
  */
 export declare function serve(options: ServeOptions): Promise<void>;
+/**
+ * The cookie name a double-submit CSRF check reads.
+ *
+ * Spelled here rather than imported, because stx does not depend on whatever
+ * framework is doing the checking - it only has to agree on the name, and this
+ * is the name every double-submit implementation in this ecosystem uses.
+ */
+export declare const CSRF_COOKIE: 'X-CSRF-Token';
 /**
  * Build the candidate regexes for a dynamic route file (stacksjs/stx#1927).
  *
@@ -112,6 +153,7 @@ export declare interface ServeRequestContext {
 export declare interface ServeOptions {
   patterns: string[]
   port?: number
+  openPath?: string
   componentsDir?: string
   layoutsDir?: string
   partialsDir?: string

package/dist/serve.js

@@ -8718,7 +8718,7 @@ var defaultConfigDir4 = /* @__PURE__ */ resolve12(process20.cwd(), "config");
 var defaultGeneratedDir4 = /* @__PURE__ */ resolve12(process20.cwd(), "src/generated");
 
 // src/serve.ts
-import { extractPageResponseStatus, stateDir, stateDirName } from "@stacksjs/stx";
+import { BUILD_ID_HEADER, extractPageResponseStatus, getBuildId, stateDir, stateDirName } from "@stacksjs/stx";
 var defaultStxModule = import("@stacksjs/stx");
 var REACTIVE_TEMPLATE_DIRECTIVE_RE = /@for|:for|@if|:if|@else|:else|x-for|x-if|x-else/;
 function extractServerScriptsFromTemplate(content) {
@@ -8756,6 +8756,29 @@ function extractServerScriptsFromTemplate(content) {
   retained.push(content.slice(retainedFrom));
   return { serverScripts, templateContent: retained.join("") };
 }
+var CSRF_COOKIE = "X-CSRF-Token";
+function csrfTokenToMint(req, cookies) {
+  const method = (req.method || "GET").toUpperCase();
+  if (method !== "GET" && method !== "HEAD")
+    return null;
+  if (cookies[CSRF_COOKIE] || cookies["csrf-token"])
+    return null;
+  const accept = req.headers.get("accept") || "";
+  if (accept && !accept.includes("text/html") && !accept.includes("*/*"))
+    return null;
+  const bytes = new Uint8Array(32);
+  crypto.getRandomValues(bytes);
+  return [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function csrfCookieHeader(token, secure) {
+  return [
+    `${CSRF_COOKIE}=${token}`,
+    "Path=/",
+    "SameSite=Lax",
+    "Max-Age=7200",
+    secure ? "Secure" : null
+  ].filter(Boolean).join("; ");
+}
 function buildDynamicRouteRegexes(fileRouteBase) {
   const toPattern = (p) => p.replace(/\[\.\.\.([^\]]+)\]/g, "(.+)").replace(/\[([^\]]+)\]/g, "([^/]+)").replace(/\//g, "\\/");
   const patterns = [new RegExp(`^${toPattern(fileRouteBase)}$`)];
@@ -8771,6 +8794,22 @@ function buildDynamicRouteRegexes(fileRouteBase) {
   }
   return patterns;
 }
+function routeSpecificity(fileRouteBase) {
+  const segments = fileRouteBase.replace(/^\.\//, "").replace(/\\/g, "/").replace(/\.(stx|md|html)$/, "").split("/");
+  let score = 0;
+  for (const segment of segments) {
+    if (/\[\.\.\./.test(segment))
+      score -= 1e4;
+    else if (segment.includes("["))
+      score += 1;
+    else
+      score += 100;
+  }
+  return score;
+}
+function isStaticAssetPath(requestPath) {
+  return /\.[a-z0-9]+$/i.test(requestPath) && !/\.(?:stx|md|html)$/i.test(requestPath);
+}
 function escapeHtml(input) {
   return input.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
 }
@@ -8878,6 +8917,15 @@ function render404Page(opts) {
   </body>
 </html>`;
 }
+function resolveServeOpenUrl(port, openPath = "/") {
+  const baseUrl = `http://localhost:${port}`;
+  try {
+    const url = new URL(openPath || "/", `${baseUrl}/`);
+    return url.origin === baseUrl ? url.toString() : `${baseUrl}/`;
+  } catch {
+    return `${baseUrl}/`;
+  }
+}
 function isRenderableCacheCandidate(html) {
   return !html.includes("<!-- Template Processing failed:") && !html.includes("<!-- stx rendering error -->");
 }
@@ -9362,7 +9410,7 @@ After installing: bun add bun-plugin-stx`);
     pageMiddlewarePatterns.length = 0;
     await Promise.all(files.map((f) => detectPageMiddleware(f)));
     try {
-      const { Router } = await import("./chunk-8nbccnre.js");
+      const { Router } = await import("./chunk-5pnbtf0j.js");
       const pagesDirs = patterns.map((p) => p.replace(/\/$/, "")).filter(Boolean);
       const router = new Router(process19.cwd(), { pagesDirs, stateDir: stateDirName() });
       if (!options.quiet)
@@ -9692,10 +9740,17 @@ After installing: bun add bun-plugin-stx`);
         }
       }
     }
-    for (const filePath of files) {
+    const isAssetRequest = isStaticAssetPath(normalizedPath);
+    const dynamicFiles = files.filter((f) => {
+      const nf = f.replace(/^\.\//, "").replace(/\\/g, "/");
+      if (!nf.includes("["))
+        return false;
+      if (isAssetRequest && /\[\.\.\./.test(nf))
+        return false;
+      return true;
+    }).sort((a, b) => routeSpecificity(b) - routeSpecificity(a));
+    for (const filePath of dynamicFiles) {
       const normalizedFilePath = filePath.replace(/^\.\//, "").replace(/\\/g, "/");
-      if (!normalizedFilePath.includes("["))
-        continue;
       let relativeFilePath = normalizedFilePath;
       for (const pattern of patterns) {
         const normalizedPattern = pattern.replace(/\\/g, "/").replace(/\/$/, "");
@@ -9963,6 +10018,7 @@ ${html}`;
               req = new Request(req, { headers });
             }
           }
+          let mintedCsrfToken = null;
           const _i18nResp = await (async () => {
             activeServeLocale = i18nLocale;
             activeServeSearch = url.search;
@@ -9970,6 +10026,9 @@ ${html}`;
             activeServeCookieHeader = req.headers.get("cookie") || "";
             activeServeCookies = parseCookies(req);
             activeServeIp = server.requestIP(req)?.address || (req.headers.get("x-forwarded-for") || "").split(",")[0].trim();
+            mintedCsrfToken = csrfTokenToMint(req, activeServeCookies);
+            if (mintedCsrfToken)
+              activeServeCookies[CSRF_COOKIE] = mintedCsrfToken;
             const reqCtx = {
               url: req.url,
               path,
@@ -10314,6 +10373,7 @@ ${trailingPageScripts.join(`
 `)}`;
                   const titleMatch = content.match(/<title[^>]*>([\s\S]*?)<\/title>/i);
                   const pageTitle = titleMatch ? titleMatch[1].trim() : "";
+                  const shipsRuntime = content.includes("data-stx-runtime");
                   return new Response(fragment, {
                     status: responseStatus,
                     headers: {
@@ -10321,7 +10381,9 @@ ${trailingPageScripts.join(`
                       "X-STX-Fragment": "true",
                       "X-STX-Layout": pageLayout,
                       "X-STX-Layout-Group": pageLayoutGroup,
+                      "X-STX-Runtime": shipsRuntime ? "true" : "false",
                       ...pageTitle && { "X-STX-Title": encodeURIComponent(pageTitle) },
+                      [BUILD_ID_HEADER]: getBuildId(),
                       ...containerAttrs && { "X-STX-Container-Attrs": encodeURIComponent(containerAttrs) },
                       "Cache-Control": "no-store",
                       ...corsHeaders
@@ -10478,7 +10540,20 @@ ${trailingPageScripts.join(`
               activeServeIp = "";
             }
           })();
-          const _finalResp = await applyI18nToResponse(_i18nResp, i18nLocale ?? (i18nConfig?.defaultLocale ?? "en"), path);
+          let _finalResp = await applyI18nToResponse(_i18nResp, i18nLocale ?? (i18nConfig?.defaultLocale ?? "en"), path);
+          if (mintedCsrfToken) {
+            try {
+              _finalResp.headers.append("Set-Cookie", csrfCookieHeader(mintedCsrfToken, req.url.startsWith("https://")));
+            } catch {
+              const headers = new Headers(_finalResp.headers);
+              headers.append("Set-Cookie", csrfCookieHeader(mintedCsrfToken, req.url.startsWith("https://")));
+              _finalResp = new Response(_finalResp.body, {
+                status: _finalResp.status,
+                statusText: _finalResp.statusText,
+                headers
+              });
+            }
+          }
           if (options.onResponse) {
             const hooked = await options.onResponse(req, _finalResp);
             if (hooked instanceof Response)
@@ -10538,10 +10613,11 @@ ${trailingPageScripts.join(`
     const elapsed = (performance.now() - startTime).toFixed(0);
     const routeCount = sourceFiles?.length || 0;
     const patternsStr = patterns.join(", ");
+    const openUrl = resolveServeOpenUrl(actualPort, options.openPath);
     console.log();
     console.log(`  \x1B[36m\x1B[1mstx\x1B[0m`);
     console.log();
-    console.log(`  \x1B[32m\u279C\x1B[0m  \x1B[1mLocal\x1B[0m:   \x1B[36mhttp://localhost:${actualPort}/\x1B[0m`);
+    console.log(`  \x1B[32m\u279C\x1B[0m  \x1B[1mLocal\x1B[0m:   \x1B[36m${openUrl}\x1B[0m`);
     console.log(`  \x1B[32m\u279C\x1B[0m  \x1B[1mRoutes\x1B[0m:  \x1B[2m${routeCount} files from ${patternsStr}\x1B[0m`);
     console.log();
     console.log(`  \x1B[2mready in ${elapsed}ms\x1B[0m`);
@@ -10557,7 +10633,7 @@ ${trailingPageScripts.join(`
         const cmd = line.trim().toLowerCase();
         if (cmd === "o") {
           const openCmd = process19.platform === "darwin" ? "open" : process19.platform === "win32" ? "start" : "xdg-open";
-          Bun.spawn([openCmd, `http://localhost:${actualPort}/`]);
+          Bun.spawn([openCmd, openUrl]);
         } else if (cmd === "q") {
           process19.exit(0);
         }
@@ -10582,10 +10658,16 @@ if (import.meta.main) {
 export {
   staticCacheControl,
   serve,
+  routeSpecificity,
+  resolveServeOpenUrl,
   render404Page,
+  isStaticAssetPath,
   isRenderableCacheCandidate,
   isProductionServe,
   extractServerScriptsFromTemplate,
+  csrfTokenToMint,
+  csrfCookieHeader,
   bundleBrowserAsset,
-  buildDynamicRouteRegexes
+  buildDynamicRouteRegexes,
+  CSRF_COOKIE
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "bun-plugin-stx",
   "type": "module",
-  "version": "0.2.152",
+  "version": "0.2.154",
   "description": "A Bun plugin that allows for using Laravel Blade-like syntax.",
   "author": "Chris Breuer <chris@stacksjs.org>",
   "license": "MIT",
@@ -39,6 +39,7 @@
       "import": "./dist/preload.js"
     },
     "./serve": {
+      "types": "./dist/serve.d.ts",
       "bun": "./dist/serve.js",
       "import": "./dist/serve.js"
     },