@k8ordo/router 0.1.0

package/docs/GUIDE.md

@@ -0,0 +1,372 @@
+# @k8ordo/router
+
+The URL's pathname axis, owned. One route table is the application's pathname
+schema, and from it come the types, the matching, the links, and the
+navigation — over the Navigation API and URLPattern.
+
+Like every k8ordo package it assumes React 19 and Server Components, uses only
+what has reached Baseline newly available, and ships no polyfills or legacy
+fallbacks. Both the Navigation API and URLPattern reached Baseline in 2025–26;
+this package treats them as simply present.
+
+## What it does not own
+
+Search params and history-entry state belong to `@k8ordo/state`. This package
+has no `useSearchParams`, and it never hands out the raw search string: a
+component that reads one field of the search should re-render when that field
+changes and not otherwise, which is a job for keyed subscriptions, not for a
+router. The division is the URL itself — pathname here, everything after it
+there.
+
+It also does not fetch. There is no loader, no route-level data API, and no
+cache. Data belongs to the component that needs it — `use()` and `<Suspense>`
+in a client app, the server in a framework one — and a router that owned
+fetching would be a second, competing answer to a question React already
+answers.
+
+## The shape of it
+
+```
+routes.ts        defineRoutes({ … })      the pathname schema, one place
+   ↓ mounted once
+<Router routes>  match → stack → render   layouts wrap through <Outlet />
+   ↑ never imported by pages
+pages            href / navigateTo / useParams
+                 take the pattern string; Register supplies the check
+```
+
+The table's value is held by `<Router>` and nothing else. Everything a page
+needs — building a link, going somewhere, reading its own params — works from
+the pattern **string**, so the module that imports the pages is never imported
+back by them.
+
+## The route table
+
+```ts
+// routes.ts
+import { defineRoutes } from '@k8ordo/router';
+
+import { DocsLayout } from './docs-layout';
+import { Guide } from './guide';
+import { Home } from './home';
+import { NotFound } from './not-found';
+import { ProductList } from './product-list';
+import { ProductPage } from './product-page';
+
+export const routes = defineRoutes({
+  '/': Home,
+  '/products': {
+    children: {
+      '/': ProductList,
+      '/:id': ProductPage,
+    },
+  },
+  '/(docs)': {
+    layout: DocsLayout,
+    children: { '/guide': Guide },
+  },
+  '/*': NotFound,
+});
+```
+
+- A **leaf** is the component to render. A **branch** is `{ layout?, children }`,
+  and a child key of `'/'` is the branch's own index page.
+- **`/:name`** captures a segment, decoded. **`/*`** matches whatever nothing
+  before it did.
+- **`/(name)`** is a route group: it structures the table — its own layout, its
+  own subtree — without contributing a URL segment. It exists because `'/'` can
+  only appear once in an object, so two sections at the same depth could not
+  otherwise have different layouts.
+- **A trailing slash is the same pathname.** `/products/` matches `/products`.
+- A branch may name an **`error`** component beside its layout:
+  `{ layout, error, children }`. When anything below throws, it renders in
+  the layout's hole instead — with `{ error, reset }` as props — and the
+  frame around it survives. Leaving the page that failed clears the failure.
+
+### Order is the rule
+
+Matching walks the table top to bottom and takes the first pattern that fits.
+Precedence is what you wrote — there is no specificity ranking to reason
+backwards from, which means a table can be read like the code it is.
+
+```ts
+defineRoutes({ '/:slug': Article, '/about': About }); // /about → Article
+defineRoutes({ '/about': About, '/:slug': Article }); // /about → About
+```
+
+Put `/*` last, for the same reason.
+
+### What fails at definition time
+
+A table is checked when the module loads, not when someone first navigates:
+
+| written                                                   | error                                                           |
+| --------------------------------------------------------- | --------------------------------------------------------------- |
+| the same full pattern twice, wherever the copies nest     | `route pattern "/x" is declared twice`                          |
+| a group with no children (it would redeclare the index)   | `route group "/(oops)" must have children`                      |
+| a key not starting with `/`                               | `route pattern "x" must start with "/"`                         |
+| parentheses that are not exactly a group (`/(admin)/new`) | `route group "/(admin)/new" must be "/(name)" and nothing else` |
+| a pattern URLPattern cannot parse                         | URLPattern's own `TypeError`                                    |
+
+## Mounting it
+
+```tsx
+import { Outlet, Router } from '@k8ordo/router';
+
+import { routes } from './routes';
+
+export function App() {
+  return <Router routes={routes} />;
+}
+
+// a layout renders what it wraps through Outlet
+export const DocsLayout = () => (
+  <section>
+    <nav>…</nav>
+    <Outlet />
+  </section>
+);
+```
+
+Every same-origin link or programmatic navigation the table claims is handled
+in the browser; the rest is left alone, so a real document load — and a real
+404 — stays the server's answer. A pathname the table does not match renders
+nothing rather than guessing.
+
+Four kinds of navigation are never the application's, whatever the table says:
+a reload, a form submitted with a body (POST), a download, and a fragment-only
+change. Intercepting any of them would silently do nothing where the platform
+would have done the obvious thing — a POST body only the server can act on, an
+`F5` that stops reloading. A GET form carries no body, so the search-shaped
+submissions `@k8ordo/state` builds still come through. Mark a link to a file
+the host serves as an attachment with `download`, so the browser tells the
+router before the click rather than after the answer.
+
+A leaf can be `React.lazy(...)`, which the table stores as any other component;
+put a `<Suspense>` in the layout above it so there is somewhere to fall back
+to while the chunk arrives.
+
+## Links and navigation
+
+```tsx
+import {
+  href,
+  navigateTo,
+  useParams,
+  usePathname,
+  useRoute,
+} from '@k8ordo/router';
+
+<a href={href('/products/:id', { id })}>…</a>;
+<a href={href('/products')}>…</a>; // no params, no second argument
+
+navigateTo('/products/:id', { id }); // pushes: the back button undoes it
+navigateTo('/products', { history: 'replace' });
+
+const { id } = useParams('/products/:id');
+const { pattern } = useRoute(); // untyped: the winning pattern and its params
+const pathname = usePathname(); // where the browser is, table or no table
+```
+
+**There is no `<Link>`.** Under the Navigation API a plain `<a>` is already a
+client navigation — the router intercepts the event the browser was going to
+send anyway. A component wrapping it would add a second way to write the same
+thing and nothing else. An active link is a question you ask, not a prop:
+
+```tsx
+import { matchPath, useMatch } from '@k8ordo/router';
+
+useMatch('/products/:id'); // { id } when that page is showing, else null
+useMatch('/products/*'); // {} anywhere under /products, else null
+matchPath('/products/:id', pathname); // the same, pure, for a pathname in hand
+```
+
+`useMatch` takes a pattern from the table, or a table pattern followed by
+`/*` to mean "everything below it" — what a sidebar asks when it wants to
+know which section of the site is open. The pattern's own page is not below
+it: `/products/*` matches `/products/42` and not `/products`, which is
+`useMatch('/products')`; ask both when a section includes its index. It is built on `usePathname`, so it
+re-renders on the pathname and never on the search, and it needs no table in
+the browser — which is what makes it the one of these that also works under
+the framework, where `useRoute` has no match to read.
+
+**`usePathname` changes when the URL changes, not when the new page appears.**
+Interception commits the URL first and the tree arrives when it has loaded, so
+on a slow navigation a link marks itself active while the previous page is
+still on screen — the same order the browser's own address bar follows. Pair it
+with `useTransition` if the wait needs showing — `navigateTo`'s `finished`
+resolves when the tree is on screen (below).
+
+`usePathname` reads the platform rather than the table, which is why it is the
+one that also works under the framework, where the browser holds no table at
+all. It answers _where the URL is_; `useRoute` answers _which route won_, and
+only something holding the table can say that. The search string is
+deliberately not on offer here: a component re-rendering on every search change
+would defeat `@k8ordo/state`'s keyed subscriptions, and the split at the `?` is
+the boundary between the two packages.
+
+`href` refuses a wildcard: `/*` is something to match, never something to link
+to. Param values are URL-encoded on the way in and decoded on the way out.
+`normalizePathname` is the router's own reading of a pathname — a trailing
+slash dropped, root excepted — for code that compares pathnames the way the
+table does.
+
+`navigateTo` returns the platform's own `{ committed, finished }`, so it
+composes with React 19's async transitions:
+
+```tsx
+const [isPending, startTransition] = useTransition();
+
+startTransition(async () => {
+  await navigateTo('/products/:id', { id }).finished;
+});
+```
+
+Its default is `push`, the opposite of `@k8ordo/state`'s `update()`, and for
+the same reason: going to a page is what the back button should undo, while
+refining what is on the page is not. **Changing pages goes through
+`navigateTo`; changing state goes through `update`.**
+
+## Checking patterns against the real table
+
+Params are inferred from the pattern literal on their own, so a missing or
+misspelled one fails to compile with no setup at all. To have the **pattern**
+checked against the app's actual table as well, augment `Register` once:
+
+```ts
+// types/k8ordo-router.d.ts
+import type { routes } from '../src/routes';
+
+declare module '@k8ordo/router' {
+  interface Register {
+    routes: typeof routes;
+  }
+}
+```
+
+```ts
+href('/products/:id', { id }); // ok
+href('/prodcuts/:id', { id }); // ✗ not a pattern in the table
+href('/products/:id'); // ✗ ":id" is missing
+```
+
+Without the augmentation the constraint is any `/`-prefixed string. Augment
+only in an application — a library doing it would impose its table on every
+consumer.
+
+Under `@k8ordo/static` or `@k8ordo/server` this file is generated into
+`.k8ordo/register.gen.ts` from `routes/` — for `@k8ordo/state` too, when the
+application depends on it — so hand-writing it there is writing a second
+answer to a question already answered. Hand-write it in a client application
+that mounts `<Router>` itself.
+
+The framework's generated `Register` also carries `params`: per pattern, the
+type the route file's `paramsSchema` produces. With it, `href` and
+`navigateTo` take a param as the page receives it — `{ id: 42 }` for a
+schema that said number — and spell it the one way the schema reads back. A
+value with no URL spelling (an object) is refused. Before `Register` is
+augmented — or where no schema covers a param — a link takes any value with
+one spelling (a string, a number, a boolean), so a link written for a schema
+compiles before the generated file exists. `useParams` is unaffected: what a
+hand-written table matches is always a string.
+
+## Typed paths for @k8ordo/state
+
+`@k8ordo/state`'s `Register` takes the same line this one does:
+
+```ts
+declare module '@k8ordo/state' {
+  interface Register {
+    routes: typeof routes;
+  }
+}
+```
+
+With that, `listState.href('/products', { q })` is checked against the same
+table this router matches against, and the two packages agree on what a path
+is. `RouteOf<typeof routes>` is that pathname space as a union, for any other
+typed-path consumer.
+
+## What navigation guarantees
+
+**`finished` means the page is on screen.** The intercept handler resolves in
+an effect after React commits the new tree, so anything awaiting the platform's
+promise — including `@k8ordo/state`'s `update().finished` — is awaiting the
+render, not the URL write.
+
+**A state change is not a page change.** When only the search or the entry
+state moved, the pathname is the one whose tree is on screen: the route tree
+is left alone, nothing remounts, and scroll and focus are not disturbed. This
+is why a search update never scrolls the page back to the top. The comparison
+is against the page showing, not against the address bar — interception
+commits the URL first, so a state update issued while another page is still
+loading is a page change and lets that page finish arriving.
+
+**Route changes run in a transition.** The new tree is applied inside
+`startTransition`, so React can keep the old page interactive while the new
+one prepares.
+
+**A new page starts at the top.** Once the new tree is on screen, the
+viewport goes where a document load would have put it: the top, or the
+element a `#fragment` names. Back and forward are left to the browser, which
+restores the position it saved. A state change never moves the viewport —
+same pathname, same place — so a filter update does not scroll the reader
+back to the top.
+
+**Superseded navigations abort.** A second navigation aborts the first through
+the platform's own signal: the overtaken `finished` rejects with the abort
+reason, and its tree never reaches the screen even if its load had already
+come back. `load` receives that signal, so a payload fetch under the framework
+is cancelled outright. A `React.lazy` chunk cannot be — a dynamic import takes
+no signal — so in a client application it finishes in the background and is
+kept for the next visit, while the page it belonged to is never shown.
+
+## Testing
+
+Nothing here is mocked, so a test needs a browser environment (this package's
+own suite uses Vitest's Chromium browser mode). The one thing to know: a test
+that navigates must intercept, or `navigation.navigate()` is a cross-document
+load that takes the test runner with it.
+
+```tsx
+// a test that mounts <Router> is already intercepting; one that sets up a URL
+// outside the table has to play the router itself
+const interceptEverything = (event: NavigateEvent) => {
+  if (event.canIntercept) event.intercept();
+};
+```
+
+`match` is a pure function and needs no browser: a table's shape, its params
+and its precedence can all be asserted directly.
+
+## Under the framework
+
+`@k8ordo/static` and `@k8ordo/server` render pages on the server, so the
+browser receives a tree rather than building one from a table — there is no
+route table in the client bundle at all, and layouts nest through `children`
+instead of `<Outlet />`. What stays is navigation: both build on
+`useInterceptedNavigation`, the primitive `<Router>` itself uses.
+
+```tsx
+const { generation } = useInterceptedNavigation<Value>({
+  claim: (url) => boolean, // synchronous: the only moment interception is possible
+  load: (url, signal) => Value | Promise<Value>,
+  apply: (value) => void, // called inside a transition
+});
+```
+
+`generation` changes exactly when a new tree is applied — not when the URL
+moved — and a host provides it through `<NavigationGeneration value>` so the
+table's `error` boundaries know when to let a failure go. `<Router>` does
+this itself; the framework's runtime does too.
+
+What carries across unchanged is everything that needs no table: `href`,
+`navigateTo`, `usePathname` and `useMatch`. `usePathname` needs one thing on the server,
+where there is no Navigation API to read: the pathname the render is for,
+supplied by `<PathnameProvider pathname>`. `<Router>` mounts one itself and
+both mode runtimes supply it, so an application never writes it — only a host
+building its own seam out of `useInterceptedNavigation` has to. What does not
+carry across is `useRoute` and `useParams` —
+both read the match from context, and under the framework there is no match in
+the browser to read. A framework page receives its `params` as a prop from the
+server instead, which is the only form Server Components can take them in.

package/docs/llms.txt

@@ -0,0 +1,54 @@
+# @k8ordo/router
+
+> The URL's pathname axis, owned. One `defineRoutes` table is the application's
+> pathname schema: types, matching, links and navigation all come from it, over
+> the Navigation API and URLPattern. Search params and history-entry state are
+> not its business — those belong to `@k8ordo/state`.
+>
+> Like every k8ordo package it assumes React 19 and Server Components, uses
+> only what has reached Baseline newly available, and ships no polyfills or
+> legacy fallbacks.
+
+When installed via npm, these docs live under `node_modules/@k8ordo/router/docs/`.
+
+## Guide
+
+- [Design Guide](GUIDE.md): the table's grammar (leaves, branches, params,
+  wildcards, route groups, declaration order), mounting `<Router>` and
+  `<Outlet>`, links without a `<Link>` component, `useMatch` for active
+  sections, `Register` for checked patterns, what navigation guarantees
+  (`finished` after commit, scroll to top or fragment on a new page), and
+  how the framework reuses the navigation half.
+
+## Entry point
+
+- `@k8ordo/router` — `defineRoutes(record)` returns a table whose one operation
+  is `match(pathname)`; `<Router routes>` mounts it on the Navigation API and
+  `<Outlet />` renders the rest of the matched stack; a branch's `error`
+  component (`{ error, reset }` props, type `ErrorComponent`) renders in the
+  layout's hole when what is below throws, keyed by `NavigationGeneration`
+  so leaving the page clears it. `href(pattern, params?)`
+  and `navigateTo(pattern, params?, options?)` build and perform navigations
+  from the pattern **string** alone — no table import, so no cycle — with
+  params inferred from the literal and the pattern itself checked once
+  `interface Register { routes }` is augmented. `useParams(pattern)` returns
+  typed params and throws if rendered under a different pattern; under the
+  framework `Register` also carries `params` — the type each pattern's
+  `paramsSchema` produces — so `href` takes a param as the page receives it
+  (`ParsedParams` / `ParsedParamsMap` / `ParamsSchemaFor` are the types the
+  generated code uses); `useRoute()`
+  is the untyped form. `RouteOf<typeof routes>` is the pathname union to feed
+  `@k8ordo/state`'s `Register`. `usePathname()` reads the platform's
+  pathname — never the search — so it works with or without a table, which
+  makes it the location hook that also works under the framework;
+  `useMatch(pattern)` / `matchPath(pattern, pathname)` answer whether that
+  pattern — or, with a trailing `/*`, anything strictly below it — is the pathname
+  showing, with its params, table-free, so a sidebar can ask which section is
+  open under the framework too; `normalizePathname(pathname)` is the router's
+  own trailing-slash rule;
+  `<PathnameProvider pathname>` seeds it for a server render and hydration,
+  and is mounted by `<Router>` and by both mode runtimes, never by an
+  application. `useInterceptedNavigation({claim, load, apply})` returns
+  `{ generation }` and is the
+  navigation primitive `<Router>` is built on, and the seam the framework
+  uses to render server-produced trees instead.

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@k8ordo/router",
+  "version": "0.1.0",
+  "description": "The pathname axis of the URL, owned. One route table derives the types, the matching, the links, and the navigation, over the Navigation API and URLPattern.",
+  "keywords": [
+    "navigation-api",
+    "react",
+    "router",
+    "routing",
+    "server-components",
+    "typescript",
+    "urlpattern"
+  ],
+  "homepage": "https://ordo.k8o.me",
+  "bugs": {
+    "url": "https://github.com/k35o/k8ordo/issues"
+  },
+  "license": "MIT",
+  "author": "k8o <kosakanoki@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/k35o/k8ordo.git"
+  },
+  "files": [
+    "dist/**",
+    "docs/**"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "0.18.5",
+    "@types/react": "19.2.18",
+    "@vitejs/plugin-react": "6.0.5",
+    "@vitest/browser-playwright": "4.1.10",
+    "publint": "0.3.23",
+    "react": "19.2.8",
+    "react-dom": "19.2.8",
+    "typescript": "7.0.2",
+    "vite": "8.2.1",
+    "vite-plus": "0.2.9",
+    "vitest": "4.1.10",
+    "vitest-browser-react": "2.2.0"
+  },
+  "peerDependencies": {
+    "@types/react": ">=19.2.18",
+    "react": ">=19.2.6",
+    "typescript": ">=7.0.2"
+  },
+  "peerDependenciesMeta": {
+    "@types/react": {
+      "optional": true
+    },
+    "typescript": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "vp pack",
+    "test": "vp test",
+    "typecheck": "tsc --noEmit",
+    "check": "vp check",
+    "check:write": "vp check --fix",
+    "check:package": "publint && attw --pack . --profile esm-only"
+  }
+}