stx-router 0.2.151 → 0.2.153

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,27 @@ 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.
+  function runsAlways(declared, code){
+    if(declared==='always')return true;
+    if(declared==='once')return false;
+    var head=code.trimStart();
+    return head.charAt(0)==='('||head.charAt(0)===';'||code.indexOf('window.stx.mount')>-1;
+  }
   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;
@@ -364,6 +407,10 @@ 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')||'';
@@ -433,12 +480,15 @@ else {
           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 '';
         });
@@ -541,17 +591,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;
@@ -590,6 +637,11 @@ 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)}
     var newContent=doc.querySelector(containerSel)||doc.querySelector('[data-stx-content]')||doc.querySelector('main');
     if(!newContent){location.href=url;return Promise.resolve(false)}
 
@@ -703,7 +755,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);
@@ -831,6 +883,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 +940,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;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "stx-router",
   "type": "module",
-  "version": "0.2.151",
+  "version": "0.2.153",
   "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",