bun-plugin-stx 0.2.153 → 0.2.154

package/dist/{chunk-3dygdr9g.js → chunk-5pnbtf0j.js}

@@ -853,11 +853,28 @@ function getRouterScript() {
   // _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)===';'||code.indexOf('window.stx.mount')>-1;
+    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}
@@ -870,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||'';
@@ -935,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);
@@ -951,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);
@@ -987,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);
@@ -994,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;
@@ -1016,6 +1136,7 @@ else {
         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');
@@ -1028,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.
@@ -1058,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);
@@ -1068,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
@@ -1077,6 +1217,22 @@ 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);
@@ -1148,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'});
@@ -1218,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'));
       }
@@ -1242,6 +1403,22 @@ else {
     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)}
 
@@ -1328,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
@@ -1462,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);
@@ -1644,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]});
@@ -1743,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
@@ -73,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).
  *

package/dist/serve.js

@@ -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;");
 }
@@ -9371,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-3dygdr9g.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)
@@ -9701,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(/\/$/, "");
@@ -9972,6 +10018,7 @@ ${html}`;
               req = new Request(req, { headers });
             }
           }
+          let mintedCsrfToken = null;
           const _i18nResp = await (async () => {
             activeServeLocale = i18nLocale;
             activeServeSearch = url.search;
@@ -9979,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,
@@ -10323,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: {
@@ -10330,6 +10381,7 @@ ${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) },
@@ -10488,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)
@@ -10593,11 +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.153",
+  "version": "0.2.154",
   "description": "A Bun plugin that allows for using Laravel Blade-like syntax.",
   "author": "Chris Breuer <chris@stacksjs.org>",
   "license": "MIT",