@excom/kit-router 0.1.0

package/.rush/temp/chunked-rush-logs/kit-router.apply-exports.chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: cd \"$RUSH_PROJECT_FOLDER\" && node ../heft-rig/scripts/apply-exports.mjs \n"}

package/.rush/temp/operation/apply-exports/all.log

@@ -0,0 +1 @@
+Invoking: cd "$RUSH_PROJECT_FOLDER" && node ../heft-rig/scripts/apply-exports.mjs 

package/.rush/temp/operation/apply-exports/log-chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: cd \"$RUSH_PROJECT_FOLDER\" && node ../heft-rig/scripts/apply-exports.mjs \n"}

package/.rush/temp/operation/apply-exports/state.json

@@ -0,0 +1,3 @@
+{
+  "nonCachedDurationMs": 37.992282000000046
+}

package/.rush/temp/shrinkwrap-deps.json

@@ -0,0 +1,3 @@
+{
+  "../../packages/kit-router": "../../packages/kit-router:I5XuvojLXZI78sLENPismUjh78Y1gFYqYjR+W/4GjSU=:"
+}

package/config/rig.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/rig-package/rig.schema.json",
+  "rigPackageName": "@excom/heft-rig",
+  "rigProfile": "default"
+}
+

package/index.ts

@@ -0,0 +1,422 @@
+import { hashObject } from "@excom/hash-object";
+import { KitLogger } from "@excom/kit-logger";
+import { requestIdleCb } from "@excom/kit-shims";
+
+export interface KitRouteState {
+  id: string;
+  url: string;
+  title?: string;
+  isInit?: boolean;
+  scrollX?: number;
+  scrollY?: number;
+  ttypes?: string[];
+}
+
+export interface KitChangeStateOptions {
+  url: string;
+  ttypes?: string[];
+  title?: string;
+  scrollY?: number;
+  scrollX?: number;
+}
+
+export interface KitRouteData {
+  previous: KitRouteState | null;
+  active: KitRouteState;
+  next: KitRouteState | null;
+  all: KitRouteState[];
+  params: Record<string, string> | null;
+  match: Array<any> | null;
+  move: null | "push" | "replace" | "back" | "forward";
+  event?: {
+    hasUAVisualTransition: boolean;
+  };
+  route: KitRoute;
+}
+
+export interface KitRouteOpts {
+  matchNested?: boolean;
+}
+
+export type KitRouteHandler = (data: KitRouteData) => void;
+
+export class KitRoute {
+  key: string | RegExp;
+  regex: RegExp;
+  paramNames: string[];
+  handler: KitRouteHandler;
+  opts: KitRouteOpts;
+  constructor(
+    key: string | RegExp,
+    handler: KitRouteHandler,
+    opts: KitRouteOpts = {}
+  ) {
+    if (!key || !handler) throw new Error("Invalid route or handler");
+    this.key = key;
+    this.handler = handler;
+    this.opts = opts;
+    this.paramNames = [];
+    if (typeof key === "string") {
+      const expression = key
+        .replace(/([:*])(\w+)/g, (_full, _dots, name) => {
+          // `_full` and `_dots` are unused
+          this.paramNames.push(name);
+          return "([^/]+)";
+        })
+        .replace(/\*/g, "(?:.*)");
+      const endOfPath = opts.matchNested ? "/" : "$";
+      this.regex = new RegExp(`^${expression}${endOfPath}`);
+    } else if (key instanceof RegExp) {
+      this.regex = key;
+    } else {
+      throw new Error("Invalid route key type. Must be string or RegExp.");
+    }
+  }
+  public match(pathname: string) {
+    const { regex, paramNames } = this;
+    const match = pathname.match(regex);
+    return {
+      match,
+      params:
+        match && match.length > 0
+          ? this.collectRouteParams(match, paramNames)
+          : null,
+    };
+  }
+  private collectRouteParams(match: string[], paramNames: string[]) {
+    try {
+      return match.slice(1, match.length).reduce((params, value, index) => {
+        params[paramNames[index]] = decodeURIComponent(value);
+
+        return params;
+      }, {});
+    } catch (_) {
+      return {};
+    }
+  }
+}
+
+/**
+ * History-backed router. Caps retained states so sessionStorage stays bounded.
+ */
+export class KitRouter {
+  // ~0.2kb per data-heavy state → ~5mb at this cap in sessionStorage
+  public DEFAULT_MAX_STATES = 25000;
+  public MAX_STATES = 25000;
+  protected routes: KitRoute[] = [];
+  protected states: KitRouteState[];
+  protected currentTempData: {
+    move: KitRouteData["move"];
+    event?: KitRouteData["event"];
+  };
+  protected currentStateId: string | null;
+  private handlePopState: (e: PopStateEvent) => void;
+
+  constructor() {
+    const sessionData = this.getInitSessionData();
+    this.states = sessionData.states;
+    this.currentTempData = sessionData.currentTempData;
+    this.currentStateId = sessionData.currentStateId;
+    this.routes = [];
+    this.handlePopState = (e: PopStateEvent) => {
+      if (this.currentStateId) {
+        const lastPopStateIndex = this.getStateIndex(this.currentStateId);
+        const currentStateIndex = this.getStateIndex(history.state?.id);
+        if (lastPopStateIndex < currentStateIndex) {
+          this.setScrollData(this.states[lastPopStateIndex]);
+          this.setSessionData({
+            currentTempData: {
+              move: "forward",
+              event: {
+                hasUAVisualTransition: e.hasUAVisualTransition,
+              },
+            },
+          });
+        } else if (lastPopStateIndex > currentStateIndex) {
+          this.setScrollData(this.states[lastPopStateIndex]);
+          this.setSessionData({
+            currentTempData: {
+              move: "back",
+              event: {
+                hasUAVisualTransition: e.hasUAVisualTransition,
+              },
+            },
+          });
+        }
+      } else {
+        // TODO: set scroll data here?
+        this.setSessionData({
+          currentTempData: {
+            move: "back",
+            event: {
+              hasUAVisualTransition: e.hasUAVisualTransition,
+            },
+          },
+        });
+      }
+      this.setSessionData({
+        // Falls back to the initial state id when history has no recognized id
+        currentStateId: this.getActiveState(
+          this.getStateIndex(history.state?.id)
+        ).id,
+      });
+      this.locationChanged();
+    };
+    window.addEventListener("popstate", this.handlePopState);
+  }
+
+  public destroy() {
+    window.removeEventListener("popstate", this.handlePopState);
+  }
+
+  public pushState(changeStateOptions: KitChangeStateOptions) {
+    this.beforePushState();
+    const state = buildState(changeStateOptions);
+    this.setSessionData({
+      states: [...this.states, state],
+      currentStateId: state.id,
+      currentTempData: {
+        move: "push",
+        event: undefined,
+      },
+    });
+    history.pushState(
+      { id: state.id },
+      changeStateOptions.title ?? document.title,
+      changeStateOptions.url
+    );
+    this.locationChanged();
+  }
+  public replaceState(changeStateOptions: KitChangeStateOptions) {
+    this.beforePushState();
+    const state = buildState(changeStateOptions);
+    this.setSessionData({
+      states: [...this.states.slice(0, -1), state],
+      currentStateId: state.id,
+      currentTempData: {
+        move: "replace",
+        event: undefined,
+      },
+    });
+    this._replaceState(changeStateOptions.url, changeStateOptions.title, {
+      id: state.id,
+    });
+  }
+  private _replaceState(url, title?, historyState = history.state) {
+    history.replaceState(historyState, title ?? document.title, url);
+    this.locationChanged();
+  }
+  public canGoBack() {
+    const activeStateIndex = this.getStateIndex(history.state?.id);
+    if (activeStateIndex > 0) {
+      return true;
+    } else {
+      const activeState = this.getActiveState(activeStateIndex);
+      // Past `MAX_STATES` the oldest (init) state is gone; back still works, just without metadata.
+      return !activeState.isInit;
+    }
+  }
+  public canGoForward() {
+    const activeStateIndex = this.getStateIndex(history.state?.id);
+    const nextState = this.getNextState(activeStateIndex);
+    return !!nextState;
+  }
+  public back(stateIndex = -1) {
+    history.go(stateIndex);
+  }
+  public forward(stateIndex = 1) {
+    history.go(stateIndex);
+  }
+
+  private locationChanged(routes = this.routes) {
+    const pathname = decodeURI(location.pathname);
+    const search = location.search;
+    const hash = location.hash;
+
+    if (this.shouldStripSlash(pathname)) {
+      // Private `_replaceState` so we don't track this slash-strip replace
+      this._replaceState(
+        pathname.slice(0, pathname.length - 1) + search + hash
+      );
+    } else {
+      const activeStateIndex = this.getStateIndex(history.state?.id);
+      const previous = this.getPreviousState(activeStateIndex);
+      const active = this.getActiveState(activeStateIndex);
+      const next = this.getNextState(activeStateIndex);
+      routes.forEach((route) => {
+        const { match, params } = route.match(pathname);
+        const data: KitRouteData = {
+          previous,
+          active,
+          next,
+          all: this.states,
+          params,
+          match,
+          move: this.currentTempData.move,
+          event: this.currentTempData.event,
+          route,
+        };
+        route.handler(data);
+      });
+    }
+  }
+
+  public on(route: KitRoute) {
+    if (
+      !this.routes.some(
+        (r) => r.key === route.key && r.handler === route.handler
+      )
+    ) {
+      this.routes.push(route);
+      // Call the handler now so it gets current info
+      this.locationChanged([route]);
+    } else {
+      throw new Error("Route already registered");
+    }
+
+    return route;
+  }
+
+  public off(route: KitRoute) {
+    this.routes = this.routes.filter((r) => r !== route);
+
+    return null;
+  }
+
+  private beforePushState() {
+    const index = this.getStateIndex(history.state?.id);
+    const currentState = this.getActiveState(index);
+    this.setScrollData(currentState);
+    // Drop states after the current one (went back, then pushed a new one)
+    this.setSessionData({
+      states: this.states.slice(0, index + 1),
+    });
+  }
+
+  private setScrollData(state: KitRouteState) {
+    if (window.scrollY) {
+      // Non-zero: keep `scrollY`
+      state.scrollY = window.scrollY;
+    }
+    if (window.scrollX) {
+      // Non-zero: keep `scrollX`
+      state.scrollX = window.scrollX;
+    }
+  }
+
+  private getStateIndex(id) {
+    if (!id) return 0;
+    else {
+      // Search from the end in case two states share an id
+      const foundState = this.states
+        .slice()
+        .reverse()
+        .find((s) => s.id === id);
+      const foundIndex = this.states.findIndex((s) => s === foundState);
+      return foundIndex > -1 ? foundIndex : 0;
+    }
+  }
+
+  private getPreviousState(activeStateIndex) {
+    if (activeStateIndex < 1) return null;
+    else return this.states[activeStateIndex - 1];
+  }
+
+  private getActiveState(activeStateIndex) {
+    return this.states[activeStateIndex]!;
+  }
+
+  private getNextState(activeStateIndex) {
+    if (activeStateIndex >= this.states.length - 1) return null;
+    else return this.states[activeStateIndex + 1];
+  }
+
+  private shouldStripSlash(pathname) {
+    return (
+      pathname !== "/" &&
+      pathname?.endsWith?.("/") &&
+      // No trailing-slash route matches this path exactly
+      !this.routes.find((route) => {
+        const { match } = route.match(pathname);
+        return (
+          match?.[0] &&
+          typeof route.key === "string" &&
+          !route.key?.endsWith?.("/")
+        );
+      })
+    );
+  }
+  private setSessionData({
+    states,
+    currentStateId,
+    currentTempData,
+  }: {
+    states?: KitRouteState[];
+    currentStateId?: string | null;
+    currentTempData?: {
+      move: null | "push" | "replace" | "back" | "forward";
+      event?: {
+        hasUAVisualTransition: boolean;
+      };
+    };
+  }) {
+    this.states = (states ?? this.states).slice(-this.MAX_STATES);
+    this.currentStateId = currentStateId ?? this.currentStateId;
+    this.currentTempData = currentTempData ?? this.currentTempData;
+    requestIdleCb(() => {
+      // Idle write is enough; no need to block here
+      try {
+        sessionStorage.setItem(
+          "__spa_router_data__",
+          JSON.stringify({
+            states: this.states,
+            currentStateId: this.currentStateId,
+            currentTempData: this.currentTempData,
+          })
+        );
+      } catch (e) {
+        KitLogger.error("Error setting session data", e);
+      }
+    }, 0);
+  }
+  private getInitSessionData() {
+    let sessionStorageData;
+    try {
+      sessionStorageData = JSON.parse(
+        sessionStorage.getItem("__spa_router_data__") || "null"
+      );
+    } catch (e) {
+      KitLogger.error("Error getting session data", e);
+    }
+    return (
+      // Restore session data, or start fresh
+      sessionStorageData || {
+        states: [buildState({ isInit: true })],
+        currentStateId: null,
+        currentTempData: {
+          move: null,
+        },
+      }
+    );
+  }
+}
+
+function buildState(obj: Partial<KitRouteState> = {}): KitRouteState {
+  const newState: Partial<KitRouteState> = Object.assign(
+    {},
+    { url: obj.url ?? getUrl() },
+    obj.title && { title: obj.title },
+    obj.scrollY && { scrollY: obj.scrollY },
+    obj.scrollX && { scrollX: obj.scrollX },
+    obj.isInit && { isInit: obj.isInit },
+    obj.ttypes && obj.ttypes?.length > 0 && { ttypes: obj.ttypes }
+  );
+  newState.id = hashObject(newState);
+  return newState as KitRouteState;
+}
+
+function getUrl() {
+  return location.pathname + location.search + location.hash;
+}
+
+export const kitRouter = new KitRouter();

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@excom/kit-router",
+  "version": "0.1.0",
+  "description": "kit-router library",
+  "license": "MIT",
+  "engines": {
+    "node": ">=24.13.0"
+  },
+  "type": "module",
+  "dependencies": {
+    "@excom/hash-object": "^0.1.0",
+    "@excom/kit-logger": "^0.1.0",
+    "@excom/kit-shims": "^0.1.0"
+  },
+  "peerDependencies": {},
+  "devDependencies": {
+    "@excom/heft-rig": "^0.1.0"
+  },
+  "repository": {
+    "url": "excom-dev/nucleus",
+    "directory": "packages/kit-router"
+  },
+  "homepage": "https://github.com/excom-dev/nucleus/tree/main/packages/kit-router/support/docs/README.md",
+  "bugs": "https://github.com/excom-dev/nucleus/issues",
+  "keywords": [
+    "kit-router"
+  ],
+  "excom": {
+    "documented": false,
+    "packageType": "library"
+  },
+  "scripts": {
+    "build": "node node_modules/@excom/heft-rig/scripts/vite-build.mjs",
+    "build:watch": "node node_modules/@excom/heft-rig/scripts/vite-build-watch.mjs",
+    "format": "node node_modules/@excom/heft-rig/scripts/format.mjs",
+    "test": "node node_modules/@excom/heft-rig/scripts/vitest.mjs",
+    "coverage": "node node_modules/@excom/heft-rig/scripts/coverage.mjs"
+  }
+}

package/rush-logs/kit-router.apply-exports.cache.log

@@ -0,0 +1 @@
+Caching has been disabled for this project's "apply-exports" command.

package/rush-logs/kit-router.apply-exports.log

@@ -0,0 +1 @@
+Invoking: cd "$RUSH_PROJECT_FOLDER" && node ../heft-rig/scripts/apply-exports.mjs 

package/support/tests/kit-router-history.test.ts

@@ -0,0 +1,344 @@
+import { KitRoute, KitRouter, kitRouter } from "../../index";
+import { KitLogger } from "@excom/kit-logger";
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  vi,
+  wait,
+} from "@excom/heft-rig/profiles/default/config/test-utils";
+
+const SESSION_KEY = "__spa_router_data__";
+
+const popstate = (id: string | null, hasUAVisualTransition?: boolean) => {
+  if (id !== null) {
+    // happy-dom keeps the pushed state object; mutate the id to emulate
+    // the browser moving through history.
+    (history.state as { id: string }).id = id;
+  }
+  const e = new PopStateEvent("popstate");
+  if (hasUAVisualTransition !== undefined) {
+    Object.defineProperty(e, "hasUAVisualTransition", {
+      value: hasUAVisualTransition,
+    });
+  }
+  window.dispatchEvent(e);
+};
+
+const statesOf = (router: KitRouter) =>
+  (router as unknown as { states: Array<{ id: string; url: string }> }).states;
+
+describe("KitRoute params", () => {
+  it("returns empty params when a param cannot be decoded", () => {
+    const route = new KitRoute("/u/:name", () => {});
+    // malformed percent-encoding makes decodeURIComponent throw
+    const result = route.match("/u/%E0%A4%A");
+    expect(result.match).not.toBeNull();
+    expect(result.params).toEqual({});
+  });
+
+  it("supports wildcards", () => {
+    const route = new KitRoute("/files/*", () => {});
+    expect(route.match("/files/a/b/c.txt").match).not.toBeNull();
+    expect(route.match("/files/").match).not.toBeNull();
+    expect(route.match("/other").match).toBeNull();
+  });
+
+  it("does not match nested paths without a trailing segment", () => {
+    const route = new KitRoute("/settings", () => {}, { matchNested: true });
+    expect(route.match("/settingsx").match).toBeNull();
+    expect(route.match("/settings/").match).not.toBeNull();
+  });
+});
+
+describe("KitRouter history", () => {
+  let router: KitRouter;
+
+  beforeEach(() => {
+    history.replaceState(null, "", "/");
+  });
+
+  afterEach(() => {
+    router?.destroy();
+    vi.restoreAllMocks();
+    sessionStorage.removeItem(SESSION_KEY);
+    window.scrollTo(0, 0);
+    history.replaceState(null, "", "/");
+  });
+
+  it("exports a singleton router", () => {
+    expect(kitRouter).toBeInstanceOf(KitRouter);
+  });
+
+  it("handles popstate back / forward / same-entry moves", () => {
+    router = new KitRouter();
+    const handler = vi.fn();
+    router.on(new KitRoute(/.*/, handler));
+    router.pushState({ url: "/p1" });
+    router.pushState({ url: "/p2" });
+    const states = statesOf(router);
+    expect(states.map((s) => s.url)).toEqual(["/", "/p1", "/p2"]);
+    handler.mockClear();
+
+    // back to /p1
+    popstate(states[1].id, false);
+    expect(handler).toHaveBeenCalledTimes(1);
+    expect(handler).toHaveBeenLastCalledWith(
+      expect.objectContaining({
+        move: "back",
+        event: { hasUAVisualTransition: false },
+        previous: expect.objectContaining({ url: "/" }),
+        active: expect.objectContaining({ url: "/p1" }),
+        next: expect.objectContaining({ url: "/p2" }),
+      })
+    );
+    expect(router.canGoForward()).toBe(true);
+    expect(router.canGoBack()).toBe(true);
+
+    // forward to /p2
+    popstate(states[2].id, true);
+    expect(handler).toHaveBeenCalledTimes(2);
+    expect(handler).toHaveBeenLastCalledWith(
+      expect.objectContaining({
+        move: "forward",
+        event: { hasUAVisualTransition: true },
+        active: expect.objectContaining({ url: "/p2" }),
+        next: null,
+      })
+    );
+    expect(router.canGoForward()).toBe(false);
+
+    // popstate on the same entry keeps the last move
+    popstate(states[2].id);
+    expect(handler).toHaveBeenCalledTimes(3);
+    expect(handler).toHaveBeenLastCalledWith(
+      expect.objectContaining({ move: "forward" })
+    );
+  });
+
+  it("treats popstate as back when no state id has been tracked yet", () => {
+    router = new KitRouter();
+    const handler = vi.fn();
+    router.on(new KitRoute(/.*/, handler));
+    handler.mockClear();
+
+    window.dispatchEvent(new PopStateEvent("popstate"));
+    expect(handler).toHaveBeenCalledTimes(1);
+    expect(handler).toHaveBeenLastCalledWith(
+      expect.objectContaining({
+        move: "back",
+        event: { hasUAVisualTransition: false },
+        previous: null,
+        next: null,
+      })
+    );
+  });
+
+  it("stores the scroll position of the outgoing state on push and on popstate", () => {
+    router = new KitRouter();
+    const handler = vi.fn();
+    router.on(new KitRoute(/.*/, handler));
+    router.pushState({ url: "/first" });
+    handler.mockClear();
+
+    window.scrollTo(10, 100);
+    router.pushState({ url: "/second" });
+    expect(handler).toHaveBeenLastCalledWith(
+      expect.objectContaining({
+        previous: expect.objectContaining({
+          url: "/first",
+          scrollX: 10,
+          scrollY: 100,
+        }),
+      })
+    );
+
+    window.scrollTo(3, 7);
+    const states = statesOf(router);
+    popstate(states[1].id);
+    expect(states[2]).toEqual(
+      expect.objectContaining({ url: "/second", scrollX: 3, scrollY: 7 })
+    );
+    window.scrollTo(0, 0);
+    router.pushState({ url: "/third" });
+    // zero offsets are not stored
+    expect(states[1]).toEqual(
+      expect.objectContaining({ scrollX: 10, scrollY: 100 })
+    );
+  });
+
+  it("drops forward states when pushing after going back", () => {
+    router = new KitRouter();
+    router.on(new KitRoute(/.*/, () => {}));
+    router.pushState({ url: "/a" });
+    router.pushState({ url: "/b" });
+    popstate(statesOf(router)[1].id);
+    router.pushState({ url: "/c" });
+    expect(statesOf(router).map((s) => s.url)).toEqual(["/", "/a", "/c"]);
+    expect(router.canGoForward()).toBe(false);
+  });
+
+  it("keeps state metadata (title, scroll, transition types)", () => {
+    router = new KitRouter();
+    const handler = vi.fn();
+    router.on(new KitRoute(/.*/, handler));
+    router.pushState({
+      url: "/meta",
+      title: "Meta",
+      scrollX: 3,
+      scrollY: 7,
+      ttypes: ["fade"],
+    });
+    expect(handler).toHaveBeenLastCalledWith(
+      expect.objectContaining({
+        active: expect.objectContaining({
+          url: "/meta",
+          title: "Meta",
+          scrollX: 3,
+          scrollY: 7,
+          ttypes: ["fade"],
+        }),
+      })
+    );
+    router.replaceState({ url: "/meta-2", ttypes: [] });
+    const active = handler.mock.lastCall![0].active;
+    expect(active.url).toBe("/meta-2");
+    expect(active).not.toHaveProperty("ttypes");
+    expect(active).not.toHaveProperty("title");
+  });
+
+  it("canGoBack is true after a push and when the oldest state is not initial", () => {
+    router = new KitRouter();
+    router.on(new KitRoute(/.*/, () => {}));
+    expect(router.canGoBack()).toBe(false);
+    router.pushState({ url: "/x" });
+    expect(router.canGoBack()).toBe(true);
+
+    // exceeding MAX_STATES drops the initial state; back is still possible
+    router.MAX_STATES = 1;
+    router.pushState({ url: "/y" });
+    expect(statesOf(router).map((s) => s.url)).toEqual(["/y"]);
+    expect(router.canGoBack()).toBe(true);
+  });
+
+  it("back / forward delegate to history.go", () => {
+    router = new KitRouter();
+    const goSpy = vi.spyOn(history, "go").mockImplementation(() => {});
+    router.back();
+    expect(goSpy).toHaveBeenLastCalledWith(-1);
+    router.back(-2);
+    expect(goSpy).toHaveBeenLastCalledWith(-2);
+    router.forward();
+    expect(goSpy).toHaveBeenLastCalledWith(1);
+    router.forward(3);
+    expect(goSpy).toHaveBeenLastCalledWith(3);
+  });
+
+  describe("trailing slash", () => {
+    it("strips a trailing slash when no route wants it", () => {
+      router = new KitRouter();
+      const handler = vi.fn();
+      router.on(new KitRoute(/.*/, handler));
+      router.on(new KitRoute("/foo", () => {}));
+      handler.mockClear();
+      router.pushState({ url: "/foo/?q=1#h" });
+      expect(location.pathname).toBe("/foo");
+      expect(location.search).toBe("?q=1");
+      expect(location.hash).toBe("#h");
+      expect(handler).toHaveBeenCalledTimes(1);
+      expect(handler).toHaveBeenLastCalledWith(
+        expect.objectContaining({ move: "push" })
+      );
+    });
+
+    it("strips a trailing slash when only a trailing-slash string route matches", () => {
+      router = new KitRouter();
+      const handler = vi.fn();
+      router.on(new KitRoute("/bar/", handler));
+      handler.mockClear();
+      router.pushState({ url: "/bar/" });
+      expect(location.pathname).toBe("/bar");
+      expect(handler).toHaveBeenLastCalledWith(
+        expect.objectContaining({ match: null })
+      );
+    });
+
+    it("keeps a trailing slash when a nested string route matches it", () => {
+      router = new KitRouter();
+      const handler = vi.fn();
+      router.on(new KitRoute("/baz", handler, { matchNested: true }));
+      handler.mockClear();
+      router.pushState({ url: "/baz/" });
+      expect(location.pathname).toBe("/baz/");
+      expect(handler).toHaveBeenCalledTimes(1);
+      expect(handler.mock.lastCall![0].match).not.toBeNull();
+    });
+
+    it("never strips the root path", () => {
+      router = new KitRouter();
+      const handler = vi.fn();
+      router.on(new KitRoute("/", handler));
+      handler.mockClear();
+      router.pushState({ url: "/" });
+      expect(location.pathname).toBe("/");
+      expect(handler.mock.lastCall![0].match).not.toBeNull();
+    });
+  });
+
+  describe("session storage", () => {
+    it("persists router data and restores it in a new router", async () => {
+      router = new KitRouter();
+      router.pushState({ url: "/persisted" });
+      await wait(5);
+      const stored = JSON.parse(sessionStorage.getItem(SESSION_KEY)!);
+      expect(stored.states.map((s) => s.url)).toEqual(["/", "/persisted"]);
+      expect(stored.currentTempData.move).toBe("push");
+
+      const restored = new KitRouter();
+      try {
+        expect(statesOf(restored).map((s) => s.url)).toEqual([
+          "/",
+          "/persisted",
+        ]);
+      } finally {
+        restored.destroy();
+      }
+    });
+
+    it("falls back to a fresh state when stored data is unreadable", () => {
+      const errorSpy = vi
+        .spyOn(KitLogger, "error")
+        .mockImplementation(() => {});
+      sessionStorage.setItem(SESSION_KEY, "{not json");
+      router = new KitRouter();
+      expect(errorSpy).toHaveBeenCalledWith(
+        "Error getting session data",
+        expect.anything()
+      );
+      const states = statesOf(router);
+      expect(states).toHaveLength(1);
+      expect(states[0]).toEqual(expect.objectContaining({ isInit: true }));
+    });
+
+    it("logs when session data cannot be written", async () => {
+      router = new KitRouter();
+      const errorSpy = vi
+        .spyOn(KitLogger, "error")
+        .mockImplementation(() => {});
+      const setItemSpy = vi
+        .spyOn(sessionStorage, "setItem")
+        .mockImplementation(() => {
+          throw new Error("quota");
+        });
+      router.pushState({ url: "/unwritable" });
+      await wait(5);
+      setItemSpy.mockRestore();
+      expect(errorSpy).toHaveBeenCalledWith(
+        "Error setting session data",
+        expect.any(Error)
+      );
+    });
+  });
+});

package/support/tests/kit-router.test.ts

@@ -0,0 +1,200 @@
+import { KitRoute, KitRouter } from "../../index";
+import {
+  afterEach,
+  describe,
+  expect,
+  it,
+  vi,
+} from "@excom/heft-rig/node_modules/vitest";
+
+describe("KitRoute", () => {
+  it("matches routes with params", () => {
+    const route = new KitRoute("/users/:id", () => {});
+    const match = route.match("/users/123");
+    expect(match?.params).toEqual({ id: "123" });
+  });
+
+  it("supports nested matches when enabled", () => {
+    const route = new KitRoute("/settings", () => {}, { matchNested: true });
+    const match = route.match("/settings/profile");
+    expect(match.match).not.toBeNull();
+  });
+
+  it("does not match non-nested paths by default", () => {
+    const route = new KitRoute("/settings", () => {});
+    const result = route.match("/settings/profile");
+    expect(result.match).toBeNull();
+  });
+
+  it("matches exact path", () => {
+    const route = new KitRoute("/about", () => {});
+    const result = route.match("/about");
+    expect(result.match).not.toBeNull();
+    expect(result.params).toEqual({});
+  });
+
+  it("extracts multiple params", () => {
+    const route = new KitRoute("/users/:userId/posts/:postId", () => {});
+    const result = route.match("/users/42/posts/99");
+    expect(result.params).toEqual({ userId: "42", postId: "99" });
+  });
+
+  it("decodes URI-encoded params", () => {
+    const route = new KitRoute("/search/:query", () => {});
+    const result = route.match("/search/hello%20world");
+    expect(result.params).toEqual({ query: "hello world" });
+  });
+
+  it("returns null params for non-matching route", () => {
+    const route = new KitRoute("/users/:id", () => {});
+    const result = route.match("/posts/123");
+    expect(result.match).toBeNull();
+    expect(result.params).toBeNull();
+  });
+
+  it("works with regex keys", () => {
+    const route = new KitRoute(/^\/api\/(.+)$/, () => {});
+    const result = route.match("/api/v1/users");
+    expect(result.match).not.toBeNull();
+    expect(result.match![1]).toBe("v1/users");
+  });
+
+  it("throws for invalid route or handler", () => {
+    expect(() => new KitRoute("", () => {})).toThrow("Invalid route");
+    expect(() => new KitRoute("/path", null as any)).toThrow(
+      "Invalid route",
+    );
+  });
+
+  it("throws for invalid key type", () => {
+    expect(() => new KitRoute(123 as any, () => {})).toThrow(
+      "Invalid route key type",
+    );
+  });
+
+  it("matches root path", () => {
+    const route = new KitRoute("/", () => {});
+    const result = route.match("/");
+    expect(result.match).not.toBeNull();
+  });
+});
+
+describe("KitRouter", () => {
+  let router: KitRouter;
+
+  afterEach(() => {
+    router?.destroy();
+    vi.restoreAllMocks();
+    sessionStorage.removeItem("__spa_router_data__");
+  });
+
+  it("registers a route and immediately calls its handler", () => {
+    router = new KitRouter();
+    const handler = vi.fn();
+    const route = new KitRoute(/.*/, handler);
+    router.on(route);
+    expect(handler).toHaveBeenCalledTimes(1);
+    expect(handler).toHaveBeenCalledWith(
+      expect.objectContaining({
+        active: expect.any(Object),
+        match: expect.any(Array),
+      }),
+    );
+  });
+
+  it("throws when registering a duplicate route", () => {
+    router = new KitRouter();
+    const handler = vi.fn();
+    const route = new KitRoute(/.*/, handler);
+    router.on(route);
+    expect(() => router.on(route)).toThrow("Route already registered");
+  });
+
+  it("unregisters a route with off()", () => {
+    router = new KitRouter();
+    const handler = vi.fn();
+    const route = new KitRoute(/.*/, handler);
+    router.on(route);
+    expect(handler).toHaveBeenCalledTimes(1);
+    router.off(route);
+    router.pushState({ url: "/test-off" });
+    expect(handler).toHaveBeenCalledTimes(1);
+  });
+
+  it("pushState calls matching handlers", () => {
+    router = new KitRouter();
+    const handler = vi.fn();
+    const route = new KitRoute(/.*/, handler);
+    router.on(route);
+    handler.mockClear();
+
+    router.pushState({ url: "/new-page" });
+    expect(handler).toHaveBeenCalledTimes(1);
+    expect(handler).toHaveBeenCalledWith(
+      expect.objectContaining({ move: "push" }),
+    );
+  });
+
+  it("replaceState calls matching handlers", () => {
+    router = new KitRouter();
+    const handler = vi.fn();
+    const route = new KitRoute(/.*/, handler);
+    router.on(route);
+    handler.mockClear();
+
+    router.replaceState({ url: "/replaced" });
+    expect(handler).toHaveBeenCalledTimes(1);
+    expect(handler).toHaveBeenCalledWith(
+      expect.objectContaining({ move: "replace" }),
+    );
+  });
+
+  it("canGoBack returns false on initial state", () => {
+    router = new KitRouter();
+    expect(router.canGoBack()).toBe(false);
+  });
+
+  it("canGoForward returns false with no forward states", () => {
+    router = new KitRouter();
+    expect(router.canGoForward()).toBe(false);
+  });
+
+  it("provides previous/active/next state to handlers", () => {
+    router = new KitRouter();
+    const handler = vi.fn();
+    const route = new KitRoute(/.*/, handler);
+    router.on(route);
+    handler.mockClear();
+
+    router.pushState({ url: "/page1" });
+    const data = handler.mock.calls[0][0];
+    expect(data.previous).not.toBeNull();
+    expect(data.active).toBeDefined();
+    expect(data.active.url).toBe("/page1");
+    expect(data.next).toBeNull();
+  });
+
+  it("passes route params to handler", () => {
+    router = new KitRouter();
+    const handler = vi.fn();
+    const route = new KitRoute("/items/:id", handler);
+    router.on(route);
+    handler.mockClear();
+
+    history.replaceState({}, "", "/items/42");
+    router.pushState({ url: "/items/42" });
+    const data = handler.mock.calls[0][0];
+    expect(data.params).toEqual({ id: "42" });
+  });
+
+  it("stores title in state when provided", () => {
+    router = new KitRouter();
+    const handler = vi.fn();
+    router.on(new KitRoute(/.*/, handler));
+    handler.mockClear();
+
+    router.pushState({ url: "/titled", title: "My Page" });
+    const data = handler.mock.calls[0][0];
+    expect(data.active.title).toBe("My Page");
+  });
+});

package/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "@excom/heft-rig/profiles/default/config/tsconfig.json",
+  "include": ["./*.ts"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.spec.ts"]
+}