@owlmeans/router 0.1.10 → 0.1.14

package/agent-meta/instructions/router.instructions.md

@@ -1,30 +1,40 @@
 ---
-description: "How to use @owlmeans/router — abstract router service interface used by web-router and native router implementations. Use when implementing a custom router."
+description: "How to use @owlmeans/router — the UI routing plugin host: RouterService registry, cascade selection, neutral route IR, and pure matcher. Use when registering a routing plugin, using the router service, or reusing the matcher."
 applyTo: "**/*.ts, **/*.tsx"
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
 
 # @owlmeans/router
 
-**Layer:** Core
-**Install:** `"@owlmeans/router": "^0.1.10"` in `dependencies`
+**Layer:** Core (L1)
+**Install:** `"@owlmeans/router": "^0.1.14"` in `dependencies`
+
+The plugin **host** for OwlMeans UI routing. Defines the contract, holds a registry of routing
+plugins, and selects the active one by cascade. Concrete mechanics are plugins:
+`@owlmeans/web-router` (default OwlMeans browser router) and `@owlmeans/web-router-react-router`
+(opt-in react-router v7).
 
 ## Key Exports
 
 | Export | Description |
 |--------|-------------|
-| `RouterService` types | Abstract router service interface |
-| Constants | `DEFAULT_ALIAS` for the router service |
-| Service helpers | Build a router service skeleton |
+| `RouterService` | Facade + registry; `outlet/provider/useParams/useLocation/useNavigate/useSearchParams/compile` delegate to the active plugin. |
+| `RouterPlugin`, `RouterEnv`, `RouteObject` | Plugin contract, selection env (`{hasWindow,ssr,request?}`), neutral route IR (`{index?,path?,children?,Component?}`). |
+| `makeRouterService`, `ensureRouterService(ctx)` | Build / idempotently get the host. |
+| `flattenRoutes`, `rankRouteBranches`, `matchRoutes` | Pure DOM-free matcher (static/`:param`/nested/index). |
+| `defaultRouterEnv()`, `ROUTER_SERVICE`, `DEFAULT_ROUTER_PRIORITY`, `ROUTER_PLUGIN` | Env + constants. |
+
+## Cascade
 
-## Usage
+Plugins sorted by `priority` desc; `service.plugin(env?)` returns the first whose `match(env)` is
+truthy (undefined ⇒ always). Browser plugin = priority 0, `match: () => true`; a higher-priority
+SSR plugin can win when `env.ssr`. Facade methods stay writable (native monkey-patches them).
 
 ```typescript
-import { DEFAULT_ALIAS as ROUTER } from '@owlmeans/router'
-const router = ctx.service(ROUTER)
-router.navigate('/projects')
+import { ROUTER_SERVICE } from '@owlmeans/router'
+ctx.service(ROUTER_SERVICE).useParams()   // delegates to the active plugin
 ```
 
 ## Depends On
 
-- `@owlmeans/context`, `@owlmeans/route`
+- `@owlmeans/context`; peer `react` (types only — no react-router, no DOM here)

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "package": "@owlmeans/router",
-  "version": "0.1.10",
-  "generatedAt": "2026-06-17T09:37:28.183Z",
+  "version": "0.1.14",
+  "generatedAt": "2026-08-05T16:56:53.383Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

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

@@ -1,34 +1,59 @@
 ---
 name: router
-description: How to use @owlmeans/router — abstract router service interface used by web-router and native router implementations. Auto-invoked when importing router service types or implementing a custom router.
+description: How to use @owlmeans/router — the UI routing plugin HOST (RouterService registry + cascade selection + neutral route IR + pure matcher). Auto-invoked when importing router service types, the matcher, or implementing/registering a routing plugin.
 user-invocable: false
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
 
 # @owlmeans/router
 
-**Layer:** Core
-**Install:** `"@owlmeans/router": "^0.1.10"` in `dependencies`
+**Layer:** Core (L1)
+**Install:** `"@owlmeans/router": "^0.1.14"` 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
+active one by cascade. Concrete mechanics ship as plugins: `@owlmeans/web-router` (the default
+OwlMeans in-browser router) and `@owlmeans/web-router-react-router` (opt-in react-router v7).
 
 ## Key Exports
 
 | Export | Description |
 |--------|-------------|
-| `RouterService` types | Abstract router service interface |
-| Constants | `DEFAULT_ALIAS` for the router service |
-| Service helpers | Build a router service skeleton |
-
-## Usage
-
-Concrete routers (e.g. `@owlmeans/web-router` for React Router 7) implement this interface. Apps don't usually import from `@owlmeans/router` directly — the layer-specific package wires everything up.
+| `RouterService` | Facade + plugin registry. `outlet/provider/useParams/useLocation/useNavigate/useSearchParams/compile` all delegate to the active plugin. |
+| `RouterPlugin` | The interface a routing mechanic implements. |
+| `RouterEnv` | `{ hasWindow, ssr, request? }` — drives cascade selection (SSR pre-design seam). |
+| `RouteObject` | Neutral route IR: `{ index?, path?, children?, Component? }` — shape-compatible with react-router. |
+| `makeRouterService(alias?)` | Build an empty host. |
+| `ensureRouterService(ctx)` | Idempotently get/create the host on a context (plugin packages call this before `registerPlugin`). |
+| `flattenRoutes` / `rankRouteBranches` / `matchRoutes` | Pure, DOM-free matcher (static / `:param` / nested / index). |
+| `defaultRouterEnv()` | Default environment (`window`-based); override per-request for SSR. |
+| Constants | `ROUTER_SERVICE` (`'router-service'`), `DEFAULT_ROUTER_PRIORITY`, `ROUTER_PLUGIN`. |
+
+## Cascade selection
+
+Plugins are kept sorted by `priority` (desc, stable). `service.plugin(env?)` returns the first
+plugin whose `match(env, ctx)` is truthy (`match` undefined ⇒ always applies). The browser plugin
+registers at priority 0 with `match: () => true` (universal fallback); a higher-priority SSR plugin
+can later win when `env.ssr` is true. Every facade call re-selects, so plugins can be added at any
+time (e.g. `appendReactRouter(ctx)` outranks the default).
 
 ```typescript
-import { DEFAULT_ALIAS as ROUTER } from '@owlmeans/router'
-const router = ctx.service(ROUTER)
-router.navigate('/projects')
+import { ROUTER_SERVICE } from '@owlmeans/router'
+const params = ctx.service(ROUTER_SERVICE).useParams()   // delegates to the active plugin
 ```
 
+## Native-safety invariant
+
+The facade methods are **plain writable instance properties**, never getters — the native router
+(`@owlmeans/native-router`) monkey-patches `service.outlet = …` directly. When extending the host,
+keep them assignable.
+
 ## Depends On
 
 - `@owlmeans/context` — service registration
-- `@owlmeans/route` — route shape
+- peer `react` — component/hook types only (no react-router, no DOM here)
+
+## Related
+
+- [[web-router]] (default OwlMeans browser plugin) · [[router-plugins]] (authoring plugins)
+- `@owlmeans/web-router-react-router` (react-router plugin)

package/build/consts.d.ts

@@ -1,3 +1,7 @@
 export declare const DEFAULT_ALIAS = "router-service";
 export declare const ROUTER_SERVICE = "router-service";
+/** Default plugin priority; higher-priority plugins win the cascade. */
+export declare const DEFAULT_ROUTER_PRIORITY = 0;
+/** Config-record id for declaring a preferred router plugin via `clientPlugin`. */
+export declare const ROUTER_PLUGIN = "router-plugin";
 //# sourceMappingURL=consts.d.ts.map

package/build/consts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,aAAa,mBAAmB,CAAA;AAE7C,eAAO,MAAM,cAAc,mBAAgB,CAAA"}
+{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,aAAa,mBAAmB,CAAA;AAE7C,eAAO,MAAM,cAAc,mBAAgB,CAAA;AAE3C,wEAAwE;AACxE,eAAO,MAAM,uBAAuB,IAAI,CAAA;AAExC,mFAAmF;AACnF,eAAO,MAAM,aAAa,kBAAkB,CAAA"}

package/build/consts.js

@@ -1,3 +1,7 @@
 export const DEFAULT_ALIAS = 'router-service';
 export const ROUTER_SERVICE = DEFAULT_ALIAS;
+/** Default plugin priority; higher-priority plugins win the cascade. */
+export const DEFAULT_ROUTER_PRIORITY = 0;
+/** Config-record id for declaring a preferred router plugin via `clientPlugin`. */
+export const ROUTER_PLUGIN = 'router-plugin';
 //# sourceMappingURL=consts.js.map

package/build/consts.js.map

@@ -1 +1 @@
-{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA,MAAM,CAAC,MAAM,aAAa,GAAG,gBAAgB,CAAA;AAE7C,MAAM,CAAC,MAAM,cAAc,GAAG,aAAa,CAAA"}
+{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA,MAAM,CAAC,MAAM,aAAa,GAAG,gBAAgB,CAAA;AAE7C,MAAM,CAAC,MAAM,cAAc,GAAG,aAAa,CAAA;AAE3C,wEAAwE;AACxE,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAA;AAExC,mFAAmF;AACnF,MAAM,CAAC,MAAM,aAAa,GAAG,eAAe,CAAA"}

package/build/env.d.ts

@@ -0,0 +1,12 @@
+import type { RouterEnv } from './types.js';
+/**
+ * Default routing environment. In the browser `hasWindow` is true and `ssr` is
+ * false, so the browser plugin (which matches always) is selected. An SSR host
+ * will later provide a per-request env (with `ssr: true` and a `request`) so an
+ * SSR plugin registered at a higher priority wins.
+ *
+ * This is the single source of environment truth for cascade selection — do not
+ * bake `typeof window` checks into a plugin's `match`.
+ */
+export declare const defaultRouterEnv: () => RouterEnv;
+//# sourceMappingURL=env.d.ts.map

package/build/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAE3C;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,QAAO,SAGnC,CAAA"}

package/build/env.js

@@ -0,0 +1,14 @@
+/**
+ * Default routing environment. In the browser `hasWindow` is true and `ssr` is
+ * false, so the browser plugin (which matches always) is selected. An SSR host
+ * will later provide a per-request env (with `ssr: true` and a `request`) so an
+ * SSR plugin registered at a higher priority wins.
+ *
+ * This is the single source of environment truth for cascade selection — do not
+ * bake `typeof window` checks into a plugin's `match`.
+ */
+export const defaultRouterEnv = () => {
+    const hasWindow = typeof window !== 'undefined';
+    return { hasWindow, ssr: !hasWindow };
+};
+//# sourceMappingURL=env.js.map

package/build/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAc,EAAE;IAC9C,MAAM,SAAS,GAAG,OAAO,MAAM,KAAK,WAAW,CAAA;IAC/C,OAAO,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,SAAS,EAAE,CAAA;AACvC,CAAC,CAAA"}

package/build/index.d.ts

@@ -1,4 +1,6 @@
 export type * from './types.js';
 export * from './consts.js';
 export * from './service.js';
+export * from './matcher.js';
+export * from './env.js';
 //# sourceMappingURL=index.d.ts.map

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"}
+{"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"}

package/build/index.js

@@ -1,3 +1,5 @@
 export * from './consts.js';
 export * from './service.js';
+export * from './matcher.js';
+export * from './env.js';
 //# sourceMappingURL=index.js.map

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"}
+{"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"}

package/build/matcher.d.ts

@@ -0,0 +1,37 @@
+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 {};
+//# sourceMappingURL=matcher.d.ts.map

package/build/matcher.d.ts.map

@@ -0,0 +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,GAAI,OAAO,MAAM,KAAG,MAAM,EACS,CAAA;AAEzD,eAAO,MAAM,UAAU,GAAI,OAAO,MAAM,KAAG,cAAc,EAKrD,CAAA;AAEJ;;;GAGG;AACH,eAAO,MAAM,aAAa,GACxB,QAAQ,WAAW,EAAE,EACrB,cAAa,WAAW,EAAO,EAC/B,iBAAgB,cAAc,EAAO,KACpC,WAAW,EAuBb,CAAA;AAaD,0FAA0F;AAC1F,eAAO,MAAM,iBAAiB,GAAI,UAAU,WAAW,EAAE,KAAG,WAAW,EAKvC,CAAA;AAsBhC;;;;GAIG;AACH,eAAO,MAAM,WAAW,GAAI,UAAU,WAAW,EAAE,EAAE,UAAU,MAAM,KAAG,UAAU,EAAE,GAAG,IAgBtF,CAAA"}

package/build/matcher.js

@@ -0,0 +1,111 @@
+/**
+ * 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;
+        }
+        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));
+        }
+    }
+    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;
+        }
+        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;
+};
+//# sourceMappingURL=matcher.js.map

package/build/matcher.js.map

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

package/build/service.d.ts

@@ -1,3 +1,18 @@
-import type { RouterService } from "./types";
+import type { BasicContext } from "@owlmeans/context";
+import type { RouterService } from "./types.js";
+/**
+ * Router service = plugin host. It holds a registry of routing plugins and, on
+ * every facade call, resolves the active plugin by cascade (priority desc, first
+ * whose `match(env)` is truthy) and delegates to it.
+ *
+ * The facade methods stay ordinary writable properties (never getters) so that
+ * non-plugin implementations — e.g. the native router — can keep overriding them
+ * directly, exactly as `web-router` did before the plugin model.
+ */
 export declare const makeRouterService: (alias?: string) => RouterService;
+/**
+ * Idempotently obtain the router service on a context, registering an empty host
+ * if none exists yet. Plugin packages call this before `registerPlugin`.
+ */
+export declare const ensureRouterService: (ctx: BasicContext<any>) => RouterService;
 //# sourceMappingURL=service.d.ts.map

package/build/service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAE5C,eAAO,MAAM,iBAAiB,GAAI,QAAO,MAAsB,KAAG,aAwBjE,CAAA"}
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAGrD,OAAO,KAAK,EACV,aAAa,EACd,MAAM,YAAY,CAAA;AAEnB;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,GAAI,QAAO,MAAsB,KAAG,aAwCjE,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,mBAAmB,GAAI,KAAK,YAAY,CAAC,GAAG,CAAC,KAAG,aAO5D,CAAA"}

package/build/service.js

@@ -1,23 +1,55 @@
 import { createService } from "@owlmeans/context";
 import { DEFAULT_ALIAS } from "./consts.js";
+import { defaultRouterEnv } from "./env.js";
+/**
+ * Router service = plugin host. It holds a registry of routing plugins and, on
+ * every facade call, resolves the active plugin by cascade (priority desc, first
+ * whose `match(env)` is truthy) and delegates to it.
+ *
+ * The facade methods stay ordinary writable properties (never getters) so that
+ * non-plugin implementations — e.g. the native router — can keep overriding them
+ * directly, exactly as `web-router` did before the plugin model.
+ */
 export const makeRouterService = (alias = DEFAULT_ALIAS) => {
+    const plugins = [];
     const service = createService(alias, {
-        outlet: () => {
-            throw new Error('Router Outlet is not implemented');
+        registerPlugin: plugin => {
+            const existing = plugins.findIndex(candidate => candidate.alias === plugin.alias);
+            if (existing >= 0) {
+                plugins.splice(existing, 1);
+            }
+            plugins.push(plugin);
+            plugins.sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
         },
-        provider: () => {
-            throw new Error('Router Provider is not implemented');
+        plugin: env => {
+            const environment = env ?? defaultRouterEnv();
+            const ctx = service.ctx;
+            const plugin = plugins.find(candidate => candidate.match?.(environment, ctx) ?? true);
+            if (plugin == null) {
+                throw new Error('router: no plugin matches the current environment');
+            }
+            return plugin;
         },
-        useParams: () => {
-            throw new Error('Router useParams is not implemented');
-        },
-        useLocation: () => {
-            throw new Error('Router useLocation is not implemented');
-        },
-        useNavigate: () => {
-            throw new Error('Router useNavigate is not implemented');
-        }
+        outlet: () => service.plugin().outlet(),
+        provider: () => service.plugin().provider(),
+        useParams: (() => service.plugin().useParams()),
+        useLocation: () => service.plugin().useLocation(),
+        useNavigate: () => service.plugin().useNavigate(),
+        useSearchParams: ((init) => service.plugin().useSearchParams(init)),
+        compile: routes => service.plugin().compile(routes, service.ctx)
     });
     return service;
 };
+/**
+ * Idempotently obtain the router service on a context, registering an empty host
+ * if none exists yet. Plugin packages call this before `registerPlugin`.
+ */
+export const ensureRouterService = (ctx) => {
+    if (ctx.hasService(DEFAULT_ALIAS)) {
+        return ctx.service(DEFAULT_ALIAS);
+    }
+    const service = makeRouterService();
+    ctx.registerService(service);
+    return service;
+};
 //# sourceMappingURL=service.js.map

package/build/service.js.map

@@ -1 +1 @@
-{"version":3,"file":"service.js","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAG3C,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,QAAgB,aAAa,EAAiB,EAAE;IAChF,MAAM,OAAO,GAAG,aAAa,CAAgB,KAAK,EAAE;QAClD,MAAM,EAAE,GAAG,EAAE;YACX,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAA;QACrD,CAAC;QAED,QAAQ,EAAE,GAAG,EAAE;YACb,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAA;QACvD,CAAC;QAED,SAAS,EAAE,GAAG,EAAE;YACd,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAA;QACxD,CAAC;QAED,WAAW,EAAE,GAAG,EAAE;YAChB,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAA;QAC1D,CAAC;QAED,WAAW,EAAE,GAAG,EAAE;YAChB,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAA;QAC1D,CAAC;KACF,CAAC,CAAA;IAEF,OAAO,OAAO,CAAA;AAChB,CAAC,CAAA"}
+{"version":3,"file":"service.js","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAEjD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAA;AAK3C;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,QAAgB,aAAa,EAAiB,EAAE;IAChF,MAAM,OAAO,GAAmB,EAAE,CAAA;IAElC,MAAM,OAAO,GAAkB,aAAa,CAAgB,KAAK,EAAE;QACjE,cAAc,EAAE,MAAM,CAAC,EAAE;YACvB,MAAM,QAAQ,GAAG,OAAO,CAAC,SAAS,CAAC,SAAS,CAAC,EAAE,CAAC,SAAS,CAAC,KAAK,KAAK,MAAM,CAAC,KAAK,CAAC,CAAA;YACjF,IAAI,QAAQ,IAAI,CAAC,EAAE,CAAC;gBAClB,OAAO,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAA;YAC7B,CAAC;YACD,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;YACpB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,CAAC,CAAA;QAC/D,CAAC;QAED,MAAM,EAAE,GAAG,CAAC,EAAE;YACZ,MAAM,WAAW,GAAG,GAAG,IAAI,gBAAgB,EAAE,CAAA;YAC7C,MAAM,GAAG,GAAG,OAAO,CAAC,GAAoC,CAAA;YACxD,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC,WAAW,EAAE,GAAG,CAAC,IAAI,IAAI,CAAC,CAAA;YACrF,IAAI,MAAM,IAAI,IAAI,EAAE,CAAC;gBACnB,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAA;YACtE,CAAC;YACD,OAAO,MAAM,CAAA;QACf,CAAC;QAED,MAAM,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE;QAEvC,QAAQ,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QAE3C,SAAS,EAAE,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,SAAS,EAAE,CAAkB;QAEhE,WAAW,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,WAAW,EAAE;QAEjD,WAAW,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,WAAW,EAAE;QAEjD,eAAe,EAAE,CAAC,CAAC,IAA+C,EAAE,EAAE,CACpE,OAAO,CAAC,MAAM,EAAE,CAAC,eAAe,CAAC,IAAI,CAAC,CAAwB;QAEhE,OAAO,EAAE,MAAM,CAAC,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,GAAoC,CAAC;KAClG,CAAC,CAAA;IAEF,OAAO,OAAO,CAAA;AAChB,CAAC,CAAA;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,GAAsB,EAAiB,EAAE;IAC3E,IAAI,GAAG,CAAC,UAAU,CAAC,aAAa,CAAC,EAAE,CAAC;QAClC,OAAO,GAAG,CAAC,OAAO,CAAgB,aAAa,CAAC,CAAA;IAClD,CAAC;IACD,MAAM,OAAO,GAAG,iBAAiB,EAAE,CAAA;IACnC,GAAG,CAAC,eAAe,CAAC,OAAO,CAAC,CAAA;IAC5B,OAAO,OAAO,CAAA;AAChB,CAAC,CAAA"}

package/build/types.d.ts

@@ -1,14 +1,61 @@
-import type { InitializedService } from "@owlmeans/context";
-export type { ComponentType } from 'react';
+import type { InitializedService, BasicContext } from "@owlmeans/context";
+import type { ComponentType } from 'react';
+export type { ComponentType };
 export type LibraryRouter = unknown;
-export type RouteObject = unknown;
-export type RouterProvider = React.ComponentType<any>;
+/**
+ * Neutral route intermediate representation. Shape-compatible with react-router's
+ * `RouteObject` so that `createBrowserRouter` accepts it directly AND the OwlMeans
+ * matcher can consume the very same objects.
+ */
+export interface RouteObject {
+    index?: boolean;
+    path?: string;
+    children?: RouteObject[];
+    Component?: ComponentType;
+}
+export type RouterProvider = ComponentType<any>;
+/**
+ * Environment descriptor used by the cascade to select a routing plugin.
+ * Pre-designed for SSR: an SSR plugin selects on `ssr`/`request`; the browser
+ * plugin is the universal fallback in the browser.
+ */
+export interface RouterEnv {
+    hasWindow: boolean;
+    ssr: boolean;
+    request?: unknown;
+}
+/**
+ * A pluggable routing mechanic. Multiple plugins may be registered on a single
+ * router service; the active one is chosen by cascade (priority + `match`).
+ */
+export interface RouterPlugin {
+    alias: string;
+    /** Higher wins among matching plugins. Defaults to 0. */
+    priority?: number;
+    /** Free-form tag, e.g. 'browser' | 'ssr' | 'memory'. */
+    mode?: string;
+    /** Selector; `undefined` means "always applicable". */
+    match?: (env: RouterEnv, ctx?: BasicContext<any>) => boolean;
+    /** Compile the neutral route IR into a plugin-specific library router. */
+    compile: (routes: RouteObject[], ctx?: BasicContext<any>) => LibraryRouter | Promise<LibraryRouter>;
+    provider: () => RouterProvider;
+    outlet: () => ComponentType;
+    useParams: UseParamsHook;
+    useLocation: UseLocationHook;
+    useNavigate: UseNavigateHook;
+    useSearchParams: UseSearchParamsHook;
+}
 export interface RouterService extends InitializedService {
-    outlet: () => React.ComponentType;
+    registerPlugin: (plugin: RouterPlugin) => void;
+    /** Select the active plugin for the given (or default) environment. */
+    plugin: (env?: RouterEnv) => RouterPlugin;
+    outlet: () => ComponentType;
     provider: () => RouterProvider;
     useParams: UseParamsHook;
     useLocation: UseLocationHook;
     useNavigate: UseNavigateHook;
+    useSearchParams: UseSearchParamsHook;
+    compile: (routes: RouteObject[]) => LibraryRouter | Promise<LibraryRouter>;
 }
 export type RouteParams = Record<string, string | undefined>;
 export interface UseParamsHook {
@@ -26,7 +73,7 @@ export interface Location<State = any> extends Path {
 export interface UseLocationHook {
     (): Location;
 }
-interface NavigateOptions {
+export interface NavigateOptions {
     replace?: boolean;
     state?: any;
     preventScrollReset?: boolean;
@@ -41,4 +88,13 @@ export interface NavigateFunction {
 export interface UseNavigateHook {
     (): NavigateFunction;
 }
+export interface SetSearchParams {
+    (next: URLSearchParams | Record<string, string> | ((prev: URLSearchParams) => URLSearchParams), options?: {
+        replace?: boolean;
+        state?: any;
+    }): void;
+}
+export interface UseSearchParamsHook {
+    (init?: URLSearchParams | Record<string, string>): [URLSearchParams, SetSearchParams];
+}
 //# 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":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AAC3D,YAAY,EAAE,aAAa,EAAE,MAAM,OAAO,CAAA;AAE1C,MAAM,MAAM,aAAa,GAAG,OAAO,CAAA;AAEnC,MAAM,MAAM,WAAW,GAAG,OAAO,CAAA;AAEjC,MAAM,MAAM,cAAc,GAAG,KAAK,CAAC,aAAa,CAAC,GAAG,CAAC,CAAA;AAErD,MAAM,WAAW,aAAc,SAAQ,kBAAkB;IACvD,MAAM,EAAE,MAAM,KAAK,CAAC,aAAa,CAAA;IACjC,QAAQ,EAAE,MAAM,cAAc,CAAA;IAC9B,SAAS,EAAE,aAAa,CAAA;IACxB,WAAW,EAAE,eAAe,CAAA;IAC5B,WAAW,EAAE,eAAe,CAAA;CAC7B;AAED,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;AAE5D,MAAM,WAAW,aAAa;IAC5B,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,KAAK,CAAC,CAAA;CAC3C;AAED,MAAM,WAAW,IAAI;IACnB,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,QAAQ,CAAC,KAAK,GAAG,GAAG,CAAE,SAAQ,IAAI;IACjD,KAAK,EAAE,KAAK,CAAA;IAEZ,GAAG,EAAE,MAAM,CAAA;CACZ;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,QAAQ,CAAA;CACb;AAED,UAAU,eAAe;IACvB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,KAAK,CAAC,EAAE,GAAG,CAAA;IACX,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAC5B,QAAQ,CAAC,EAAE,OAAO,GAAG,MAAM,CAAA;IAC3B,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,cAAc,CAAC,EAAE,OAAO,CAAA;CACzB;AAED,MAAM,WAAW,gBAAgB;IAC/B,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC7E,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACtC;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,gBAAgB,CAAA;CACrB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/router",
-  "version": "0.1.10",
+  "version": "0.1.14",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -21,17 +21,17 @@
     }
   },
   "dependencies": {
-    "@owlmeans/context": "^0.1.10"
+    "@owlmeans/context": "^0.1.14"
   },
   "peerDependencies": {
     "react": "*"
   },
   "devDependencies": {
     "@owlmeans/dep-config": "workspace:*",
-    "@types/node": "^24.10.1",
-    "@types/react": "^19.2.7",
-    "nodemon": "^3.1.11",
-    "typescript": "^6.0.2"
+    "@types/node": "^26.1.0",
+    "@types/react": "^19.2.17",
+    "nodemon": "^3.1.14",
+    "typescript": "^6.0.3"
   },
   "publishConfig": {
     "access": "public"

package/src/consts.ts

@@ -1,4 +1,10 @@
 
 export const DEFAULT_ALIAS = 'router-service'
 
-export const ROUTER_SERVICE = DEFAULT_ALIAS
+export const ROUTER_SERVICE = DEFAULT_ALIAS
+
+/** Default plugin priority; higher-priority plugins win the cascade. */
+export const DEFAULT_ROUTER_PRIORITY = 0
+
+/** Config-record id for declaring a preferred router plugin via `clientPlugin`. */
+export const ROUTER_PLUGIN = 'router-plugin'

package/src/env.ts

@@ -0,0 +1,15 @@
+import type { RouterEnv } from './types.js'
+
+/**
+ * Default routing environment. In the browser `hasWindow` is true and `ssr` is
+ * false, so the browser plugin (which matches always) is selected. An SSR host
+ * will later provide a per-request env (with `ssr: true` and a `request`) so an
+ * SSR plugin registered at a higher priority wins.
+ *
+ * This is the single source of environment truth for cascade selection — do not
+ * bake `typeof window` checks into a plugin's `match`.
+ */
+export const defaultRouterEnv = (): RouterEnv => {
+  const hasWindow = typeof window !== 'undefined'
+  return { hasWindow, ssr: !hasWindow }
+}

package/src/index.ts

@@ -2,3 +2,5 @@
 export type * from './types.js'
 export * from './consts.js'
 export * from './service.js'
+export * from './matcher.js'
+export * from './env.js'

package/src/matcher.ts

@@ -0,0 +1,149 @@
+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
+}
+
+export interface RouteMatch {
+  route: RouteObject
+  params: RouteParams
+  pathname: string
+}
+
+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 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))
+    }
+  }
+
+  return 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
+}
+
+/** 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 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
+}

package/src/service.ts

@@ -1,29 +1,71 @@
 import { createService } from "@owlmeans/context"
+import type { BasicContext } from "@owlmeans/context"
 import { DEFAULT_ALIAS } from "./consts.js"
-import type { RouterService } from "./types"
+import { defaultRouterEnv } from "./env.js"
+import type {
+  RouterService, RouterPlugin, UseParamsHook, UseSearchParamsHook
+} from "./types.js"
 
+/**
+ * Router service = plugin host. It holds a registry of routing plugins and, on
+ * every facade call, resolves the active plugin by cascade (priority desc, first
+ * whose `match(env)` is truthy) and delegates to it.
+ *
+ * The facade methods stay ordinary writable properties (never getters) so that
+ * non-plugin implementations — e.g. the native router — can keep overriding them
+ * directly, exactly as `web-router` did before the plugin model.
+ */
 export const makeRouterService = (alias: string = DEFAULT_ALIAS): RouterService => {
-  const service = createService<RouterService>(alias, {
-    outlet: () => {
-      throw new Error('Router Outlet is not implemented')
-    },
+  const plugins: RouterPlugin[] = []
 
-    provider: () => {
-      throw new Error('Router Provider is not implemented')
+  const service: RouterService = createService<RouterService>(alias, {
+    registerPlugin: plugin => {
+      const existing = plugins.findIndex(candidate => candidate.alias === plugin.alias)
+      if (existing >= 0) {
+        plugins.splice(existing, 1)
+      }
+      plugins.push(plugin)
+      plugins.sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0))
     },
 
-    useParams: () => {
-      throw new Error('Router useParams is not implemented')
+    plugin: env => {
+      const environment = env ?? defaultRouterEnv()
+      const ctx = service.ctx as BasicContext<any> | undefined
+      const plugin = plugins.find(candidate => candidate.match?.(environment, ctx) ?? true)
+      if (plugin == null) {
+        throw new Error('router: no plugin matches the current environment')
+      }
+      return plugin
     },
 
-    useLocation: () => {
-      throw new Error('Router useLocation is not implemented')
-    },
+    outlet: () => service.plugin().outlet(),
+
+    provider: () => service.plugin().provider(),
+
+    useParams: (() => service.plugin().useParams()) as UseParamsHook,
+
+    useLocation: () => service.plugin().useLocation(),
 
-    useNavigate: () => {
-      throw new Error('Router useNavigate is not implemented')
-    }
+    useNavigate: () => service.plugin().useNavigate(),
+
+    useSearchParams: ((init?: URLSearchParams | Record<string, string>) =>
+      service.plugin().useSearchParams(init)) as UseSearchParamsHook,
+
+    compile: routes => service.plugin().compile(routes, service.ctx as BasicContext<any> | undefined)
   })
 
   return service
-}
+}
+
+/**
+ * Idempotently obtain the router service on a context, registering an empty host
+ * if none exists yet. Plugin packages call this before `registerPlugin`.
+ */
+export const ensureRouterService = (ctx: BasicContext<any>): RouterService => {
+  if (ctx.hasService(DEFAULT_ALIAS)) {
+    return ctx.service<RouterService>(DEFAULT_ALIAS)
+  }
+  const service = makeRouterService()
+  ctx.registerService(service)
+  return service
+}

package/src/types.ts

@@ -1,18 +1,70 @@
-import type { InitializedService } from "@owlmeans/context"
-export type { ComponentType } from 'react'
+import type { InitializedService, BasicContext } from "@owlmeans/context"
+import type { ComponentType } from 'react'
+export type { ComponentType }
 
 export type LibraryRouter = unknown
 
-export type RouteObject = unknown
+/**
+ * Neutral route intermediate representation. Shape-compatible with react-router's
+ * `RouteObject` so that `createBrowserRouter` accepts it directly AND the OwlMeans
+ * matcher can consume the very same objects.
+ */
+export interface RouteObject {
+  index?: boolean
+  path?: string
+  children?: RouteObject[]
+  Component?: ComponentType
+}
+
+export type RouterProvider = ComponentType<any>
+
+/**
+ * Environment descriptor used by the cascade to select a routing plugin.
+ * Pre-designed for SSR: an SSR plugin selects on `ssr`/`request`; the browser
+ * plugin is the universal fallback in the browser.
+ */
+export interface RouterEnv {
+  hasWindow: boolean
+  ssr: boolean
+  request?: unknown
+}
 
-export type RouterProvider = React.ComponentType<any>
+/**
+ * A pluggable routing mechanic. Multiple plugins may be registered on a single
+ * router service; the active one is chosen by cascade (priority + `match`).
+ */
+export interface RouterPlugin {
+  alias: string
+  /** Higher wins among matching plugins. Defaults to 0. */
+  priority?: number
+  /** Free-form tag, e.g. 'browser' | 'ssr' | 'memory'. */
+  mode?: string
+  /** Selector; `undefined` means "always applicable". */
+  match?: (env: RouterEnv, ctx?: BasicContext<any>) => boolean
+  /** Compile the neutral route IR into a plugin-specific library router. */
+  compile: (routes: RouteObject[], ctx?: BasicContext<any>) => LibraryRouter | Promise<LibraryRouter>
+  provider: () => RouterProvider
+  outlet: () => ComponentType
+  useParams: UseParamsHook
+  useLocation: UseLocationHook
+  useNavigate: UseNavigateHook
+  useSearchParams: UseSearchParamsHook
+}
 
 export interface RouterService extends InitializedService {
-  outlet: () => React.ComponentType
+  registerPlugin: (plugin: RouterPlugin) => void
+  /** Select the active plugin for the given (or default) environment. */
+  plugin: (env?: RouterEnv) => RouterPlugin
+  // Facade — every method delegates to the active plugin.
+  // NOTE: these remain plain writable instance properties so that alternative
+  // implementations (e.g. the native router) can monkey-patch them directly.
+  outlet: () => ComponentType
   provider: () => RouterProvider
   useParams: UseParamsHook
   useLocation: UseLocationHook
   useNavigate: UseNavigateHook
+  useSearchParams: UseSearchParamsHook
+  compile: (routes: RouteObject[]) => LibraryRouter | Promise<LibraryRouter>
 }
 
 export type RouteParams = Record<string, string | undefined>
@@ -37,7 +89,7 @@ export interface UseLocationHook {
   (): Location
 }
 
-interface NavigateOptions {
+export interface NavigateOptions {
   replace?: boolean
   state?: any
   preventScrollReset?: boolean
@@ -53,4 +105,15 @@ export interface NavigateFunction {
 
 export interface UseNavigateHook {
   (): NavigateFunction
-}
+}
+
+export interface SetSearchParams {
+  (
+    next: URLSearchParams | Record<string, string> | ((prev: URLSearchParams) => URLSearchParams),
+    options?: { replace?: boolean; state?: any }
+  ): void
+}
+
+export interface UseSearchParamsHook {
+  (init?: URLSearchParams | Record<string, string>): [URLSearchParams, SetSearchParams]
+}

package/tsconfig.json

@@ -7,5 +7,5 @@
     "rootDir": "./src/",
     "outDir": "./build/"
   },
-  "exclude": ["./dist/**/*", "./build/**/*", "./*.ts"]
+  "exclude": ["./dist/**/*", "./build/**/*", "./tests/**/*", "./*.ts"]
 }