@owlmeans/router 0.1.18-rc.9 → 0.1.18

package/README.md

@@ -1,24 +1,196 @@
 # @owlmeans/router
 
-Internal router service for the OwlMeans entrypoint system.
-
-## Overview
-
-- Provides the `RouterService` that attaches entrypoints to a runtime router (e.g. Express, Bun's HTTP server)
-- Used internally by `@owlmeans/server-route` and `@owlmeans/client-route`
-- Not typically used directly in application code
+The plugin host for OwlMeans UI routing. It defines the `RouterService` facade (`outlet`,
+`provider`, `useParams`, `useLocation`, `useNavigate`, `useSearchParams`, `compile`), keeps a
+registry of `RouterPlugin`s and selects the active one by cascade, and ships the neutral route IR
+(`RouteObject`) plus a pure, DOM-free route matcher. An app imports it for the router types and the
+`ROUTER_SERVICE` alias, and a plugin author builds on it. It does not route anything by itself — a
+browser app gets the default OwlMeans router from `@owlmeans/web-router` (registered by
+`@owlmeans/web-client` / `@owlmeans/web-panel`) or opts into react-router v7 with
+`@owlmeans/web-router-react-router`. It has nothing to do with server HTTP routing; that is
+`@owlmeans/server-route`. The package's skills are `router` and `router-plugins`.
 
 ## Installation
 
 ```bash
-bun add @owlmeans/router@^0.1.18-rc.7
+bun add @owlmeans/router@^0.1.18
 ```
 
-## Related Packages
+`react` is a peer dependency — the package uses its component types only.
+
+## Concepts
+
+- **Host** — `RouterService`, a lazy service registered under `ROUTER_SERVICE` (`'router-service'`).
+  Every facade call re-selects the active plugin and delegates to it.
+- **Plugin** — a `RouterPlugin`: one routing mechanic (browser History, react-router, SSR, native)
+  with its own `compile`, provider, outlet and hooks. Plugins are keyed by `alias`; registering the
+  same alias again replaces the earlier one.
+- **Cascade** — plugins are kept sorted by `priority` (descending, stable). `plugin(env?)` returns
+  the first whose `match(env, ctx)` is truthy (`match` omitted means "always applies") and throws
+  when none matches.
+- **Environment** — `RouterEnv` (`{ hasWindow, ssr, request? }`) is what `match` sees.
+  `defaultRouterEnv()` derives it from `window`; an SSR host passes a per-request env.
+- **Route IR** — `RouteObject` (`{ index?, path?, children?, Component? }`), shape-compatible with
+  react-router's route objects, produced by `@owlmeans/client` from the entrypoint tree and consumed
+  by every plugin.
+- **Matcher** — `routeMatcherHelper`: flattens a route tree into branches, ranks them (static beats
+  `:param`, deeper beats shallower) and matches a pathname to a root→leaf chain with merged params.
+
+## Usage
+
+### Read routing state through the facade
+
+In a client app the facade is also reachable as `context.router()`; the alias works anywhere a
+context is at hand.
+
+```typescript
+import { ROUTER_SERVICE } from '@owlmeans/router'
+import type { RouterService } from '@owlmeans/router'
+
+export const useProjectId = (ctx: AppContext): string | undefined => {
+  const router = ctx.service<RouterService>(ROUTER_SERVICE)
+  const { projectId } = router.useParams<{ projectId?: string }>()
+
+  return projectId
+}
+```
+
+### Switch an app to another plugin
+
+The default browser plugin registers at priority 0. A plugin with a higher priority wins the
+cascade without removing it:
+
+```typescript
+import { makeContext as makeBase } from '@owlmeans/web-panel'
+import { appendReactRouter } from '@owlmeans/web-router-react-router'
+
+export const makeContext = (cfg: AppConfig) => {
+  const context = makeBase(cfg)
+  appendReactRouter(context) // priority 100 — outranks the default OwlMeans router
+
+  return context
+}
+```
+
+### Author a plugin
+
+Reach the host with `ensureRouterService` (it registers an empty host when none exists yet), set a
+priority above `DEFAULT_ROUTER_PRIORITY` and a `match` that fires only in your environment. The
+matcher can be reused as is — it is pure and SSR-safe.
+
+```typescript
+import { DEFAULT_ROUTER_PRIORITY, ensureRouterService, routeMatcherHelper } from '@owlmeans/router'
+import type { LibraryRouter, RouterPlugin } from '@owlmeans/router'
+import type { BasicConfig, BasicContext } from '@owlmeans/context'
+
+export const makeSsrRouterPlugin = (): RouterPlugin => ({
+  alias: 'ssr-router',
+  priority: DEFAULT_ROUTER_PRIORITY + 50,
+  mode: 'ssr',
+  match: env => env.ssr,
+  compile: routes => ({
+    routes,
+    branches: routeMatcherHelper.rankRouteBranches(routeMatcherHelper.flattenRoutes(routes)),
+  }) as LibraryRouter,
+  provider: () => SsrRouterProvider,
+  outlet: () => SsrOutlet,
+  useParams: useSsrParams,
+  useLocation: useSsrLocation,
+  useNavigate: useSsrNavigate,
+  useSearchParams: useSsrSearchParams,
+})
+
+export const appendSsrRouter = <C extends BasicConfig, T extends BasicContext<C>>(ctx: T): T => {
+  ensureRouterService(ctx).registerPlugin(makeSsrRouterPlugin())
+
+  return ctx
+}
+```
+
+### Match a pathname without a DOM
+
+```typescript
+import { routeMatcherHelper } from '@owlmeans/router'
+import type { RouteObject } from '@owlmeans/router'
+
+const routes: RouteObject[] = [
+  { path: '/', children: [
+    { index: true },
+    { path: 'projects/:projectId', children: [{ index: true }, { path: 'stories/:storyId' }] },
+  ] },
+]
+
+const branches = routeMatcherHelper.rankRouteBranches(routeMatcherHelper.flattenRoutes(routes))
+const chain = routeMatcherHelper.matchRoutes(branches, '/projects/p1/stories/s7')
+// chain: root → leaf RouteMatch[]; every level carries { projectId: 'p1', storyId: 's7' }
+```
+
+## API
+
+### Functions and helpers
+
+| Symbol | Purpose |
+|---|---|
+| `makeRouterService(alias?)` | Build an empty host (lazy service, default alias `ROUTER_SERVICE`) |
+| `ensureRouterService(ctx)` | Return the host on a context, registering an empty one if missing |
+| `defaultRouterEnv()` | `{ hasWindow, ssr: !hasWindow }` from the global `window` |
+| `createRouteMatcherHelper()` / `routeMatcherHelper` | The matcher factory and its shared instance |
+| `routeMatcherHelper.splitPath(path?)` | Non-empty `/`-separated parts |
+| `routeMatcherHelper.segmentsOf(path?)` | Static / `:param` / splat pattern segments |
+| `routeMatcherHelper.flattenRoutes(routes)` | Route tree → `RouteBranch[]` (each with its root→node chain) |
+| `routeMatcherHelper.rankRouteBranches(branches)` | Most specific first, stable within equal score |
+| `routeMatcherHelper.matchRoutes(branches, pathname)` | `RouteMatch[]` chain or `null`; static segments match case-insensitively, params are URI-decoded |
+
+### `RouterService` members
+
+| Member | Purpose |
+|---|---|
+| `registerPlugin(plugin)` | Add or replace (by alias) a plugin and re-sort by priority |
+| `plugin(env?)` | The active plugin for `env` (default `defaultRouterEnv()`) |
+| `outlet()`, `provider()` | Components of the active plugin |
+| `useParams`, `useLocation`, `useNavigate`, `useSearchParams` | Hooks of the active plugin |
+| `compile(routes)` | Compile a `RouteObject[]` into the active plugin's `LibraryRouter` |
+
+### Constants
+
+| Symbol | Value | Purpose |
+|---|---|---|
+| `ROUTER_SERVICE`, `DEFAULT_ALIAS` | `'router-service'` | Host alias |
+| `DEFAULT_ROUTER_PRIORITY` | `0` | Priority of the default plugin |
+| `ROUTER_PLUGIN` | `'router-plugin'` | Config-record id for declaring a preferred router plugin |
+
+### Types
+
+| Symbol | Purpose |
+|---|---|
+| `RouterService`, `RouterPlugin`, `RouterEnv` | Host, plugin contract, selection environment |
+| `RouteObject`, `LibraryRouter`, `RouterProvider` | Route IR, opaque compiled router, the component rendering it |
+| `RouteBranch`, `RouteMatch`, `PatternSegment`, `RouteParams` | Matcher output |
+| `RouteMatcherHelper` | The matcher's interface |
+| `UseParamsHook`, `UseLocationHook`, `UseNavigateHook`, `UseSearchParamsHook` | Hook signatures a plugin implements |
+| `Location`, `Path`, `NavigateFunction`, `NavigateOptions`, `SetSearchParams` | Navigation value types |
+| `ComponentType` | Re-exported from `react` |
+
+## Common pitfalls
+
+- Splat (`*`) and optional (`:x?`) segments are not implemented — `matchRoutes` throws on a splat
+  branch. Keep route trees to static, `:param`, nested and index routes.
+- Do not check `typeof window` inside a plugin's `match`; selection reads `RouterEnv`, which an SSR
+  host overrides per request.
+- Keep the facade methods assignable plain properties when extending the host — a native host
+  replaces them by assignment.
+- Keep the host lazy: plugin packages call `ensureRouterService` from `makeContext`, before the
+  context is initialized, and an eager service would throw there.
+- Registering a plugin under an existing alias replaces it; use a distinct alias to add a second
+  mechanic.
+
+## Related packages
 
-- [`@owlmeans/server-route`](../server-route) — server-side router implementation
-- [`@owlmeans/client-route`](../client-route) — client-side router implementation
-- [`@owlmeans/entrypoint`](../entrypoint) — entrypoints registered with the router
+- [`@owlmeans/web-router`](../web-router) — the default OwlMeans in-browser plugin (`appendWebRouter`)
+- [`@owlmeans/web-router-react-router`](../web-router-react-router) — opt-in react-router v7 plugin (`appendReactRouter`)
+- [`@owlmeans/client`](../client) — builds the `RouteObject` tree from entrypoints and exposes `context.router()`
+- [`@owlmeans/client-route`](../client-route) — client-side route declarations
+- [`@owlmeans/context`](../context) — the lazy service the host is built on
 
 <!-- owlmeans:agent-guidance:start -->
 ## Agent guidance
@@ -28,7 +200,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
 your project's skill store (`.agents/skills/`):
 
 ```sh
-npx @owlmeans/agent-skills@^0.1.18-rc.13
+npx @owlmeans/agent-skills@^0.1.18
 ```
 
 The embedded files are version-matched to this package release. Do not edit them

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
-  "schemaVersion": 2,
+  "schemaVersion": 3,
   "package": "@owlmeans/router",
-  "version": "0.1.18-rc.9",
-  "generatedAt": "2026-09-10T18:54:42.499Z",
+  "version": "0.1.18",
+  "generatedAt": "2026-10-28T00:31:34.744Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

package/agent-meta/skills/router/SKILL.md

@@ -8,7 +8,7 @@ user-invocable: false
 # @owlmeans/router
 
 **Layer:** Core (L1)
-**Install:** `"@owlmeans/router": "^0.1.18-rc.9"` in `dependencies`
+**Install:** `"@owlmeans/router": "^0.1.18"` in `dependencies`
 
 `@owlmeans/router` is the **plugin host** for OwlMeans UI routing. It does not talk to any
 concrete router; it defines the contract, holds a registry of routing plugins, and selects the

package/build/consts.local.d.ts

@@ -0,0 +1,8 @@
+export declare const SEP = "/";
+export declare const PARAM = ":";
+export declare const SPLAT = "*";
+export declare const STATIC_WEIGHT = 10;
+export declare const PARAM_WEIGHT = 4;
+export declare const INDEX_WEIGHT = 2;
+export declare const EMPTY_WEIGHT = 1;
+//# sourceMappingURL=consts.local.d.ts.map

package/build/consts.local.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.local.d.ts","sourceRoot":"","sources":["../src/consts.local.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,GAAG,MAAM,CAAA;AAEtB,eAAO,MAAM,KAAK,MAAM,CAAA;AAExB,eAAO,MAAM,KAAK,MAAM,CAAA;AAExB,eAAO,MAAM,aAAa,KAAK,CAAA;AAE/B,eAAO,MAAM,YAAY,IAAI,CAAA;AAE7B,eAAO,MAAM,YAAY,IAAI,CAAA;AAE7B,eAAO,MAAM,YAAY,IAAI,CAAA"}

package/build/consts.local.js

@@ -0,0 +1,8 @@
+export const SEP = '/';
+export const PARAM = ':';
+export const SPLAT = '*';
+export const STATIC_WEIGHT = 10;
+export const PARAM_WEIGHT = 4;
+export const INDEX_WEIGHT = 2;
+export const EMPTY_WEIGHT = 1;
+//# sourceMappingURL=consts.local.js.map

package/build/consts.local.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.local.js","sourceRoot":"","sources":["../src/consts.local.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,GAAG,GAAG,GAAG,CAAA;AAEtB,MAAM,CAAC,MAAM,KAAK,GAAG,GAAG,CAAA;AAExB,MAAM,CAAC,MAAM,KAAK,GAAG,GAAG,CAAA;AAExB,MAAM,CAAC,MAAM,aAAa,GAAG,EAAE,CAAA;AAE/B,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAA;AAE7B,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAA;AAE7B,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAA"}

package/build/index.d.ts

@@ -1,4 +1,5 @@
 export type * from './types.js';
+export type * from './matcher/types.js';
 export * from './consts.js';
 export * from './service.js';
 export * from './matcher.js';

package/build/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,mBAAmB,YAAY,CAAA;AAC/B,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,cAAc,CAAA;AAC5B,cAAc,UAAU,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,mBAAmB,YAAY,CAAA;AAC/B,mBAAmB,oBAAoB,CAAA;AACvC,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,cAAc,CAAA;AAC5B,cAAc,UAAU,CAAA"}

package/build/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,cAAc,CAAA;AAC5B,cAAc,UAAU,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,cAAc,CAAA;AAC5B,cAAc,UAAU,CAAA"}

package/build/matcher/types.d.ts

@@ -0,0 +1,31 @@
+import type { PatternSegment, RouteBranch, RouteMatch, RouteObject } from '../types.js';
+/**
+ * Pure, DOM-free route matcher. Supports exactly the route-description subset used
+ * across the OwlMeans projects: static segments, `:param` dynamic segments, nested
+ * (parent/child) routes and index routes. Splat (`*`) and optional (`:x?`) segments
+ * are intentionally not implemented yet — a seam is reserved so they can be added
+ * without changing the public shape.
+ *
+ * Segment weights mirror react-router's ranking intuition (static beats dynamic,
+ * more specific / deeper beats shallower).
+ */
+export interface RouteMatcherHelper {
+    /** The non-empty `/`-separated parts of a path. */
+    splitPath: (path?: string) => string[];
+    /** The pattern segments of a route path: static, `:param` or splat. */
+    segmentsOf: (path?: string) => PatternSegment[];
+    /**
+     * Flatten a route tree into ranked-matchable branches. Every leaf and every node
+     * carrying an index child produces a branch.
+     */
+    flattenRoutes: (routes: RouteObject[], parentChain?: RouteObject[], parentSegments?: PatternSegment[]) => RouteBranch[];
+    /** Rank branches so the most specific match is tried first. Stable within equal score. */
+    rankRouteBranches: (branches: RouteBranch[]) => RouteBranch[];
+    /**
+     * Match a pathname against ranked branches. Returns the winning branch as a
+     * root→leaf chain of `RouteMatch` (params merged across the whole chain so every
+     * depth sees the full leaf param set, matching react-router's `useParams`).
+     */
+    matchRoutes: (branches: RouteBranch[], pathname: string) => RouteMatch[] | null;
+}
+//# sourceMappingURL=types.d.ts.map

package/build/matcher/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/matcher/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAEvF;;;;;;;;;GASG;AACH,MAAM,WAAW,kBAAkB;IACjC,mDAAmD;IACnD,SAAS,EAAE,CAAC,IAAI,CAAC,EAAE,MAAM,KAAK,MAAM,EAAE,CAAA;IACtC,uEAAuE;IACvE,UAAU,EAAE,CAAC,IAAI,CAAC,EAAE,MAAM,KAAK,cAAc,EAAE,CAAA;IAC/C;;;OAGG;IACH,aAAa,EAAE,CAAC,MAAM,EAAE,WAAW,EAAE,EAAE,WAAW,CAAC,EAAE,WAAW,EAAE,EAAE,cAAc,CAAC,EAAE,cAAc,EAAE,KAAK,WAAW,EAAE,CAAA;IACvH,0FAA0F;IAC1F,iBAAiB,EAAE,CAAC,QAAQ,EAAE,WAAW,EAAE,KAAK,WAAW,EAAE,CAAA;IAC7D;;;;OAIG;IACH,WAAW,EAAE,CAAC,QAAQ,EAAE,WAAW,EAAE,EAAE,QAAQ,EAAE,MAAM,KAAK,UAAU,EAAE,GAAG,IAAI,CAAA;CAChF"}

package/build/matcher/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/build/matcher/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/matcher/types.ts"],"names":[],"mappings":""}

package/build/matcher.d.ts

@@ -1,37 +1,4 @@
-import type { RouteObject, RouteParams } from './types.js';
-type SegmentKind = 'static' | 'param' | 'splat';
-export interface PatternSegment {
-    kind: SegmentKind;
-    /** literal value for static, param name for param */
-    value: string;
-}
-export interface RouteBranch {
-    /** root → node chain; drives outlet depth in the renderer */
-    chain: RouteObject[];
-    segments: PatternSegment[];
-    /** true when the terminal node is an index route */
-    index: boolean;
-    score: number;
-}
-export interface RouteMatch {
-    route: RouteObject;
-    params: RouteParams;
-    pathname: string;
-}
-export declare const splitPath: (path?: string) => string[];
-export declare const segmentsOf: (path?: string) => PatternSegment[];
-/**
- * Flatten a route tree into ranked-matchable branches. Every leaf and every node
- * carrying an index child produces a branch.
- */
-export declare const flattenRoutes: (routes: RouteObject[], parentChain?: RouteObject[], parentSegments?: PatternSegment[]) => RouteBranch[];
-/** Rank branches so the most specific match is tried first. Stable within equal score. */
-export declare const rankRouteBranches: (branches: RouteBranch[]) => RouteBranch[];
-/**
- * Match a pathname against ranked branches. Returns the winning branch as a
- * root→leaf chain of `RouteMatch` (params merged across the whole chain so every
- * depth sees the full leaf param set, matching react-router's `useParams`).
- */
-export declare const matchRoutes: (branches: RouteBranch[], pathname: string) => RouteMatch[] | null;
-export {};
+import type { RouteMatcherHelper } from './matcher/types.js';
+export declare const createRouteMatcherHelper: () => RouteMatcherHelper;
+export declare const routeMatcherHelper: RouteMatcherHelper;
 //# sourceMappingURL=matcher.d.ts.map

package/build/matcher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"matcher.d.ts","sourceRoot":"","sources":["../src/matcher.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAsB1D,KAAK,WAAW,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAA;AAE/C,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,WAAW,CAAA;IACjB,qDAAqD;IACrD,KAAK,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,WAAW;IAC1B,6DAA6D;IAC7D,KAAK,EAAE,WAAW,EAAE,CAAA;IACpB,QAAQ,EAAE,cAAc,EAAE,CAAA;IAC1B,oDAAoD;IACpD,KAAK,EAAE,OAAO,CAAA;IACd,KAAK,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,WAAW,CAAA;IAClB,MAAM,EAAE,WAAW,CAAA;IACnB,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED,eAAO,MAAM,SAAS,UAAW,MAAM,KAAG,MAAM,EACS,CAAA;AAEzD,eAAO,MAAM,UAAU,UAAW,MAAM,KAAG,cAAc,EAKrD,CAAA;AAEJ;;;GAGG;AACH,eAAO,MAAM,aAAa,WAChB,WAAW,EAAE,gBACR,WAAW,EAAE,mBACV,cAAc,EAAE,KAC/B,WAAW,EAuBb,CAAA;AAaD,0FAA0F;AAC1F,eAAO,MAAM,iBAAiB,aAAc,WAAW,EAAE,KAAG,WAAW,EAKvC,CAAA;AAsBhC;;;;GAIG;AACH,eAAO,MAAM,WAAW,aAAc,WAAW,EAAE,YAAY,MAAM,KAAG,UAAU,EAAE,GAAG,IAgBtF,CAAA"}
+{"version":3,"file":"matcher.d.ts","sourceRoot":"","sources":["../src/matcher.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AAE5D,eAAO,MAAM,wBAAwB,QAAO,kBAiG3C,CAAA;AAED,eAAO,MAAM,kBAAkB,oBAA6B,CAAA"}

package/build/matcher.js

@@ -1,111 +1,89 @@
-/**
- * Pure, DOM-free route matcher. Supports exactly the route-description subset used
- * across the OwlMeans projects: static segments, `:param` dynamic segments, nested
- * (parent/child) routes and index routes. Splat (`*`) and optional (`:x?`) segments
- * are intentionally not implemented yet — a seam is reserved so they can be added
- * without changing the public shape.
- *
- * Segment weights mirror react-router's ranking intuition (static beats dynamic,
- * more specific / deeper beats shallower).
- */
-const SEP = '/';
-const PARAM = ':';
-const SPLAT = '*';
-const STATIC_WEIGHT = 10;
-const PARAM_WEIGHT = 4;
-const INDEX_WEIGHT = 2;
-const EMPTY_WEIGHT = 1;
-export const splitPath = (path) => (path ?? '').split(SEP).filter(part => part.length > 0);
-export const segmentsOf = (path) => splitPath(path).map(part => {
-    if (part === SPLAT)
-        return { kind: 'splat', value: SPLAT };
-    if (part.startsWith(PARAM))
-        return { kind: 'param', value: part.slice(PARAM.length) };
-    return { kind: 'static', value: part };
-});
-/**
- * Flatten a route tree into ranked-matchable branches. Every leaf and every node
- * carrying an index child produces a branch.
- */
-export const flattenRoutes = (routes, parentChain = [], parentSegments = []) => {
-    const branches = [];
-    for (const route of routes) {
-        const chain = [...parentChain, route];
-        if (route.index === true) {
-            // An index route contributes an empty terminal at the parent's path.
-            branches.push({ chain, segments: parentSegments, index: true, score: 0 });
-            continue;
+import { EMPTY_WEIGHT, INDEX_WEIGHT, PARAM, PARAM_WEIGHT, SEP, SPLAT, STATIC_WEIGHT } from './consts.local.js';
+export const createRouteMatcherHelper = () => {
+    const splitPath = (path) => (path ?? '').split(SEP).filter(part => part.length > 0);
+    const segmentsOf = (path) => splitPath(path).map(part => {
+        if (part === SPLAT)
+            return { kind: 'splat', value: SPLAT };
+        if (part.startsWith(PARAM))
+            return { kind: 'param', value: part.slice(PARAM.length) };
+        return { kind: 'static', value: part };
+    });
+    const flattenRoutes = (routes, parentChain = [], parentSegments = []) => {
+        const branches = [];
+        for (const route of routes) {
+            const chain = [...parentChain, route];
+            if (route.index === true) {
+                // An index route contributes an empty terminal at the parent's path.
+                branches.push({ chain, segments: parentSegments, index: true, score: 0 });
+                continue;
+            }
+            const segments = [...parentSegments, ...segmentsOf(route.path)];
+            const children = route.children ?? [];
+            if (children.length === 0) {
+                branches.push({ chain, segments, index: false, score: 0 });
+            }
+            else {
+                branches.push(...flattenRoutes(children, chain, segments));
+            }
         }
-        const segments = [...parentSegments, ...segmentsOf(route.path)];
-        const children = route.children ?? [];
-        if (children.length === 0) {
-            branches.push({ chain, segments, index: false, score: 0 });
+        return branches;
+    };
+    const scoreBranch = (branch) => {
+        let score = branch.segments.reduce((acc, seg) => {
+            if (seg.kind === 'static')
+                return acc + STATIC_WEIGHT;
+            if (seg.kind === 'param')
+                return acc + PARAM_WEIGHT;
+            return acc + EMPTY_WEIGHT;
+        }, 0);
+        if (branch.segments.length === 0)
+            score += EMPTY_WEIGHT;
+        if (branch.index)
+            score += INDEX_WEIGHT;
+        return score;
+    };
+    const rankRouteBranches = (branches) => branches
+        .map(branch => ({ ...branch, score: scoreBranch(branch) }))
+        .map((branch, index) => ({ branch, index }))
+        .sort((a, b) => (b.branch.score - a.branch.score) || (a.index - b.index))
+        .map(({ branch }) => branch);
+    const matchBranch = (branch, parts) => {
+        if (branch.segments.some(seg => seg.kind === 'splat')) {
+            throw new Error('router matcher: splat (*) segments are not implemented yet');
         }
-        else {
-            branches.push(...flattenRoutes(children, chain, segments));
+        // Exact-length match (no splats/optionals in the supported subset).
+        if (branch.segments.length !== parts.length)
+            return null;
+        const params = {};
+        for (let i = 0; i < branch.segments.length; i++) {
+            const seg = branch.segments[i];
+            const part = parts[i];
+            if (seg.kind === 'static') {
+                if (seg.value.toLowerCase() !== part.toLowerCase())
+                    return null;
+            }
+            else {
+                params[seg.value] = decodeURIComponent(part);
+            }
         }
-    }
-    return branches;
-};
-const scoreBranch = (branch) => {
-    let score = branch.segments.reduce((acc, seg) => {
-        if (seg.kind === 'static')
-            return acc + STATIC_WEIGHT;
-        if (seg.kind === 'param')
-            return acc + PARAM_WEIGHT;
-        return acc + EMPTY_WEIGHT;
-    }, 0);
-    if (branch.segments.length === 0)
-        score += EMPTY_WEIGHT;
-    if (branch.index)
-        score += INDEX_WEIGHT;
-    return score;
-};
-/** Rank branches so the most specific match is tried first. Stable within equal score. */
-export const rankRouteBranches = (branches) => branches
-    .map(branch => ({ ...branch, score: scoreBranch(branch) }))
-    .map((branch, index) => ({ branch, index }))
-    .sort((a, b) => (b.branch.score - a.branch.score) || (a.index - b.index))
-    .map(({ branch }) => branch);
-const matchBranch = (branch, parts) => {
-    if (branch.segments.some(seg => seg.kind === 'splat')) {
-        throw new Error('router matcher: splat (*) segments are not implemented yet');
-    }
-    // Exact-length match (no splats/optionals in the supported subset).
-    if (branch.segments.length !== parts.length)
-        return null;
-    const params = {};
-    for (let i = 0; i < branch.segments.length; i++) {
-        const seg = branch.segments[i];
-        const part = parts[i];
-        if (seg.kind === 'static') {
-            if (seg.value.toLowerCase() !== part.toLowerCase())
-                return null;
+        return params;
+    };
+    const matchRoutes = (branches, pathname) => {
+        const parts = splitPath(pathname);
+        const ranked = rankRouteBranches(branches);
+        for (const branch of ranked) {
+            const params = matchBranch(branch, parts);
+            if (params == null)
+                continue;
+            return branch.chain.map(route => ({
+                route,
+                params,
+                pathname: SEP + parts.join(SEP)
+            }));
         }
-        else {
-            params[seg.value] = decodeURIComponent(part);
-        }
-    }
-    return params;
-};
-/**
- * Match a pathname against ranked branches. Returns the winning branch as a
- * root→leaf chain of `RouteMatch` (params merged across the whole chain so every
- * depth sees the full leaf param set, matching react-router's `useParams`).
- */
-export const matchRoutes = (branches, pathname) => {
-    const parts = splitPath(pathname);
-    const ranked = rankRouteBranches(branches);
-    for (const branch of ranked) {
-        const params = matchBranch(branch, parts);
-        if (params == null)
-            continue;
-        return branch.chain.map(route => ({
-            route,
-            params,
-            pathname: SEP + parts.join(SEP)
-        }));
-    }
-    return null;
+        return null;
+    };
+    return { splitPath, segmentsOf, flattenRoutes, rankRouteBranches, matchRoutes };
 };
+export const routeMatcherHelper = createRouteMatcherHelper();
 //# sourceMappingURL=matcher.js.map

package/build/matcher.js.map

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

package/build/types.d.ts

@@ -1,5 +1,6 @@
 import type { LazyService, BasicContext } from "@owlmeans/context";
 import type { ComponentType } from 'react';
+import type { SegmentKind } from './types.local.js';
 export type { ComponentType };
 export type LibraryRouter = unknown;
 /**
@@ -97,4 +98,22 @@ export interface SetSearchParams {
 export interface UseSearchParamsHook {
     (init?: URLSearchParams | Record<string, string>): [URLSearchParams, SetSearchParams];
 }
+export interface PatternSegment {
+    kind: SegmentKind;
+    /** literal value for static, param name for param */
+    value: string;
+}
+export interface RouteBranch {
+    /** root → node chain; drives outlet depth in the renderer */
+    chain: RouteObject[];
+    segments: PatternSegment[];
+    /** true when the terminal node is an index route */
+    index: boolean;
+    score: number;
+}
+export interface RouteMatch {
+    route: RouteObject;
+    params: RouteParams;
+    pathname: string;
+}
 //# sourceMappingURL=types.d.ts.map

package/build/types.d.ts.map

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

package/build/types.local.d.ts

@@ -0,0 +1,2 @@
+export type SegmentKind = 'static' | 'param' | 'splat';
+//# sourceMappingURL=types.local.d.ts.map

package/build/types.local.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.local.d.ts","sourceRoot":"","sources":["../src/types.local.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAA"}

package/build/types.local.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.local.js.map

package/build/types.local.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.local.js","sourceRoot":"","sources":["../src/types.local.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/router",
-  "version": "0.1.18-rc.9",
+  "version": "0.1.18",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -21,15 +21,15 @@
     }
   },
   "dependencies": {
-    "@owlmeans/context": "^0.1.18-rc.9"
+    "@owlmeans/context": "^0.1.18"
   },
   "peerDependencies": {
     "react": "*"
   },
   "devDependencies": {
-    "@owlmeans/dep-config": "workspace:*",
-    "@types/node": "^26.1.0",
-    "@types/react": "^19.2.17",
+    "@owlmeans/dep-config": "^0.1.18",
+    "@types/node": "^26.6.4",
+    "@types/react": "^19.3.0",
     "nodemon": "^3.1.14",
     "typescript": "^7.0.2"
   },

package/src/consts.local.ts

@@ -0,0 +1,13 @@
+export const SEP = '/'
+
+export const PARAM = ':'
+
+export const SPLAT = '*'
+
+export const STATIC_WEIGHT = 10
+
+export const PARAM_WEIGHT = 4
+
+export const INDEX_WEIGHT = 2
+
+export const EMPTY_WEIGHT = 1

package/src/index.ts

@@ -1,5 +1,6 @@
 
 export type * from './types.js'
+export type * from './matcher/types.js'
 export * from './consts.js'
 export * from './service.js'
 export * from './matcher.js'

package/src/matcher/types.ts

@@ -0,0 +1,31 @@
+import type { PatternSegment, RouteBranch, RouteMatch, RouteObject } from '../types.js'
+
+/**
+ * Pure, DOM-free route matcher. Supports exactly the route-description subset used
+ * across the OwlMeans projects: static segments, `:param` dynamic segments, nested
+ * (parent/child) routes and index routes. Splat (`*`) and optional (`:x?`) segments
+ * are intentionally not implemented yet — a seam is reserved so they can be added
+ * without changing the public shape.
+ *
+ * Segment weights mirror react-router's ranking intuition (static beats dynamic,
+ * more specific / deeper beats shallower).
+ */
+export interface RouteMatcherHelper {
+  /** The non-empty `/`-separated parts of a path. */
+  splitPath: (path?: string) => string[]
+  /** The pattern segments of a route path: static, `:param` or splat. */
+  segmentsOf: (path?: string) => PatternSegment[]
+  /**
+   * Flatten a route tree into ranked-matchable branches. Every leaf and every node
+   * carrying an index child produces a branch.
+   */
+  flattenRoutes: (routes: RouteObject[], parentChain?: RouteObject[], parentSegments?: PatternSegment[]) => RouteBranch[]
+  /** Rank branches so the most specific match is tried first. Stable within equal score. */
+  rankRouteBranches: (branches: RouteBranch[]) => RouteBranch[]
+  /**
+   * Match a pathname against ranked branches. Returns the winning branch as a
+   * root→leaf chain of `RouteMatch` (params merged across the whole chain so every
+   * depth sees the full leaf param set, matching react-router's `useParams`).
+   */
+  matchRoutes: (branches: RouteBranch[], pathname: string) => RouteMatch[] | null
+}

package/src/matcher.ts

@@ -1,149 +1,104 @@
-import type { RouteObject, RouteParams } from './types.js'
-
-/**
- * Pure, DOM-free route matcher. Supports exactly the route-description subset used
- * across the OwlMeans projects: static segments, `:param` dynamic segments, nested
- * (parent/child) routes and index routes. Splat (`*`) and optional (`:x?`) segments
- * are intentionally not implemented yet — a seam is reserved so they can be added
- * without changing the public shape.
- *
- * Segment weights mirror react-router's ranking intuition (static beats dynamic,
- * more specific / deeper beats shallower).
- */
-
-const SEP = '/'
-const PARAM = ':'
-const SPLAT = '*'
-
-const STATIC_WEIGHT = 10
-const PARAM_WEIGHT = 4
-const INDEX_WEIGHT = 2
-const EMPTY_WEIGHT = 1
-
-type SegmentKind = 'static' | 'param' | 'splat'
-
-export interface PatternSegment {
-  kind: SegmentKind
-  /** literal value for static, param name for param */
-  value: string
-}
-
-export interface RouteBranch {
-  /** root → node chain; drives outlet depth in the renderer */
-  chain: RouteObject[]
-  segments: PatternSegment[]
-  /** true when the terminal node is an index route */
-  index: boolean
-  score: number
-}
+import type { RouteObject, RouteParams, PatternSegment, RouteBranch, RouteMatch } from './types.js'
+import { EMPTY_WEIGHT, INDEX_WEIGHT, PARAM, PARAM_WEIGHT, SEP, SPLAT, STATIC_WEIGHT } from './consts.local.js'
+import type { RouteMatcherHelper } from './matcher/types.js'
+
+export const createRouteMatcherHelper = (): RouteMatcherHelper => {
+  const splitPath = (path?: string): string[] =>
+    (path ?? '').split(SEP).filter(part => part.length > 0)
+
+  const segmentsOf = (path?: string): PatternSegment[] =>
+    splitPath(path).map(part => {
+      if (part === SPLAT) return { kind: 'splat', value: SPLAT }
+      if (part.startsWith(PARAM)) return { kind: 'param', value: part.slice(PARAM.length) }
+      return { kind: 'static', value: part }
+    })
+
+  const flattenRoutes = (
+    routes: RouteObject[],
+    parentChain: RouteObject[] = [],
+    parentSegments: PatternSegment[] = []
+  ): RouteBranch[] => {
+    const branches: RouteBranch[] = []
+
+    for (const route of routes) {
+      const chain = [...parentChain, route]
+
+      if (route.index === true) {
+        // An index route contributes an empty terminal at the parent's path.
+        branches.push({ chain, segments: parentSegments, index: true, score: 0 })
+        continue
+      }
+
+      const segments = [...parentSegments, ...segmentsOf(route.path)]
+      const children = route.children ?? []
+
+      if (children.length === 0) {
+        branches.push({ chain, segments, index: false, score: 0 })
+      } else {
+        branches.push(...flattenRoutes(children, chain, segments))
+      }
+    }
 
-export interface RouteMatch {
-  route: RouteObject
-  params: RouteParams
-  pathname: string
-}
+    return branches
+  }
 
-export const splitPath = (path?: string): string[] =>
-  (path ?? '').split(SEP).filter(part => part.length > 0)
-
-export const segmentsOf = (path?: string): PatternSegment[] =>
-  splitPath(path).map(part => {
-    if (part === SPLAT) return { kind: 'splat', value: SPLAT }
-    if (part.startsWith(PARAM)) return { kind: 'param', value: part.slice(PARAM.length) }
-    return { kind: 'static', value: part }
-  })
-
-/**
- * Flatten a route tree into ranked-matchable branches. Every leaf and every node
- * carrying an index child produces a branch.
- */
-export const flattenRoutes = (
-  routes: RouteObject[],
-  parentChain: RouteObject[] = [],
-  parentSegments: PatternSegment[] = []
-): RouteBranch[] => {
-  const branches: RouteBranch[] = []
-
-  for (const route of routes) {
-    const chain = [...parentChain, route]
-
-    if (route.index === true) {
-      // An index route contributes an empty terminal at the parent's path.
-      branches.push({ chain, segments: parentSegments, index: true, score: 0 })
-      continue
-    }
+  const scoreBranch = (branch: RouteBranch): number => {
+    let score = branch.segments.reduce((acc, seg) => {
+      if (seg.kind === 'static') return acc + STATIC_WEIGHT
+      if (seg.kind === 'param') return acc + PARAM_WEIGHT
+      return acc + EMPTY_WEIGHT
+    }, 0)
+    if (branch.segments.length === 0) score += EMPTY_WEIGHT
+    if (branch.index) score += INDEX_WEIGHT
+    return score
+  }
 
-    const segments = [...parentSegments, ...segmentsOf(route.path)]
-    const children = route.children ?? []
+  const rankRouteBranches = (branches: RouteBranch[]): RouteBranch[] =>
+    branches
+      .map(branch => ({ ...branch, score: scoreBranch(branch) }))
+      .map((branch, index) => ({ branch, index }))
+      .sort((a, b) => (b.branch.score - a.branch.score) || (a.index - b.index))
+      .map(({ branch }) => branch)
 
-    if (children.length === 0) {
-      branches.push({ chain, segments, index: false, score: 0 })
-    } else {
-      branches.push(...flattenRoutes(children, chain, segments))
+  const matchBranch = (branch: RouteBranch, parts: string[]): RouteParams | null => {
+    if (branch.segments.some(seg => seg.kind === 'splat')) {
+      throw new Error('router matcher: splat (*) segments are not implemented yet')
     }
+    // Exact-length match (no splats/optionals in the supported subset).
+    if (branch.segments.length !== parts.length) return null
+
+    const params: RouteParams = {}
+    for (let i = 0; i < branch.segments.length; i++) {
+      const seg = branch.segments[i]
+      const part = parts[i]
+      if (seg.kind === 'static') {
+        if (seg.value.toLowerCase() !== part.toLowerCase()) return null
+      } else {
+        params[seg.value] = decodeURIComponent(part)
+      }
+    }
+    return params
   }
 
-  return branches
-}
+  const matchRoutes = (branches: RouteBranch[], pathname: string): RouteMatch[] | null => {
+    const parts = splitPath(pathname)
+    const ranked = rankRouteBranches(branches)
 
-const scoreBranch = (branch: RouteBranch): number => {
-  let score = branch.segments.reduce((acc, seg) => {
-    if (seg.kind === 'static') return acc + STATIC_WEIGHT
-    if (seg.kind === 'param') return acc + PARAM_WEIGHT
-    return acc + EMPTY_WEIGHT
-  }, 0)
-  if (branch.segments.length === 0) score += EMPTY_WEIGHT
-  if (branch.index) score += INDEX_WEIGHT
-  return score
-}
+    for (const branch of ranked) {
+      const params = matchBranch(branch, parts)
+      if (params == null) continue
 
-/** Rank branches so the most specific match is tried first. Stable within equal score. */
-export const rankRouteBranches = (branches: RouteBranch[]): RouteBranch[] =>
-  branches
-    .map(branch => ({ ...branch, score: scoreBranch(branch) }))
-    .map((branch, index) => ({ branch, index }))
-    .sort((a, b) => (b.branch.score - a.branch.score) || (a.index - b.index))
-    .map(({ branch }) => branch)
-
-const matchBranch = (branch: RouteBranch, parts: string[]): RouteParams | null => {
-  if (branch.segments.some(seg => seg.kind === 'splat')) {
-    throw new Error('router matcher: splat (*) segments are not implemented yet')
-  }
-  // Exact-length match (no splats/optionals in the supported subset).
-  if (branch.segments.length !== parts.length) return null
-
-  const params: RouteParams = {}
-  for (let i = 0; i < branch.segments.length; i++) {
-    const seg = branch.segments[i]
-    const part = parts[i]
-    if (seg.kind === 'static') {
-      if (seg.value.toLowerCase() !== part.toLowerCase()) return null
-    } else {
-      params[seg.value] = decodeURIComponent(part)
+      return branch.chain.map(route => ({
+        route,
+        params,
+        pathname: SEP + parts.join(SEP)
+      }))
     }
-  }
-  return params
-}
 
-/**
- * Match a pathname against ranked branches. Returns the winning branch as a
- * root→leaf chain of `RouteMatch` (params merged across the whole chain so every
- * depth sees the full leaf param set, matching react-router's `useParams`).
- */
-export const matchRoutes = (branches: RouteBranch[], pathname: string): RouteMatch[] | null => {
-  const parts = splitPath(pathname)
-  const ranked = rankRouteBranches(branches)
-
-  for (const branch of ranked) {
-    const params = matchBranch(branch, parts)
-    if (params == null) continue
-
-    return branch.chain.map(route => ({
-      route,
-      params,
-      pathname: SEP + parts.join(SEP)
-    }))
+    return null
   }
 
-  return null
+  return { splitPath, segmentsOf, flattenRoutes, rankRouteBranches, matchRoutes }
 }
+
+export const routeMatcherHelper = createRouteMatcherHelper()

package/src/types.local.ts

@@ -0,0 +1 @@
+export type SegmentKind = 'static' | 'param' | 'splat'

package/src/types.ts

@@ -1,5 +1,6 @@
 import type { LazyService, BasicContext } from "@owlmeans/context"
 import type { ComponentType } from 'react'
+import type { SegmentKind } from './types.local.js'
 export type { ComponentType }
 
 export type LibraryRouter = unknown
@@ -117,3 +118,24 @@ export interface SetSearchParams {
 export interface UseSearchParamsHook {
   (init?: URLSearchParams | Record<string, string>): [URLSearchParams, SetSearchParams]
 }
+
+export interface PatternSegment {
+  kind: SegmentKind
+  /** literal value for static, param name for param */
+  value: string
+}
+
+export interface RouteBranch {
+  /** root → node chain; drives outlet depth in the renderer */
+  chain: RouteObject[]
+  segments: PatternSegment[]
+  /** true when the terminal node is an index route */
+  index: boolean
+  score: number
+}
+
+export interface RouteMatch {
+  route: RouteObject
+  params: RouteParams
+  pathname: string
+}