feat: add @microsoft/webui-router client-side routing package

- Navigation API interception for SPA transitions
- Self-registering <webui-route> custom element via connectedCallback
- Iterative path matching with :param, :param?, *splat (no regex)
- Specificity-based route ranking
- Opt-in lazy loading via loaders config with promise dedup
- SSR-safe: preserves server-rendered DOM on initial navigation
- Component inventory bloom filter for template dedup
- webui:route:navigated CustomEvent after each navigation

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: mohamedmansour

package.json

@@ -11,5 +11,5 @@
   },
   "author": "Microsoft Edge",
   "license": "MIT",
-  "packageManager": "pnpm@10.30.3"
+  "packageManager": "pnpm@10.31.0+sha512.e3927388bfaa8078ceb79b748ffc1e8274e84d75163e67bc22e06c0d3aed43dd153151cbf11d7f8301ff4acb98c68bdc5cadf6989532801ffafe3b3e4a63c268"
 }

packages/webui-router/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@microsoft/webui-router",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "Lightweight client-side router for WebUI apps. Intercepts navigation, matches routes locally or via server route-data, and hydrates components.",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist/"
+  ],
+  "scripts": {
+    "build": "esbuild src/index.ts --bundle --outfile=dist/index.js --format=esm --platform=browser && tsc --emitDeclarationOnly",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "esbuild": "catalog:",
+    "typescript": "catalog:"
+  }
+}

packages/webui-router/src/index.ts

@@ -0,0 +1,20 @@
+/**
+ * @microsoft/webui-router — DOM-native client-side router for WebUI apps.
+ *
+ * Routes are `<webui-route>` custom elements (transformed from `<route>` at build time).
+ * The router uses the Navigation API to intercept navigations and show/hide matching routes.
+ *
+ * @example
+ * ```ts
+ * import { Router } from '@microsoft/webui-router';
+ * Router.start();
+ * Router.navigate('/contacts/42');
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+export { Router, WebUIRouter, WebUIRouteElement } from './router.js';
+export type { RouterConfig, NavigationEvent } from './types.js';
+export { matchPath, parseTemplate, specificity } from './matcher.js';
+export type { Segment, PathMatch } from './matcher.js';

packages/webui-router/src/matcher.ts

@@ -0,0 +1,99 @@
+/**
+ * Iterative path template matching — no regex.
+ *
+ * Supports `:param`, `:param?` (optional), and `*splat` segments.
+ */
+
+/** A single parsed segment from a path template. */
+export type Segment =
+  | { type: 'literal'; value: string }
+  | { type: 'param'; name: string }
+  | { type: 'optional'; name: string }
+  | { type: 'splat'; name: string };
+
+/** Result of a successful path match. */
+export interface PathMatch {
+  params: Record<string, string>;
+}
+
+/** Parse a path template string into typed segments. */
+export function parseTemplate(path: string): Segment[] {
+  return path
+    .split('/')
+    .filter(Boolean)
+    .map((seg): Segment => {
+      if (seg.startsWith(':')) {
+        const raw = seg.slice(1);
+        if (raw.endsWith('?')) {
+          return { type: 'optional', name: raw.slice(0, -1) };
+        }
+        return { type: 'param', name: raw };
+      }
+      if (seg.startsWith('*')) {
+        return { type: 'splat', name: seg.slice(1) || 'rest' };
+      }
+      return { type: 'literal', value: seg };
+    });
+}
+
+// Module-level cache: template strings are static, avoid re-parsing.
+const templateCache = new Map<string, Segment[]>();
+
+function getCachedSegments(template: string): Segment[] {
+  let segs = templateCache.get(template);
+  if (!segs) {
+    segs = parseTemplate(template);
+    templateCache.set(template, segs);
+  }
+  return segs;
+}
+
+/**
+ * Try to match a request path against a single route template.
+ *
+ * Returns bound parameters on success, `null` on failure.
+ */
+export function matchPath(
+  template: string,
+  requestPath: string,
+  exact: boolean,
+): PathMatch | null {
+  const segs = getCachedSegments(template);
+  const parts = requestPath.split('/').filter(Boolean);
+  const params: Record<string, string> = {};
+  let pi = 0;
+
+  for (let si = 0; si < segs.length; si++) {
+    const seg = segs[si];
+    switch (seg.type) {
+      case 'literal':
+        if (pi >= parts.length || parts[pi] !== seg.value) return null;
+        pi++;
+        break;
+      case 'param':
+        if (pi >= parts.length) return null;
+        params[seg.name] = decodeURIComponent(parts[pi++]);
+        break;
+      case 'optional':
+        if (pi < parts.length) {
+          params[seg.name] = decodeURIComponent(parts[pi++]);
+        }
+        break;
+      case 'splat':
+        params[seg.name] = parts.slice(pi).map(decodeURIComponent).join('/');
+        pi = parts.length;
+        break;
+    }
+  }
+
+  if (exact && pi < parts.length) return null;
+  return { params };
+}
+
+/**
+ * Count the number of literal (non-param) segments in a template.
+ * Used to rank matches by specificity.
+ */
+export function specificity(template: string): number {
+  return getCachedSegments(template).filter(s => s.type === 'literal').length;
+}