@valancex/router 0.0.0-stage → 0.12.0

package/README.md

@@ -1,3 +1,29 @@
-# Temporary Holding Version
+# @valancex/router
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Routing for VALANCE applications: route definitions, typed path and query parameters, guards, programmatic navigation and a title per route. **Provisional** (0.x).
+
+```ts
+import { Schema } from "effect";
+import { createRouter, redirect, route } from "@valancex/router";
+
+const router = createRouter({
+  routes: {
+    home: route("/", { title: () => "Home" }),
+    message: route("/inbox/:id", {
+      params: { id: Schema.NumberFromString },
+      title: ({ params }) => `Message ${params.id}`,
+      canActivate: ({ context }) => (context().signedIn ? true : redirect("login")),
+    }),
+    login: route("/login", { title: () => "Sign in" }),
+  },
+  notFound: "notFound",
+  context: () => ({ signedIn: false }),
+});
+
+await Web.run(app, { container, primitives, present: "mount", plugins: [router.plugin] });
+```
+
+- `router.commands(state)` gives `navigate`, `go` and `replace` commands for the application's state.
+- Guards: `canMatch` (sync), `canActivate`, `canDeactivate`, and `beforeEach`; each answers a boolean, a `redirect(...)`, or a Promise/Effect of one. A refused Back/Forward is undone.
+- Redirects name a route, never a URL; `router.safeNext(address)` only accepts an address on the application.
+- Not yet: nested routes, a `beforeunload` guard, typed HTTP interceptors.

package/dist/guards.d.ts

@@ -0,0 +1,7 @@
+import { Effect } from "effect";
+import type { Route } from "./route.js";
+import type { Guard, GuardContext, GuardResult, Redirect } from "./types.js";
+/** Sends a navigation to another route: `redirect(login, {}, { next: "/inbox" })`. The target is a route, never an address, so a redirect cannot leave the application. */
+export declare const redirect: <P, Q>(to: Route<P, Q, any, any> | string, params?: Readonly<Record<string, unknown>>, query?: Readonly<Record<string, unknown>>) => Redirect;
+/** Runs a guard whatever it returns, and says what it answered. A guard that throws, rejects or fails refuses. */
+export declare const runGuard: <S>(guard: Guard<S>, context: GuardContext<S>) => Effect.Effect<GuardResult>;

package/dist/guards.js

@@ -0,0 +1,14 @@
+import { Effect } from "effect";
+/** Sends a navigation to another route: `redirect(login, {}, { next: "/inbox" })`. The target is a route, never an address, so a redirect cannot leave the application. */
+export const redirect = (to, params = {}, query = {}) => ({
+    _tag: "Redirect",
+    name: typeof to === "string" ? to : to.name,
+    params,
+    query,
+});
+const isRedirect = (value) => typeof value === "object" && value !== null && value._tag === "Redirect";
+/** Runs a guard whatever it returns, and says what it answered. A guard that throws, rejects or fails refuses. */
+export const runGuard = (guard, context) => Effect.suspend(() => {
+    const answer = guard(context);
+    return Effect.isEffect(answer) ? answer : Effect.tryPromise(async () => answer);
+}).pipe(Effect.map((answer) => (isRedirect(answer) ? answer : answer === true)), Effect.catchAllCause((cause) => Effect.logError("route guard failed", cause).pipe(Effect.as(false))));

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { createRouter } from "./router.js";
+export type { Router, RouterOptions } from "./router.js";
+export { route } from "./route.js";
+export type { Route, RouteConfig } from "./route.js";
+export { redirect } from "./guards.js";
+export { RouteDefinitionError } from "./pattern.js";
+export { RouteState } from "./types.js";
+export type { Decision, Guard, GuardContext, GuardResult, NavigationKind, Redirect, TitleContext } from "./types.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { createRouter } from "./router.js";
+export { route } from "./route.js";
+export { redirect } from "./guards.js";
+export { RouteDefinitionError } from "./pattern.js";
+export { RouteState } from "./types.js";

package/dist/pattern.d.ts

@@ -0,0 +1,40 @@
+export declare class RouteDefinitionError extends Error {
+    constructor(message: string);
+}
+export type Segment = {
+    readonly kind: "literal";
+    readonly value: string;
+} | {
+    readonly kind: "param";
+    readonly name: string;
+} | {
+    readonly kind: "rest";
+    readonly name: string;
+};
+export interface Pattern {
+    readonly source: string;
+    readonly segments: ReadonlyArray<Segment>;
+    /** The names a match fills, in order. */
+    readonly names: ReadonlyArray<string>;
+    /** How specific it is, segment by segment (literal 3, parameter 2, rest 1), for ranking. */
+    readonly score: ReadonlyArray<number>;
+    /** The pattern with every parameter name removed: two routes with the same shape cannot be told apart. */
+    readonly shape: string;
+}
+/** Limits on what is matched, so a hostile address costs a bounded amount. */
+export declare const LIMITS: {
+    readonly path: 2048;
+    readonly segments: 32;
+    readonly segment: 512;
+    readonly queryKeys: 64;
+    readonly queryValue: 2048;
+};
+export declare const parsePattern: (source: string) => Pattern;
+/** Higher first: compare segment by segment, then the longer pattern. */
+export declare const bySpecificity: (a: Pattern, b: Pattern) => number;
+/** The path's segments decoded once, or `undefined` for a path that is not an address this router would read. */
+export declare const segmentsOf: (pathname: string) => ReadonlyArray<string> | undefined;
+/** The values the pattern takes from the segments (as strings, for a Schema to decode), or `undefined` when it does not match. */
+export declare const matchSegments: (pattern: Pattern, segments: ReadonlyArray<string>) => Readonly<Record<string, string>> | undefined;
+/** The path for `values` (strings), each piece percent-encoded. A missing or empty value is an error: a path with a hole is not an address. */
+export declare const buildPath: (pattern: Pattern, values: Readonly<Record<string, string>>) => string;

package/dist/pattern.js

@@ -0,0 +1,125 @@
+// A route's path pattern: literal segments, `:name` parameters and a trailing `*` (or `*name`) that takes the rest. Matching is strict where a loose reading would be a hole: the whole path is
+// bounded, every segment is percent-decoded once and may not hold a control character, a literal is compared exactly (case and all), and a trailing slash is the same address.
+export class RouteDefinitionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "RouteDefinitionError";
+    }
+}
+/** Limits on what is matched, so a hostile address costs a bounded amount. */
+export const LIMITS = { path: 2048, segments: 32, segment: 512, queryKeys: 64, queryValue: 2048 };
+const NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+export const parsePattern = (source) => {
+    if (!source.startsWith("/") || source.includes("//") || (source.length > 1 && source.endsWith("/"))) {
+        throw new RouteDefinitionError(`the path "${source}" must start with "/", hold no empty segment and not end with "/" (the root is "/")`);
+    }
+    const parts = source === "/" ? [] : source.slice(1).split("/");
+    const segments = [];
+    const names = new Set();
+    parts.forEach((part, at) => {
+        if (part.startsWith(":")) {
+            const name = part.slice(1);
+            if (!NAME.test(name) || names.has(name)) {
+                throw new RouteDefinitionError(`the path "${source}" has a parameter ":${name}" that is not a name or is used twice`);
+            }
+            names.add(name);
+            segments.push({ kind: "param", name });
+        }
+        else if (part.startsWith("*")) {
+            const name = part.length === 1 ? "rest" : part.slice(1);
+            if (at !== parts.length - 1 || !NAME.test(name) || names.has(name)) {
+                throw new RouteDefinitionError(`the path "${source}" may end with "*" or "*name" and nowhere else, and the name must be new`);
+            }
+            names.add(name);
+            segments.push({ kind: "rest", name });
+        }
+        else if (part === "" || /[:*?#\s]/.test(part)) {
+            throw new RouteDefinitionError(`the path "${source}" has a segment "${part}" that is empty or holds one of : * ? # or a space (write a parameter as ":name")`);
+        }
+        else {
+            segments.push({ kind: "literal", value: part });
+        }
+    });
+    return {
+        source,
+        segments,
+        names: [...names],
+        score: segments.map((segment) => (segment.kind === "literal" ? 3 : segment.kind === "param" ? 2 : 1)),
+        shape: `/${segments.map((segment) => (segment.kind === "literal" ? segment.value : segment.kind === "param" ? ":" : "*")).join("/")}`,
+    };
+};
+/** Higher first: compare segment by segment, then the longer pattern. */
+export const bySpecificity = (a, b) => {
+    for (let at = 0; at < Math.max(a.score.length, b.score.length); at += 1) {
+        const difference = (b.score[at] ?? 0) - (a.score[at] ?? 0);
+        if (difference !== 0) {
+            return difference;
+        }
+    }
+    return 0;
+};
+// oxlint-disable-next-line no-control-regex -- refusing control characters in an address is the point
+const CONTROL = /[\u0000-\u001f\u007f]/;
+const decode = (segment) => {
+    try {
+        const value = decodeURIComponent(segment);
+        return CONTROL.test(value) ? undefined : value;
+    }
+    catch {
+        return undefined;
+    }
+};
+/** The path's segments decoded once, or `undefined` for a path that is not an address this router would read. */
+export const segmentsOf = (pathname) => {
+    if (!pathname.startsWith("/") || pathname.includes("//") || pathname.length > LIMITS.path) {
+        return undefined;
+    }
+    const trimmed = pathname.length > 1 && pathname.endsWith("/") ? pathname.slice(0, -1) : pathname;
+    const raw = trimmed === "/" ? [] : trimmed.slice(1).split("/");
+    if (raw.length > LIMITS.segments || raw.some((part) => part === "" || part.length > LIMITS.segment)) {
+        return undefined;
+    }
+    const decoded = raw.map(decode);
+    return decoded.every((part) => part !== undefined) ? decoded : undefined;
+};
+/** The values the pattern takes from the segments (as strings, for a Schema to decode), or `undefined` when it does not match. */
+export const matchSegments = (pattern, segments) => {
+    const values = Object.create(null);
+    const last = pattern.segments[pattern.segments.length - 1];
+    const rest = last?.kind === "rest";
+    if (rest ? segments.length < pattern.segments.length : segments.length !== pattern.segments.length) {
+        return undefined;
+    }
+    for (const [at, segment] of pattern.segments.entries()) {
+        if (segment.kind === "literal") {
+            if (segments[at] !== segment.value) {
+                return undefined;
+            }
+        }
+        else if (segment.kind === "param") {
+            values[segment.name] = segments[at];
+        }
+        else {
+            values[segment.name] = segments.slice(at).join("/");
+        }
+    }
+    return values;
+};
+/** The path for `values` (strings), each piece percent-encoded. A missing or empty value is an error: a path with a hole is not an address. */
+export const buildPath = (pattern, values) => {
+    if (pattern.segments.length === 0) {
+        return "/";
+    }
+    return `/${pattern.segments
+        .map((segment) => {
+        if (segment.kind === "literal") {
+            return encodeURIComponent(segment.value);
+        }
+        const value = values[segment.name];
+        if (value === undefined || value === "") {
+            throw new RouteDefinitionError(`the path "${pattern.source}" needs a value for "${segment.name}"`);
+        }
+        return segment.kind === "param" ? encodeURIComponent(value) : value.split("/").map(encodeURIComponent).join("/");
+    })
+        .join("/")}`;
+};

package/dist/route.d.ts

@@ -0,0 +1,58 @@
+import type { Schema } from "effect";
+import type { Pattern } from "./pattern.js";
+import type { Guard, Redirect, TitleContext } from "./types.js";
+/** What a route is configured with. `S` is the application's state, `C` the matching context. */
+export interface RouteConfig<P, Q, S, C> {
+    /** The route's name: unique, and what state, redirects and `href` refer to. */
+    readonly name: string;
+    /** The path parameters. The encoded side is strings (what an address holds); the decoded side is what the application sees. A value that does not decode, or that decodes to something that is not JSON (a `NaN`, a Date), means the route does not match. */
+    readonly params?: Schema.Schema<P, any>;
+    /** The query parameters, the same way. A key that appears more than once arrives as an array of strings. A query that does not decode means the route does not match. */
+    readonly query?: Schema.Schema<Q, any>;
+    /** The document's title for this route: a string, or a function of its parameters. */
+    readonly title?: string | ((context: TitleContext<P, Q>) => string | undefined);
+    /** Static facts about the route for guards to read (`{ requires: "admin" }`). */
+    readonly data?: Readonly<Record<string, unknown>>;
+    /**
+     * A **matching condition**: is this route available here and now at all (a feature flag, the signed-in role)? Synchronous and a function of `context` only, so matching stays a pure function
+     * of the address. A route that is not available is skipped: the address falls to the next candidate, then to not found. Not for conditions that need the application's state or to wait:
+     * those are guards.
+     */
+    readonly canMatch?: (context: C) => boolean;
+    /** Asked before the route is entered. */
+    readonly canActivate?: Guard<S>;
+    /** Asked before the route is left for another route or other parameters (not for a change of query alone): unsaved edits, a running upload. */
+    readonly canDeactivate?: Guard<S>;
+    /** The address is another route's: matching it gives that route's state. */
+    readonly redirectTo?: Redirect;
+    /** `static` (default): the build writes a page for it, for each of `staticParams`, or once when it has none. `client`: only the browser knows these addresses, and the host must serve the app shell for them. */
+    readonly delivery?: "static" | "client";
+    /** The parameter sets to write pages for (a `static` route with parameters). */
+    readonly staticParams?: () => ReadonlyArray<P>;
+    /** A change of the query alone, on the same route and parameters, replaces the history entry instead of adding one (a search box). */
+    readonly replaceQuery?: boolean;
+}
+/** A route: its pattern and its configuration. The type parameters remember what its Schemas decode to, so `href` can be checked. */
+export interface Route<P = Record<string, never>, Q = Record<string, never>, S = any, C = any> {
+    readonly _tag: "Route";
+    readonly pattern: Pattern;
+    readonly config: RouteConfig<P, Q, S, C>;
+    readonly name: string;
+    /** Not present at run time: carries `P` and `Q` for the checker. */
+    readonly types?: {
+        readonly params: P;
+        readonly query: Q;
+    };
+}
+/**
+ * Defines a route.
+ *
+ *     const message = route("/inbox/:id", {
+ *       name: "message",
+ *       params: Schema.Struct({ id: Schema.NumberFromString }),
+ *       query: Schema.Struct({ tab: Schema.optional(Schema.Literal("all", "unread")) }),
+ *       title: ({ params }) => `Message ${params.id}`,
+ *       canDeactivate: ({ state }) => !state.draft.dirty,
+ *     });
+ */
+export declare const route: <P = Record<string, never>, Q = Record<string, never>, S = any, C = any>(path: string, config: RouteConfig<P, Q, S, C>) => Route<P, Q, S, C>;

package/dist/route.js

@@ -0,0 +1,18 @@
+import { parsePattern } from "./pattern.js";
+/**
+ * Defines a route.
+ *
+ *     const message = route("/inbox/:id", {
+ *       name: "message",
+ *       params: Schema.Struct({ id: Schema.NumberFromString }),
+ *       query: Schema.Struct({ tab: Schema.optional(Schema.Literal("all", "unread")) }),
+ *       title: ({ params }) => `Message ${params.id}`,
+ *       canDeactivate: ({ state }) => !state.draft.dirty,
+ *     });
+ */
+export const route = (path, config) => ({
+    _tag: "Route",
+    pattern: parsePattern(path),
+    config,
+    name: config.name,
+});

package/dist/router.d.ts

@@ -0,0 +1,53 @@
+import * as Nexus from "@valancex/nexus";
+import type { Plugin, RouteTable } from "@valancex/valance/web/plugin";
+import { Effect } from "effect";
+import type { Route } from "./route.js";
+import { RouteState } from "./types.js";
+import type { Decision, Guard, NavigationKind } from "./types.js";
+export interface RouterOptions<S, C> {
+    readonly routes: ReadonlyArray<Route<any, any, S, C>>;
+    /** Where the application is served: `/` (default) or `/docs/`. */
+    readonly base?: string;
+    /** What `canMatch` is given. Read for every match, so it must be cheap and synchronous (a role from a store, a feature flag). */
+    readonly context?: () => C;
+    /** The key of the application's state that holds the `RouteState`. Default `route`. */
+    readonly key?: string;
+    /** A guard for every navigation, asked after the route being left and before the route being entered. */
+    readonly beforeEach?: Guard<S>;
+    /** The route state for an address no route matches. Default name `notFound`. */
+    readonly notFound?: {
+        readonly name?: string;
+        readonly title?: string;
+    };
+}
+export declare const createRouter: <S extends Record<string, any>, C = undefined>(options: RouterOptions<S, C>) => {
+    base: string;
+    key: string;
+    notFoundName: string;
+    table: RouteTable<S>;
+    plugin: Plugin<S>;
+    commands: (state: Nexus.State.StateHandle<S>) => {
+        navigate: Nexus.Command.Command<RouteState, void, never, never>;
+        go: Nexus.Command.Command<{
+            readonly to: string;
+        }, void, never, never>;
+        replace: Nexus.Command.Command<{
+            readonly to: string;
+        }, void, never, never>;
+    };
+    match: (address: string) => RouteState;
+    href: <P, Q>(to: Route<P, Q, S, C> | string, params?: P | Readonly<Record<string, unknown>>, query?: Q | Readonly<Record<string, unknown>>) => string;
+    hrefOf: (state: RouteState) => string;
+    resolve: (to: string) => RouteState | undefined;
+    safeNext: (raw: string | null | undefined) => string | undefined;
+    decide: (input: {
+        readonly from: RouteState | undefined;
+        readonly to: RouteState;
+        readonly state: S;
+        readonly kind: NavigationKind;
+    }) => Effect.Effect<Decision>;
+    titleOf: (state: RouteState) => string | undefined;
+    route: (name: string) => Route<any, any, S, C> | undefined;
+    paths: () => ReadonlyArray<string>;
+};
+export type Router<S extends Record<string, any>, C = undefined> = ReturnType<typeof createRouter<S, C>>;

package/dist/router.js

@@ -0,0 +1,390 @@
+// The router: route definitions in, a URL policy for `Web.run` out. It matches an address to a route (path and query parameters decoded by the route's Schemas), builds an address for a route,
+// decides whether a navigation may happen (matching conditions, guards for leaving and entering), titles a route, and offers the two commands that change where the application is.
+import * as Nexus from "@valancex/nexus";
+import { Effect, Either, Schema } from "effect";
+import { runGuard } from "./guards.js";
+import { bySpecificity, buildPath, LIMITS, matchSegments, RouteDefinitionError, segmentsOf } from "./pattern.js";
+import { RouteState } from "./types.js";
+const DEFAULT_KEY = "route";
+const POISON = new Set(["__proto__", "constructor", "prototype"]);
+const MAX_REDIRECTS = 8;
+/** Whether a decoded value can live in the application's state and be embedded in a page: null, booleans, strings, finite numbers, and arrays and plain records of those, to a bounded depth. */
+const jsonSafe = (value, depth = 0) => {
+    if (depth > 8) {
+        return false;
+    }
+    if (value === null || typeof value === "string" || typeof value === "boolean") {
+        return true;
+    }
+    if (typeof value === "number") {
+        return Number.isFinite(value);
+    }
+    if (Array.isArray(value)) {
+        return value.length <= 1024 && value.every((each) => jsonSafe(each, depth + 1));
+    }
+    if (typeof value === "object") {
+        const proto = Object.getPrototypeOf(value);
+        return (proto === Object.prototype || proto === null) && Object.values(value).every((each) => jsonSafe(each, depth + 1));
+    }
+    return false;
+};
+const canonical = (value) => {
+    if (Array.isArray(value)) {
+        return `[${value.map(canonical).join(",")}]`;
+    }
+    if (typeof value === "object" && value !== null) {
+        return `{${Object.keys(value)
+            .sort()
+            .map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(value) ?? "null";
+};
+const Destination = Schema.Struct({ to: Schema.String });
+export const createRouter = (options) => {
+    const base = options.base ?? "/";
+    const key = options.key ?? DEFAULT_KEY;
+    const notFoundName = options.notFound?.name ?? "notFound";
+    if (!/^\/([\w.~-]+\/)*$/.test(base)) {
+        throw new RouteDefinitionError(`the base "${base}" must start and end with "/" ("/" or "/docs/")`);
+    }
+    const byName = new Map();
+    const shapes = new Map();
+    for (const each of options.routes) {
+        if (each.name === notFoundName || byName.has(each.name)) {
+            throw new RouteDefinitionError(`the route name "${each.name}" is ${each.name === notFoundName ? "the not-found name" : "used twice"}`);
+        }
+        if (shapes.has(each.pattern.shape)) {
+            throw new RouteDefinitionError(`the paths "${shapes.get(each.pattern.shape)}" and "${each.pattern.source}" cannot be told apart`);
+        }
+        byName.set(each.name, each);
+        shapes.set(each.pattern.shape, each.pattern.source);
+    }
+    for (const each of options.routes) {
+        if (each.config.redirectTo !== undefined && !byName.has(each.config.redirectTo.name)) {
+            throw new RouteDefinitionError(`the route "${each.name}" redirects to "${each.config.redirectTo.name}", which is not a route`);
+        }
+    }
+    const ranked = [...options.routes]
+        .map((each, at) => ({ each, at }))
+        .sort((a, b) => bySpecificity(a.each.pattern, b.each.pattern) || a.at - b.at)
+        .map(({ each }) => each);
+    // ---- addresses ------------------------------------------------------------------------------------------------------------------------------------------
+    const routeNamed = (name) => byName.get(name);
+    const withBase = (path) => (base === "/" ? path : path === "/" ? base : `${base.slice(0, -1)}${path}`);
+    /** The query as the address holds it: a key once is a string, repeated is an array. Too many keys or too long a value is not an address this router reads. */
+    const readQuery = (search) => {
+        const found = {};
+        let count = 0;
+        for (const [name, value] of search.entries()) {
+            if (POISON.has(name) || value.length > LIMITS.queryValue) {
+                if (POISON.has(name)) {
+                    continue;
+                }
+                return undefined;
+            }
+            const existing = found[name];
+            if (existing === undefined) {
+                count += 1;
+                found[name] = value;
+            }
+            else {
+                found[name] = Array.isArray(existing) ? [...existing, value] : [existing, value];
+            }
+            if (count > LIMITS.queryKeys) {
+                return undefined;
+            }
+        }
+        return found;
+    };
+    const decodeWith = (schema, raw, fallback) => {
+        if (schema === undefined) {
+            return fallback;
+        }
+        const decoded = Schema.decodeUnknownEither(schema)(raw);
+        return Either.isRight(decoded) && jsonSafe(decoded.right) ? decoded.right : undefined;
+    };
+    /** The state for a route's decoded parameters and query, following its `redirectTo`, or `undefined` when it cannot be built. */
+    const settle = (start, params, query, depth = 0) => {
+        const target = start.config.redirectTo;
+        if (target === undefined) {
+            return { name: start.name, params, query };
+        }
+        const next = routeNamed(target.name);
+        return depth >= MAX_REDIRECTS || next === undefined ? undefined : settle(next, target.params, target.query, depth + 1);
+    };
+    const notFoundState = (url) => {
+        const path = `${url.pathname}${url.search}`;
+        return { name: notFoundName, params: { path: path.length <= LIMITS.path && path.startsWith("/") && !path.startsWith("//") ? path : "/" }, query: {} };
+    };
+    /** The route an address belongs to, and the state that says so. `undefined` when none does. */
+    const matchUrl = (url) => {
+        if (!url.pathname.startsWith(base) && url.pathname !== base.slice(0, -1)) {
+            return undefined;
+        }
+        const inside = url.pathname === base.slice(0, -1) ? "/" : `/${url.pathname.slice(base.length)}`;
+        const segments = segmentsOf(inside);
+        const query = readQuery(url.searchParams);
+        if (segments === undefined || query === undefined) {
+            return undefined;
+        }
+        const context = options.context?.();
+        for (const candidate of ranked) {
+            const values = matchSegments(candidate.pattern, segments);
+            if (values === undefined || (candidate.config.canMatch !== undefined && !candidate.config.canMatch(context))) {
+                continue;
+            }
+            const params = decodeWith(candidate.config.params, values, { ...values });
+            const decodedQuery = decodeWith(candidate.config.query, query, {});
+            if (params === undefined || decodedQuery === undefined) {
+                continue;
+            }
+            const state = settle(candidate, params, decodedQuery);
+            if (state !== undefined) {
+                return { route: candidate, state };
+            }
+        }
+        return undefined;
+    };
+    const FALLBACK_ORIGIN = "http://router.invalid";
+    /** The state for an address (a path and query under the base): the route that matches, or not found. */
+    const stateFor = (address) => {
+        const url = new URL(address, FALLBACK_ORIGIN);
+        return matchUrl(url)?.state ?? notFoundState(url);
+    };
+    const encodeWith = (schema, value, what, route) => {
+        if (schema === undefined) {
+            return { ...value };
+        }
+        const encoded = Schema.encodeUnknownEither(schema)(value);
+        if (Either.isLeft(encoded)) {
+            throw new RouteDefinitionError(`the ${what} for route "${route}" do not fit its Schema`);
+        }
+        return encoded.right;
+    };
+    /** The address for a route and its decoded parameters and query: `href(message, { id: 42 }, { tab: "unread" })` is `/inbox/42?tab=unread`. */
+    const href = (to, params, query) => {
+        const target = typeof to === "string" ? routeNamed(to) : to;
+        if (target === undefined) {
+            throw new RouteDefinitionError(`there is no route named "${String(to)}"`);
+        }
+        const strings = {};
+        for (const [name, value] of Object.entries(encodeWith(target.config.params, params ?? {}, "parameters", target.name))) {
+            strings[name] = String(value);
+        }
+        const search = new URLSearchParams();
+        const encoded = encodeWith(target.config.query, query ?? {}, "query", target.name);
+        for (const name of Object.keys(encoded).sort()) {
+            const value = encoded[name];
+            for (const each of Array.isArray(value) ? value : [value]) {
+                if (each !== undefined) {
+                    search.append(name, String(each));
+                }
+            }
+        }
+        const tail = search.toString();
+        return `${withBase(buildPath(target.pattern, strings))}${tail === "" ? "" : `?${tail}`}`;
+    };
+    /** The address a state is at. */
+    const hrefOf = (state) => {
+        if (state.name === notFoundName) {
+            const path = state.params["path"];
+            return typeof path === "string" && path.startsWith("/") && !path.startsWith("//") ? path : base;
+        }
+        return href(state.name, state.params, state.query);
+    };
+    /** The state for an address given as a string on this application (`/inbox/42?tab=unread`, under the base), for programmatic navigation. `undefined` for another origin or a path outside the base. */
+    const resolve = (to) => {
+        let url;
+        try {
+            url = new URL(to, `${FALLBACK_ORIGIN}${base}`);
+        }
+        catch {
+            return undefined;
+        }
+        if (url.origin !== FALLBACK_ORIGIN || to.startsWith("//") || /^[a-z][a-z0-9+.-]*:/i.test(to)) {
+            return undefined;
+        }
+        return matchUrl(url)?.state ?? (url.pathname.startsWith(base) ? notFoundState(url) : undefined);
+    };
+    /** A `?next=`-style address from outside, made safe to navigate to: the address of a declared route on this application, or `undefined`. Never a route that is not declared, never another origin. */
+    const safeNext = (raw) => {
+        if (raw === null || raw === undefined || raw === "" || raw.length > LIMITS.path) {
+            return undefined;
+        }
+        const state = resolve(raw);
+        return state === undefined || state.name === notFoundName ? undefined : hrefOf(state);
+    };
+    const redirectState = (to) => {
+        const target = routeNamed(to.name);
+        if (target === undefined) {
+            return undefined;
+        }
+        try {
+            href(target, to.params, to.query);
+        }
+        catch {
+            return undefined;
+        }
+        return settle(target, to.params, to.query);
+    };
+    // ---- deciding -------------------------------------------------------------------------------------------------------------------------------------------
+    const sameDestination = (a, b) => a.name === b.name && canonical(a.params) === canonical(b.params) && canonical(a.query) === canonical(b.query);
+    /**
+     * May the application go from `from` to `to`? In order: the route being left (`canDeactivate`, when the route or its parameters change, not for a query alone), the router's `beforeEach`,
+     * then the route being entered (`canActivate`). A `Redirect` restarts the entering side at its target, at most eight times. Nothing runs when the destination is where the application already is.
+     */
+    const decide = (input) => Effect.gen(function* () {
+        const { from, state, kind } = input;
+        let to = input.to;
+        if (from !== undefined && sameDestination(from, to)) {
+            return { _tag: "Allow", to };
+        }
+        const context = (route, destination) => ({
+            from,
+            to: destination,
+            state,
+            kind,
+            data: route?.config.data ?? {},
+        });
+        const leaving = from === undefined ? undefined : routeNamed(from.name);
+        if (from !== undefined && leaving?.config.canDeactivate !== undefined && (from.name !== to.name || canonical(from.params) !== canonical(to.params))) {
+            const answer = yield* runGuard(leaving.config.canDeactivate, context(leaving, to));
+            if (answer !== true) {
+                return { _tag: "Refuse", by: "canDeactivate", route: from.name };
+            }
+        }
+        for (let hops = 0;; hops += 1) {
+            if (hops > MAX_REDIRECTS) {
+                return { _tag: "Refuse", by: "redirects", route: to.name };
+            }
+            const entering = routeNamed(to.name);
+            const checks = [
+                [options.beforeEach, "beforeEach", undefined],
+                [entering?.config.canActivate, "canActivate", entering],
+            ];
+            let redirected;
+            for (const [guard, by, owner] of checks) {
+                if (guard === undefined) {
+                    continue;
+                }
+                const answer = yield* runGuard(guard, context(owner, to));
+                if (answer === false) {
+                    return { _tag: "Refuse", by, route: to.name };
+                }
+                if (answer !== true) {
+                    redirected = redirectState(answer);
+                    if (redirected === undefined) {
+                        return { _tag: "Refuse", by, route: to.name };
+                    }
+                    break;
+                }
+            }
+            if (redirected === undefined) {
+                return to === input.to ? { _tag: "Allow", to } : { _tag: "Redirect", to };
+            }
+            to = redirected;
+        }
+    });
+    // ---- what Web.run needs ---------------------------------------------------------------------------------------------------------------------------------
+    const routeOf = (state) => {
+        const value = state[key];
+        return value;
+    };
+    const strip = (state) => ({ name: state.name, params: state.params, query: state.query });
+    const titleOf = (state) => {
+        if (state.name === notFoundName) {
+            return options.notFound?.title;
+        }
+        const found = routeNamed(state.name);
+        const title = found?.config.title;
+        return typeof title === "function" ? title({ params: state.params, query: state.query, data: found?.config.data ?? {} }) : title;
+    };
+    const paths = () => {
+        const out = new Set();
+        for (const each of options.routes) {
+            if (each.config.delivery === "client" || each.config.redirectTo !== undefined) {
+                continue;
+            }
+            if (each.pattern.names.length === 0) {
+                out.add(href(each));
+            }
+            else {
+                for (const params of each.config.staticParams?.() ?? []) {
+                    out.add(href(each, params));
+                }
+            }
+        }
+        return [...out];
+    };
+    const table = {
+        urlOf: (state) => {
+            const current = routeOf(state);
+            return current === undefined ? base : hrefOf(current);
+        },
+        stateOf: (url) => strip(matchUrl(url)?.state ?? notFoundState(url)),
+        navigate: "navigate",
+        known: (pathname) => matchUrl(new URL(pathname, FALLBACK_ORIGIN)) !== undefined,
+        paths,
+        delivery: (pathname) => {
+            const found = matchUrl(new URL(pathname, FALLBACK_ORIGIN));
+            return found?.route.config.delivery === "client" ? "server" : "static";
+        },
+        modeOf: (previous, next) => {
+            const before = routeOf(previous);
+            const after = routeOf(next);
+            if (after?.replace === true) {
+                return "replace";
+            }
+            const route = before === undefined ? undefined : routeNamed(before.name);
+            return before !== undefined &&
+                after !== undefined &&
+                route?.config.replaceQuery === true &&
+                before.name === after.name &&
+                canonical(before.params) === canonical(after.params)
+                ? "replace"
+                : "push";
+        },
+        guard: (navigation, state) => {
+            const from = routeOf(state);
+            const to = matchUrl(navigation.url)?.state ?? notFoundState(navigation.url);
+            return Effect.runPromise(decide({ from, to, state, kind: navigation.kind }).pipe(Effect.map((decision) => (decision._tag === "Allow" ? true : decision._tag === "Redirect" ? { redirect: hrefOf(decision.to) } : false))));
+        },
+    };
+    const plugin = {
+        name: "router",
+        routes: table,
+        head: (state) => {
+            const current = routeOf(state);
+            const title = current === undefined ? undefined : titleOf(current);
+            return title === undefined ? {} : { title };
+        },
+    };
+    /**
+     * The commands the router adds to the application's table:
+     *
+     * - `navigate`: what `Web.run` invokes for a link or Back/Forward once the browser-side guard allowed it. It takes the route state and sets it.
+     * - `go` and `replace`: programmatic navigation to an address, `go({ to: "/inbox/42?tab=unread" })`; `replace` rewrites the current history entry instead of adding one. Each decides first (the guard
+     *   for leaving, then the one for entering), then sets the state; a refusal leaves it where it is. They take one argument so a template can call them: `on.click={go("/inbox")}`.
+     */
+    const moveTo = (state, to, replace) => Effect.gen(function* () {
+        const target = resolve(to);
+        if (target === undefined) {
+            yield* Effect.logWarning("the address is not on this application");
+            return;
+        }
+        const current = yield* state.get;
+        const decision = yield* decide({ from: routeOf(current), to: target, state: current, kind: "programmatic" });
+        if (decision._tag === "Refuse") {
+            return;
+        }
+        const next = decision._tag === "Redirect" ? { ...decision.to, replace: true } : { ...decision.to, ...(replace ? { replace: true } : {}) };
+        yield* state.update((latest) => Effect.succeed({ ...latest, [key]: next }));
+    });
+    const commands = (state) => ({
+        navigate: Nexus.Command.define("navigate", RouteState, (next) => state.update((current) => Effect.succeed({ ...current, [key]: strip(next) })).pipe(Effect.asVoid)),
+        go: Nexus.Command.define("go", Destination, ({ to }) => moveTo(state, to, false)),
+        replace: Nexus.Command.define("replace", Destination, ({ to }) => moveTo(state, to, true)),
+    });
+    return { base, key, notFoundName, table, plugin, commands, match: stateFor, href, hrefOf, resolve, safeNext, decide, titleOf, route: routeNamed, paths };
+};

package/dist/types.d.ts

@@ -0,0 +1,56 @@
+import type { Effect } from "effect";
+import { Schema } from "effect";
+/**
+ * Where the application is: the route's name and its decoded parameters and query. Plain data (it lives in the application's state, and the server embeds it for the browser), so what a
+ * route's Schemas decode to must be JSON: strings, numbers, booleans, null, arrays and records, never a Date or a class.
+ */
+export interface RouteState {
+    readonly name: string;
+    readonly params: Readonly<Record<string, unknown>>;
+    readonly query: Readonly<Record<string, unknown>>;
+    /** Set by programmatic navigation that asked to replace the current entry; read by the router's `modeOf`. Not part of the address. */
+    readonly replace?: boolean;
+}
+export declare const RouteState: Schema.Schema<RouteState>;
+/** Where a navigation came from. */
+export type NavigationKind = "link" | "popstate" | "programmatic";
+/** What a guard is told. `state` is the application's state now, before the navigation. */
+export interface GuardContext<S> {
+    /** The route being left; `undefined` for the first navigation. */
+    readonly from: RouteState | undefined;
+    /** The route being entered. */
+    readonly to: RouteState;
+    readonly state: S;
+    readonly kind: NavigationKind;
+    /** The `data` of the route the guard belongs to. */
+    readonly data: Readonly<Record<string, unknown>>;
+}
+/** Send the navigation to another route instead. Make one with `redirect`. */
+export interface Redirect {
+    readonly _tag: "Redirect";
+    readonly name: string;
+    readonly params: Readonly<Record<string, unknown>>;
+    readonly query: Readonly<Record<string, unknown>>;
+}
+/** `true` lets it through, `false` stops it, a `Redirect` sends it elsewhere. */
+export type GuardResult = boolean | Redirect;
+/** A guard may answer now, later (a Promise) or as an Effect that needs nothing. A throw or a failure counts as `false`. */
+export type Guard<S> = (context: GuardContext<S>) => GuardResult | Promise<GuardResult> | Effect.Effect<GuardResult, unknown>;
+/** What the router decided about one navigation. */
+export type Decision = {
+    readonly _tag: "Allow";
+    readonly to: RouteState;
+} | {
+    readonly _tag: "Redirect";
+    readonly to: RouteState;
+} | {
+    readonly _tag: "Refuse";
+    readonly by: "canDeactivate" | "canActivate" | "beforeEach" | "redirects";
+    readonly route: string;
+};
+/** The data a route's title function sees. */
+export interface TitleContext<P, Q> {
+    readonly params: P;
+    readonly query: Q;
+    readonly data: Readonly<Record<string, unknown>>;
+}

package/dist/types.js

@@ -0,0 +1,7 @@
+import { Schema } from "effect";
+export const RouteState = Schema.Struct({
+    name: Schema.String,
+    params: Schema.Record({ key: Schema.String, value: Schema.Unknown }),
+    query: Schema.Record({ key: Schema.String, value: Schema.Unknown }),
+    replace: Schema.optional(Schema.Boolean),
+});

package/package.json

@@ -1,6 +1,66 @@
 {
   "name": "@valancex/router",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.12.0",
+  "description": "Routing for VALANCE applications: route definitions with typed path and query parameters, matching conditions, guards for entering and leaving a route, programmatic navigation, and a title per route. Plugs into Web.run as the URL policy.",
+  "keywords": [
+    "valance",
+    "router",
+    "routes",
+    "guards"
+  ],
+  "homepage": "https://github.com/ValanceX/Valance/tree/main/packages/router#readme",
+  "bugs": {
+    "url": "https://github.com/ValanceX/Valance/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ValanceX/Valance.git",
+    "directory": "packages/router"
+  },
+  "license": "MIT",
+  "author": "Jack Miller <jackmiller0899@gmail.com>",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@valancex/nexus": "^0.12.0"
+  },
+  "peerDependencies": {
+    "@valancex/valance": "^0.12.0",
+    "effect": "^3.10.0"
+  },
+  "devDependencies": {
+    "@types/jsdom": "^21.1.7",
+    "@types/node": "^22.0.0",
+    "@valancex/mesh-compiler": "^0.11.0",
+    "@valancex/mesh-runtime": "^0.11.0",
+    "@valancex/port-web": "^0.4.0",
+    "effect": "^3.10.0",
+    "jsdom": "^26.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^3.2.0",
+    "@valancex/valance": "^0.12.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.typecheck.json",
+    "test": "vitest run"
+  }
 }