@firsthandjs/router 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Firsthand contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,153 @@
+# @firsthandjs/router
+
+Nested routes, real links, and route code that arrives when the route does.
+
+**Documentation:** [guide](https://github.com/firsthandjs/firsthand/blob/main/docs/guide/08-routing.md) · [API reference](https://github.com/firsthandjs/firsthand/blob/main/docs/reference/router.md) · [all docs](https://github.com/firsthandjs/firsthand/blob/main/docs/README.md)
+
+```
+npm install @firsthandjs/router
+```
+
+3.36 kB gzip. No dependencies other than `@firsthandjs/core` and `@firsthandjs/dom`.
+
+## The shape of it
+
+```tsx
+import { render, component } from '@firsthandjs/dom';
+import { Router, Outlet, NavLink, route, type RouteProps } from '@firsthandjs/router';
+
+const Shell = component(() => (
+  <main>
+    <nav>
+      <NavLink to="/" end>
+        Home
+      </NavLink>
+      <NavLink to="/users">Users</NavLink>
+      <NavLink to="/reports" preload>
+        Reports
+      </NavLink>
+    </nav>
+    <Outlet />
+  </main>
+));
+
+// `props.params` is typed by the route's path, below. Nothing says `id` twice.
+const User = component<RouteProps<{ id: string }>>((props) => <h2>User {props.params.id}</h2>);
+
+const routes = [
+  route({
+    path: '/',
+    component: Shell,
+    children: (child) => [
+      child({ index: true, component: Home }),
+      child({ path: 'users/:id', component: User }),
+      // Not in the initial bundle. Fetched when the route is entered — or on
+      // hover, because the link above asks for it.
+      child({ path: 'reports', lazy: () => import('./reports.js') }),
+      child({ path: '*', component: NotFound }),
+    ],
+  }),
+];
+
+render(() => <Router routes={routes} />);
+```
+
+## How it differs from react-router
+
+The path syntax, the ranking rules, nesting, `Outlet`, `Link`, `NavLink`,
+`Navigate`, `useNavigate`, `useLocation`, `useRouteParams` and `useSearchParams` all
+behave as they do there. Two things are different on purpose.
+
+**Routes are objects, not elements.** React Router can write
+`<Route path="/users" element={<Users />} />` because a React element is a
+description that the router reads before anything renders. A Firsthand element is
+DOM — `<Users />` builds it — so there would be nothing to read. Writing the
+route table as data is the same information without the costume, and it is also
+what makes `lazy` straightforward: a route can name a module it has not loaded,
+which an element cannot.
+
+**Read-only hooks return cells.** A component body runs once, so a hook that
+returned a value would return the value it had at setup and never change.
+
+```tsx
+const params = useRouteParams<{ id: string }>();
+return <h2>User {params.value.id}</h2>; // fine-grained: updates this text node
+```
+
+Navigating from `/users/1` to `/users/2` does not re-create the page. The route
+is the same, so the component instance is the same; only the text that read the
+parameter is rewritten. Changing to a _different_ route disposes the old page
+and builds the new one.
+
+## Code splitting
+
+```ts
+{ path: 'reports', lazy: () => import('./reports.js') }
+```
+
+`lazy` is called the first time the route is entered, once per route, and the
+result is cached. Until it resolves the router renders `pending` — the route's
+own, or the one passed to `Router` — and swaps to the real page by itself when
+the module arrives, because reading the loaded component is an ordinary
+reactive read.
+
+`<Link preload>` starts that import on hover and on focus, so the usual case is
+that the chunk is already there when the click happens. `preloadRoutes(routes,
+path)` does the same from anywhere.
+
+The module may export the component as `default` or be the component itself.
+
+## API
+
+| Export                                                                      | What it is                                                            |
+| --------------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| `Router`                                                                    | Root. Takes `routes`, and optionally `history`, `basename`, `pending` |
+| `Outlet`                                                                    | Where a route renders its matched child                               |
+| `Link`, `NavLink`                                                           | A real `<a href>`; `NavLink` adds a class while active                |
+| `Navigate`                                                                  | Redirects when rendered                                               |
+| `useRouter`                                                                 | The router itself: its history, routes and matches                    |
+| `useLocation`, `useRouteParams`, `useMatches`, `useMatch`                   | Cells                                                                 |
+| `useSearchParams`                                                           | `[cell, setter]`                                                      |
+| `useNavigate`                                                               | `(to: string \| number, options?) => void`                            |
+| `useBasePath`, `resolvePath`, `isActivePath`                                | The rules links use, exposed                                          |
+| `createBrowserHistory`, `createHashHistory`, `createMemoryHistory`          | History adapters                                                      |
+| `route`                                                                     | One route, with its parameters read from its own path                 |
+| `matchRoutes`, `routeComponent`, `preloadRoutes`                            | The matcher, usable on its own                                        |
+| `compilePattern`, `matchPattern`, `normalizePath`, `sameParams`, `segments` | Path utilities                                                        |
+
+### Paths
+
+- `/users/:id` — a parameter, available as `params.value.id`, URL-decoded
+- `/users/:id?` — an optional segment
+- `/files/*` — a splat, available as `params.value['*']`
+- `index: true` — matches when the parent matches and nothing is left over
+
+Routes are **ranked**, not tried in order: `/users/new` wins over `/users/:id`
+however the array is sorted.
+
+### Links
+
+`Link` intercepts only a plain left-click on a same-window link. Modified
+clicks, middle clicks and `target="_blank"` are left to the browser, and the
+`href` is always a real URL — the status bar, "open in new tab" and crawlers all
+work. Any prop the router does not use is forwarded to the anchor.
+
+### History
+
+`createBrowserHistory(basename)` is the default. `createHashHistory()` suits a
+host that cannot rewrite every path to one document. `createMemoryHistory()` is
+what tests should use:
+
+```tsx
+const history = createMemoryHistory(['/users/1']);
+const view = mount(() => <Router routes={routes} history={history} />);
+history.push('/users/2'); // synchronous: the DOM is already updated
+```
+
+A history the `Router` created is disposed with it; one you passed in is yours.
+
+## Deployment
+
+A router that owns paths the file system does not know about needs its host to
+serve the application's document for unknown paths. That is one rule in most
+static hosts, and `createHashHistory()` is the way out when it is not available.

package/dist/history.d.ts

@@ -0,0 +1,54 @@
+/**
+ * History adapters.
+ *
+ * Three, with the same interface: the browser's own history, a hash-based one
+ * for static hosts, and an in-memory one for tests and for rendering outside a
+ * browser. The location is a signal, so everything downstream — matching, the
+ * active class on a link, a component reading a parameter — is an ordinary
+ * reactive read rather than a subscription the application has to manage.
+ */
+import { type ReadonlyCell } from '@firsthandjs/core';
+export interface Location {
+    readonly pathname: string;
+    /** Including the leading `?`, or empty. */
+    readonly search: string;
+    /** Including the leading `#`, or empty. */
+    readonly hash: string;
+    /** Whatever was passed to `push`/`replace`. */
+    readonly state: unknown;
+    /** Changes on every navigation, including to the same URL. */
+    readonly key: string;
+}
+export interface NavigateOptions {
+    readonly replace?: boolean;
+    readonly state?: unknown;
+}
+export interface History {
+    readonly location: ReadonlyCell<Location>;
+    push(to: string, options?: NavigateOptions): void;
+    replace(to: string, options?: NavigateOptions): void;
+    go(delta: number): void;
+    /** Turns a router path into something an `href` can use. */
+    href(to: string): string;
+    /** Stops listening. Returns nothing; calling it twice is harmless. */
+    dispose(): void;
+}
+/** Splits a URL-ish string into its three parts. */
+export declare function parsePath(to: string): Omit<Location, 'state' | 'key'>;
+/**
+ * The browser's history: real URLs, real back button.
+ *
+ * `basename` lets an application live under a sub-path without every route
+ * knowing about it.
+ */
+export declare function createBrowserHistory(basename?: string): History;
+/** Hash routing, for hosts that cannot rewrite every path to one document. */
+export declare function createHashHistory(): History;
+/**
+ * An in-memory history.
+ *
+ * What tests should use, and what a server would use: no `window`, and the
+ * entry stack is inspectable.
+ */
+export declare function createMemoryHistory(initial?: readonly string[]): History;
+//# sourceMappingURL=history.d.ts.map

package/dist/history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"history.d.ts","sourceRoot":"","sources":["../src/history.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAU,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAE9D,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,2CAA2C;IAC3C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,+CAA+C;IAC/C,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,8DAA8D;IAC9D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC;IAC1C,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,IAAI,CAAC;IAClD,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,IAAI,CAAC;IACrD,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,4DAA4D;IAC5D,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,sEAAsE;IACtE,OAAO,IAAI,IAAI,CAAC;CACjB;AAKD,oDAAoD;AACpD,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC,QAAQ,EAAE,OAAO,GAAG,KAAK,CAAC,CAQrE;AAMD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,SAAK,GAAG,OAAO,CA2C3D;AAED,8EAA8E;AAC9E,wBAAgB,iBAAiB,IAAI,OAAO,CAqC3C;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,SAAS,MAAM,EAAU,GAAG,OAAO,CA+B/E"}

package/dist/hooks.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Hooks.
+ *
+ * The names are react-router's, the return types are not: each read-only hook
+ * hands back a cell rather than a value, because a component body runs once.
+ * `useRouteParams().value.id` inside a JSX expression is a fine-grained read, and
+ * changing the parameter updates exactly that text node.
+ */
+import { type ReadonlyCell } from '@firsthandjs/core';
+import { type RouterState } from './router.js';
+import { type Params } from './match.js';
+import type { Location, NavigateOptions } from './history.js';
+import type { RouteMatch } from './routes.js';
+/** What `useNavigate` returns: a path, or a delta through the history stack. */
+export type NavigateFunction = (to: string | number, options?: NavigateOptions) => void;
+/**
+ * Resolves `to` against a base path.
+ *
+ * `..` steps up a path segment. React Router steps up a *route* level, which
+ * differs only when one route owns several segments; the path rule is the one
+ * that can be explained without knowing the route tree.
+ */
+export declare function resolvePath(to: string, base: string): string;
+/** The path everything relative in the surrounding route resolves against. */
+export declare function useBasePath(): ReadonlyCell<string>;
+/**
+ * The router above this component.
+ *
+ * The same shape as `useQueryClient()` in `@firsthandjs/query`: a `use*` hook that
+ * returns the thing itself, because a router does not change under you.
+ */
+export declare function useRouter(): RouterState;
+export declare function useLocation(): ReadonlyCell<Location>;
+/**
+ * The parameters of the deepest matched route, merged down the chain.
+ *
+ * The type parameter names what the route captures — `useRouteParams<{ id: string
+ * }>()` — which is what lets `params.value.id` be written as a property
+ * instead of an index. It is an assertion about the route, exactly as it is in
+ * react-router, and it appears only in the return type.
+ */
+export declare function useRouteParams<P extends Params = Params>(): ReadonlyCell<P>;
+/** The whole matched chain, outermost first. */
+export declare function useMatches(): ReadonlyCell<readonly RouteMatch[]>;
+export declare function useNavigate(): NavigateFunction;
+/** Whether a path is active, by the same rule `NavLink` uses. */
+export declare function isActivePath(current: string, target: string, end: boolean): boolean;
+export declare function useMatch<P extends Params = Params>(path: string): ReadonlyCell<{
+    params: P;
+} | null>;
+/** Reads and writes the query string. */
+export declare function useSearchParams(): [
+    ReadonlyCell<URLSearchParams>,
+    (next: URLSearchParams | Record<string, string>, options?: NavigateOptions) => void
+];
+//# sourceMappingURL=hooks.d.ts.map

package/dist/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAwB,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAC5E,OAAO,EAA+B,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAC5E,OAAO,EAML,KAAK,MAAM,EACZ,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC9D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,gFAAgF;AAChF,MAAM,MAAM,gBAAgB,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,KAAK,IAAI,CAAC;AAExF;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAmB5D;AAED,8EAA8E;AAC9E,wBAAgB,WAAW,IAAI,YAAY,CAAC,MAAM,CAAC,CAMlD;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,IAAI,WAAW,CAEvC;AAED,wBAAgB,WAAW,IAAI,YAAY,CAAC,QAAQ,CAAC,CAEpD;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,KAAK,YAAY,CAAC,CAAC,CAAC,CAW3E;AAED,gDAAgD;AAChD,wBAAgB,UAAU,IAAI,YAAY,CAAC,SAAS,UAAU,EAAE,CAAC,CAEhE;AAED,wBAAgB,WAAW,IAAI,gBAAgB,CAgB9C;AAED,iEAAiE;AACjE,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAInF;AAGD,wBAAgB,QAAQ,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,EAChD,IAAI,EAAE,MAAM,GACX,YAAY,CAAC;IAAE,MAAM,EAAE,CAAC,CAAA;CAAE,GAAG,IAAI,CAAC,CAIpC;AAED,yCAAyC;AACzC,wBAAgB,eAAe,IAAI;IACjC,YAAY,CAAC,eAAe,CAAC;IAC7B,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,EAAE,eAAe,KAAK,IAAI;CACpF,CASA"}

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * `@firsthandjs/router` — nested routes, real links, and route code loaded on
+ * demand.
+ *
+ * The API is react-router's, with two deliberate differences:
+ *
+ * 1. Routes are plain objects, not `<Route>` elements. Firsthand has no element
+ *    descriptors to inspect before rendering, so a JSX route tree would be a
+ *    costume rather than a design.
+ * 2. Read-only hooks return cells, not values, because a component body runs
+ *    once. `useRouteParams().value.id` is a fine-grained read; a navigation updates
+ *    the text node that read it and nothing else.
+ *
+ * Everything else — path syntax, ranking, nesting, `Outlet`, `Link`,
+ * `NavLink`, `Navigate`, `useNavigate`, `useLocation`, `useSearchParams` —
+ * behaves as it does there.
+ */
+export { Router, Outlet, RouterContext } from './router.js';
+export type { RouterProps, RouterState } from './router.js';
+export { Link, NavLink } from './links.js';
+export type { LinkProps, NavLinkProps } from './links.js';
+export { Navigate } from './navigate.js';
+export type { NavigateProps } from './navigate.js';
+export { useRouter, useLocation, useMatch, useMatches, useNavigate, useRouteParams, useSearchParams, useBasePath, resolvePath, isActivePath, } from './hooks.js';
+export type { NavigateFunction } from './hooks.js';
+export { matchRoutes, routeComponent, preloadRoutes, route } from './routes.js';
+export type { RouteBuilder, RouteDefinition, RouteMatch, RouteComponent, RouteProps, LazyModule, } from './routes.js';
+export { createBrowserHistory, createHashHistory, createMemoryHistory, parsePath, } from './history.js';
+export type { History, Location, NavigateOptions } from './history.js';
+export { compilePattern, matchPattern, normalizePath, sameParams, segments } from './match.js';
+export type { Params, ParamsOf, Pattern } from './match.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5D,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAC3C,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1D,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,YAAY,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EACL,SAAS,EACT,WAAW,EACX,QAAQ,EACR,UAAU,EACV,WAAW,EACX,cAAc,EACd,eAAe,EACf,WAAW,EACX,WAAW,EACX,YAAY,GACb,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAChF,YAAY,EACV,YAAY,EACZ,eAAe,EACf,UAAU,EACV,cAAc,EACd,UAAU,EACV,UAAU,GACX,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,oBAAoB,EACpB,iBAAiB,EACjB,mBAAmB,EACnB,SAAS,GACV,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACvE,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC/F,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1 @@
+import{computed as M,createContext as T,onCleanup as me,provide as $,useContext as U}from"@firsthandjs/core";import{component as H}from"@firsthandjs/dom";import{isComponent as fe}from"@firsthandjs/dom/internal";import{part as he}from"@firsthandjs/dom/internal";import{signal as O}from"@firsthandjs/core";var Z=0,m=()=>`k${String(++Z)}`;function f(e){let t=e.indexOf("#"),n=t===-1?"":e.slice(t),r=t===-1?e:e.slice(0,t),o=r.indexOf("?"),a=o===-1?"":r.slice(o),i=o===-1?r:r.slice(0,o);return{pathname:i===""?"/":i,search:a,hash:n}}function C(e,t){return{...f(e),state:t,key:m()}}function S(e=""){let t=e.endsWith("/")?e.slice(0,-1):e,n=u=>t!==""&&u.startsWith(t)?u.slice(t.length)||"/":u,r=()=>({pathname:n(window.location.pathname),search:window.location.search,hash:window.location.hash,state:window.history.state,key:m()}),o=O(r()),a=()=>{o.value=r()};window.addEventListener("popstate",a);let i=u=>`${t}${u.startsWith("/")?u:`/${u}`}`,s=(u,c,w)=>{let B=c?.state??null;window.history[w?"replaceState":"pushState"](B,"",i(u)),o.value=C(u,B)};return{location:o,push:(u,c)=>{s(u,c,c?.replace===!0)},replace:(u,c)=>{s(u,c,!0)},go:u=>{window.history.go(u)},href:i,dispose:()=>{window.removeEventListener("popstate",a)}}}function ee(){let e=()=>({...f(window.location.hash.slice(1)||"/"),state:null,key:m()}),t=O(e()),n=()=>{t.value=e()};window.addEventListener("hashchange",n);let r=o=>`#${o.startsWith("/")?o:`/${o}`}`;return{location:t,push:(o,a)=>{a?.replace===!0?window.location.replace(r(o)):window.location.hash=r(o).slice(1),t.value={...f(o),state:a?.state??null,key:m()}},replace:(o,a)=>{window.location.replace(r(o)),t.value={...f(o),state:a?.state??null,key:m()}},go:o=>{window.history.go(o)},href:r,dispose:()=>{window.removeEventListener("hashchange",n)}}}function te(e=["/"]){let t=e.map(o=>C(o,null)),n=t.length-1,r=O(t[n]);return{location:r,push:(o,a)=>{let i=C(o,a?.state??null);a?.replace===!0?t[n]=i:(t.length=n+1,t.push(i),n++),r.value=i},replace:(o,a)=>{let i=C(o,a?.state??null);t[n]=i,r.value=i},go:o=>{let a=Math.min(Math.max(n+o,0),t.length-1);n=a,r.value=t[a]},href:o=>o,dispose:()=>{}}}import{signal as ue}from"@firsthandjs/core";function h(e,t){let n=Object.keys(e);return n.length===Object.keys(t).length&&n.every(r=>e[r]===t[r])}var ne=10,oe=6,re=4,ae=1,ie=2;function se(e){return e.replace(/[.*+?^${}()|[\]\\]/g,"\\$&")}function d(e){return e.split("/").filter(t=>t!=="")}function y(e,t){let n=d(e),r=[],o=n.length===0?ie:0,a="";for(let s of n){if(s==="*"){r.push("*"),o+=ae,a+="(?:/(.*))?";continue}if(s.startsWith(":")){let u=s.endsWith("?");r.push(s.slice(1,u?-1:void 0)),o+=u?re:oe,a+=u?"(?:/([^/]+))?":"/([^/]+)";continue}o+=ne,a+=`/${se(s)}`}let i=new RegExp(`^${a}${t?"/?$":"(?=/|$)"}`,"i");return{source:e,regex:i,keys:r,score:o,end:t}}function g(e,t){let n=e.regex.exec(t);if(n===null)return null;let r={};for(let o=0;o<e.keys.length;o++){let a=n[o+1];a!==void 0&&(r[e.keys[o]]=decodeURIComponent(a))}return{params:r,consumed:n[0]}}function v(e){return`/${d(e).join("/")}`}var z=new WeakMap;function ce(e){return e.index===!0?"":e.path??""}function W(e,t,n){for(let r of e){let o=[...t,r];n.push(le(o));let a=r.children;a!==void 0&&W(a,o,n)}}function le(e){let t=e.map((n,r)=>({route:n,pattern:y(ce(n),r===e.length-1)}));return{levels:t,score:t.reduce((n,r)=>n+r.pattern.score,0)}}function de(e){let t=z.get(e);if(t!==void 0)return t;let n=[];return W(e,[],n),n.sort((r,o)=>o.score-r.score),z.set(e,n),n}function L(e,t){for(let n of de(e)){let r=[],o=t===""?"/":t,a="",i={},s=!1;for(let u of n.levels){let c=g(u.pattern,o);if(c===null){s=!0;break}i={...i,...c.params},a+=c.consumed,r.push({route:u.route,params:i,pathname:a===""?"/":a}),o=o.slice(c.consumed.length)}if(!s)return r}return null}var V=new WeakMap;function k(e){if(e.component!==void 0)return e.component;let t=V.get(e);return t===void 0&&(t=ue(void 0),V.set(e,t),pe(e,t)),t.value}async function pe(e,t){let n=await e.lazy();t.value=typeof n=="function"?n:n.default}function D(e,t){let n=L(e,t);if(n!==null)for(let r of n)r.route.component===void 0&&r.route.lazy!==void 0&&k(r.route)}var I=e=>{let{children:t,...n}=e;return typeof t!="function"?e:{...n,children:t(I)}};var l=T(),P=T(-1,"route depth"),ye=()=>null,ge=Object.freeze({}),K=new WeakMap;function ve(e,t){if(fe(e))return e;let n=K.get(e);return n===void 0&&(n=H(r=>e(r),void 0,`firsthand/router:route(${t})`,"Route"),K.set(e,n)),n}function _(e){let t=U(l),n=M(()=>t.value.matches.value[e]?.route),r=M(()=>t.value.matches.value[e]?.params??ge,{equals:h}),o=new Proxy({},{get:(i,s)=>typeof s=="string"?r.value[s]:void 0,has:(i,s)=>typeof s=="string"&&s in r.value,ownKeys:()=>Object.keys(r.value),getOwnPropertyDescriptor:(i,s)=>typeof s=="string"&&s in r.value?{configurable:!0,enumerable:!0,value:r.value[s]}:void 0}),a=Object.freeze({params:o});return he(()=>{let i=n.value;if(i===void 0)return null;$(P,e);let s=k(i);return s===void 0?(i.pending??t.value.pending??ye)():ve(s,i.path??"")(a)})}var Pe=H(e=>{let t=e.history===void 0,n=e.history??S(e.basename??"");t&&me(()=>{n.dispose()});let r=e.routes,o=M(()=>L(r,n.location.value.pathname)??[]);return $(l,{history:n,routes:r,matches:o,pending:e.pending}),$(P,-1),_(0)},void 0,"firsthand/router:Router","Router"),Re=H(()=>_(U(P).value+1),void 0,"firsthand/router:Outlet","Outlet");import{bind as A,computed as q,useContext as Y}from"@firsthandjs/core";import{component as X}from"@firsthandjs/dom";import{insert as ke,on as be,rest as Ne,setAttribute as G,setClass as Oe,spread as Se}from"@firsthandjs/dom/internal";import{computed as b,useContext as p}from"@firsthandjs/core";function R(e,t){let n=e.search(/[?#]/),r=n===-1?e:e.slice(0,n),o=n===-1?"":e.slice(n);if(r.startsWith("/"))return`${v(r)}${o}`;let a=d(t);for(let i of d(r))if(i!=="."){if(i===".."){a.pop();continue}a.push(i)}return`/${a.join("/")}${o}`}function x(){let e=p(l),t=p(P).value;return b(()=>e.value.matches.value[t]?.pathname??"/")}function F(){return p(l).value}function j(){return F().history.location}function xe(){let e=p(l);return b(()=>{let t=e.value.matches.value;return t[t.length-1]?.params??{}},{equals:h})}function we(){return p(l).value.matches}function N(){let e=p(l),t=x();return(n,r)=>{let{history:o}=e.value;if(typeof n=="number"){o.go(n);return}let a=R(n,t.value);r?.replace===!0?o.replace(a,r):o.push(a,r)}}function E(e,t,n){let r=v(e),o=v(t);return n?r===o:r===o||r.startsWith(o==="/"?"/":`${o}/`)}function Ce(e){let t=y(e,!0),n=j();return b(()=>g(t,n.value.pathname))}function Le(){let e=j(),t=N();return[b(()=>new URLSearchParams(e.value.search)),(o,a)=>{let i=new URLSearchParams(o).toString();t(`${e.value.pathname}${i===""?"":`?${i}`}`,a)}]}var J=["to","replace","state","preload","onClick","children"],De=[...J,"end","activeClass","class"];function Me(e,t){return e.button===0&&!e.metaKey&&!e.altKey&&!e.ctrlKey&&!e.shiftKey&&(t.target===""||t.target==="_self")}function Q(e,t){let n=Y(l),r=x(),o=document.createElement("a"),a=q(()=>R(e.to,r.value));A(()=>{G(o,"href",n.value.history.href(a.value))});let i=Ne(e,t);if(A(()=>{Se(o,i)}),ke(o,()=>e.children),be(o,"click",s=>{let u=s;if(e.onClick?.(u),u.defaultPrevented||!Me(u,o))return;u.preventDefault();let{history:c}=n.value,w={replace:e.replace===!0,state:e.state};e.replace===!0?c.replace(a.value,w):c.push(a.value,w)}),e.preload===!0){let s=()=>{D(n.value.routes,a.value)};o.addEventListener("pointerenter",s),o.addEventListener("focus",s)}return o}var $e=X(e=>Q(e,J),void 0,"firsthand/router:Link","Link"),He=X(e=>{let t=Q(e,De),n=Y(l),r=x(),o=q(()=>E(n.value.history.location.value.pathname,R(e.to,r.value),e.end===!0));return A(()=>{let a=o.value?e.activeClass??"active":"",i=e.class??"";Oe(t,`${i}${i!==""&&a!==""?" ":""}${a}`),G(t,"aria-current",o.value?"page":null)}),t},void 0,"firsthand/router:NavLink","NavLink");import{onCleanup as je}from"@firsthandjs/core";import{component as Ee}from"@firsthandjs/dom";var Ae=Ee(e=>{let t=N(),n=!0;return je(()=>{n=!1}),queueMicrotask(()=>{n&&t(e.to,{replace:e.replace??!0,state:e.state})}),null},void 0,"firsthand/router:Navigate","Navigate");export{$e as Link,He as NavLink,Ae as Navigate,Re as Outlet,Pe as Router,l as RouterContext,y as compilePattern,S as createBrowserHistory,ee as createHashHistory,te as createMemoryHistory,E as isActivePath,g as matchPattern,L as matchRoutes,v as normalizePath,f as parsePath,D as preloadRoutes,R as resolvePath,I as route,k as routeComponent,h as sameParams,d as segments,x as useBasePath,j as useLocation,Ce as useMatch,we as useMatches,N as useNavigate,xe as useRouteParams,F as useRouter,Le as useSearchParams};

package/dist/links.d.ts

@@ -0,0 +1,28 @@
+import { type View } from '@firsthandjs/dom';
+export interface LinkProps {
+    readonly to: string;
+    readonly replace?: boolean;
+    readonly state?: unknown;
+    /**
+     * Starts loading the target route's code on hover and on focus.
+     *
+     * The chunk is then usually already there when the click happens, which is
+     * what makes on-demand loading feel like no loading at all.
+     */
+    readonly preload?: boolean;
+    readonly onClick?: (event: MouseEvent) => void;
+    readonly children?: View;
+    /** Anything else is forwarded to the anchor. */
+    readonly [attribute: string]: unknown;
+}
+export interface NavLinkProps extends LinkProps {
+    /** Active only on an exact match, rather than on a prefix. */
+    readonly end?: boolean;
+    /** Class added while the link is active. Defaults to `active`. */
+    readonly activeClass?: string;
+    readonly class?: string;
+}
+export declare const Link: import("@firsthandjs/dom").Component<LinkProps>;
+/** A `Link` that knows whether it points at where you already are. */
+export declare const NavLink: import("@firsthandjs/dom").Component<NavLinkProps>;
+//# sourceMappingURL=links.d.ts.map

package/dist/links.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"links.d.ts","sourceRoot":"","sources":["../src/links.ts"],"names":[],"mappings":"AAaA,OAAO,EAAa,KAAK,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAMxD,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IAC/C,QAAQ,CAAC,QAAQ,CAAC,EAAE,IAAI,CAAC;IACzB,gDAAgD;IAChD,QAAQ,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;CACvC;AAED,MAAM,WAAW,YAAa,SAAQ,SAAS;IAC7C,8DAA8D;IAC9D,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC;IACvB,kEAAkE;IAClE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AA8DD,eAAO,MAAM,IAAI,iDAKhB,CAAC;AAEF,sEAAsE;AACtE,eAAO,MAAM,OAAO,oDAuBnB,CAAC"}

package/dist/match.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Path matching and route ranking.
+ *
+ * The rules are react-router's, because a router that matches *almost* like the
+ * one people know is worse than one that matches differently on purpose:
+ *
+ * - a segment beginning with `:` is a parameter,
+ * - a trailing `*` is a splat, captured as the `*` parameter,
+ * - a parameter may end with `?` to make that segment optional,
+ * - routes are ranked, not tried in order, so the most specific match wins
+ *   regardless of how the array happens to be sorted.
+ *
+ * Matching is done on a pre-compiled regular expression per pattern, built once
+ * when the route tree is first walked.
+ */
+/** Captured parameters, including `*` for a splat. */
+export type Params = Readonly<Record<string, string>>;
+/**
+ * Same keys, same values.
+ *
+ * Every navigation builds a fresh params object, so identity would report a
+ * change whenever anything in the URL moved; this reports one only when the
+ * parameters did.
+ */
+export declare function sameParams(a: Params, b: Params): boolean;
+/** Flattens an intersection so editors show one object rather than `A & B`. */
+export type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+/** The parameters one path segment contributes. */
+type SegmentParams<S extends string> = S extends `:${infer Name}?` ? {
+    readonly [K in Name]?: string;
+} : S extends `:${infer Name}` ? {
+    readonly [K in Name]: string;
+} : S extends `*` ? {
+    readonly '*': string;
+} : {};
+/**
+ * The parameters a path declares, read from the path itself.
+ *
+ * `ParamsOf<'users/:id/files/*'>` is `{ id: string; '*': string }`. Nothing
+ * has to be declared twice: the route table already says what the path is.
+ */
+export type ParamsOf<Path extends string> = Path extends `${infer Head}/${infer Rest}` ? SegmentParams<Head> & ParamsOf<Rest> : SegmentParams<Path>;
+export interface Pattern {
+    readonly source: string;
+    readonly regex: RegExp;
+    readonly keys: readonly string[];
+    /** Higher wins. Static segments beat dynamic ones, which beat a splat. */
+    readonly score: number;
+    /** Whether the pattern must consume the whole path. */
+    readonly end: boolean;
+}
+/** Splits a path into segments, ignoring empty ones from leading/double slashes. */
+export declare function segments(path: string): string[];
+/**
+ * Compiles a path pattern.
+ *
+ * `end` is false for a parent route in a nested tree: it has to match a prefix
+ * so that its children can match the rest.
+ */
+export declare function compilePattern(path: string, end: boolean): Pattern;
+/** Runs a compiled pattern against a pathname. */
+export declare function matchPattern(pattern: Pattern, pathname: string): {
+    params: Params;
+    consumed: string;
+} | null;
+/** Normalises a pathname: always a leading slash, never a trailing one. */
+export declare function normalizePath(pathname: string): string;
+export {};
+//# sourceMappingURL=match.d.ts.map

package/dist/match.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"match.d.ts","sourceRoot":"","sources":["../src/match.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,sDAAsD;AACtD,MAAM,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAEtD;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAGxD;AAED,+EAA+E;AAC/E,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CAAE,GAAG,EAAE,CAAC;AAExD,mDAAmD;AACnD,KAAK,aAAa,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,SAAS,IAAI,MAAM,IAAI,GAAG,GAC9D;IAAE,QAAQ,EAAE,CAAC,IAAI,IAAI,CAAC,CAAC,EAAE,MAAM;CAAE,GACjC,CAAC,SAAS,IAAI,MAAM,IAAI,EAAE,GACxB;IAAE,QAAQ,EAAE,CAAC,IAAI,IAAI,GAAG,MAAM;CAAE,GAChC,CAAC,SAAS,GAAG,GACX;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAGxB,EAAE,CAAC;AAEX;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,CAAC,IAAI,SAAS,MAAM,IAAI,IAAI,SAAS,GAAG,MAAM,IAAI,IAAI,MAAM,IAAI,EAAE,GAClF,aAAa,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC,GACpC,aAAa,CAAC,IAAI,CAAC,CAAC;AAExB,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,uDAAuD;IACvD,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;CACvB;AAYD,oFAAoF;AACpF,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAE/C;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CA0BlE;AAED,kDAAkD;AAClD,wBAAgB,YAAY,CAC1B,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,MAAM,GACf;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAa7C;AAED,2EAA2E;AAC3E,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGtD"}

package/dist/navigate.d.ts

@@ -0,0 +1,14 @@
+import type { NavigateOptions } from './history.js';
+export interface NavigateProps extends NavigateOptions {
+    readonly to: string;
+}
+/**
+ * Navigates as soon as it is rendered.
+ *
+ * The navigation is deferred to a microtask rather than performed during
+ * setup: setup runs inside the render that is producing this element, and
+ * changing the location from there would re-enter the render that is still in
+ * progress. Nothing is painted in between, so the redirect is still invisible.
+ */
+export declare const Navigate: import("@firsthandjs/dom").Component<NavigateProps>;
+//# sourceMappingURL=navigate.d.ts.map

package/dist/navigate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigate.d.ts","sourceRoot":"","sources":["../src/navigate.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD,MAAM,WAAW,aAAc,SAAQ,eAAe;IACpD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,QAAQ,qDAiBpB,CAAC"}

package/dist/router.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The router itself: context, the matched chain, and `Outlet`.
+ *
+ * Rendering a chain of nested routes needs one property that is easy to lose:
+ * navigating from `/users/1` to `/users/2` must *update* the user page, not
+ * replace it, because replacing it would throw away its DOM and its state for
+ * a change that only moved a parameter. So each depth watches the route
+ * *object* at that depth, not the match: the component is created again only
+ * when the route actually differs, and parameters reach it as ordinary
+ * reactive reads.
+ */
+import { type ReadonlyCell } from '@firsthandjs/core';
+import { type Component, type View } from '@firsthandjs/dom';
+import { type History } from './history.js';
+import { type RouteDefinition, type RouteMatch } from './routes.js';
+export interface RouterState {
+    readonly history: History;
+    readonly routes: readonly RouteDefinition[];
+    /** The chain from the outermost matched route to the leaf. Empty if none matched. */
+    readonly matches: ReadonlyCell<readonly RouteMatch[]>;
+    /** Shown while a lazy route is loading, unless the route has its own. */
+    readonly pending: (() => View) | undefined;
+}
+export declare const RouterContext: import("@firsthandjs/core").Context<RouterState>;
+/** How deep in the matched chain the surrounding route sits. */
+export declare const DepthContext: import("@firsthandjs/core").Context<number>;
+export interface RouterProps {
+    readonly routes: readonly RouteDefinition[];
+    /** Defaults to a browser history over the real URL. */
+    readonly history?: History;
+    /** Sub-path the application is served under; ignored if `history` is given. */
+    readonly basename?: string;
+    /** Shown while a lazy route is loading. */
+    readonly pending?: () => View;
+}
+/**
+ * The root of a routed application.
+ *
+ * A history it created is disposed with it; one that was passed in is not,
+ * because the caller owns that.
+ */
+export declare const Router: Component<RouterProps>;
+/** Where a route renders its matched child route. */
+export declare const Outlet: Component<Record<string, never>>;
+//# sourceMappingURL=router.d.ts.map

package/dist/router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../src/router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAML,KAAK,YAAY,EAClB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAa,KAAK,SAAS,EAAE,KAAK,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAGxE,OAAO,EAAwB,KAAK,OAAO,EAAE,MAAM,cAAc,CAAC;AAClE,OAAO,EAIL,KAAK,eAAe,EACpB,KAAK,UAAU,EAEhB,MAAM,aAAa,CAAC;AAGrB,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,SAAS,eAAe,EAAE,CAAC;IAC5C,qFAAqF;IACrF,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC,SAAS,UAAU,EAAE,CAAC,CAAC;IACtD,yEAAyE;IACzE,QAAQ,CAAC,OAAO,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAAC;CAC5C;AAED,eAAO,MAAM,aAAa,kDAA+B,CAAC;AAE1D,gEAAgE;AAChE,eAAO,MAAM,YAAY,6CAAmC,CAAC;AAiG7D,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,SAAS,eAAe,EAAE,CAAC;IAC5C,uDAAuD;IACvD,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,2CAA2C;IAC3C,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;CAC/B;AAED;;;;;GAKG;AACH,eAAO,MAAM,MAAM,wBAsBlB,CAAC;AAEF,qDAAqD;AACrD,eAAO,MAAM,MAAM,kCAKlB,CAAC"}

package/dist/routes.d.ts

@@ -0,0 +1,116 @@
+import type { View } from '@firsthandjs/dom';
+import { type Params, type ParamsOf, type Simplify } from './match.js';
+/**
+ * What a route hands its component.
+ *
+ * One prop, because there is exactly one thing a route knows that its
+ * component does not: what the URL captured. Reading `props.params` is an
+ * ordinary reactive read, so a navigation from `/users/1` to `/users/2`
+ * updates what read it and remounts nothing.
+ */
+export interface RouteProps<P extends Params = Params> {
+    readonly params: P;
+}
+/** A component that a route renders. */
+export type RouteComponent<P extends Params = Params> = (props: RouteProps<P>) => View;
+/** What a `lazy` import may resolve to: the component, or a module holding it. */
+export type LazyModule<P extends Params = Params> = RouteComponent<P> | {
+    readonly default: RouteComponent<P>;
+};
+export interface RouteDefinition {
+    /** Relative to the parent, unless it starts with `/`. */
+    readonly path?: string;
+    /** Matches when the parent matches and nothing is left over. */
+    readonly index?: boolean;
+    readonly component?: RouteComponent;
+    /**
+     * Loads the component when the route is first entered.
+     *
+     * This is the code-splitting seam: `lazy: () => import('./Settings.js')`
+     * keeps that module out of the initial bundle, and the bundler turns it into
+     * its own chunk. The import runs once per route and the result is cached.
+     */
+    readonly lazy?: () => Promise<LazyModule>;
+    /** Shown while `lazy` is loading, instead of the router's own fallback. */
+    readonly pending?: () => View;
+    readonly children?: readonly RouteDefinition[];
+}
+export interface RouteMatch {
+    readonly route: RouteDefinition;
+    readonly params: Params;
+    /** The portion of the pathname this route and its ancestors consumed. */
+    readonly pathname: string;
+}
+/**
+ * Matches a pathname against a route tree.
+ *
+ * Returns the chain from the outermost route to the matched leaf, which is
+ * what `Outlet` walks, or `null` when nothing matched.
+ */
+export declare function matchRoutes(routes: readonly RouteDefinition[], pathname: string): RouteMatch[] | null;
+/**
+ * The component for a route, loading it on first use.
+ *
+ * Reading this inside a reactive scope subscribes to the load, so the view
+ * swaps from the pending state to the real one by itself when the chunk
+ * arrives — no callback, no state machine in the application.
+ */
+export declare function routeComponent(route: RouteDefinition): RouteComponent | undefined;
+/**
+ * Loads the code for whatever `pathname` would render, without navigating.
+ *
+ * Called on hover or focus by `<Link preload>`, so the chunk is usually already
+ * there by the time the click happens.
+ */
+export declare function preloadRoutes(routes: readonly RouteDefinition[], pathname: string): void;
+/**
+ * One route, with its parameters read from its own path.
+ *
+ * The route table already says what each path is, so nothing is declared
+ * twice: `route({ path: 'users/:id', … })` types its component's
+ * `props.params` as `{ id: string }`, and a component that reaches for a
+ * parameter the path does not capture does not compile.
+ *
+ * ```tsx
+ * const routes = [
+ *   route({
+ *     path: '/',
+ *     component: Shell,
+ *     children: (child) => [
+ *       child({ index: true, component: Home }),
+ *       child({ path: 'users/:id', component: ({ params }) => <User id={params.id} /> }),
+ *     ],
+ *   }),
+ * ];
+ * ```
+ *
+ * `children` as a **function** is what carries a parent's parameters down: the
+ * builder it is handed knows what the ancestors captured, so the child above
+ * sees both. Children as a plain array work too, and see only their own.
+ *
+ * All of it is types. `route` returns the object it was given, with a
+ * function-form `children` called once, and a table written as plain
+ * `RouteDefinition[]` still works — its components just see `Params`.
+ */
+export declare const route: RouteBuilder<unknown>;
+/** What `route` accepts, with `Own` from its path and `Inherited` from above. */
+interface RouteSpec<Own, Inherited> {
+    readonly component?: RouteComponent<Simplify<Inherited & Own> & Params>;
+    /** Loaded when the route is first entered; the result is cached. */
+    readonly lazy?: () => Promise<LazyModule<Simplify<Inherited & Own> & Params>>;
+    /** Shown while `lazy` is loading, instead of the router's own fallback. */
+    readonly pending?: () => View;
+    readonly children?: readonly RouteDefinition[] | ((child: RouteBuilder<Simplify<Inherited & Own>>) => readonly RouteDefinition[]);
+}
+/** Builds one route, knowing what the routes above it captured. */
+export interface RouteBuilder<Inherited> {
+    <const Path extends string>(spec: {
+        readonly path: Path;
+    } & RouteSpec<ParamsOf<Path>, Inherited>): RouteDefinition;
+    /** An index route adds no path, so it captures exactly what its parent did. */
+    (spec: {
+        readonly index: true;
+    } & RouteSpec<unknown, Inherited>): RouteDefinition;
+}
+export {};
+//# sourceMappingURL=routes.d.ts.map

package/dist/routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../src/routes.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@firsthandjs/router",
+  "version": "0.1.0",
+  "description": "Routing for Firsthand: nested routes, params, and route code loaded on demand.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "main": "./dist/index.js",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@firsthandjs/core": "0.1.0",
+    "@firsthandjs/dom": "0.1.0"
+  },
+  "engines": {
+    "node": ">=20.11.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/firsthandjs/firsthand.git",
+    "directory": "packages/router"
+  },
+  "bugs": {
+    "url": "https://github.com/firsthandjs/firsthand/issues"
+  },
+  "homepage": "https://github.com/firsthandjs/firsthand#readme",
+  "keywords": [
+    "firsthand",
+    "router",
+    "routing",
+    "code-splitting",
+    "lazy"
+  ]
+}