stx-router 0.2.155 → 0.2.157

package/dist/client.js

@@ -12,11 +12,11 @@ export function getRouterScript() {
   cachedRouterScript = minifyRouterScript(`
 ;(function(){
   'use strict';
-  var ROUTER_REV=3;
+  var ROUTER_REV=7;
   if(window.__stxRouter&&window.__stxRouter.__rev===ROUTER_REV)return;
 
   // \u2500\u2500 Configuration \u2500\u2500
-  var defaults={container:'main',loadingClass:'stx-navigating',viewTransitions:true,cache:true,scrollToTop:true,prefetch:true,progress:true,progressColor:'#78dce8',progressHeight:'2px',interceptAllLinks:false,prefetchCacheMax:50};
+  var defaults={container:'main',loadingClass:'stx-navigating',viewTransitions:true,cache:true,scrollToTop:true,prefetch:true,progress:true,progressColor:'#78dce8',progressHeight:'2px',interceptAllLinks:false,prefetchCacheMax:50,routeFocus:true,announceRoute:true,interceptForms:false};
   var o=Object.assign({},defaults,window.__stxRouterConfig||{},window.STX_ROUTER_OPTIONS||{});
   var containerSel=o.container;
   var debug=!!o.debug;
@@ -527,6 +527,23 @@ 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);
+        // A route guard answered with a redirect and fetch followed it
+        // transparently, so r.ok is the DESTINATION's 200 and this markup
+        // belongs to r.url \u2014 not to the path that was requested. Without
+        // retargeting, an auth guard's /login body is swapped in while the
+        // address bar, the history entry and the cache key all still read
+        // /dashboard: the user sees a login form at a URL that claims to be
+        // the page they asked for, and reloading bounces them again (#1849).
+        if(r.redirected&&r.url){
+          var rd=new URL(r.url,location.href);
+          // A guard that sends you off-origin (a hosted IdP) cannot be
+          // resolved by swapping a fragment \u2014 hand it to the browser.
+          if(rd.origin!==location.origin){location.href=r.url;return null}
+          log('[router] guard redirected:',url,'->',rd.pathname);
+          url=rd.pathname+rd.search+rd.hash;
+          targetPath=cacheKey(url);
+          targetHash=rd.hash;
+        }
         // 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')||'';
@@ -588,6 +605,60 @@ else {
   // 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;
+  // \u2500\u2500 Focus and route announcement \u2500\u2500
+  // A fragment swap replaces content without a document load, so the browser
+  // does none of what it normally does for a navigation. Focus stays on a link
+  // that no longer exists, which the browser resets to <body> \u2014 a keyboard user
+  // is silently returned to the top of the tab order \u2014 and a screen reader says
+  // nothing at all, so there is no signal the page changed. Neither is fixable
+  // from app code, because only the router knows a navigation happened (#1862).
+  function routeAnnouncer(){
+    var el=document.getElementById('stx-route-announcer');
+    if(el)return el;
+    el=document.createElement('div');
+    el.id='stx-route-announcer';
+    el.setAttribute('aria-live','polite');
+    el.setAttribute('role','status');
+    el.setAttribute('aria-atomic','true');
+    // Visually hidden but still ANNOUNCED. display:none and visibility:hidden
+    // are both skipped by screen readers, which would make this a silent no-op
+    // that looks correct in the DOM.
+    el.style.cssText='position:absolute;width:1px;height:1px;margin:-1px;padding:0;overflow:hidden;clip:rect(0 0 0 0);clip-path:inset(50%);white-space:nowrap;border:0';
+    document.body.appendChild(el);
+    return el;
+  }
+
+  function announceRoute(){
+    if(o.announceRoute===false)return;
+    var c=getContainer();
+    var h=c&&c.querySelector?c.querySelector('h1'):null;
+    // The heading names the destination better than the title, which often
+    // carries a site-name suffix. Falls back to the title, then gives up
+    // rather than announcing an empty string.
+    var label=(h&&(h.textContent||'').trim())||document.title||'';
+    if(!label)return;
+    var el=routeAnnouncer();
+    // Cleared first: several screen readers ignore a live-region update whose
+    // text is identical to what is already there, so navigating between two
+    // pages with the same heading would announce only the first.
+    el.textContent='';
+    el.textContent=label;
+  }
+
+  function focusAfterNavigation(hash){
+    if(o.routeFocus===false)return;
+    var target=null;
+    if(hash){try{target=document.querySelector(hash)}catch(e){target=null}}
+    if(!target)target=getContainer();
+    if(!target||!target.focus)return;
+    // The container is not naturally focusable. tabindex="-1" makes it
+    // programmatically focusable without inserting it into the tab order.
+    if(!target.hasAttribute('tabindex'))target.setAttribute('tabindex','-1');
+    // preventScroll because scroll position is already decided just above \u2014
+    // focusing would otherwise fight scrollToTop and the hash scrollIntoView.
+    try{target.focus({preventScroll:true})}catch(e){try{target.focus()}catch(e2){}}
+  }
+
   function swap(html,url,pushState,hash){
     var fragMark=/^<!--stx-fragment(?: rt=([01]))?-->/.exec(html);
     var isFragment=!!fragMark;
@@ -710,6 +781,12 @@ else {
         if(o.scrollToTop&&!hash)window.scrollTo({top:0,behavior:'instant'});
         else if(hash){var el=document.querySelector(hash);if(el)el.scrollIntoView({behavior:'smooth'})}
         window.dispatchEvent(new CustomEvent('stx:navigate',{detail:{url:url}}));
+        // Before page scripts run, so a page that focuses its own control on
+        // mount still wins \u2014 its script executes after this.
+        focusAfterNavigation(hash);
+        // Deferred a tick because the title is applied by the caller after this
+        // swap resolves, and the announcement should read the new one.
+        setTimeout(announceRoute,0);
         // Execute page scripts FIRST \u2014 they define setup functions and set _latestSetup
         log('[router] frag scripts:', fragScripts.length);
         document.querySelectorAll('script[data-stx-page]').forEach(function(s){s.remove()});
@@ -1182,16 +1259,66 @@ else {
   }
 
   // \u2500\u2500 Link interception \u2500\u2500
+  // Links the router must never touch, however it found them. This is the
+  // opt-out set, and it is deliberately separate from shouldIntercept's
+  // eligibility rules below: [data-stx-link] is an author saying "this is a
+  // router link", which answers eligibility but must NOT override an explicit
+  // opt-out or a non-navigational scheme.
+  function isRouterExcluded(link){
+    if(!link)return true;
+    var href=link.getAttribute('href');
+    if(!href)return true;
+    if(href.startsWith('http')||href.startsWith('#')||href.startsWith('mailto:')||href.startsWith('tel:')||href.startsWith('javascript:'))return true;
+    if(link.target==='_blank')return true;
+    if(link.hasAttribute('data-stx-no-router')||link.hasAttribute('data-no-router')||link.hasAttribute('download'))return true;
+    return false;
+  }
+
+  // Paths the router can actually render, compiled from the server's own route
+  // table and shipped as regex sources (#1864). Absent when discovery found
+  // nothing, which means UNKNOWN, not "owns nothing" \u2014 treating it as the
+  // latter would disable SPA navigation for a whole site.
+  var ownedRoutes=null;
+  (function(){
+    var raw=o.ownedRoutes;
+    if(!raw||!raw.length)return;
+    var compiled=[];
+    for(var i=0;i<raw.length;i++){
+      try{compiled.push(new RegExp(raw[i]))}
+      catch(e){}
+    }
+    if(compiled.length)ownedRoutes=compiled;
+  })();
+
+  // Does the router own this path? Only meaningful when the route table made it
+  // to the client; otherwise every path is treated as owned, preserving the old
+  // behaviour.
+  function routerOwns(pathname){
+    if(!ownedRoutes)return true;
+    for(var i=0;i<ownedRoutes.length;i++){
+      if(ownedRoutes[i].test(pathname))return true;
+    }
+    return false;
+  }
+
+  // Eligibility for auto-claiming an arbitrary same-origin anchor under
+  // interceptAllLinks. Only reached for anchors the author did not mark.
   function shouldIntercept(link){
-    if(!link)return false;
+    if(isRouterExcluded(link))return false;
     var href=link.getAttribute('href');
-    if(!href)return false;
-    if(href.startsWith('http')||href.startsWith('#')||href.startsWith('mailto:')||href.startsWith('tel:')||href.startsWith('javascript:'))return false;
-    if(link.target==='_blank')return false;
-    if(link.hasAttribute('data-stx-no-router')||link.hasAttribute('data-no-router')||link.hasAttribute('download'))return false;
     if(href.startsWith('?'))return true;
     if(href===location.pathname)return false;
     if(!getContainer())return false;
+    // An endpoint the router cannot render must go to the browser. Claiming it
+    // meant a failed fragment fetch, a fallback navigation, and the endpoint
+    // hit TWICE \u2014 on OAuth redirects, that mints state twice.
+    var path=href;
+    var q=path.indexOf('?');if(q!==-1)path=path.slice(0,q);
+    var h=path.indexOf('#');if(h!==-1)path=path.slice(0,h);
+    if(path.charAt(0)==='/'&&!routerOwns(path)){
+      log('[router] not a known route, leaving to the browser:',href);
+      return false;
+    }
     return true;
   }
 
@@ -1204,6 +1331,10 @@ else {
     if(e.metaKey||e.ctrlKey||e.shiftKey||e.altKey||e.button!==0)return;
     if(!e.target||!e.target.closest)return;
     var link=e.target.closest('[data-stx-link]');
+    // A marked link still has to clear the opt-out set. It used to skip it
+    // entirely, so data-no-router on a [data-stx-link] anchor was silently
+    // ignored and an OAuth redirect got claimed by the router.
+    if(link&&isRouterExcluded(link)){log('[router] excluded:',link.getAttribute('href'));return}
     if(!link&&o.interceptAllLinks){
       var anchor=e.target.closest('a[href]');
       if(anchor&&shouldIntercept(anchor))link=anchor;
@@ -1211,14 +1342,147 @@ else {
     if(!link){return}
     var href=link.getAttribute('href');
     log('[router] click intercepted:',href,'container:',!!getContainer(),'defaultPrevented:',e.defaultPrevented);
-    if(!href||href.startsWith('http')||href.startsWith('#')||href.startsWith('mailto:')||href.startsWith('tel:')){log('[router] skipped:',href);return}
-    if(link.target==='_blank'||link.hasAttribute('download'))return;
     e.preventDefault();
     e.stopPropagation();
     log('[router] navigating to:',href);
     navigate(withCurrentLocale(href));
   },true);
 
+  // \u2500\u2500 Form submission \u2500\u2500
+  // A submit IS a navigation, and the router only ever watched clicks. So any
+  // in-app form tore down the SPA with a full document load and discarded
+  // every signal on the page, and the only way out was a hand-written fetch in
+  // a @submit handler with its own loading and error state.
+  //
+  // Gated exactly like links: a form opts in with data-stx-form, or
+  // interceptForms claims them all \u2014 the same shape as [data-stx-link] /
+  // interceptAllLinks. Deliberately not on by default: a POST has side
+  // effects, so claiming one has to be a decision rather than something that
+  // starts happening on upgrade (#1863).
+  function formAttrOf(form,submitter,submitterAttr,formAttr){
+    // A submit button overrides the form: formaction / formmethod / formenctype.
+    var v=submitter&&submitter.getAttribute?submitter.getAttribute(submitterAttr):null;
+    return (v!==null&&v!==undefined)?v:form.getAttribute(formAttr);
+  }
+
+  function formTargetUrl(form,submitter){
+    return formAttrOf(form,submitter,'formaction','action')||(location.pathname+location.search);
+  }
+
+  function formMethodOf(form,submitter){
+    return String(formAttrOf(form,submitter,'formmethod','method')||'get').toLowerCase();
+  }
+
+  function formExcluded(form,submitter){
+    if(!form||form.tagName!=='FORM')return true;
+    if(form.hasAttribute('data-stx-no-router')||form.hasAttribute('data-no-router'))return true;
+    // A form aimed at another browsing context is not this page's navigation.
+    if(form.target&&form.target!=='_self')return true;
+    try{
+      // Resolving against location handles relative, absolute and foreign
+      // schemes in one step: mailto: parses to a null origin and is excluded.
+      if(new URL(formTargetUrl(form,submitter),location.href).origin!==location.origin)return true;
+    }
+    catch(e){return true}
+    return false;
+  }
+
+  function setFormPending(form,on){
+    if(on){form.classList.add('stx-submitting');form.setAttribute('aria-busy','true')}
+    else{form.classList.remove('stx-submitting');form.removeAttribute('aria-busy')}
+  }
+
+  function submitForm(form,submitter){
+    var method=formMethodOf(form,submitter);
+    var action=formTargetUrl(form,submitter);
+    var fd=new FormData(form);
+    // A named submit button contributes its value, exactly as a native submit
+    // would. FormData does not include it, so multi-button forms (Save vs
+    // Delete) would otherwise lose the one piece of state that distinguishes them.
+    if(submitter&&submitter.name)fd.append(submitter.name,submitter.value||'');
+
+    if(method==='get'){
+      // A GET form is a link whose href the user filled in. Serialise and hand
+      // it to the ordinary navigation path \u2014 no special swap handling, and it
+      // inherits caching, prefetch and the guard-redirect behaviour for free.
+      var qs=new URLSearchParams();
+      fd.forEach(function(v,k){if(typeof v==='string')qs.append(k,v)});
+      var gu=new URL(action,location.href);
+      gu.search=qs.toString();
+      return navigate(gu.pathname+gu.search+gu.hash);
+    }
+
+    setFormPending(form,true);
+    form.dispatchEvent(new CustomEvent('stx:form-submit',{bubbles:true,detail:{action:action,method:method}}));
+
+    var enctype=String(formAttrOf(form,submitter,'formenctype','enctype')||'').toLowerCase();
+    // Respect the declared encoding. Handing FormData to fetch always produces
+    // multipart, which a server expecting urlencoded will read as empty.
+    var body=enctype.indexOf('multipart')===0?fd:new URLSearchParams(fd);
+    var wantsFragment=shouldUseFragmentResponse();
+
+    return fetch(action,{
+      method:method.toUpperCase(),
+      body:body,
+      headers:wantsFragment?{'X-STX-Router':'true','Accept':'text/html'}:{'Accept':'text/html'},
+      credentials:'same-origin',
+    }).then(function(r){
+      // POST/redirect/GET. The server said where the result lives, so go there
+      // through the normal path rather than swapping the POST's body under the
+      // form's own URL \u2014 otherwise reloading re-submits.
+      if(r.redirected&&r.url){
+        var rd=new URL(r.url,location.href);
+        if(rd.origin!==location.origin){location.href=r.url;return}
+        return navigate(rd.pathname+rd.search+rd.hash);
+      }
+      return r.text().then(function(html){
+        var isFrag=wantsFragment&&r.headers.get('X-STX-Fragment')==='true';
+        pendingContainerAttrs=isFrag?(r.headers.get('X-STX-Container-Attrs')||''):'';
+        pendingLayoutDecl=isFrag?null:{layout:r.headers.get('X-STX-Layout')||'',group:r.headers.get('X-STX-Layout-Group')||''};
+        var marked=isFrag?fragmentMarker(r.headers.get('X-STX-Runtime')||'')+html:html;
+        // Deliberately NOT cached: this body is the answer to one POST, and
+        // serving it later for a GET of the same path would be a lie.
+        // 'replace' so re-rendered validation errors do not stack one history
+        // entry per attempt.
+        return Promise.resolve(swap(marked,cacheKey(action),'replace','')).then(function(){
+          applyTitle(r.headers.get('X-STX-Title')||'');
+        });
+      });
+    }).catch(function(err){
+      // No native re-submit on failure: that would send the POST a second time.
+      // The app is told instead, and the form is left intact for a retry.
+      console.error('[router] form submit failed:',err);
+      form.dispatchEvent(new CustomEvent('stx:form-error',{bubbles:true,detail:{error:err,action:action}}));
+    }).finally(function(){setFormPending(form,false)});
+  }
+
+  document.addEventListener('submit',function(e){
+    // Bubble phase, and defaultPrevented is honoured, so a page's own @submit
+    // handler always wins. This is a fallback for forms nobody else claimed,
+    // never an override of one that is already handled.
+    if(e.defaultPrevented)return;
+    var form=e.target;
+    if(!form||form.tagName!=='FORM')return;
+    if(!form.hasAttribute('data-stx-form')&&!form.hasAttribute('data-stx-link')&&!o.interceptForms)return;
+    var submitter=e.submitter||null;
+    if(formExcluded(form,submitter))return;
+    // Without a container there is nothing to swap into, so a native submit is
+    // the only thing that can work.
+    if(!getContainer())return;
+    // Constraint validation has already run by the time submit fires, so an
+    // invalid form never reaches here.
+    e.preventDefault();
+    // A synchronous throw in here would be swallowed by dispatchEvent, and
+    // preventDefault has already run \u2014 so the form would be silently dead with
+    // nothing in the console. Report it and clear the pending state instead.
+    try{submitForm(form,submitter)}
+    catch(err){
+      console.error('[router] form submit failed:',err);
+      setFormPending(form,false);
+      form.dispatchEvent(new CustomEvent('stx:form-error',{bubbles:true,detail:{error:err}}));
+    }
+  });
+
   // \u2500\u2500 Back/forward \u2500\u2500
   window.addEventListener('popstate',function(){
     navigate(location.pathname+location.search+location.hash,false);
@@ -1229,13 +1493,23 @@ else {
     document.addEventListener('mouseover',function(e){
       if(!e.target||!e.target.closest)return;
       var link=e.target.closest('[data-stx-link]');
-      if(!link)return;
+      // Same opt-out set as the click path. Without it, hovering a link the
+      // router is not allowed to claim still fired a real GET at it \u2014 a
+      // logout or OAuth URL was requested on hover alone.
+      if(isRouterExcluded(link))return;
       var href=withCurrentLocale(link.getAttribute('href'));
       var key=cacheKey(href);
       if(cache[key]||prefetching[key])return;
       prefetching[key]=true;
       var wantsFragment=shouldUseFragmentResponse();
       fetch(href,{headers:wantsFragment?{'X-STX-Router':'true','Accept':'text/html'}:{'Accept':'text/html'}}).then(function(r){
+        // Never cache a body that came from somewhere else. A guarded route
+        // prefetched while logged out answers with /login's markup, and
+        // storing it under the guarded key poisons the cache: the later real
+        // navigation is a cache hit, so it swaps the login page in without
+        // ever hitting the network, where the redirect check above would
+        // have caught it (#1849).
+        if(r.redirected)return null;
         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')||'';
@@ -1243,7 +1517,7 @@ else {
         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);
+        if(result&&o.cache)setCache(key,result.html,result.layout,result.layoutGroup,result.title);
       }).catch(function(){}).finally(function(){delete prefetching[key]});
     },true);
   }
@@ -1343,6 +1617,27 @@ else {
         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(){});
       }
     },
+    // Re-run the CURRENT route against the server and swap the result.
+    //
+    // There was no way to do this. invalidate() on a query only re-runs client
+    // fetches, so anything the server rendered \u2014 a list the mutation just
+    // changed, a count in the layout \u2014 could only be refreshed with a full
+    // document load, which discards every signal on the page. That is the
+    // exact thing the SPA exists to avoid, so apps reached for
+    // location.reload() and lost their state (#1850, #1858).
+    //
+    // force:true both evicts the cache entry and defeats navigate's
+    // same-URL early return, so this is exposing behaviour the router already
+    // had rather than adding a second code path. 'replace' because a refresh
+    // is not a new place \u2014 it must not add a history entry you can go Back to.
+    refresh:function(){
+      return navigate(location.pathname+location.search+location.hash,'replace',true);
+    },
+    // Expire ONE entry, so a mutation can invalidate just the page it affected
+    // and let the next visit re-fetch, instead of throwing the whole cache away.
+    invalidate:function(url){
+      evictCache(cacheKey(url||(location.pathname+location.search)));
+    },
     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},
     cache:cache,
     swap:swap,

package/dist/codegen.d.ts

@@ -1,4 +1,19 @@
 import type { Route } from './types';
+/**
+ * Write the route declaration consumed by `CheckHref` in `@stacksjs/stx`.
+ *
+ * This used to emit `declare module "stx/routes"`, a specifier nothing in the
+ * source tree declares or imports. TypeScript therefore read it as an ambient
+ * module declaration rather than an augmentation, so it constrained nothing and
+ * `navigate('/typo')` type-checked (stacksjs/stx#1887).
+ *
+ * Two details are load-bearing rather than cosmetic:
+ *
+ *  - the trailing `export {}` makes this a module, so `declare module` is an
+ *    augmentation of the real package instead of a replacement for it;
+ *  - non-page routes are filtered out, which `generateRouteManifest` already
+ *    did and this did not — the two artifacts disagreed about membership.
+ */
 export declare function generateRouteTypes(routes: Route[], outputDir: string): void;
 /**
  * Generate a route manifest file (.stx/routes.ts).

package/dist/codegen.js

@@ -1,27 +1,34 @@
 import fs from "node:fs";
 import path from "node:path";
+import { isNonPageRoutePattern } from "./page-routes.js";
 export function generateRouteTypes(routes, outputDir) {
-  const lines = [
-    "// Auto-generated by STX - do not edit",
-    'declare module "stx/routes" {',
-    "  interface RouteMap {"
-  ];
-  for (const route of routes) {
-    const paramEntries = [];
-    for (const p of route.params) {
-      const type = route.pattern.includes(`:${p}*`) ? "string[]" : "string";
-      paramEntries.push(`${p}: ${type}`);
+  const pageRoutes = routes.filter((r) => !isNonPageRoutePattern(r.pattern)), lines = ["// Auto-generated by STX - do not edit"];
+  if (pageRoutes.length === 0)
+    lines.push("// No page routes found \u2014 route paths stay typed as string.", "export {}", "");
+  else {
+    lines.push("declare module '@stacksjs/stx' {", "  interface KnownRoutes {");
+    for (const route of pageRoutes) {
+      const paramEntries = [];
+      for (const p of route.params) {
+        const optional = route.pattern.includes(`:${p}?`) ? "?" : "";
+        paramEntries.push(`${p}${optional}: string`);
+      }
+      const paramsStr = paramEntries.join("; ");
+      lines.push(`    '${route.pattern}': { ${paramsStr} }`);
     }
-    const paramsStr = paramEntries.join("; ");
-    lines.push(`    '${route.pattern}': { ${paramsStr} }`);
+    lines.push("  }", "}", "", "export {}", "");
   }
-  lines.push("  }", "}", "");
-  fs.mkdirSync(outputDir, { recursive: !0 });
-  fs.writeFileSync(path.join(outputDir, "route-types.d.ts"), lines.join(`
-`));
+  const contents = lines.join(`
+`), target = path.join(outputDir, "route-types.d.ts");
+  try {
+    if (fs.existsSync(target) && fs.readFileSync(target, "utf8") === contents)
+      return;
+    fs.mkdirSync(outputDir, { recursive: !0 });
+    fs.writeFileSync(target, contents);
+  } catch {}
 }
 export function generateRouteManifest(routes, outputDir, pagesDir) {
-  const cwd = process.cwd(), relativePages = path.relative(cwd, pagesDir), excludeDirs = ["components", "layouts", "partials"], pageRoutes = routes.filter((r) => !excludeDirs.some((dir) => r.pattern.startsWith(`/${dir}/`) || r.pattern === `/${dir}`)), lines = [
+  const cwd = process.cwd(), relativePages = path.relative(cwd, pagesDir), pageRoutes = routes.filter((r) => !isNonPageRoutePattern(r.pattern)), lines = [
     "// Auto-generated by stx \u2014 do not edit",
     `// Source: ${relativePages || "pages"}/`,
     "",

package/dist/file-router.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { generateRouteManifest, generateRouteTypes } from "./codegen.js";
 import { filePathToPattern, patternToRegex } from "./matcher.js";
 import { resolveLayoutChain } from "./nested-layouts.js";
+import { NON_PAGE_DIRS } from "./page-routes.js";
 function scanDirectory(dir, extensions) {
   const files = [];
   if (!fs.existsSync(dir))
@@ -13,6 +14,8 @@ function scanDirectory(dir, extensions) {
     if (entry.isDirectory()) {
       if (entry.name.startsWith("."))
         continue;
+      if (NON_PAGE_DIRS.includes(entry.name))
+        continue;
       files.push(...scanDirectory(fullPath, extensions));
     } else if (entry.isFile()) {
       const ext = path.extname(entry.name);

package/dist/index.d.ts

@@ -49,5 +49,7 @@ export { resolveLayoutChain } from './nested-layouts';
 export { deriveLayoutGroup, extractLayoutMetadata } from './layout-metadata';
 // Route type generation
 export { generateRouteTypes, generateRouteManifest } from './codegen';
+// Which files under a page root are public routes (#1866)
+export { NON_PAGE_DIRS, isNonPageRoutePath, isNonPageRoutePattern } from './page-routes';
 // Client-side SPA navigation
 export { getRouterScript } from './client';

package/dist/index.js

@@ -21,4 +21,5 @@ export {
 export { resolveLayoutChain } from "./nested-layouts.js";
 export { deriveLayoutGroup, extractLayoutMetadata } from "./layout-metadata.js";
 export { generateRouteTypes, generateRouteManifest } from "./codegen.js";
+export { NON_PAGE_DIRS, isNonPageRoutePath, isNonPageRoutePattern } from "./page-routes.js";
 export { getRouterScript } from "./client.js";

package/dist/middleware.d.ts

@@ -24,5 +24,20 @@ export declare function getMiddlewareNames(): string[];
 // =============================================================================
 export declare function loadMiddlewareFromDirectory(baseDir: string, middlewareDir?: string): Promise<void>;
 export declare function createRouteLocation(pathname: string, params: Record<string, string>, meta: Record<string, unknown>, search?: string): RouteLocation;
-export declare function createMiddlewareContext(to: RouteLocation, from: RouteLocation | null, request?: Request): MiddlewareContext;
+/**
+ * Build the context a middleware chain runs against.
+ *
+ * `options.isServer` exists because sniffing `typeof window` is wrong whenever a
+ * DOM has been polyfilled into a server process, and this repo does exactly that
+ * — `bunfig.toml` preloads happy-dom for every test, and
+ * `story/visual-testing.ts` imports very-happy-dom at runtime. In those
+ * processes `window` is defined, so the sniff says "client" on the server and
+ * {@link runMiddleware}'s mode filters inverted: `mode: 'server'` middleware was
+ * SKIPPED and `mode: 'client'` middleware RAN. Every middleware test in the repo
+ * was therefore asserting the mirror image of production. See #1849.
+ *
+ * A caller that knows which side it is on should say so. The sniff remains the
+ * default so existing callers are unaffected.
+ */
+export declare function createMiddlewareContext(to: RouteLocation, from: RouteLocation | null, request?: Request, options?: { isServer?: boolean }): MiddlewareContext;
 export declare function runMiddleware(middlewareNames: string | string[], context: MiddlewareContext): Promise<MiddlewareResult>;

package/dist/middleware.js

@@ -186,8 +186,8 @@ export function createRouteLocation(pathname, params, meta, search = "") {
     meta
   };
 }
-export function createMiddlewareContext(to, from, request) {
-  const isServer = typeof window > "u", isClient = !isServer, responseHeaders = new Headers;
+export function createMiddlewareContext(to, from, request, options) {
+  const isServer = options?.isServer ?? typeof window > "u", isClient = !isServer, responseHeaders = new Headers;
   return {
     to,
     from,
@@ -205,13 +205,22 @@ export async function runMiddleware(middlewareNames, context) {
   for (const name of names) {
     const middleware = getMiddleware(name);
     if (!middleware) {
-      console.warn(`Middleware '${name}' not found`);
-      continue;
+      console.error(`Route middleware '${name}' is not registered \u2014 failing the guard closed.`);
+      return {
+        passed: !1,
+        abort: {
+          type: "abort",
+          error: {
+            statusCode: 500,
+            message: `Route middleware '${name}' is not registered`
+          }
+        },
+        state: context.state,
+        responseHeaders: context.responseHeaders
+      };
     }
     if (middleware.mode === "server" && !isServer)
       continue;
-    if (middleware.mode === "client" && isServer)
-      continue;
     try {
       const result = await middleware.handler(context);
       if (result) {

package/dist/page-routes.d.ts

@@ -0,0 +1,41 @@
+/**
+ * True when a path relative to a page root sits inside a non-page directory,
+ * at any depth.
+ *
+ * Accepts either OS-native or POSIX separators.
+ */
+export declare function isNonPageRoutePath(relativePath: string): boolean;
+/**
+ * True when a URL pattern points *into* a non-page directory.
+ *
+ * `/components/foo` and `/admin/components/foo` qualify; bare `/components`
+ * does not, and must not — the scanner already skips the directory, so the only
+ * way that pattern exists is a real `components.stx` page. Excluding it here
+ * would route the page but leave it out of `.stx/routes.ts` and the generated
+ * route types, which is the manifest-versus-table disagreement this module was
+ * added to end.
+ */
+export declare function isNonPageRoutePattern(pattern: string): boolean;
+/**
+ * Which files under a page root are actually public routes.
+ *
+ * `components/`, `layouts/` and `partials/` under `pagesDir` are building
+ * blocks, not pages. They were already filtered out of the generated route
+ * manifest and route types — but only there (`codegen.ts`), which meant the
+ * manifest and the live route table disagreed: `.stx/routes.ts` said a site had
+ * 30 routes while `Router.routes` had 34, and the four extra ones were served,
+ * statically built to HTML, and advertised in sitemap.xml as public URLs
+ * (stacksjs/stx#1866).
+ *
+ * One reporting app worked around it structurally — deleting
+ * `resources/views/layouts/` so layouts *could not* be routed — which is the
+ * kind of fix that only exists because the framework made it necessary.
+ *
+ * The rule lives here so the scanner and the codegen share it rather than
+ * restating it. The codegen's version also only matched a leading segment, so
+ * `resources/views/admin/components/x.stx` slipped through it.
+ *
+ * @module page-routes
+ */
+/** Directories under a page root whose contents are never public routes. */
+export declare const NON_PAGE_DIRS: readonly string[];

package/dist/page-routes.js

@@ -0,0 +1,7 @@
+export const NON_PAGE_DIRS = ["components", "layouts", "partials"];
+export function isNonPageRoutePath(relativePath) {
+  return relativePath.split(/[\\/]/).filter(Boolean).slice(0, -1).some((segment) => NON_PAGE_DIRS.includes(segment));
+}
+export function isNonPageRoutePattern(pattern) {
+  return isNonPageRoutePath(pattern.replace(/^\//, ""));
+}

package/dist/types.d.ts

@@ -92,7 +92,13 @@ export declare interface MiddlewareResult {
   state: Record<string, unknown>
   responseHeaders: Headers
 }
-export type MiddlewareMode = 'universal' | 'server' | 'client';
+// 'client' was removed (stacksjs/stx#1891): the SPA router is a stringified
+// runtime with no access to this registry, and every runMiddleware caller is a
+// server process, so a client-mode guard could never run. Keeping the mode was
+// an API that looked like a browser-side security boundary while doing nothing —
+// worse than not having it. If browser-side UX guards are wanted, they belong in
+// a separately named, non-enforcement API.
+export type MiddlewareMode = 'universal' | 'server';
 export type RouteMiddlewareHandler = (
   context: MiddlewareContext,
 ) => void | Promise<void> | NavigationResult | Promise<NavigationResult | void>;

package/package.json

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