@vizejs/router 0.0.0-stage → 0.714.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ubugeeei
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,70 @@
-# Temporary Holding Version
+# `@vizejs/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.
+> Experimental: the route table, SSR handoff shape, and generated metadata contract may change
+> during the Vize alpha line.
+
+The package is released on npm as `@vizejs/router`; the route and navigation contracts remain
+experimental throughout the Vize alpha line.
+
+`@vizejs/router` provides the first typed route-table kernel for Vize applications. It is
+intentionally SSR-safe: matching and serialization do not touch browser globals, timers, or reactive
+scope state.
+
+```ts
+import { createRouterMatcher, defineRoutes } from "@vizejs/router";
+
+const routes = defineRoutes([
+  { name: "home", path: "/", component: "./routes/home.vue" },
+  { name: "user", path: "/users/:id/:tab?", component: "./routes/user.vue" },
+] as const);
+
+const router = createRouterMatcher(routes);
+const match = router.match("/users/42/settings?from=ssr");
+
+router.resolve("user", { id: "42" });
+```
+
+Route components are declared as `.vue` specifiers. JavaScript render-function component sources are
+not part of this package surface.
+
+SSR integrations can pass `serializeRouteMatch(match, data)` through their own safe serialization
+channel, then call `hydrateRouteState(routes, state, currentUrl)` during client activation. Hydration
+rematches the pathname against the current table and checks route identity, decoded params, query,
+and hash. Malformed or stale handoffs return `undefined`; match and load the current URL afresh in
+that case. The optional third argument checks the activation URL without reading browser globals.
+Omitting it reconciles the serialized pathname and params only; it cannot detect navigation since
+the server render. Query key order is ignored, while repeated-value order is preserved.
+
+## Navigation lifecycle
+
+`createRouter(routes, adapters)` adds cancellable guards, loaders, redirects, stale-result custody,
+history commits, and explicit focus/scroll/announcement effects without reading browser globals.
+Integrations provide the browser or native adapters they support; missing adapters are deliberate
+no-ops rather than implicit global access.
+
+```ts
+import { createRouter } from "@vizejs/router";
+
+const router = createRouter(routes, {
+  history: {
+    push: (url, leaving) => history.pushState(leaving, "", url),
+    replace: (url, leaving) => history.replaceState(leaving, "", url),
+  },
+  announce: (title) => announceRoute(title),
+});
+
+router.beforeEach(({ to }) => (to.meta.requiresAuth && !session.value ? "/login" : undefined));
+await router.navigate({ name: "user", params: { id: "42" } });
+```
+
+Starting a second navigation aborts the first one. A late loader result is reported as `stale` and
+cannot replace current state. Explicit cancellation reports `cancelled`; loader/guard failures
+report `error` and retain the route's optional `.vue` error boundary. History traversal passes saved
+scroll/focus values through `navigate(..., { history: "pop", scroll, focus })`.
+
+## File routes and evidence
+
+`createFileRoutes` maps `index.vue`, `[id].vue`, `[[tab]].vue`, and `[...slug].vue` into explicit
+route records. Each source can override its generated name/path while retaining the same manifest,
+SSR, and navigation contracts. `vp run --filter './npm/compose/router' bench` records cold table
+construction, warm matching, warm navigation, and a 1,000-route table in one machine-readable row.

package/dist/index.d.mts

@@ -0,0 +1,265 @@
+//#region src/types.d.ts
+/** A source-owned Vue route component. */
+type RouteComponentSpecifier = `${string}.vue`;
+/** Serializable metadata attached to a route record. */
+type RouteMeta = Readonly<Record<string, unknown>>;
+/** Query values preserve repeated keys without depending on URLSearchParams at hydration time. */
+type RouteQuery = Readonly<Record<string, string | readonly string[]>>;
+/** Context passed to a route loader. */
+interface RouteLoaderContext<Params = RouteParams> {
+  /** URL pathname that matched the route. */
+  readonly pathname: string;
+  /** Params decoded from dynamic path segments. */
+  readonly params: Params;
+  /** Parsed query string. Repeated keys become arrays in insertion order. */
+  readonly query: RouteQuery;
+  /** Hash without the leading `#`. */
+  readonly hash: string;
+  /** Abort signal owned by the current navigation or server render. */
+  readonly signal?: AbortSignal;
+}
+/** Loader invoked by integrations after a route has matched. */
+type RouteLoader<Params, Data> = (context: RouteLoaderContext<Params>) => Data | Promise<Data>;
+/** Typed route record accepted by defineRoutes. */
+interface RouteDefinition<Name extends string = string, Path extends string = string, Meta extends RouteMeta = RouteMeta, Data = unknown> {
+  /** Literal route name used for typed navigation. */
+  readonly name: Name;
+  /** Absolute path pattern. Dynamic segments use `:id`; optional segments use `:tab?`. */
+  readonly path: Path;
+  /** `.vue` component source for the route. */
+  readonly component: RouteComponentSpecifier;
+  /** Serializable route metadata available on server and client. */
+  readonly meta?: Meta;
+  /** Optional data loader. Its param type is inferred from `path`. */
+  readonly loader?: RouteLoader<Simplify<RoutePathParams<Path>>, Data>;
+  /** Optional redirect evaluated before the loader. */
+  readonly redirect?: RouteRedirect<Simplify<RoutePathParams<Path>>>;
+  /** Source-owned error boundary selected when the loader or a guard fails. */
+  readonly errorComponent?: RouteComponentSpecifier;
+}
+/** Redirect returned by a route record or navigation guard. */
+type RouteRedirect<Params = RouteParams> = string | URL | ((context: RouteLoaderContext<Params>) => string | URL | Promise<string | URL>);
+/** Matched route result shared by server and client runtimes. */
+interface RouteMatch<Route extends RouteDefinition = RouteDefinition> {
+  readonly route: Route;
+  readonly name: Route["name"];
+  readonly pathname: string;
+  readonly params: Simplify<RoutePathParams<Route["path"]>>;
+  readonly query: RouteQuery;
+  readonly hash: string;
+  readonly meta: Route["meta"] extends RouteMeta ? Route["meta"] : RouteMeta;
+}
+/** Serialized route state embedded into SSR HTML and restored during hydration. */
+interface SerializedRouteState<Name extends string = string> {
+  readonly schemaVersion: 1;
+  readonly name: Name;
+  readonly pathname: string;
+  readonly params: RouteParams;
+  readonly query: RouteQuery;
+  readonly hash: string;
+  readonly data?: unknown;
+}
+/** Options for typed URL generation. */
+interface RouteResolveOptions {
+  /**
+   * Query values appended to the generated URL.
+   *
+   * @default {}
+   */
+  readonly query?: Readonly<Record<string, string | number | boolean | readonly (string | number | boolean)[] | null | undefined>>;
+  /**
+   * Hash appended without requiring a leading `#`.
+   *
+   * @default ""
+   */
+  readonly hash?: string;
+}
+/** Machine-readable route manifest for generators and docs. */
+interface RouteManifest {
+  readonly schemaVersion: 1;
+  readonly routes: readonly RouteManifestEntry[];
+}
+/** Serializable manifest row for one route. */
+interface RouteManifestEntry {
+  readonly name: string;
+  readonly path: string;
+  readonly component: RouteComponentSpecifier;
+  readonly meta: RouteMeta;
+  readonly errorComponent?: RouteComponentSpecifier;
+}
+/** A named, type-safe navigation target. */
+type NamedRouteLocation<Routes extends readonly RouteDefinition[], Name extends RouteNames<Routes> = RouteNames<Routes>> = Name extends RouteNames<Routes> ? {
+  readonly name: Name;
+  readonly params: RouteParamsForName<Routes, Name>;
+  readonly query?: RouteResolveOptions["query"];
+  readonly hash?: string;
+} : never;
+/** Input accepted by the navigation lifecycle. */
+type RouteLocation<Routes extends readonly RouteDefinition[]> = string | URL | NamedRouteLocation<Routes>;
+/** History operation performed after a successful navigation. */
+type NavigationHistoryMode = "push" | "replace" | "pop" | "none";
+/** Observable phase of the router navigation lifecycle. */
+type NavigationStatus = "idle" | "pending" | "success" | "cancelled" | "stale" | "error";
+/** Per-navigation history, scroll, and focus behavior. */
+interface NavigationOptions {
+  /** History behavior after a successful navigation. @default "push" */
+  readonly history?: NavigationHistoryMode;
+  /** Scroll snapshot restored for a history traversal. @default undefined */
+  readonly scroll?: unknown;
+  /** Focus snapshot restored for a history traversal. @default undefined */
+  readonly focus?: unknown;
+}
+/** Stable inputs supplied to each registered navigation guard. */
+interface NavigationContext<Routes extends readonly RouteDefinition[]> {
+  readonly from: RouteMatch<Routes[number]> | undefined;
+  readonly to: RouteMatch<Routes[number]>;
+  readonly signal: AbortSignal;
+}
+/** Result accepted from a navigation guard. */
+type NavigationGuardResult<Routes extends readonly RouteDefinition[]> = void | true | false | RouteLocation<Routes>;
+/** Guard that can continue, cancel, or redirect a navigation. */
+type NavigationGuard<Routes extends readonly RouteDefinition[]> = (context: NavigationContext<Routes>) => NavigationGuardResult<Routes> | Promise<NavigationGuardResult<Routes>>;
+/** Terminal result returned to the caller that started a navigation. */
+type NavigationResult<Routes extends readonly RouteDefinition[]> = {
+  readonly status: "success";
+  readonly match: RouteMatch<Routes[number]>;
+  readonly data: unknown;
+  readonly redirected: boolean;
+} | {
+  readonly status: "cancelled" | "stale";
+  readonly match?: RouteMatch<Routes[number]>;
+} | {
+  readonly status: "error";
+  readonly match?: RouteMatch<Routes[number]>;
+  readonly error: unknown;
+  readonly errorComponent?: RouteComponentSpecifier;
+};
+/** Current observable state, including the route that owns pending work. */
+interface RouterNavigationState<Routes extends readonly RouteDefinition[]> {
+  readonly status: NavigationStatus;
+  readonly current: RouteMatch<Routes[number]> | undefined;
+  readonly pending: RouteMatch<Routes[number]> | undefined;
+  readonly data: unknown;
+  readonly error: unknown;
+}
+/** Explicit history boundary used by browser and non-browser hosts. */
+interface RouterHistoryAdapter {
+  readonly push: (url: string, leaving: RouterHistorySnapshot) => void | Promise<void>;
+  readonly replace: (url: string, leaving: RouterHistorySnapshot) => void | Promise<void>;
+}
+/** Host-owned focus and scroll state retained in a history entry. */
+interface RouterHistorySnapshot {
+  readonly scroll?: unknown;
+  readonly focus?: unknown;
+}
+/** Focus custody supplied by a navigation host. */
+interface RouterFocusAdapter {
+  readonly capture?: () => unknown;
+  readonly restore?: (snapshot: unknown) => void | Promise<void>;
+  readonly focusMain?: (match: RouteMatch) => void | Promise<void>;
+}
+/** Scroll custody supplied by a navigation host. */
+interface RouterScrollAdapter {
+  readonly capture?: () => unknown;
+  readonly restore?: (snapshot: unknown) => void | Promise<void>;
+  readonly top?: (match: RouteMatch) => void | Promise<void>;
+}
+/** Host adapters and lifecycle defaults used by createRouter. */
+interface RouterNavigationOptions<Routes extends readonly RouteDefinition[]> {
+  /** Initial URL to match without running loaders or guards. @default undefined */
+  readonly initial?: string | URL;
+  /** History writer. Omission keeps navigation history side-effect free. @default undefined */
+  readonly history?: RouterHistoryAdapter;
+  /** Focus capture and restoration adapter. @default undefined */
+  readonly focus?: RouterFocusAdapter;
+  /** Scroll capture and restoration adapter. @default undefined */
+  readonly scroll?: RouterScrollAdapter;
+  /** Accessible route announcement hook. @default undefined */
+  readonly announce?: (message: string, match: RouteMatch<Routes[number]>) => void | Promise<void>;
+  /** Maximum redirect chain before failing closed. @default 16 */
+  readonly maxRedirects?: number;
+}
+/** Stateful navigation facade produced by createRouter. */
+interface Router<Routes extends readonly RouteDefinition[]> {
+  readonly matcher: RouterMatcher<Routes>;
+  readonly state: () => RouterNavigationState<Routes>;
+  readonly navigate: (location: RouteLocation<Routes>, options?: NavigationOptions) => Promise<NavigationResult<Routes>>;
+  readonly beforeEach: (guard: NavigationGuard<Routes>) => () => void;
+  readonly subscribe: (listener: (state: RouterNavigationState<Routes>) => void) => () => void;
+  readonly cancel: (reason?: unknown) => void;
+}
+/** Source row used by the file-route generator. */
+interface FileRouteSource {
+  readonly file: RouteComponentSpecifier;
+  readonly name?: string;
+  readonly path?: string;
+  readonly meta?: RouteMeta;
+  readonly loader?: RouteLoader<RouteParams, unknown>;
+  readonly redirect?: RouteRedirect<RouteParams>;
+  readonly errorComponent?: RouteComponentSpecifier;
+}
+/** Matcher produced by createRouterMatcher. */
+interface RouterMatcher<Routes extends readonly RouteDefinition[]> {
+  readonly routes: Routes;
+  readonly match: (input: string | URL) => RouteMatch<Routes[number]> | undefined;
+  readonly manifest: () => RouteManifest;
+  readonly resolve: <Name extends RouteNames<Routes>>(name: Name, params: RouteParamsForName<Routes, Name>, options?: RouteResolveOptions) => string;
+}
+/** Literal names available in a route table. */
+type RouteNames<Routes extends readonly RouteDefinition[]> = Routes[number]["name"];
+/** Route record selected by literal name. */
+type RouteByName<Routes extends readonly RouteDefinition[], Name extends RouteNames<Routes>> = Extract<Routes[number], {
+  readonly name: Name;
+}>;
+/** Params required by the route with `Name`. */
+type RouteParamsForName<Routes extends readonly RouteDefinition[], Name extends RouteNames<Routes>> = RouteByName<Routes, Name> extends RouteDefinition<string, infer Path> ? Simplify<RoutePathParams<Path>> : never;
+/** Param object inferred from a path pattern. */
+type RoutePathParams<Path extends string> = Path extends `${infer Head}/${infer Tail}` ? Simplify<SegmentParams<Head> & RoutePathParams<Tail>> : SegmentParams<Path>;
+/** Generic decoded route-param record used when no literal path is available. */
+type RouteParams = Readonly<Record<string, string | undefined>>;
+type SegmentParams<Segment extends string> = Segment extends `:${infer Name}?` ? { readonly [Key in CleanParamName<Name>]?: string } : Segment extends `:${infer Name}` ? { readonly [Key in CleanParamName<Name>]: string } : Segment extends `*${infer Name}` ? { readonly [Key in CleanParamName<Name>]: string } : {};
+type CleanParamName<Name extends string> = Name extends "" ? never : Name;
+/** Materialize an inferred intersection as one readonly object type. */
+type Simplify<T> = { readonly [Key in keyof T]: T[Key] } & {};
+/** Internal matcher row exposed for generator and adapter integrations. */
+interface CompiledRoute<Route extends RouteDefinition = RouteDefinition> {
+  readonly route: Route;
+  readonly pattern: RegExp;
+  readonly params: readonly string[];
+}
+//#endregion
+//#region src/file-routes.d.ts
+/** Generate route records from source-owned `.vue` route modules. */
+declare function createFileRoutes(sources: readonly FileRouteSource[]): readonly RouteDefinition[];
+/** Convert `routes/users/[id].vue` into `/users/:id`. */
+declare function routePathFromFile(file: `${string}.vue`): string;
+/** Produce a stable manifest name from a file route. */
+declare function routeNameFromFile(file: `${string}.vue`): string;
+//#endregion
+//#region src/navigation.d.ts
+/**
+ * Create an SSR-safe navigation lifecycle around a literal route table.
+ *
+ * Browser history, focus, scrolling, and announcements are explicit adapters;
+ * importing or constructing a router never reads browser globals.
+ */
+declare function createRouter<const Routes extends readonly RouteDefinition[]>(routes: Routes, options?: RouterNavigationOptions<Routes>): Router<Routes>;
+//#endregion
+//#region src/runtime.d.ts
+/** Define a literal route table and fail closed on duplicate or unsupported rows. */
+declare function defineRoutes<const Routes extends readonly RouteDefinition[]>(routes: Routes): Routes;
+/** Define one route record while preserving loader param inference from its path. */
+declare function defineRoute<const Name extends string, const Path extends string, const Meta extends Readonly<Record<string, unknown>> = Readonly<Record<string, unknown>>, Data = unknown>(route: RouteDefinition<Name, Path, Meta, Data>): RouteDefinition<Name, Path, Meta, Data>;
+/** Create an SSR-safe matcher and typed URL resolver for a route table. */
+declare function createRouterMatcher<const Routes extends readonly RouteDefinition[]>(routes: Routes): RouterMatcher<Routes>;
+/** Emit serializable metadata for generators, docs, and devtools. */
+declare function createRouteManifest<const Routes extends readonly RouteDefinition[]>(routes: Routes): RouteManifest;
+/** Serialize a route match for SSR handoff. */
+declare function serializeRouteMatch<Route extends RouteDefinition>(match: RouteMatch<Route>, data?: unknown): SerializedRouteState<Route["name"]>;
+/**
+ * Reconcile SSR state with the client table, optionally checking the activation URL.
+ * Returns undefined for stale or malformed state; integrations must match/load afresh.
+ */
+declare function hydrateRouteState<const Routes extends readonly RouteDefinition[]>(routes: Routes, state: SerializedRouteState<RouteNames<Routes>>, input?: string | URL): RouteMatch<Routes[number]> | undefined;
+//#endregion
+export { CompiledRoute, FileRouteSource, NamedRouteLocation, NavigationContext, NavigationGuard, NavigationGuardResult, NavigationHistoryMode, NavigationOptions, NavigationResult, NavigationStatus, RouteByName, RouteComponentSpecifier, RouteDefinition, RouteLoader, RouteLoaderContext, RouteLocation, RouteManifest, RouteManifestEntry, RouteMatch, RouteMeta, RouteNames, RouteParams, RouteParamsForName, RoutePathParams, RouteQuery, RouteRedirect, RouteResolveOptions, Router, RouterFocusAdapter, RouterHistoryAdapter, RouterHistorySnapshot, RouterMatcher, RouterNavigationOptions, RouterNavigationState, RouterScrollAdapter, SerializedRouteState, Simplify, createFileRoutes, createRouteManifest, createRouter, createRouterMatcher, defineRoute, defineRoutes, hydrateRouteState, routeNameFromFile, routePathFromFile, serializeRouteMatch };

package/dist/index.mjs

@@ -0,0 +1,468 @@
+//#region src/runtime.ts
+const ROUTER_ERROR = {
+	duplicateName: "VIZE_ROUTER_DUPLICATE_NAME",
+	duplicatePath: "VIZE_ROUTER_DUPLICATE_PATH",
+	invalidComponent: "VIZE_ROUTER_COMPONENT_NOT_VUE",
+	invalidPath: "VIZE_ROUTER_INVALID_PATH",
+	missingParam: "VIZE_ROUTER_MISSING_PARAM",
+	unknownRoute: "VIZE_ROUTER_UNKNOWN_ROUTE"
+};
+/** Define a literal route table and fail closed on duplicate or unsupported rows. */
+function defineRoutes(routes) {
+	validateRoutes(routes);
+	return routes;
+}
+/** Define one route record while preserving loader param inference from its path. */
+function defineRoute(route) {
+	validateRoutes([route]);
+	return route;
+}
+/** Create an SSR-safe matcher and typed URL resolver for a route table. */
+function createRouterMatcher(routes) {
+	validateRoutes(routes);
+	const compiled = routes.map((route) => ({
+		route,
+		...compilePath(route.path)
+	}));
+	return {
+		routes,
+		match(input) {
+			const url = toUrl(input);
+			for (const candidate of compiled) {
+				const matched = candidate.pattern.exec(url.pathname);
+				if (!matched) continue;
+				const params = Object.fromEntries(candidate.params.flatMap((name, index) => {
+					const value = matched[index + 1];
+					return value == null ? [] : [[name, decodeURIComponent(value)]];
+				}));
+				return {
+					route: candidate.route,
+					name: candidate.route.name,
+					pathname: url.pathname,
+					params,
+					query: parseQuery(url.searchParams),
+					hash: url.hash.startsWith("#") ? url.hash.slice(1) : url.hash,
+					meta: candidate.route.meta ?? {}
+				};
+			}
+		},
+		manifest: () => createRouteManifest(routes),
+		resolve(name, params, options) {
+			const route = routes.find((candidate) => candidate.name === name);
+			if (!route) throw new Error(`[${ROUTER_ERROR.unknownRoute}] Unknown route ${String(name)}`);
+			return `${buildPath(route.path, params)}${stringifyQuery(options?.query)}${stringifyHash(options?.hash)}`;
+		}
+	};
+}
+/** Emit serializable metadata for generators, docs, and devtools. */
+function createRouteManifest(routes) {
+	validateRoutes(routes);
+	return {
+		schemaVersion: 1,
+		routes: routes.map((route) => ({
+			name: route.name,
+			path: route.path,
+			component: route.component,
+			meta: route.meta ?? {},
+			...route.errorComponent === void 0 ? {} : { errorComponent: route.errorComponent }
+		}))
+	};
+}
+/** Serialize a route match for SSR handoff. */
+function serializeRouteMatch(match, data) {
+	return {
+		schemaVersion: 1,
+		name: match.name,
+		pathname: match.pathname,
+		params: match.params,
+		query: match.query,
+		hash: match.hash,
+		...data === void 0 ? {} : { data }
+	};
+}
+/**
+* Reconcile SSR state with the client table, optionally checking the activation URL.
+* Returns undefined for stale or malformed state; integrations must match/load afresh.
+*/
+function hydrateRouteState(routes, state, input) {
+	if (!state || state.schemaVersion !== 1 || typeof state.name !== "string" || typeof state.pathname !== "string" || !state.pathname.startsWith("/") || state.pathname.startsWith("//") || typeof state.hash !== "string" || !isRecord(state.params) || !isRecord(state.query) || !Object.values(state.params).every((value) => value === void 0 || typeof value === "string") || !Object.values(state.query).every((value) => typeof value === "string" || Array.isArray(value) && value.every((item) => typeof item === "string"))) return void 0;
+	const matcher = createRouterMatcher(routes);
+	try {
+		const match = matcher.match(state.pathname);
+		const params = Object.fromEntries(Object.entries(state.params).filter(([, value]) => value !== void 0));
+		if (!match || match.name !== state.name || match.pathname !== state.pathname || !sameRecord(match.params, params)) return void 0;
+		if (input !== void 0) {
+			const current = matcher.match(input);
+			if (!current || current.name !== match.name || current.pathname !== match.pathname || current.hash !== state.hash || !sameRecord(current.query, state.query)) return void 0;
+		}
+		return {
+			...match,
+			query: state.query,
+			hash: state.hash
+		};
+	} catch (error) {
+		if (error instanceof URIError || error instanceof TypeError) return void 0;
+		throw error;
+	}
+}
+function isRecord(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function sameRecord(left, right) {
+	const entries = Object.entries(left);
+	return entries.length === Object.keys(right).length && entries.every(([key, value]) => {
+		if (!Object.hasOwn(right, key)) return false;
+		const other = right[key];
+		return Array.isArray(value) ? Array.isArray(other) && value.length === other.length && value.every((item, index) => item === other[index]) : value === other;
+	});
+}
+function validateRoutes(routes) {
+	const names = /* @__PURE__ */ new Set();
+	const paths = /* @__PURE__ */ new Set();
+	for (const route of routes) {
+		if (!route.path.startsWith("/")) throw new Error(`[${ROUTER_ERROR.invalidPath}] Route ${route.name} path must start with /`);
+		if (!route.component.endsWith(".vue")) throw new Error(`[${ROUTER_ERROR.invalidComponent}] Route ${route.name} must use a .vue component`);
+		if (route.errorComponent !== void 0 && !route.errorComponent.endsWith(".vue")) throw new Error(`[${ROUTER_ERROR.invalidComponent}] Route ${route.name} error boundary must use a .vue component`);
+		if (names.has(route.name)) throw new Error(`[${ROUTER_ERROR.duplicateName}] Duplicate route name ${route.name}`);
+		if (paths.has(route.path)) throw new Error(`[${ROUTER_ERROR.duplicatePath}] Duplicate route path ${route.path}`);
+		names.add(route.name);
+		paths.add(route.path);
+	}
+}
+function compilePath(pathPattern) {
+	if (pathPattern === "/") return {
+		pattern: /^\/$/,
+		params: []
+	};
+	const params = [];
+	const source = pathPattern.split("/").filter(Boolean).map((segment) => {
+		if (segment.startsWith(":")) {
+			const optional = segment.endsWith("?");
+			const name = segment.slice(1, optional ? -1 : void 0);
+			params.push(name);
+			return optional ? "(?:/([^/]+))?" : "/([^/]+)";
+		}
+		if (segment.startsWith("*")) {
+			const name = segment.slice(1);
+			params.push(name);
+			return "/(.+)";
+		}
+		return `/${escapeRegExp(segment)}`;
+	}).join("");
+	return {
+		pattern: new RegExp(`^${source}$`),
+		params
+	};
+}
+function buildPath(pathPattern, params) {
+	if (pathPattern === "/") return "/";
+	return `/${pathPattern.split("/").filter(Boolean).flatMap((segment) => {
+		if (!segment.startsWith(":") && !segment.startsWith("*")) return [segment];
+		const optional = segment.endsWith("?");
+		const name = segment.slice(segment.startsWith(":") ? 1 : 1, optional ? -1 : void 0);
+		const value = params[name];
+		if (value == null) {
+			if (optional) return [];
+			throw new Error(`[${ROUTER_ERROR.missingParam}] Missing route param ${name}`);
+		}
+		return [segment.startsWith("*") ? value.split("/").map(encodeURIComponent).join("/") : encodeURIComponent(value)];
+	}).join("/")}`;
+}
+function toUrl(input) {
+	return input instanceof URL ? input : new URL(input, "https://vize.local");
+}
+function parseQuery(searchParams) {
+	const query = /* @__PURE__ */ new Map();
+	for (const [key, value] of searchParams) {
+		const current = query.get(key);
+		if (current == null) query.set(key, value);
+		else if (Array.isArray(current)) current.push(value);
+		else query.set(key, [current, value]);
+	}
+	return Object.fromEntries(query);
+}
+function stringifyQuery(query) {
+	if (!query) return "";
+	const search = new URLSearchParams();
+	for (const [key, value] of Object.entries(query)) {
+		if (value == null) continue;
+		const values = Array.isArray(value) ? value : [value];
+		for (const item of values) search.append(key, String(item));
+	}
+	const text = search.toString();
+	return text === "" ? "" : `?${text}`;
+}
+function stringifyHash(hash) {
+	if (!hash) return "";
+	return hash.startsWith("#") ? hash : `#${hash}`;
+}
+function escapeRegExp(value) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+//#endregion
+//#region src/file-routes.ts
+/** Generate route records from source-owned `.vue` route modules. */
+function createFileRoutes(sources) {
+	return defineRoutes(sources.map((source) => ({
+		name: source.name ?? routeNameFromFile(source.file),
+		path: source.path ?? routePathFromFile(source.file),
+		component: source.file,
+		...source.meta === void 0 ? {} : { meta: source.meta },
+		...source.loader === void 0 ? {} : { loader: source.loader },
+		...source.redirect === void 0 ? {} : { redirect: source.redirect },
+		...source.errorComponent === void 0 ? {} : { errorComponent: source.errorComponent }
+	})));
+}
+/** Convert `routes/users/[id].vue` into `/users/:id`. */
+function routePathFromFile(file) {
+	const segments = routeSegments(file).flatMap((segment) => {
+		if (segment === "index") return [];
+		const rest = segment.match(/^\[\.\.\.([^\]]+)\]$/u);
+		if (rest?.[1]) return [`*${rest[1]}`];
+		const optional = segment.match(/^\[\[([^\]]+)\]\]$/u);
+		if (optional?.[1]) return [`:${optional[1]}?`];
+		const dynamic = segment.match(/^\[([^\]]+)\]$/u);
+		if (dynamic?.[1]) return [`:${dynamic[1]}`];
+		return [segment];
+	});
+	return segments.length === 0 ? "/" : `/${segments.join("/")}`;
+}
+/** Produce a stable manifest name from a file route. */
+function routeNameFromFile(file) {
+	const segments = routeSegments(file).filter((segment) => segment !== "index").map((segment) => segment.replace(/^\[+\.\.\./u, "").replace(/^\[+/u, "").replace(/\]+$/u, ""));
+	return segments.length === 0 ? "index" : segments.join("-");
+}
+function routeSegments(file) {
+	const normalized = file.replaceAll("\\", "/").replace(/^\.\//u, "");
+	const routeRoot = normalized.lastIndexOf("/routes/");
+	return (routeRoot === -1 ? normalized.replace(/^routes\//u, "") : normalized.slice(routeRoot + 8)).slice(0, -4).split("/").filter(Boolean);
+}
+//#endregion
+//#region src/navigation.ts
+const MAX_REDIRECTS = 16;
+/**
+* Create an SSR-safe navigation lifecycle around a literal route table.
+*
+* Browser history, focus, scrolling, and announcements are explicit adapters;
+* importing or constructing a router never reads browser globals.
+*/
+function createRouter(routes, options = {}) {
+	const matcher = createRouterMatcher(routes);
+	const guards = /* @__PURE__ */ new Set();
+	const listeners = /* @__PURE__ */ new Set();
+	let revision = 0;
+	let active;
+	let state = {
+		status: "idle",
+		current: options.initial === void 0 ? void 0 : matcher.match(options.initial),
+		pending: void 0,
+		data: void 0,
+		error: void 0
+	};
+	const publish = (next) => {
+		state = next;
+		for (const listener of listeners) listener(state);
+	};
+	return {
+		matcher,
+		state: () => state,
+		beforeEach(guard) {
+			guards.add(guard);
+			return () => guards.delete(guard);
+		},
+		subscribe(listener) {
+			listeners.add(listener);
+			return () => listeners.delete(listener);
+		},
+		cancel(reason) {
+			active?.abort(reason ?? /* @__PURE__ */ new Error("Navigation cancelled"));
+		},
+		async navigate(location, navigationOptions = {}) {
+			const navigationRevision = ++revision;
+			active?.abort(/* @__PURE__ */ new Error("Navigation superseded"));
+			const controller = new AbortController();
+			active = controller;
+			const initial = resolveLocation(matcher, location);
+			if (!initial) {
+				const result = {
+					status: "error",
+					error: /* @__PURE__ */ new Error(`No route matches ${locationLabel(location)}`)
+				};
+				publish({
+					...state,
+					status: "error",
+					pending: void 0,
+					error: result.error
+				});
+				return result;
+			}
+			let resolved = initial;
+			publish({
+				...state,
+				status: "pending",
+				pending: resolved.match,
+				error: void 0
+			});
+			let redirected = false;
+			try {
+				for (let redirectCount = 0; redirectCount <= (options.maxRedirects ?? MAX_REDIRECTS); redirectCount += 1) {
+					if (isStale(navigationRevision, revision, controller.signal)) return finishInterrupted(navigationRevision, revision, state, publish);
+					const guarded = await runGuards(guards, navigationContext(state.current, resolved.match, controller.signal));
+					if (guarded === false) {
+						publish({
+							...state,
+							status: "cancelled",
+							pending: void 0,
+							error: void 0
+						});
+						return {
+							status: "cancelled",
+							match: resolved.match
+						};
+					}
+					if (isRouteLocation(guarded)) {
+						const next = resolveLocation(matcher, guarded);
+						if (!next) throw new Error(`Redirect does not match a route: ${locationLabel(guarded)}`);
+						resolved = next;
+						redirected = true;
+						publish({
+							...state,
+							status: "pending",
+							pending: resolved.match,
+							error: void 0
+						});
+						continue;
+					}
+					const redirect = resolved.match.route.redirect;
+					if (redirect !== void 0) {
+						const nextLocation = typeof redirect === "function" ? await redirect(loaderContext(resolved.match, controller.signal)) : redirect;
+						const next = resolveLocation(matcher, nextLocation);
+						if (!next) throw new Error(`Redirect does not match a route: ${String(nextLocation)}`);
+						resolved = next;
+						redirected = true;
+						publish({
+							...state,
+							status: "pending",
+							pending: resolved.match,
+							error: void 0
+						});
+						continue;
+					}
+					const data = resolved.match.route.loader === void 0 ? void 0 : await resolved.match.route.loader(loaderContext(resolved.match, controller.signal));
+					if (isStale(navigationRevision, revision, controller.signal)) return finishInterrupted(navigationRevision, revision, state, publish);
+					await commitNavigation(options, resolved.url, resolved.match, navigationOptions);
+					publish({
+						status: "success",
+						current: resolved.match,
+						pending: void 0,
+						data,
+						error: void 0
+					});
+					return {
+						status: "success",
+						match: resolved.match,
+						data,
+						redirected
+					};
+				}
+				throw new Error(`Redirect limit exceeded (${options.maxRedirects ?? MAX_REDIRECTS})`);
+			} catch (error) {
+				if (isStale(navigationRevision, revision, controller.signal)) return finishInterrupted(navigationRevision, revision, state, publish);
+				publish({
+					...state,
+					status: "error",
+					pending: void 0,
+					error
+				});
+				return {
+					status: "error",
+					match: resolved.match,
+					error,
+					...resolved.match.route.errorComponent === void 0 ? {} : { errorComponent: resolved.match.route.errorComponent }
+				};
+			} finally {
+				if (active === controller) active = void 0;
+			}
+		}
+	};
+}
+function resolveLocation(matcher, location) {
+	const url = isNamedLocation(location) ? matcher.resolve(location.name, location.params, {
+		...location.query === void 0 ? {} : { query: location.query },
+		...location.hash === void 0 ? {} : { hash: location.hash }
+	}) : location instanceof URL ? `${location.pathname}${location.search}${location.hash}` : location;
+	const match = matcher.match(url);
+	return match === void 0 ? void 0 : {
+		match,
+		url
+	};
+}
+function isNamedLocation(location) {
+	return typeof location === "object" && !(location instanceof URL) && "name" in location;
+}
+function locationLabel(location) {
+	if (typeof location === "string") return location;
+	if (location instanceof URL) return location.href;
+	return location.name;
+}
+function isRouteLocation(value) {
+	return typeof value === "string" || value instanceof URL || value !== null && typeof value === "object" && "name" in value;
+}
+function navigationContext(from, to, signal) {
+	return {
+		from,
+		to,
+		signal
+	};
+}
+function loaderContext(match, signal) {
+	return {
+		pathname: match.pathname,
+		params: match.params,
+		query: match.query,
+		hash: match.hash,
+		signal
+	};
+}
+async function runGuards(guards, context) {
+	for (const guard of guards) {
+		const result = await guard(context);
+		if (result === false || isRouteLocation(result)) return result;
+	}
+}
+function isStale(current, revision, signal) {
+	return current !== revision || signal.aborted;
+}
+function finishInterrupted(current, revision, state, publish) {
+	const status = current === revision ? "cancelled" : "stale";
+	if (current === revision) publish({
+		...state,
+		status,
+		pending: void 0,
+		error: void 0
+	});
+	return {
+		status,
+		...state.pending === void 0 ? {} : { match: state.pending }
+	};
+}
+async function commitNavigation(options, url, match, navigation) {
+	const history = navigation.history ?? "push";
+	const leaving = {
+		...options.scroll?.capture === void 0 ? {} : { scroll: options.scroll.capture() },
+		...options.focus?.capture === void 0 ? {} : { focus: options.focus.capture() }
+	};
+	if (history === "push") await options.history?.push(url, leaving);
+	if (history === "replace") await options.history?.replace(url, leaving);
+	if (history === "pop") {
+		if (navigation.scroll !== void 0) await options.scroll?.restore?.(navigation.scroll);
+		if (navigation.focus !== void 0) await options.focus?.restore?.(navigation.focus);
+	} else {
+		await options.scroll?.top?.(match);
+		await options.focus?.focusMain?.(match);
+	}
+	const title = typeof match.meta?.title === "string" ? match.meta.title : match.name;
+	await options.announce?.(title, match);
+}
+//#endregion
+export { createFileRoutes, createRouteManifest, createRouter, createRouterMatcher, defineRoute, defineRoutes, hydrateRouteState, routeNameFromFile, routePathFromFile, serializeRouteMatch };

package/package.json

@@ -1,6 +1,65 @@
 {
   "name": "@vizejs/router",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.714.0",
+  "description": "Strongly typed SSR router foundations for Vize applications",
+  "keywords": [
+    "router",
+    "ssr",
+    "type-safe",
+    "vize",
+    "vue"
+  ],
+  "homepage": "https://github.com/ubugeeei-prod/vize",
+  "bugs": {
+    "url": "https://github.com/ubugeeei-prod/vize/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ubugeeei-prod/vize.git",
+    "directory": "npm/compose/router"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "25.9.2",
+    "tsdown": "0.22.14",
+    "typescript": "6.0.3",
+    "vite-plus": "0.1.24"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "metadata": {
+    "vize": {
+      "stability": "experimental",
+      "stabilityDocs": "https://github.com/ubugeeei-prod/vize/blob/main/docs/content/stability.md#package-support-tiers"
+    }
+  },
+  "scripts": {
+    "build": "vp pack",
+    "bench": "vp exec node --test src/benchmark.test.ts",
+    "dev": "vp pack --watch",
+    "test": "vp exec node --test 'src/**/*.test.ts'",
+    "check": "vp check src vite.config.ts && vp exec tsc --noEmit -p tsconfig.json",
+    "check:fix": "vp check --fix src vite.config.ts",
+    "check:types": "vp exec tsc --noEmit -p tsconfig.json",
+    "fmt": "vp fmt --write src vite.config.ts"
+  }
 }