@owlmeans/web-router 0.1.18-rc.50 → 0.1.18-rc.51

package/README.md

@@ -1,46 +1,149 @@
 # @owlmeans/web-router
 
-The default OwlMeans in-browser routing plugin for the OwlMeans context system. It depends on no
-third-party router — react-router is a separate opt-in plugin,
-[`@owlmeans/web-router-react-router`](../web-router-react-router).
-
-## Overview
-
-- `makeWebRouterService()` — creates a router service backed by the OwlMeans browser router
-- `appendWebRouter(ctx)` — registers the web router service in the context
-- Provides `useParams`, `useLocation`, `useNavigate`, `outlet()`, `provider()` via the service
-- Used internally by `@owlmeans/web-client`'s `makeContext` — not typically used directly
+The default OwlMeans in-browser routing plugin: standard URL routing over the browser History API,
+a pure route matcher from `@owlmeans/router`, and a React provider, outlet and hooks — with no
+third-party router. It registers itself as a `RouterPlugin` on the `@owlmeans/router` host, and
+`@owlmeans/web-client` / `@owlmeans/web-panel` call `appendWebRouter` in their `makeContext`, so a
+web app gets it without importing anything. An app imports it directly only for a custom context
+setup or to reach the plugin's components and hooks outside the `context.router()` facade. To route
+with react-router instead, add `@owlmeans/web-router-react-router` (higher priority, wins the
+cascade); an SSR or React Native host is a plugin of its own.
 
 ## Installation
 
 ```bash
-bun add @owlmeans/web-router@^0.1.18-rc.50
+bun add @owlmeans/web-router@^0.1.18-rc.51
 ```
 
+`react` is a peer dependency.
+
+## Concepts
+
+- **Router host** — the `RouterService` of `@owlmeans/router`, registered once per context
+  (`ensureRouterService`). Its facade (`provider`, `outlet`, `compile`, `useParams`, `useLocation`,
+  `useNavigate`, `useSearchParams`) delegates to the active plugin.
+- **Browser plugin** — `makeBrowserRouterPlugin()`: alias `BROWSER_ROUTER`, priority 0, mode
+  `'browser'`, `match` always true — the universal browser fallback any higher-priority plugin
+  outranks.
+- **Compile** — `compile(routes)` flattens and ranks the neutral `RouteObject[]`
+  (`{ index?, path?, children?, Component? }`) into matchable branches; synchronous.
+- **Route chain** — `BrowserRouterProvider` re-matches on every history change and renders the chain
+  through `RouteChain`; each `<Outlet/>` renders the next-deeper match. A match without a
+  `Component` is a pass-through, as in react-router's implicit outlet.
+- **Route syntax** — static segments, `:param`, nested routes and index routes; a static segment
+  outranks a `:param` sibling. No splat or optional segments.
+
 ## Usage
 
-This package is registered automatically when using `makeContext` from `@owlmeans/web-client`. Direct use is only needed for custom context setup:
+### Default wiring
+
+Nothing to do with `@owlmeans/web-client` or `@owlmeans/web-panel`. A context assembled by hand
+registers the plugin itself:
 
 ```typescript
 import { appendWebRouter } from '@owlmeans/web-router'
 
-appendWebRouter(context)
+appendWebRouter(context)   // ensures the router host, then registers the browser plugin
 ```
 
-## API
+### Read the route in a component
+
+Inside an OwlMeans app, reach the hooks through the facade so the active plugin answers:
+
+```tsx
+import { useContext } from '@owlmeans/client'
+
+export const UserScreen = () => {
+  const context = useContext()
+  const { id } = context.router().useParams<{ id: string }>()
+  const [query] = context.router().useSearchParams()
+  const navigate = context.router().useNavigate()
+
+  return (
+    <button onClick={() => navigate(`/users/${id}/edit`, { state: { from: query.get('tab') } })}>
+      edit
+    </button>
+  )
+}
+```
 
-### `makeWebRouterService(): RouterService`
+`navigate(to, { replace?, state? })` takes a path string, a `{ pathname?, search?, hash? }`
+object, or a number for history steps; an absolute `http…` string is a full-page navigation.
+The setter returned by `useSearchParams` (`set(next, { replace?, state? })`) rewrites the search part
+of the current path.
 
-Creates a router service with the OwlMeans browser router hooks and components.
+### Use the plugin standalone
 
-### `appendWebRouter<C, T>(ctx): void`
+The same components and hooks are exported directly — what the package's own browser harness does:
 
-Registers the web router service in the given context.
+```tsx
+import { createRoot } from 'react-dom/client'
+import type { RouteObject } from '@owlmeans/router'
+import { makeBrowserRouterPlugin, Outlet, useParams } from '@owlmeans/web-router'
 
-## Related Packages
+const Layout = () => <main><Outlet /></main>
+const Home = () => <p>home</p>
+const User = () => <p>user {useParams().id}</p>
 
-- [`@owlmeans/router`](../router) — `RouterService` base interface
+const routes: RouteObject[] = [
+  { path: '', Component: Layout, children: [
+    { index: true, Component: Home },
+    { path: 'users', children: [{ path: ':id', Component: User }] },   // component-less group passes through
+  ] },
+]
+
+const plugin = makeBrowserRouterPlugin()
+const Provider = plugin.provider()
+createRoot(document.getElementById('root')!).render(<Provider router={plugin.compile(routes)} />)
+```
+
+### Switch to react-router
+
+```typescript
+import { appendReactRouter } from '@owlmeans/web-router-react-router'
+
+appendReactRouter(context)   // priority 100 outranks the browser plugin
+```
+
+## API
+
+| Symbol | Kind | Purpose |
+|---|---|---|
+| `appendWebRouter(ctx)` | function | `ensureRouterService(ctx)` + register the browser plugin; returns the context |
+| `makeWebRouterService()` | function | back-compat: a new router host pre-loaded with the browser plugin |
+| `makeBrowserRouterPlugin()` | function | the `RouterPlugin` itself |
+| `BROWSER_ROUTER` | const | `'owlmeans-browser-router'` — the plugin alias |
+| `BrowserRouterProvider` | component | `{ router: LibraryRouter }` — subscribes to history and renders the match chain |
+| `Outlet` | component | renders the next-deeper match |
+| `RouteChain` | component | `{ depth }` — renders the chain from a depth, skipping component-less matches |
+| `useParams`, `useLocation`, `useNavigate`, `useSearchParams` | hooks | the plugin's hooks; throw outside the provider |
+| `createBrowserHistory()` | function | `BrowserHistory` over `window.history` + `popstate`; an inert stub without `window` |
+| `OwlLibraryRouter` | type | `{ routes, branches }` — what `compile` returns |
+| `RouterState` | type | `{ location, matches, navigate }` — the provider's React context value |
+| `BrowserHistory` | type | `location`, `push`, `replace`, `go`, `listen` |
+
+## Common pitfalls
+
+- A hook used outside `BrowserRouterProvider` throws
+  `owlmeans-browser-router: router hook used outside of the router provider`.
+- Calling the plugin's hooks directly bypasses the cascade; in an app, use `context.router().…` so a
+  switched plugin keeps working.
+- Splat (`*`) and optional segments are not supported; declare explicit routes.
+- `makeWebRouterService()` builds a separate host; prefer `appendWebRouter`, which reuses the
+  context's host.
+- `noRouter` works on `<App>` only — `<PanelApp>` accepts the prop by type but still mounts the
+  router.
+
+## Related packages
+
+- [`@owlmeans/router`](../router) — the router host, `RouterPlugin` contract and pure matcher
+- [`@owlmeans/web-router-react-router`](../web-router-react-router) — opt-in react-router v7 plugin
+- [`@owlmeans/client`](../client) — builds `RouteObject[]` from the entrypoint tree and exposes `context.router()`
 - [`@owlmeans/web-client`](../web-client) — calls `appendWebRouter` inside `makeContext`
+- [`@owlmeans/web-panel`](../web-panel) — the panel layer, wired the same way
+
+The `web-router` skill describes this plugin; the `router-plugins` skill covers the plugin contract,
+cascade selection and authoring a new plugin.
 
 <!-- owlmeans:agent-guidance:start -->
 ## Agent guidance
@@ -50,7 +153,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.51
+npx @owlmeans/agent-skills@^0.1.18-rc.52
 ```
 
 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,
   "package": "@owlmeans/web-router",
-  "version": "0.1.18-rc.50",
-  "generatedAt": "2026-10-06T11:45:57.681Z",
+  "version": "0.1.18-rc.51",
+  "generatedAt": "2026-10-08T21:27:54.319Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

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

@@ -8,7 +8,7 @@ user-invocable: false
 # @owlmeans/web-router
 
 **Layer:** Web (React), build level L2
-**Install:** `"@owlmeans/web-router": "^0.1.18-rc.50"` in `dependencies`
+**Install:** `"@owlmeans/web-router": "^0.1.18-rc.51"` in `dependencies`
 
 This package **is the default OwlMeans in-browser router** — a minimal, react-router-free
 implementation of standard URL routing over the browser History API. It registers itself as a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/web-router",
-  "version": "0.1.18-rc.50",
+  "version": "0.1.18-rc.51",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -26,7 +26,7 @@
   },
   "devDependencies": {
     "@owlmeans/dep-config": "workspace:*",
-    "@owlmeans/test-ui": "^0.1.18-rc.50",
+    "@owlmeans/test-ui": "^0.1.18-rc.51",
     "@types/node": "^26.6.4",
     "@types/react": "^19.3.0",
     "@vitejs/plugin-react": "^6.1.1",
@@ -39,7 +39,7 @@
   },
   "dependencies": {
     "@owlmeans/context": "^0.1.18-rc.34",
-    "@owlmeans/router": "^0.1.18-rc.33"
+    "@owlmeans/router": "^0.1.18-rc.34"
   },
   "publishConfig": {
     "access": "public"