what-router 0.11.7 → 0.12.0

package/README.md

@@ -134,6 +134,27 @@ const requireRole = asyncGuard(
 }
 ```
 
+`redirect()` throws a navigation signal. Two places catch it: route middleware,
+and a component body.
+
+```js
+{
+  path: '/admin',
+  component: AdminPanel,
+  middleware: [() => isLoggedIn() || redirect('/login')],
+}
+
+function Private() {
+  if (!isLoggedIn()) redirect('/login');
+  return h(Secret, {});
+}
+```
+
+From an event handler, a promise callback or a timer, nothing catches the
+signal and it surfaces as an uncaught error carrying `ERR_REDIRECT_NOT_CAUGHT`.
+Call `navigate(to)` there instead. A `try/catch` around a `redirect()` call
+also swallows the signal, so rethrow anything whose `name` is `RouterRedirect`.
+
 ## View Transitions
 
 Navigation uses the View Transitions API by default when available. Use helpers to customize:
@@ -165,6 +186,13 @@ enableScrollRestoration(); // call once at app entry
 | `navigate(to, opts?)` | Programmatic navigation |
 | `route` | Reactive route state object |
 | `useRoute()` | Hook returning computed route properties |
+| `useParams()` | Current route params |
+| `useSearch()` | Parsed query string of the last matched route (stale on a 404, like `route.query`) |
+| `useNavigate()` | Returns `navigate` |
+| `redirect(to, opts?)` | Abort route matching and navigate, **from route middleware** (throws, never returns) |
+| `prefetchRoute(href)` | Prefetch a route's assets |
+| `beforeNavigate(fn)` | Guard run before each route navigation (not hash links); return `false` to cancel |
+| `afterNavigate(fn)` | Callback run after each committed navigation |
 | `defineRoutes(config)` | Create routes from flat object |
 | `nestedRoutes(base, children, opts?)` | Nested route helper |
 | `routeGroup(name, routes, opts?)` | Group routes without affecting URL |

package/dist/index.min.js

@@ -1 +1,15 @@
-import{signal as x,effect as U,computed as S,batch as I,h as a,ErrorBoundary as V}from"what-core";function L(e){let t=e.replace(/\([\w-]+\)\//g,"").replace(/\[\.\.\.(\w+)\]/g,(r,c)=>`*:${c}`).replace(/\[(\w+)\]/g,":$1"),n=[],s=null,o=t.split("/").map(r=>r.startsWith("*:")?(s=r.slice(2),n.push(s),"(.+)"):r==="*"?(s="rest",n.push("rest"),"(.+)"):r.startsWith(":")?(n.push(r.slice(1)),"([^/]+)"):r.replace(/[.*+?^${}()|[\]\\]/g,"\\$&")).join("/");return{regex:new RegExp(`^${o}$`),paramNames:n,catchAll:s}}function A(e,t){let s=t.filter(o=>o.path).sort((o,i)=>{let r=(o.path.match(/:/g)||[]).length+(o.path.includes("*")?100:0),c=(i.path.match(/:/g)||[]).length+(i.path.includes("*")?100:0);return r-c});for(let o of s){let{regex:i,paramNames:r}=L(o.path),c=e.match(i);if(c){let d={};return r.forEach((u,l)=>{d[u]=decodeURIComponent(c[l+1])}),{route:o,params:d}}}return null}function q(e){let t={};if(!e)return t;let n=e.startsWith("?")?e.slice(1):e;for(let s of n.split("&")){let[o,i]=s.split("=");if(!o)continue;let r=decodeURIComponent(o),c=i?decodeURIComponent(i):"";r in t?Array.isArray(t[r])?t[r].push(c):t[r]=[t[r],c]:t[r]=c}return t}function C(e){if(typeof e!="string")return!1;let n=e.trim().replace(/[\s\x00-\x1f]/g,"").toLowerCase();return!(n.startsWith("javascript:")||n.startsWith("data:")||n.startsWith("vbscript:"))}var p=x(typeof location<"u"?location.pathname+location.search+location.hash:"/"),T=x({}),$=x({}),w=x(!1),W=x(null),h={get url(){return p()},get path(){return p().split("?")[0].split("#")[0]},get params(){return T()},get query(){return $()},get hash(){let e=p().split("#")[1];return e?"#"+e:""},get isNavigating(){return w()},get error(){return W()}};async function v(e,t={}){let{replace:n=!1,state:s=null,transition:o=!0,_fromPopstate:i=!1}=t;if(!C(e)){typeof console<"u"&&console.warn(`[what-router] Blocked navigation to unsafe URL: ${e}`);return}if(typeof window<"u"&&e.startsWith("#")){let u=p().split("#")[0]+e;history.replaceState(s,"",u),p.set(u);let l=document.querySelector(e);l&&l.scrollIntoView({behavior:"smooth"});return}if(e===p()||w.peek())return;w.set(!0),W.set(null);let r=()=>{i||(typeof window<"u"&&k.set(p(),{x:scrollX,y:scrollY}),n?history.replaceState(s,"",e):history.pushState(s,"",e)),p.set(e),w.set(!1)};if(o&&typeof document<"u"&&document.startViewTransition)try{await document.startViewTransition(r).finished}catch{}else r()}typeof window<"u"&&window.addEventListener("popstate",()=>{k.set(p(),{x:scrollX,y:scrollY});let e=location.pathname+location.search+location.hash;v(e,{replace:!0,_fromPopstate:!0,transition:!1}).then(()=>{let t=k.get(e);t&&requestAnimationFrame(()=>window.scrollTo(t.x,t.y))})});function K(e,t){let n=[];if(!e.path)return n;let s=e.path.split("/").filter(Boolean),o="";for(let i of s){o+="/"+i;let r=t.find(c=>c.layout&&c.path===o+"/_layout");r&&n.push(r.layout)}return e.layout&&n.push(e.layout),n}var g=[],B=10;function G({routes:e,fallback:t,globalLayout:n}){let s=()=>{let o=p(),i=o.split("?")[0].split("#")[0],r=o.split("?")[1]?.split("#")[0]||"",c=w(),d=A(i,e);if(d){I(()=>{T.set(d.params),$.set(q(r))});let{route:u,params:l}=d,m=q(r);if(u.middleware&&u.middleware.length>0)for(let b of u.middleware){let P=b({path:i,params:l,query:m,route:u});if(P===!1)return t?a(t,{}):a("div",{class:"what-403"},a("h1",null,"403"),a("p",null,"Access denied"));if(typeof P=="string"){if(g.push(P),g.length>B){let R=g.slice(-5).join(" \u2192 ");return g.length=0,console.error(`[what-router] Redirect loop detected: ${R}`),w.set(!1),a("div",{class:"what-redirect-loop"},a("h1",null,"Redirect Loop"),a("p",null,"Too many redirects. Check your middleware configuration."))}let E=new Set,_=!1;for(let R of g){if(E.has(R)){_=!0;break}E.add(R)}if(_){let R=g.join(" \u2192 ");return g.length=0,console.error(`[what-router] Redirect cycle detected: ${R}`),w.set(!1),a("div",{class:"what-redirect-loop"},a("h1",null,"Redirect Loop"),a("p",null,"Circular redirect detected. Check your middleware configuration."))}return v(P,{replace:!0}),null}}g.length=0;let y;u.loading&&c?y=a(u.loading,{}):y=a(u.component,{params:l,query:m,route:u}),u.error&&(y=a(V,{fallback:u.error},y));let f=K(u,e);for(let b of f.reverse())y=a(b,{params:l,query:m},y);return y}return t?a(t,{}):a("div",{class:"what-404"},a("h1",null,"404"),a("p",null,"Page not found"))};return n?a(n,{},s):s}function z({href:e,class:t,className:n,children:s,replace:o,prefetch:i=!0,activeClass:r="active",exactActiveClass:c="exact-active",transition:d=!0,...u}){let l=C(e)?e:"about:blank";!C(e)&&typeof console<"u"&&console.warn(`[what-router] Link blocked unsafe href: ${e}`);let m=l.split("?")[0].split("#")[0];return a("a",{href:l,class:()=>{let f=h.path,b=m==="/"?f==="/":f===m||f.startsWith(m+"/");return[t||n,b&&r,f===m&&c].filter(Boolean).join(" ")||void 0},onclick:f=>{f.ctrlKey||f.metaKey||f.shiftKey||f.altKey||f.button!==0||(f.preventDefault(),v(l,{replace:o,transition:d}))},onmouseenter:i?()=>j(l):void 0,...u},...Array.isArray(s)?s:[s])}function Y(e){return z(e)}function H(e){return Object.entries(e).map(([t,n])=>typeof n=="function"?{path:t,component:n}:{path:t,...n})}function M(e,t,n={}){let{layout:s,loading:o,error:i}=n;return t.map(r=>({...r,path:e+r.path,layout:r.layout||s,loading:r.loading||o,error:r.error||i}))}function J(e,t,n={}){let{layout:s,middleware:o}=n;return t.map(i=>({...i,_group:e,layout:i.layout||s,middleware:[...i.middleware||[],...o||[]]}))}function Z({to:e}){return v(e,{replace:!0}),null}function ee(e,t){return n=>function(o){let i=e(o);return i instanceof Promise?a("div",{class:"what-guard-loading"},"Loading..."):i?a(n,o):typeof t=="string"?(v(t,{replace:!0}),null):a(t,o)}}function te(e,t={}){let{fallback:n="/login",loading:s=null}=t;return o=>function(r){let c=x("pending"),d=x(null),u=!1;return U(()=>(u=!1,Promise.resolve(e(r)).then(l=>{u||(d.set(l),c.set(l?"allowed":"denied"))}).catch(()=>{u||c.set("denied")}),()=>{u=!0})),()=>{let l=c();return l==="pending"?s?a(s,{}):null:l==="allowed"?a(o,r):typeof n=="string"?(v(n,{replace:!0}),null):a(n,r)}}}var N=new Set;function j(e){if(typeof document>"u"||N.has(e))return;N.add(e);let t=document.createElement("link");t.rel="prefetch",t.href=e,document.head.appendChild(t)}var k=new Map;function ne(){typeof window>"u"||(window.addEventListener("beforeunload",()=>{k.set(location.pathname,window.scrollY)}),U(()=>{let e=h.path,t=k.get(e);requestAnimationFrame(()=>{t!==void 0?window.scrollTo(0,t):h.hash?document.querySelector(h.hash)?.scrollIntoView():window.scrollTo(0,0)})}))}function re(e){return{style:{viewTransitionName:e}}}function oe(e){typeof document>"u"||(document.documentElement.dataset.transition=e)}function ie(){return{path:S(()=>h.path),params:S(()=>h.params),query:S(()=>h.query),hash:S(()=>h.hash),isNavigating:S(()=>h.isNavigating),navigate:v,prefetch:j}}function se({children:e}){return e||null}function ae({routes:e,layout:t,fallback:n,error:s}){let o=e.map(i=>({path:i.path,component:i.component,layout:i.layout||void 0,_mode:i.mode||"client"}));return G({routes:o,globalLayout:t,fallback:n||D})}function D(){return a("div",{style:"text-align:center;padding:60px 20px"},a("h1",{style:"font-size:48px;margin-bottom:8px"},"404"),a("p",{style:"color:#64748b"},"Page not found"))}export{ae as FileRouter,z as Link,Y as NavLink,se as Outlet,Z as Redirect,G as Router,te as asyncGuard,L as compilePath,H as defineRoutes,ne as enableScrollRestoration,ee as guard,C as isSafeUrl,A as matchRoute,v as navigate,M as nestedRoutes,q as parseQuery,j as prefetch,h as route,J as routeGroup,oe as setViewTransition,ie as useRoute,re as viewTransitionName};
+import{signal as x,effect as I,computed as b,batch as M,h as c,ErrorBoundary as X}from"what-core";function O(e){let t=e.replace(/\([\w-]+\)\//g,"").replace(/\[\.\.\.(\w+)\]/g,(i,u)=>`*:${u}`).replace(/\[(\w+)\]/g,":$1"),n=[],r=null,o=t.split("/").map(i=>i.startsWith("*:")?(r=i.slice(2),n.push(r),"(.+)"):i==="*"?(r="rest",n.push("rest"),"(.+)"):i.startsWith(":")?(n.push(i.slice(1)),"([^/]+)"):i.replace(/[.*+?^${}()|[\]\\]/g,"\\$&")).join("/");return{regex:new RegExp(`^${o}$`),paramNames:n,catchAll:r}}var _=new Map,F=1e3;function H(e){let t=_.get(e);return t||(t=O(e),_.size>=F&&_.clear(),_.set(e,t)),t}function K(e,t){let n;try{n=decodeURIComponent(e)}catch{return null}let r=n.split(/[/\\]/);return!t&&r.length>1||r.includes("..")?null:n}function A(e,t){let n=t.filter(r=>r.path);n.sort((r,o)=>{let a=(r.path.match(/:/g)||[]).length+(r.path.includes("*")?100:0),i=(o.path.match(/:/g)||[]).length+(o.path.includes("*")?100:0);return a-i});for(let r of n){let{regex:o,paramNames:a,catchAll:i}=H(r.path),u=e.match(o);if(u){let p={},l=!1;if(a.forEach((s,d)=>{let g=K(u[d+1],s===i);if(g===null){l=!0;return}p[s]=g}),l)continue;return{route:r,params:p}}}return null}function C(e){let t=Object.create(null);if(!e)return t;let n=e.startsWith("?")?e.slice(1):e;for(let r of n.split("&")){let[o,a]=r.split("=");if(!o)continue;let i=decodeURIComponent(o),u=a?decodeURIComponent(a):"";Object.prototype.hasOwnProperty.call(t,i)?Array.isArray(t[i])?t[i].push(u):t[i]=[t[i],u]:t[i]=u}return t}var Q=new Set(["http:","https:","mailto:","tel:"]);function k(e){if(typeof e!="string")return!1;let n=e.trim().replace(/[\s\x00-\x1f]/g,"").toLowerCase();if(n.startsWith("javascript:")||n.startsWith("data:")||n.startsWith("vbscript:")||/^[/\\]{2}/.test(n))return!1;let r=n.match(/^([a-z][a-z0-9+.-]*:)/);return r?Q.has(r[1]):!n.includes("\\")}var h=x(typeof location<"u"?location.pathname+location.search+location.hash:"/"),G=x({}),D=x({}),y=x(!1),R=x(null),V=x(null),m={get url(){return h()},get path(){return h().split("?")[0].split("#")[0]},get params(){return G()},get query(){return D()},get hash(){let e=h().split("#")[1];return e?"#"+e:""},get isNavigating(){return y()},get error(){return V()}},T=[],q=[];function z(e,t){return e.push(t),()=>{let n=e.indexOf(t);n!==-1&&e.splice(n,1)}}function ue(e){return z(T,e)}function le(e){return z(q,e)}async function v(e,t={}){let{replace:n=!1,state:r=null,transition:o=!0,_fromPopstate:a=!1,_redirectChain:i=!1}=t;if(i||(w.length=0),!k(e)){typeof console<"u"&&console.warn("[what-router] Blocked navigation to unsafe URL:",e);return}if(typeof window<"u"&&e.startsWith("#")){let d=h().split("#")[0]+e;history.replaceState(r,"",d),h.set(d);let g=document.querySelector(e);g&&g.scrollIntoView({behavior:"smooth"});return}if(e===h()||y.peek())return;y.set(!0),R.set(e);let u=h();if(T.length){let l=!1;try{for(let s of T.slice())if(await s(e,u)===!1){l=!0;break}}catch(s){throw y.set(!1),R.set(null),s}if(l){y.set(!1),R.set(null),a&&typeof history<"u"&&history.pushState(null,"",u);return}}V.set(null);let p=()=>{a||(typeof window<"u"&&E.set(h(),{x:window.scrollX,y:window.scrollY}),n?history.replaceState(r,"",e):history.pushState(r,"",e)),h.set(e),y.set(!1),R.set(null)};if(o&&typeof document<"u"&&document.startViewTransition)try{await document.startViewTransition(p).finished}catch{}else p();if(q.length)for(let l of q.slice())l(e,u)}var B=Symbol.for("what.router.redirect"),Y=Symbol.for("what.navigation.signal");function fe(e,t={}){if(!k(e)){let r=typeof e=="string"?e:Object.prototype.toString.call(e),o=new Error(`[what-router] redirect() refused an unsafe target: ${r}`);throw o.code="ERR_UNSAFE_REDIRECT",o.suggestion='redirect() accepts same-origin paths and http:, https:, mailto: or tel: URLs only. Protocol-relative ("//host"), backslash-smuggled and javascript:/data: targets are open-redirect vectors. Check a user-supplied target against an allowlist first.',o.codeExample=`// Bad - a user-controlled target can leave your origin:
+redirect(query.next);
+
+// Good - allowlist the target first:
+redirect(ALLOWED.has(query.next) ? query.next : '/');`,o}let n=new Error(`[what-router] redirect to ${e}`);throw n.name="RouterRedirect",n.code="ERR_REDIRECT_NOT_CAUGHT",n.suggestion="Seeing this signal in your console means nothing caught it. redirect() works from route middleware and from a component body, where the Router catches it. From an event handler, a promise callback or a timer, call navigate(to) instead. A try/catch around the redirect() call also swallows it.",n.codeExample=`// Bad - an event handler runs long after the render the Router caught:
+<button onclick={() => redirect('/login')}>Sign in</button>
+
+// Good - navigate() from a handler:
+<button onclick={() => navigate('/login')}>Sign in</button>
+
+// Good - redirect() from a component body, which the Router catches:
+function Private() {
+  if (!user()) redirect('/login');
+  return <Secret />;
+}`,n[B]=!0,n[Y]=()=>{L(e,t)},n.to=e,n.options=t,n}typeof window<"u"&&window.addEventListener("popstate",()=>{E.set(h(),{x:window.scrollX,y:window.scrollY});let e=location.pathname+location.search+location.hash;v(e,{replace:!0,_fromPopstate:!0,transition:!1}).then(()=>{let t=E.get(e);t&&requestAnimationFrame(()=>window.scrollTo(t.x,t.y))})});function J(e,t){let n=[];if(!e.path)return n;let r=e.path.split("/").filter(Boolean),o="";for(let a of r){o+="/"+a;let i=t.find(u=>u.layout&&u.path===o+"/_layout");i&&n.push(i.layout)}return e.layout&&n.push(e.layout),n}var w=[],Z=10;function W(e){return c("div",{class:"what-redirect-loop"},c("h1",null,"Redirect Loop"),c("p",null,e))}function L(e,t){if(w.push(e),w.length>Z){let o=w.slice(-5).join(" \u2192 ");return w.length=0,console.error(`[what-router] Redirect loop detected: ${o}`),y.set(!1),R.set(null),W("Too many redirects. Check your middleware configuration.")}let n=new Set,r=!1;for(let o of w){if(n.has(o)){r=!0;break}n.add(o)}if(r){let o=w.join(" \u2192 ");return w.length=0,console.error(`[what-router] Redirect cycle detected: ${o}`),y.set(!1),R.set(null),W("Circular redirect detected. Check your middleware configuration.")}return v(e,{replace:!0,...t,_redirectChain:!0}),null}function ee(e,t,n){if(!e)return null;let r=e.split("?")[0].split("#")[0],o=A(r,t);return!o||o.route===n?null:o.route.loading||null}function te({routes:e,fallback:t,globalLayout:n}){let r=()=>{let a=h(),i=a.split("?")[0].split("#")[0],u=a.split("?")[1]?.split("#")[0]||"",p=y(),l=A(i,e);if(l){M(()=>{G.set(l.params),D.set(C(u))});let{route:s,params:d}=l,g=C(u);if(s.middleware&&s.middleware.length>0)for(let P of s.middleware){let N=P({path:i,params:d,query:g,route:s});if(N===!1)return t?c(t,{}):c("div",{class:"what-403"},c("h1",null,"403"),c("p",null,"Access denied"));if(typeof N=="string")return L(N)}let f,S=p?ee(R(),e,s):null;S?f=c(S,{}):s.loading&&p?f=c(s.loading,{}):f=c(s.component,{params:d,query:g,route:s}),s.error&&(f=c(X,{fallback:s.error},f));let j=J(s,e);for(let P of j.reverse())f=c(P,{params:d,query:g},f);return f}return t?c(t,{}):c("div",{class:"what-404"},c("h1",null,"404"),c("p",null,"Page not found"))},o=()=>{let a=null;try{return r()}catch(i){if(!i||!i[B])throw i;a=i}return L(a.to,a.options)};return n?c(n,{},o):o}function ne({href:e,class:t,className:n,children:r,replace:o,prefetch:a=!0,activeClass:i="active",exactActiveClass:u="exact-active",transition:p=!0,...l}){let s=k(e)?e:"about:blank";!k(e)&&typeof console<"u"&&console.warn("[what-router] Link blocked unsafe href:",e);let d=s.split("?")[0].split("#")[0];return c("a",{href:s,class:()=>{let f=m.path,S=d==="/"?f==="/":f===d||f.startsWith(d+"/");return[t||n,S&&i,f===d&&u].filter(Boolean).join(" ")||void 0},onclick:f=>{f.ctrlKey||f.metaKey||f.shiftKey||f.altKey||f.button!==0||(f.preventDefault(),v(s,{replace:o,transition:p}))},onmouseenter:a?()=>U(s):void 0,...l},...Array.isArray(r)?r:[r])}function de(e){return ne(e)}function pe(e){return Object.entries(e).map(([t,n])=>typeof n=="function"?{path:t,component:n}:{path:t,...n})}function re(e,t){let n=e.endsWith("/")?e.slice(0,-1):e,r=!t||t==="/"?"/":t.startsWith("/")?t:`/${t}`;return r==="/"?n||"/":n+r}function he(e,t,n={}){let{layout:r,loading:o,error:a}=n;return t.map(i=>({...i,path:re(e,i.path),layout:i.layout||r,loading:i.loading||o,error:i.error||a}))}function me(e,t,n={}){let{layout:r,middleware:o}=n;return t.map(a=>({...a,_group:e,layout:a.layout||r,middleware:[...a.middleware||[],...o||[]]}))}function ge({to:e}){return v(e,{replace:!0}),null}function ye(e,t){return n=>function(o){let a=e(o);return a instanceof Promise?c("div",{class:"what-guard-loading"},"Loading..."):a?c(n,o):typeof t=="string"?(v(t,{replace:!0}),null):c(t,o)}}function we(e,t={}){let{fallback:n="/login",loading:r=null}=t;return o=>function(i){let u=x("pending"),p=x(null),l=!1;return I(()=>(l=!1,Promise.resolve(e(i)).then(s=>{l||(p.set(s),u.set(s?"allowed":"denied"))}).catch(()=>{l||u.set("denied")}),()=>{l=!0})),()=>{let s=u();return s==="pending"?r?c(r,{}):null:s==="allowed"?c(o,i):typeof n=="string"?(v(n,{replace:!0}),null):c(n,i)}}}var $=new Set;function U(e){if(typeof document>"u"||$.has(e))return;$.add(e);let t=document.createElement("link");t.rel="prefetch",t.href=e,document.head.appendChild(t)}var E=new Map;function xe(){typeof window>"u"||(window.addEventListener("beforeunload",()=>{E.set(location.pathname,window.scrollY)}),I(()=>{let e=m.path,t=E.get(e);requestAnimationFrame(()=>{t!==void 0?window.scrollTo(0,t):m.hash?document.querySelector(m.hash)?.scrollIntoView():window.scrollTo(0,0)})}))}function ve(e){return{style:{viewTransitionName:e}}}function Re(e){typeof document>"u"||(document.documentElement.dataset.transition=e)}function be(){return{path:b(()=>m.path),params:b(()=>m.params),query:b(()=>m.query),hash:b(()=>m.hash),isNavigating:b(()=>m.isNavigating),navigate:v,prefetch:U}}function Ee(){return m.params}function Se(){return m.query}function _e(){return v}function Ae(e){U(e)}function Ce({children:e}){return e||null}function ke({routes:e,layout:t,fallback:n,error:r}){let o=e.map(a=>({path:a.path,component:a.component,layout:a.layout||void 0,loading:a.loading||void 0,error:a.error||r||void 0,_mode:a.mode||"client"}));return te({routes:o,globalLayout:t,fallback:n||oe})}function oe(){return c("div",{style:"text-align:center;padding:60px 20px"},c("h1",{style:"font-size:48px;margin-bottom:8px"},"404"),c("p",{style:"color:#64748b"},"Page not found"))}export{ke as FileRouter,ne as Link,de as NavLink,Ce as Outlet,ge as Redirect,te as Router,le as afterNavigate,we as asyncGuard,ue as beforeNavigate,O as compilePath,pe as defineRoutes,xe as enableScrollRestoration,ye as guard,k as isSafeUrl,A as matchRoute,v as navigate,he as nestedRoutes,C as parseQuery,U as prefetch,Ae as prefetchRoute,fe as redirect,m as route,me as routeGroup,Re as setViewTransition,_e as useNavigate,Ee as useParams,be as useRoute,Se as useSearch,ve as viewTransitionName};

package/dist/match.min.js

@@ -1 +1 @@
-function u(n){let e=n.replace(/\([\w-]+\)\//g,"").replace(/\[\.\.\.(\w+)\]/g,(t,o)=>`*:${o}`).replace(/\[(\w+)\]/g,":$1"),a=[],c=null,r=e.split("/").map(t=>t.startsWith("*:")?(c=t.slice(2),a.push(c),"(.+)"):t==="*"?(c="rest",a.push("rest"),"(.+)"):t.startsWith(":")?(a.push(t.slice(1)),"([^/]+)"):t.replace(/[.*+?^${}()|[\]\\]/g,"\\$&")).join("/");return{regex:new RegExp(`^${r}$`),paramNames:a,catchAll:c}}function h(n,e){let c=e.filter(r=>r.path).sort((r,s)=>{let t=(r.path.match(/:/g)||[]).length+(r.path.includes("*")?100:0),o=(s.path.match(/:/g)||[]).length+(s.path.includes("*")?100:0);return t-o});for(let r of c){let{regex:s,paramNames:t}=u(r.path),o=n.match(s);if(o){let i={};return t.forEach((p,l)=>{i[p]=decodeURIComponent(o[l+1])}),{route:r,params:i}}}return null}function f(n){let e={};if(!n)return e;let a=n.startsWith("?")?n.slice(1):n;for(let c of a.split("&")){let[r,s]=c.split("=");if(!r)continue;let t=decodeURIComponent(r),o=s?decodeURIComponent(s):"";t in e?Array.isArray(e[t])?e[t].push(o):e[t]=[e[t],o]:e[t]=o}return e}export{u as compilePath,h as matchRoute,f as parseQuery};
+function h(n){let t=n.replace(/\([\w-]+\)\//g,"").replace(/\[\.\.\.(\w+)\]/g,(e,s)=>`*:${s}`).replace(/\[(\w+)\]/g,":$1"),c=[],r=null,o=t.split("/").map(e=>e.startsWith("*:")?(r=e.slice(2),c.push(r),"(.+)"):e==="*"?(r="rest",c.push("rest"),"(.+)"):e.startsWith(":")?(c.push(e.slice(1)),"([^/]+)"):e.replace(/[.*+?^${}()|[\]\\]/g,"\\$&")).join("/");return{regex:new RegExp(`^${o}$`),paramNames:c,catchAll:r}}var a=new Map,m=1e3;function g(n){let t=a.get(n);return t||(t=h(n),a.size>=m&&a.clear(),a.set(n,t)),t}function x(n,t){let c;try{c=decodeURIComponent(n)}catch{return null}let r=c.split(/[/\\]/);return!t&&r.length>1||r.includes("..")?null:c}function y(n,t){let c=t.filter(r=>r.path);c.sort((r,o)=>{let l=(r.path.match(/:/g)||[]).length+(r.path.includes("*")?100:0),e=(o.path.match(/:/g)||[]).length+(o.path.includes("*")?100:0);return l-e});for(let r of c){let{regex:o,paramNames:l,catchAll:e}=g(r.path),s=n.match(o);if(s){let i={},u=!1;if(l.forEach((p,d)=>{let f=x(s[d+1],p===e);if(f===null){u=!0;return}i[p]=f}),u)continue;return{route:r,params:i}}}return null}function A(n){let t=Object.create(null);if(!n)return t;let c=n.startsWith("?")?n.slice(1):n;for(let r of c.split("&")){let[o,l]=r.split("=");if(!o)continue;let e=decodeURIComponent(o),s=l?decodeURIComponent(l):"";Object.prototype.hasOwnProperty.call(t,e)?Array.isArray(t[e])?t[e].push(s):t[e]=[t[e],s]:t[e]=s}return t}export{h as compilePath,y as matchRoute,A as parseQuery};

package/index.d.ts

@@ -49,7 +49,7 @@ export interface RouteConfig {
   /** Loading component */
   loading?: Component<{}>;
   /** Error component */
-  error?: Component<{ error: Error }>;
+  error?: Component<{ error: Error; reset: () => void }>;
   /** Route middleware */
   middleware?: RouteMiddleware[];
 }
@@ -78,6 +78,25 @@ export interface RouterProps {
 
 export function Router(props: RouterProps): VNode;
 
+// --- File-Based Router ---
+
+export interface FileRouteConfig {
+  path: string;
+  component: Component<RouteComponentProps>;
+  layout?: Component<LayoutProps>;
+  mode?: 'static' | 'server' | 'client' | 'hybrid';
+}
+
+export interface FileRouterProps {
+  routes: FileRouteConfig[];
+  layout?: Component<{ children?: VNodeChild }>;
+  fallback?: Component<{}>;
+  error?: Component<{ error: Error; reset: () => void }>;
+}
+
+/** Router driven by what-compiler's generated route manifest (virtual:what-routes). */
+export function FileRouter(props: FileRouterProps): VNode;
+
 // --- Link Component ---
 
 export interface LinkProps {
@@ -160,6 +179,82 @@ export interface UseRouteResult {
 
 export function useRoute(): UseRouteResult;
 
+// --- Route Accessors ---
+
+/** Current route params. Subscribes when read inside a tracking scope. */
+export function useParams<T = Record<string, string>>(): T;
+
+/**
+ * Query string of the last successfully matched route, parsed. Subscribes when
+ * read inside a tracking scope. Only the Router's match branch writes it, so on
+ * an unmatched (404) route this is the previous route's query, not the current
+ * URL's. Same value and same caveat as `route.query`.
+ */
+export function useSearch<T = Record<string, string>>(): T;
+
+/** The navigate function, for symmetry with useParams/useSearch. */
+export function useNavigate(): typeof navigate;
+
+/** Prefetch a route's assets. */
+export function prefetchRoute(href: string): void;
+
+// --- Redirect Signal ---
+
+/**
+ * Abort the current render and navigate.
+ *
+ * Throws a navigation signal. Two places catch it: route middleware, caught by
+ * the Router's matching pass, and a component body, caught by the runtime where
+ * it instantiates components. Anywhere else (an event handler, a promise
+ * callback, a timer, or a reactive thunk such as `{() => cond() && redirect(to)}`)
+ * nothing catches it and the signal surfaces as an uncaught error carrying
+ * `ERR_REDIRECT_NOT_CAUGHT`; call `navigate(to)` there instead. In a thunk the
+ * first render reports the error, but on a later re-run the navigation simply
+ * does not happen and the stale DOM stays, so prefer `navigate(to)` there.
+ * A `try/catch` around the call also swallows it, so rethrow anything whose
+ * `name` is `RouterRedirect`. On the server the signal escapes `renderToString`
+ * to its caller: read `.to` and emit a 302.
+ */
+export function redirect(to: string, options?: NavigateOptions): never;
+
+// --- Navigation Hooks ---
+
+/**
+ * Run before every route navigation; return false to cancel. Returns an
+ * unsubscribe. Not consulted for same-page hash navigation (`navigate('#x')`
+ * scrolls, it does not change the route). Cancelling a back/forward navigation
+ * restores the address bar by pushing the previous URL as a new history entry:
+ * the entry the browser moved to is not recovered and its `history.state` is
+ * not carried over.
+ */
+export function beforeNavigate(fn: (to: string, from: string) => boolean | Promise<boolean>): () => void;
+
+/** Run after every committed navigation. Returns an unsubscribe. */
+export function afterNavigate(fn: (to: string, from: string) => void): () => void;
+
 // --- Outlet ---
 
-export function Outlet(props: { children?: VNodeChild }): VNodeChild;
+export function Outlet(props: { children?: VNodeChild }): VNode;
+
+// --- Path Matching ---
+
+export interface CompiledPath {
+  regex: RegExp;
+  paramNames: string[];
+  catchAll: string | null;
+}
+
+/** Compile a path pattern (`/users/:id`, `/posts/*`, `/[slug]`) to a matcher. */
+export function compilePath(path: string): CompiledPath;
+
+/** Match a pathname against routes, most specific first. */
+export function matchRoute<T extends { path?: string }>(
+  path: string,
+  routes: T[],
+): { route: T; params: Record<string, string> } | null;
+
+/** Parse a query string into a null-prototype object. */
+export function parseQuery(search: string): Record<string, string>;
+
+/** Reject javascript:, data:, vbscript: and protocol-relative URLs. */
+export function isSafeUrl(url: string): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "what-router",
-  "version": "0.11.7",
+  "version": "0.12.0",
   "description": "What Framework - File-based & programmatic router with View Transitions",
   "type": "module",
   "main": "src/index.js",
@@ -33,8 +33,9 @@
   ],
   "author": "ZVN DEV (https://zvndev.com)",
   "license": "MIT",
+  "dependencies": {},
   "peerDependencies": {
-    "what-core": "^0.11.7"
+    "what-core": "^0.12.0"
   },
   "repository": {
     "type": "git",

package/src/index.js

@@ -6,7 +6,20 @@ import { signal, effect, computed, batch, h, ErrorBoundary } from 'what-core';
 import { compilePath, matchRoute, parseQuery } from './match.js';
 
 // --- URL Sanitization ---
-// Rejects javascript:, data:, vbscript: protocols (case-insensitive, trimmed).
+// Rejects javascript:, data:, vbscript: protocols (case-insensitive, trimmed),
+// any scheme outside the allowlist (blob:, about:, filesystem: ...), and
+// protocol-relative / backslash-smuggled paths that resolve to a foreign
+// origin. Browsers treat "\" like "/", so "/\evil.com" is an open redirect.
+//
+// Sibling predicate: safeLocalPath / safeRedirectTarget in
+// packages/server/src/action-handler.js. That one gates a server-issued
+// `Location:` header and must stay strictly narrower (same-origin local paths
+// only), because a form POST target is attacker-controllable in a way a client
+// navigation target is not. This one deliberately allows absolute http(s),
+// mailto: and tel:. Harden one, re-read the other; do not unify them.
+// packages/server/test/redirect-predicate-parity.test.js gates that ordering.
+
+const SAFE_PROTOCOLS = new Set(['http:', 'https:', 'mailto:', 'tel:']);
 
 export function isSafeUrl(url) {
   if (typeof url !== 'string') return false;
@@ -16,6 +29,13 @@ export function isSafeUrl(url) {
   if (normalized.startsWith('javascript:')) return false;
   if (normalized.startsWith('data:')) return false;
   if (normalized.startsWith('vbscript:')) return false;
+  if (/^[/\\]{2}/.test(normalized)) return false;
+  const scheme = normalized.match(/^([a-z][a-z0-9+.-]*:)/);
+  if (scheme) return SAFE_PROTOCOLS.has(scheme[1]);
+  // Scheme-less only: browsers normalize a backslash to a forward slash, so
+  // `\evil.com` resolves off-origin exactly as `/\evil.com` does. Absolute
+  // URLs already passed the protocol allowlist above.
+  if (normalized.includes('\\')) return false;
   return true;
 }
 
@@ -25,6 +45,12 @@ const _url = signal(typeof location !== 'undefined' ? location.pathname + locati
 const _params = signal({});
 const _query = signal({});
 const _isNavigating = signal(false);
+// The URL a navigation is heading TO, live for the duration of the navigation.
+// _url only commits at the very end, so during an awaited guard the router still
+// matches the route being LEFT. Without this, a destination route's `loading:`
+// component could never be shown: the only `loading:` in scope belonged to the
+// page the user was leaving.
+const _pendingUrl = signal(null);
 const _navigationError = signal(null);
 
 export const route = {
@@ -40,15 +66,49 @@ export const route = {
   get error() { return _navigationError(); },
 };
 
+// --- Navigation Hooks ---
+// Subscriber lists consulted by navigate(). Guards run before the URL changes
+// and can cancel by returning false; afterNavigate runs once the URL committed.
+// Module singletons on purpose: this module is browser-only (it listens for
+// popstate and mutates history), so its scope is one tab, not one request. The
+// server adapters import what-router/match, never this file, so there is no
+// shared-process path here of the kind b066671 fixed for server actions.
+
+const _beforeHooks = [];
+const _afterHooks = [];
+
+function subscribe(list, fn) {
+  list.push(fn);
+  return () => {
+    const i = list.indexOf(fn);
+    if (i !== -1) list.splice(i, 1);
+  };
+}
+
+export function beforeNavigate(fn) {
+  return subscribe(_beforeHooks, fn);
+}
+
+export function afterNavigate(fn) {
+  return subscribe(_afterHooks, fn);
+}
+
 // --- Navigation with View Transitions ---
 
 export async function navigate(to, opts = {}) {
-  const { replace = false, state = null, transition = true, _fromPopstate = false } = opts;
+  const { replace = false, state = null, transition = true, _fromPopstate = false, _redirectChain = false } = opts;
+
+  // A navigation the user asked for starts a fresh redirect chain; a hop
+  // queued by handleRedirect continues the current one.
+  if (!_redirectChain) _redirectHistory.length = 0;
 
   // Reject unsafe URLs
   if (!isSafeUrl(to)) {
     if (typeof console !== 'undefined') {
-      console.warn(`[what-router] Blocked navigation to unsafe URL: ${to}`);
+      // isSafeUrl() rejects non-strings, so the value reaching this warning is
+      // exactly the kind that can throw on template-literal coercion (Symbol,
+      // null-prototype object). Log it as a separate argument.
+      console.warn('[what-router] Blocked navigation to unsafe URL:', to);
     }
     return;
   }
@@ -68,10 +128,39 @@ export async function navigate(to, opts = {}) {
   // Don't navigate if already on the same URL
   if (to === _url()) return;
 
-  // Prevent concurrent navigations — wait for current to finish
+  // Prevent concurrent navigations: wait for the current one to finish. The
+  // flag is claimed in the same tick as the check, because an awaited
+  // beforeNavigate hook otherwise leaves a gap two navigations both get through.
   if (_isNavigating.peek()) return;
-
   _isNavigating.set(true);
+  _pendingUrl.set(to);
+
+  const from = _url();
+
+  // A popstate has already moved the browser URL, so cancelling one means
+  // pushing the previous entry back to keep the address bar in sync. That entry
+  // is a new one: the forward entry is not recoverable and its history.state is
+  // not carried over. Documented on beforeNavigate in index.d.ts.
+  if (_beforeHooks.length) {
+    let cancelled = false;
+    try {
+      for (const fn of _beforeHooks.slice()) {
+        if ((await fn(to, from)) === false) { cancelled = true; break; }
+      }
+    } catch (e) {
+      // A throwing guard must not leave the router permanently wedged.
+      _isNavigating.set(false);
+      _pendingUrl.set(null);
+      throw e;
+    }
+    if (cancelled) {
+      _isNavigating.set(false);
+      _pendingUrl.set(null);
+      if (_fromPopstate && typeof history !== 'undefined') history.pushState(null, '', from);
+      return;
+    }
+  }
+
   _navigationError.set(null);
 
   const doNavigation = () => {
@@ -79,7 +168,7 @@ export async function navigate(to, opts = {}) {
     if (!_fromPopstate) {
       // Save scroll position for current URL before navigating away
       if (typeof window !== 'undefined') {
-        scrollPositions.set(_url(), { x: scrollX, y: scrollY });
+        scrollPositions.set(_url(), { x: window.scrollX, y: window.scrollY });
       }
       if (replace) {
         history.replaceState(state, '', to);
@@ -89,6 +178,7 @@ export async function navigate(to, opts = {}) {
     }
     _url.set(to);
     _isNavigating.set(false);
+    _pendingUrl.set(null);
   };
 
   // Use View Transitions API if available and enabled
@@ -101,13 +191,71 @@ export async function navigate(to, opts = {}) {
   } else {
     doNavigation();
   }
+
+  if (_afterHooks.length) {
+    for (const fn of _afterHooks.slice()) fn(to, from);
+  }
+}
+
+// --- redirect() ---
+// Throws a navigation signal. Two places catch it:
+//
+//   - Route middleware, caught by the Router's own matching pass below.
+//   - A component body, caught by core's createComponent, which invokes the
+//     handler the signal carries under Symbol.for('what.navigation.signal')
+//     rather than reporting the throw to an ErrorBoundary. h() is lazy, so a
+//     route component is instantiated after the matching pass has returned;
+//     that is why the second catch has to live in core.
+//
+// Anywhere else (an event handler, a promise callback, a timer) nothing catches
+// it and the signal surfaces as an uncaught error. It carries a code, a fix and
+// an example for exactly that case, because that is the only case a human reads
+// it in.
+
+const REDIRECT = Symbol.for('what.router.redirect');
+const NAV_SIGNAL = Symbol.for('what.navigation.signal');
+
+export function redirect(to, options = {}) {
+  if (!isSafeUrl(to)) {
+    const target = typeof to === 'string' ? to : Object.prototype.toString.call(to);
+    const err = new Error(`[what-router] redirect() refused an unsafe target: ${target}`);
+    err.code = 'ERR_UNSAFE_REDIRECT';
+    err.suggestion = 'redirect() accepts same-origin paths and http:, https:, mailto: or tel: URLs only. Protocol-relative ("//host"), backslash-smuggled and javascript:/data: targets are open-redirect vectors. Check a user-supplied target against an allowlist first.';
+    err.codeExample = `// Bad - a user-controlled target can leave your origin:
+redirect(query.next);
+
+// Good - allowlist the target first:
+redirect(ALLOWED.has(query.next) ? query.next : '/');`;
+    throw err;
+  }
+
+  const sig = new Error(`[what-router] redirect to ${to}`);
+  sig.name = 'RouterRedirect';
+  sig.code = 'ERR_REDIRECT_NOT_CAUGHT';
+  sig.suggestion = 'Seeing this signal in your console means nothing caught it. redirect() works from route middleware and from a component body, where the Router catches it. From an event handler, a promise callback or a timer, call navigate(to) instead. A try/catch around the redirect() call also swallows it.';
+  sig.codeExample = `// Bad - an event handler runs long after the render the Router caught:
+<button onclick={() => redirect('/login')}>Sign in</button>
+
+// Good - navigate() from a handler:
+<button onclick={() => navigate('/login')}>Sign in</button>
+
+// Good - redirect() from a component body, which the Router catches:
+function Private() {
+  if (!user()) redirect('/login');
+  return <Secret />;
+}`;
+  sig[REDIRECT] = true;
+  sig[NAV_SIGNAL] = () => { handleRedirect(to, options); };
+  sig.to = to;
+  sig.options = options;
+  throw sig;
 }
 
 // Back/forward support — route through navigate() so middleware runs
 if (typeof window !== 'undefined') {
   window.addEventListener('popstate', () => {
     // Save scroll position for the URL we're leaving
-    scrollPositions.set(_url(), { x: scrollX, y: scrollY });
+    scrollPositions.set(_url(), { x: window.scrollX, y: window.scrollY });
 
     const newUrl = location.pathname + location.search + location.hash;
     // Use _fromPopstate flag so navigate() skips pushState (browser already updated URL)
@@ -164,14 +312,71 @@ function buildLayoutChain(route, routes) {
 const _redirectHistory = [];
 const MAX_REDIRECTS = 10;
 
+function loopScreen(message) {
+  return h('div', { class: 'what-redirect-loop' },
+    h('h1', null, 'Redirect Loop'),
+    h('p', null, message)
+  );
+}
+
+// Shared by the middleware string form and by a thrown redirect() signal.
+// Returns null once the navigation is queued, or the loop screen if the
+// redirect chain is cycling.
+//
+// The chain is scoped to one user navigation: navigate() clears the history
+// unless it is being called from here. Clearing it on a successful match
+// instead would never catch a cycle between two route components, because each
+// hop matches successfully before its component throws the next redirect.
+function handleRedirect(target, options) {
+  _redirectHistory.push(target);
+
+  if (_redirectHistory.length > MAX_REDIRECTS) {
+    const cycle = _redirectHistory.slice(-5).join(' → ');
+    _redirectHistory.length = 0;
+    console.error(`[what-router] Redirect loop detected: ${cycle}`);
+    _isNavigating.set(false);
+    _pendingUrl.set(null);
+    return loopScreen('Too many redirects. Check your middleware configuration.');
+  }
+
+  const seen = new Set();
+  let hasCycle = false;
+  for (const url of _redirectHistory) {
+    if (seen.has(url)) { hasCycle = true; break; }
+    seen.add(url);
+  }
+  if (hasCycle) {
+    const cycle = _redirectHistory.join(' → ');
+    _redirectHistory.length = 0;
+    console.error(`[what-router] Redirect cycle detected: ${cycle}`);
+    _isNavigating.set(false);
+    _pendingUrl.set(null);
+    return loopScreen('Circular redirect detected. Check your middleware configuration.');
+  }
+
+  navigate(target, { replace: true, ...options, _redirectChain: true });
+  return null;
+}
+
 // --- Router Component ---
 
+// The `loading:` component of the route a navigation is heading to, or null when
+// there is no pending destination, it does not match, it declares no loading
+// component, or it is the route already being rendered.
+function destinationLoading(pendingUrl, routes, currentRoute) {
+  if (!pendingUrl) return null;
+  const destPath = pendingUrl.split('?')[0].split('#')[0];
+  const dest = matchRoute(destPath, routes);
+  if (!dest || dest.route === currentRoute) return null;
+  return dest.route.loading || null;
+}
+
 export function Router({ routes, fallback, globalLayout }) {
   // The Router component runs ONCE. `content` is a reactive function child that
   // re-evaluates whenever _url changes; the fine-grained runtime reconciles only
   // the matched page in place. The globalLayout is rendered ONCE around it (below)
   // so the app shell persists across navigations instead of re-instantiating.
-  const content = () => {
+  const renderMatch = () => {
     const currentUrl = _url();
     const path = currentUrl.split('?')[0].split('#')[0];
     const search = currentUrl.split('?')[1]?.split('#')[0] || '';
@@ -198,48 +403,26 @@ export function Router({ routes, fallback, globalLayout }) {
             return h('div', { class: 'what-403' }, h('h1', null, '403'), h('p', null, 'Access denied'));
           }
           if (typeof result === 'string') {
-            // Redirect loop detection
-            _redirectHistory.push(result);
-            if (_redirectHistory.length > MAX_REDIRECTS) {
-              const cycle = _redirectHistory.slice(-5).join(' → ');
-              _redirectHistory.length = 0;
-              console.error(`[what-router] Redirect loop detected: ${cycle}`);
-              _isNavigating.set(false);
-              return h('div', { class: 'what-redirect-loop' },
-                h('h1', null, 'Redirect Loop'),
-                h('p', null, 'Too many redirects. Check your middleware configuration.')
-              );
-            }
-            // Check for direct cycle (A → B → A)
-            const seen = new Set();
-            let hasCycle = false;
-            for (const url of _redirectHistory) {
-              if (seen.has(url)) { hasCycle = true; break; }
-              seen.add(url);
-            }
-            if (hasCycle) {
-              const cycle = _redirectHistory.join(' → ');
-              _redirectHistory.length = 0;
-              console.error(`[what-router] Redirect cycle detected: ${cycle}`);
-              _isNavigating.set(false);
-              return h('div', { class: 'what-redirect-loop' },
-                h('h1', null, 'Redirect Loop'),
-                h('p', null, 'Circular redirect detected. Check your middleware configuration.')
-              );
-            }
             // Middleware returned a redirect path
-            navigate(result, { replace: true });
-            return null;
+            return handleRedirect(result);
           }
         }
       }
-      // Successful render — clear redirect history
-      _redirectHistory.length = 0;
 
       // Build element with loading state support
       let element;
 
-      if (r.loading && isNavigating) {
+      // While a navigation is in flight, a `loading:` declared by the
+      // DESTINATION wins. _url has not committed yet, so `r` is still the route
+      // being left: without this, declaring `loading:` on the page you are
+      // navigating TO could never show it. Falling back to the departing route's
+      // `loading:` preserves the existing behaviour for the case where only the
+      // page being left declares one.
+      const pendingLoading = isNavigating ? destinationLoading(_pendingUrl(), routes, r) : null;
+
+      if (pendingLoading) {
+        element = h(pendingLoading, {});
+      } else if (r.loading && isNavigating) {
         element = h(r.loading, {});
       } else {
         element = h(r.component, {
@@ -271,6 +454,21 @@ export function Router({ routes, fallback, globalLayout }) {
     );
   };
 
+  // Catches a redirect() thrown by route middleware. A redirect() thrown by a
+  // route component is caught by core instead, because h() is lazy and the
+  // component runs after renderMatch has returned. Anything unbranded
+  // propagates to the app's ErrorBoundary unchanged.
+  const content = () => {
+    let sig = null;
+    try {
+      return renderMatch();
+    } catch (e) {
+      if (!e || !e[REDIRECT]) throw e;
+      sig = e;
+    }
+    return handleRedirect(sig.to, sig.options);
+  };
+
   // Render the global layout ONCE so it — and everything it mounts (sidebars,
   // toasters, command palettes, global key listeners) — PERSISTS across
   // navigations; the reactive `content` child swaps the matched page in place.
@@ -299,7 +497,7 @@ export function Link({
   // Sanitize href — reject dangerous protocols
   const safeHref = isSafeUrl(href) ? href : 'about:blank';
   if (!isSafeUrl(href) && typeof console !== 'undefined') {
-    console.warn(`[what-router] Link blocked unsafe href: ${href}`);
+    console.warn('[what-router] Link blocked unsafe href:', href);
   }
 
   // Strip query string and hash from href for path comparison
@@ -356,12 +554,23 @@ export function defineRoutes(config) {
 
 // --- Nested Route Helper ---
 
+// Join a base path with a child path. Naive concatenation turned the index
+// child of `nestedRoutes('/dashboard', [{ path: '/' }, ...])` — the form the
+// README documents — into '/dashboard/', which '/dashboard' does not match, so
+// the documented example 404s on its own index route.
+function joinRoutePath(basePath, childPath) {
+  const base = basePath.endsWith('/') ? basePath.slice(0, -1) : basePath;
+  const child = !childPath || childPath === '/' ? '/' : (childPath.startsWith('/') ? childPath : `/${childPath}`);
+  if (child === '/') return base || '/';
+  return base + child;
+}
+
 export function nestedRoutes(basePath, children, options = {}) {
   const { layout, loading, error } = options;
 
   return children.map(child => ({
     ...child,
-    path: basePath + child.path,
+    path: joinRoutePath(basePath, child.path),
     layout: child.layout || layout,
     loading: child.loading || loading,
     error: child.error || error,
@@ -535,6 +744,29 @@ export function useRoute() {
   };
 }
 
+// --- Route Accessors ---
+// Read the singleton route state directly. Called inside a tracking scope
+// (a reactive text binding, computed or effect) they subscribe to it.
+
+export function useParams() {
+  return route.params;
+}
+
+// Same singleton `_query` signal as route.query: only the Router's match branch
+// writes it, so on an unmatched (404) route this is the last matched route's
+// query, not the current URL's. Documented on both declarations.
+export function useSearch() {
+  return route.query;
+}
+
+export function useNavigate() {
+  return navigate;
+}
+
+export function prefetchRoute(href) {
+  prefetch(href);
+}
+
 // --- Outlet Component ---
 // For nested route rendering
 
@@ -555,11 +787,16 @@ export function FileRouter({
   fallback,
   error: globalError,
 }) {
-  // Convert file-router route format to Router's expected format
+  // Convert file-router route format to Router's expected format.
+  // loading/error used to be dropped here, so a route could declare either and
+  // never see it rendered, and the `error` prop was destructured and then never
+  // read: a documented public prop that silently did nothing.
   const routerRoutes = routes.map(r => ({
     path: r.path,
     component: r.component,
     layout: r.layout || undefined,
+    loading: r.loading || undefined,
+    error: r.error || globalError || undefined,
     // Attach page mode as metadata for build system
     _mode: r.mode || 'client',
   }));

package/src/match.js

@@ -42,33 +42,75 @@ export function compilePath(path) {
   return { regex, paramNames, catchAll };
 }
 
+// Compiled patterns are stable per route path, so cache them instead of
+// rebuilding a RegExp for every route on every request.
+const patternCache = new Map();
+const PATTERN_CACHE_MAX = 1000;
+
+function getPattern(path) {
+  let compiled = patternCache.get(path);
+  if (!compiled) {
+    compiled = compilePath(path);
+    if (patternCache.size >= PATTERN_CACHE_MAX) patternCache.clear();
+    patternCache.set(path, compiled);
+  }
+  return compiled;
+}
+
+// The `([^/]+)` segment guard runs against the still-encoded path, so a param
+// only becomes multi-segment once it is decoded ("%2e%2e%2f" -> "../"). Reject
+// any decoded value that smuggles in a separator or a traversal segment, and
+// treat malformed percent-escapes as a non-match instead of throwing.
+function decodeParam(value, isCatchAll) {
+  let decoded;
+  try {
+    decoded = decodeURIComponent(value);
+  } catch {
+    return null;
+  }
+  const segments = decoded.split(/[/\\]/);
+  if (!isCatchAll && segments.length > 1) return null;
+  if (segments.includes('..')) return null;
+  return decoded;
+}
+
 export function matchRoute(path, routes) {
   // Filter out routes without a path (layout-only routes, etc.)
-  const routable = routes.filter(r => r.path);
+  // `filter` already copies, so sorting below never touches the caller's array.
+  const sorted = routes.filter(r => r.path);
 
   // Sort routes by specificity (more specific first)
-  const sorted = routable.sort((a, b) => {
+  sorted.sort((a, b) => {
     const aSpecific = (a.path.match(/:/g) || []).length + (a.path.includes('*') ? 100 : 0);
     const bSpecific = (b.path.match(/:/g) || []).length + (b.path.includes('*') ? 100 : 0);
     return aSpecific - bSpecific;
   });
 
   for (const route of sorted) {
-    const { regex, paramNames } = compilePath(route.path);
+    const { regex, paramNames, catchAll } = getPattern(route.path);
     const match = path.match(regex);
     if (match) {
       const params = {};
+      let rejected = false;
       paramNames.forEach((name, i) => {
-        params[name] = decodeURIComponent(match[i + 1]);
+        const decoded = decodeParam(match[i + 1], name === catchAll);
+        if (decoded === null) {
+          rejected = true;
+          return;
+        }
+        params[name] = decoded;
       });
+      if (rejected) continue;
       return { route, params };
     }
   }
   return null;
 }
 
+// Null-prototype so query keys like "toString" or "__proto__" stay plain data
+// instead of colliding with inherited members or replacing the prototype.
 export function parseQuery(search) {
-  const params = {};
+  const params = Object.create(null);
   if (!search) return params;
   const qs = search.startsWith('?') ? search.slice(1) : search;
   for (const pair of qs.split('&')) {
@@ -76,7 +118,7 @@ export function parseQuery(search) {
     if (!key) continue;
     const decodedKey = decodeURIComponent(key);
     const decodedVal = val ? decodeURIComponent(val) : '';
-    if (decodedKey in params) {
+    if (Object.prototype.hasOwnProperty.call(params, decodedKey)) {
       // Collect repeated keys into arrays
       if (Array.isArray(params[decodedKey])) {
         params[decodedKey].push(decodedVal);