@rivetjs/router 0.0.0-stage → 0.1.0-alpha.0

package/cli/rivet.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/cli/rivet.js

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+// Rivet router CLI.
+//   rivet sync [--root <dir>] [--config <vite config>] [--mode <mode>]
+//     Write the app's generated `.rivet/` files (route types, generated app, editor manifest) from its
+//     Vite config without starting Vite. Run before `tsc` / `rivet-check` on a fresh clone.
+//   rivet migrate server-exports [--routes src/routes] [--dry-run]
+//     Rename old `*.server.ts` export names (load, guard, actions, entries, headers, GET…) to
+//     serverLoad, serverGuard, serverActions, serverEntries, serverHeaders, onGet… (scope-aware).
+//   rivet mcp
+//     Start the Rivet MCP server (`@rivetjs/mcp`, stdio) installed in the app; same as `npx @rivetjs/mcp`.
+import { relative } from "node:path";
+const USAGE = `usage: rivet sync [--root <dir>] [--config <file>] [--mode <mode>]
+       rivet migrate server-exports [--routes <dir>] [--dry-run]
+       rivet mcp`;
+async function syncCommand(args) {
+    const options = {};
+    for (let i = 0; i < args.length; i++) {
+        const [flag, value] = [args[i], args[i + 1]];
+        if (value === undefined || !["--root", "--config", "--mode"].includes(flag)) {
+            console.error(USAGE);
+            return 2;
+        }
+        options[flag === "--root" ? "root" : flag === "--config" ? "configFile" : "mode"] = value;
+        i++;
+    }
+    const { sync } = await import("../build/sync.js");
+    const result = await sync(options);
+    const where = relative(process.cwd(), result.root) || ".";
+    if (!result.configFile) {
+        console.error(`rivet sync: no Vite config in ${where}`);
+        return 2;
+    }
+    if (!result.manifest) {
+        console.error(`rivet sync: ${relative(process.cwd(), result.configFile)} uses no Rivet Vite plugin (nothing generated)`);
+        return 2;
+    }
+    const routes = result.manifest.routes?.length ?? 0;
+    const resume = result.manifest.resumeModules?.length ?? 0;
+    console.log(`rivet sync: ${where}/.rivet (${routes} route${routes === 1 ? "" : "s"}, ${resume} resume module${resume === 1 ? "" : "s"})`);
+    return 0;
+}
+async function migrateCommand(rest) {
+    let routes = "src/routes";
+    let dry = false;
+    for (let i = 0; i < rest.length; i++) {
+        if (rest[i] === "--dry-run")
+            dry = true;
+        else if (rest[i] === "--routes" && rest[i + 1])
+            routes = rest[++i];
+        else {
+            console.error(USAGE);
+            return 2;
+        }
+    }
+    const { migrateServerExports, writeMigration } = await import("../build/migrate.js");
+    const cwd = process.cwd();
+    const report = await migrateServerExports(cwd, routes);
+    for (const line of report.renamed)
+        console.log("renamed " + line);
+    for (const line of report.skipped)
+        console.log("skipped " + line);
+    if (!dry)
+        await writeMigration(report);
+    console.log(`${dry ? "would change" : "changed"} ${report.changes.size} file(s)${report.changes.size ? ": " + [...report.changes.keys()].map((f) => relative(cwd, f)).join(", ") : ""}`);
+    return 0;
+}
+/** `rivet mcp`: run the app's `@rivetjs/mcp` bin with this process's stdio (the MCP protocol). */
+async function mcpCommand() {
+    const { createRequire } = await import("node:module");
+    const { dirname, join } = await import("node:path");
+    const { existsSync } = await import("node:fs");
+    const { spawn } = await import("node:child_process");
+    let dir;
+    try {
+        dir = dirname(createRequire(join(process.cwd(), "noop.js")).resolve("@rivetjs/mcp"));
+    }
+    catch {
+        console.error("rivet mcp: @rivetjs/mcp is not installed here; run `npx -y @rivetjs/mcp` or `npm install -D @rivetjs/mcp`");
+        return 2;
+    }
+    const cli = ["cli.js", "cli.ts"].map((name) => join(dir, name)).find((file) => existsSync(file));
+    const child = spawn(process.execPath, [cli, ...process.argv.slice(3)], { stdio: "inherit" });
+    return new Promise((done) => child.on("exit", (code) => done(code ?? 1)));
+}
+async function main(argv) {
+    const [command, ...rest] = argv;
+    if (command === "sync")
+        return syncCommand(rest);
+    if (command === "migrate" && rest[0] === "server-exports")
+        return migrateCommand(rest.slice(1));
+    if (command === "mcp")
+        return mcpCommand();
+    if (command === "-h" || command === "--help") {
+        console.log(USAGE);
+        return 0;
+    }
+    console.error(USAGE);
+    return 2;
+}
+process.exitCode = await main(process.argv.slice(2));

package/client/active.d.ts

@@ -0,0 +1,6 @@
+/** Link active mode: `"exact"` (same path) or `"prefix"` (same path or below it). */
+export type ActiveMode = "exact" | "prefix";
+/** `aria-current` for a link to `path` while the page is `here`: `page` on the page itself, `true` below it (prefix). */
+export declare function currentOf(path: string, here: string, mode: ActiveMode): "page" | "true" | undefined;
+/** @internal Generated App (apps using `<Link active>`): re-mark active links after a navigation commits. */
+export declare function _markActive(): void;

package/client/active.js

@@ -0,0 +1,22 @@
+// `<Link active>` state: the link's path against the current page's. Rendered by `<Link>` (server:
+// the request URL; browser renders: `location`); after client navigation the generated App re-marks
+// every `a[data-rivet-active]` (`_markActive`, only in apps that use `active`).
+// One optional trailing slash is the same route (the matcher accepts it).
+const trim = (path) => (path.length > 1 && path.endsWith("/") ? path.slice(0, -1) : path);
+/** `aria-current` for a link to `path` while the page is `here`: `page` on the page itself, `true` below it (prefix). */
+export function currentOf(path, here, mode) {
+    const to = trim(path), at = trim(here);
+    if (to === at)
+        return "page";
+    return mode === "prefix" && at.startsWith(to === "/" ? "/" : to + "/") ? "true" : undefined;
+}
+/** @internal Generated App (apps using `<Link active>`): re-mark active links after a navigation commits. */
+export function _markActive() {
+    document.querySelectorAll("a[data-rivet-active]").forEach((anchor) => {
+        const current = currentOf(anchor.pathname, location.pathname, anchor.getAttribute("data-rivet-active"));
+        if (current)
+            (anchor.setAttribute("aria-current", current), anchor.setAttribute("data-current", ""));
+        else
+            (anchor.removeAttribute("aria-current"), anchor.removeAttribute("data-current"));
+    });
+}

package/client/announce.d.ts

@@ -0,0 +1,2 @@
+/** Announce the committed page to screen readers: its title, else its first h1, else its path. */
+export declare function announce(): void;

package/client/announce.js

@@ -0,0 +1,21 @@
+// Route announcer: one visually hidden live region, created on the first client navigation (pages
+// that never navigate client-side get no node and run nothing). Styled through CSSOM, which strict
+// `style-src` policies allow, unlike an inline `style` attribute in markup.
+let region;
+const HIDDEN = "position:absolute;width:1px;height:1px;margin:-1px;padding:0;border:0;overflow:hidden;clip:rect(0 0 0 0);clip-path:inset(50%);white-space:nowrap";
+/** Announce the committed page to screen readers: its title, else its first h1, else its path. */
+export function announce() {
+    const text = document.title || document.querySelector("h1")?.textContent?.trim() || location.pathname;
+    if (!region) {
+        region = document.createElement("div");
+        region.setAttribute("aria-live", "assertive");
+        region.setAttribute("aria-atomic", "true");
+        region.style.cssText = HIDDEN;
+    }
+    if (!region.isConnected)
+        document.body.append(region);
+    // Cleared, then set a frame later: the same text twice in a row is announced again.
+    region.textContent = "";
+    const node = region;
+    requestAnimationFrame(() => (node.textContent = text));
+}

package/client/dev.d.ts

@@ -0,0 +1,41 @@
+import * as client from "./index.js";
+import type { Layouts, RoutePayload } from "./index.js";
+export * from "./index.js";
+/** What the DevTools Router pane shows (plain data; values are previewed by the agent). */
+export interface RouterSnapshot {
+    route: {
+        pattern: string;
+        url: string;
+        params: Readonly<Record<string, string>>;
+    } | null;
+    /** Loader data along the chain: layout ids, then `page`. */
+    data: {
+        id: string;
+        value: unknown;
+    }[];
+    layouts: string[];
+    pending: {
+        to: string;
+        type: string;
+        trigger: string;
+        ms: number;
+        state: string;
+    } | null;
+    last: RouterNavigation | null;
+    history: RouterNavigation[];
+    loadMs: number | null;
+    error: string | null;
+}
+export interface RouterNavigation {
+    from: string | null;
+    to: string;
+    type: string;
+    trigger: string;
+    /** Start to commit (ms). */
+    ms: number | null;
+    at: number;
+}
+/** `routeData`, recording the loaded route (pattern, params, loader data, time) for DevTools. */
+export declare function routeData(...args: Parameters<typeof client.routeData>): Promise<RoutePayload>;
+/** `_layouts`, keeping the generated layout table (layout ids for the chain). */
+export declare function _layouts(...args: Parameters<typeof client._layouts>): Layouts;

package/client/dev.js

@@ -0,0 +1,74 @@
+// Development façade of `@rivetjs/router/client` (`development` export condition: Vite dev, never a
+// production build). Same exports; with a devtools hook installed it names the router's contexts and
+// reports a `lib.router` describer: the shown route (pattern, params, loader data per layout), the
+// layout chain, the navigation in flight and recent navigations. Generated apps import `routeData`,
+// `_layouts` and `_landed` from this entry, so the wrappers below see every route load.
+import { untrack } from "@rivetjs/reactivity";
+import { devtoolsHook } from "@rivetjs/reactivity/debug";
+import * as client from "./index.js";
+export * from "./index.js";
+const hook = devtoolsHook();
+let table = null;
+let shown = null;
+let pending = null;
+const history = [];
+const changed = () => hook?.emit("lib.changed", { lib: "router" });
+const now = () => performance.now();
+function snapshot() {
+    const layouts = shown && table ? (table.routes.find(([pattern]) => pattern === shown.pattern)?.[1] ?? []).map((i) => table.ids[i]) : [];
+    const data = shown ? shown.data.map((value, i) => ({ id: i < layouts.length ? layouts[i] : i === shown.data.length - 1 ? "page" : "#" + i, value })) : [];
+    const state = untrack(client.navigation);
+    return {
+        route: shown ? { pattern: shown.pattern, url: shown.url, params: shown.params } : null,
+        data,
+        layouts,
+        pending: pending ? { to: pending.to, type: pending.type, trigger: pending.trigger, ms: now() - pending.start, state: state.state } : state.state !== "idle" && state.location ? { to: state.location.href, type: state.type ?? "push", trigger: "api", ms: 0, state: state.state } : null,
+        last: history.at(-1) ?? null,
+        history: history.slice(-10).reverse(),
+        loadMs: shown?.ms ?? null,
+        error: shown?.error ?? null,
+    };
+}
+if (hook !== undefined) {
+    for (const [token, name] of [
+        [client.Navigation, "Navigation"],
+        [client.SearchParams, "SearchParams"],
+        [client.RouteParamsContext, "RouteParams"],
+        [client.ServerData, "ServerData"],
+    ])
+        hook.emit("name", { value: token, name });
+    hook.emit("lib.register", { lib: "router", describe: snapshot });
+    client.onNavigate((nav) => {
+        pending = { from: nav.from?.href ?? null, to: nav.to.href, type: nav.type, trigger: nav.trigger, ms: null, at: Date.now(), start: now() };
+        changed();
+        return () => {
+            if (!pending)
+                return;
+            const { start, ...done } = pending;
+            history.push({ ...done, ms: now() - start });
+            if (history.length > 50)
+                history.shift();
+            pending = null;
+            changed();
+        };
+    });
+}
+/** `routeData`, recording the loaded route (pattern, params, loader data, time) for DevTools. */
+export function routeData(...args) {
+    const loaded = client.routeData(...args);
+    if (hook === undefined)
+        return loaded;
+    const [, match] = args, start = now();
+    const route = match;
+    const record = (data, error) => {
+        shown = { pattern: route.route?.path ?? route.url.pathname, url: route.url.href, params: route.params ?? {}, data, ms: now() - start, error };
+        changed();
+    };
+    loaded.then((result) => record(result.data, null), (error) => record([], error instanceof Error ? error.message : String(error)));
+    return loaded;
+}
+/** `_layouts`, keeping the generated layout table (layout ids for the chain). */
+export function _layouts(...args) {
+    table = args[2];
+    return client._layouts(...args);
+}

package/client/index.d.ts

@@ -0,0 +1,152 @@
+import { type Context } from "@rivetjs/reactivity";
+import { type RoutePayload } from "../shared/data.js";
+import { type NavigationState, type NavigationType } from "./navigation.js";
+import { type _go, type NavigateRequest } from "./navigate.js";
+import { type LayoutTable, type Layouts } from "./layouts.js";
+export { _layouts, _level, _enter, _take, _landed, _sync, _keepIds, type LayoutTable, type Layouts } from "./layouts.js";
+export { beforeLeave, type LeaveEvent } from "./leave.js";
+export type { ActionResult, Head, RoutePayload } from "../shared/data.js";
+export { Navigation, navigation, IDLE, type NavigationState, type NavigationType } from "./navigation.js";
+export { Link, type LinkProps } from "./link.jsx";
+export { currentOf, _markActive, type ActiveMode } from "./active.js";
+export { navigate, invalidate, revalidate, setSearchParams, _go, type NavigateOptions, type FreshData, type InvalidateTarget } from "./navigate.js";
+export { useParams, useSearchParams, RouteParamsContext } from "./params.js";
+export { SearchParams } from "./search.js";
+export { _live, _livePage, _liveRouter, _armLive, _liveIntent, _liveLevels, _serveLive, type LivePage } from "./live.js";
+export { ServerData, actionResult, type ServerRoutePayload } from "./route-context.js";
+/** @internal The app router as the client drives it. */
+export interface Navigator {
+    navigate?(to: string | URL, options?: {
+        replace?: boolean;
+        revalidate?: boolean;
+    }): void;
+}
+interface Work {
+    readonly signal: AbortSignal;
+    get<T>(token: Context<T>): T;
+}
+/**
+ * Where client navigation gets route data: the server's data endpoint, prerendered `_data.json`
+ * files (static adapter) or nowhere (CSR adapter: pages render without loader data).
+ */
+export type DataSource = "server" | "static" | "none";
+declare function dropPrefetch(except?: string, now?: number): void;
+/** URL of a page's data for client navigation; `keep`: ids of layouts whose data the client has. */
+export declare function dataURL(url: URL, source?: DataSource, keep?: string): string;
+/** Decode a data-endpoint body (resume table encoding; built-in entries load their decoders first, `x`). */
+export declare function decodeData(text: string): Promise<unknown>;
+/**
+ * @internal Server render of a generated route level: the handler's loader results (`ServerData`) through the
+ * route's result chain synchronously (`ok` / `fail` as the `then` steps of the browser chain, then `land`) — no
+ * `Promise.all` / `then` hops per request, no page import (the lazy page view loads itself, rendering
+ * synchronously once its module is in). Browser (and no `ServerData`): undefined, the generated chain runs.
+ */
+export declare function _ssrLevel<R, T>(work: Work, ok: (data: RoutePayload) => R, fail: (cause: unknown) => R, land: (result: R) => T): T | undefined;
+/** Load a generated route's data: from `ServerData` on the server, from the data endpoint in the browser. */
+export declare function routeData(work: Work, match: {
+    url: URL;
+}, router: Navigator, source?: DataSource, keep?: string): Promise<RoutePayload>;
+/**
+ * Same-origin, same-document-eligible anchor for a click/hover event, else null. With the app's page
+ * `modules`, a URL no page route matches (an endpoint, a file, another app on the origin) is not
+ * routable either: the browser loads its document (no data request, no chunk prefetch).
+ */
+export declare function routableAnchor(event: Event, modules?: ModuleTable): HTMLAnchorElement | null;
+/** One client navigation, from its start to its commit (`rivet:navigate` event detail, `onNavigate`). */
+export interface NavigationInfo {
+    readonly from: URL | null;
+    readonly to: URL;
+    readonly type: NavigationType;
+    readonly trigger: "link" | "api" | "popstate" | "redirect";
+    /** The clicked anchor (link navigations). */
+    readonly anchor?: HTMLAnchorElement;
+    /** The link's `data-transition` (`<Link transition>`). */
+    readonly transition?: string | null;
+    /** Popstate the browser already animated (`hasUAVisualTransition`, e.g. a swipe). */
+    readonly visual?: boolean;
+    /** @internal The page module's `transition` export, once its chunk is in. */
+    route?: unknown;
+}
+/** @internal Hooks installed by `@rivetjs/router/transitions` once it loads. */
+export declare const _transitions: {
+    start?(nav: NavigationInfo): void;
+    swap?(apply: () => void, next: ParentNode, nav: NavigationInfo): void;
+};
+/**
+ * Run `fn(nav)` when a client navigation starts (link, back/forward, redirect); a function it
+ * returns runs once the new page is in the document. Returns an unsubscribe function.
+ */
+export declare function onNavigate(fn: (nav: NavigationInfo) => void | (() => void)): () => void;
+/** @internal The navigation in flight (read by the transitions module when it installs). */
+export declare const _current: () => NavigationInfo | null;
+/** @internal Run the `onNavigate` callbacks' after-swap functions. */
+export declare function _afterSwap(): void;
+/** @internal Generated load: remember the loaded page module's `transition` export for the swap. */
+export declare function _routeModule(module: unknown): void;
+/** Navigation state accessor: idle unless `transitions` is on. Resumed regions reading it update in place. */
+export declare function useNavigation(): () => NavigationState;
+/** Delegated click handler: route same-origin links through the router (`modules`: only URLs a page route matches). */
+export declare function interceptClick(event: MouseEvent, router: Navigator, modules?: ModuleTable): void;
+/** Back/forward: the next settled route restores its saved position. */
+export declare function notePopstate(event?: PopStateEvent): void;
+/** Router `swap` of generated apps: the view transition when installed, then scroll and focus. */
+export declare function swapRoute(apply: () => void, next: ParentNode): void;
+/**
+ * @internal live.ts: a search-only navigation of a live page committed in place (no route render): the
+ * navigation in flight ends here, scroll and focus stay, `onNavigate` after-swap callbacks and waiters run.
+ */
+export declare function _inPlace(): void;
+/** `swapRoute` without the route announcer (generated apps of `rivetRouter({ announce: false })`). */
+export declare function swapRouteQuiet(apply: () => void, next: ParentNode): void;
+/**
+ * Router `hold` view of generated apps: on a resumed page's first client navigation the server
+ * rendered route content stays visible (inert) until the new route commits, instead of a blank region.
+ */
+export declare function heldRoutes(level?: number): Node | null;
+/** Warm a route's data on intent (pointer over / focus); `keep` as for `dataURL`. */
+export declare function prefetchData(url: URL, source?: DataSource, keep?: string): void;
+/**
+ * Page routes in match order: `[pattern, page importer]`. Rows whose importer is `_endpoint` are
+ * endpoints the server matches before a later dynamic page pattern that also fits them (generated).
+ */
+export type ModuleTable = readonly (readonly [string, () => unknown])[];
+/** @internal Generated `modules` row importer of an endpoint (its URLs load documents). */
+export declare const _endpoint: () => void;
+/** Import the page module of the route matching `url` (the import is shared with the render). */
+export declare function loadModule(url: URL, modules: ModuleTable): Promise<unknown> | undefined;
+/**
+ * Page loader of generated apps: import the page module and ready its lazy component (browser
+ * `lazyComponent(...).load`), so the route renders synchronously once loaded. Resolves the module.
+ */
+export declare function preloadPage(component: unknown, importer: () => Promise<unknown>): Promise<unknown>;
+/** Load the page chunk of the route matching `url` on intent; false when no page route matches (nothing to prefetch). */
+export declare function prefetchModule(url: URL, modules: ModuleTable): boolean;
+/** After a client-rendered route settles: restore or reset scroll, honour #hash, move focus, announce. */
+export declare function settle(url: URL): void;
+/**
+ * @internal Generated `App` of apps using `@rivetjs/forms` (codegen `forms`): every router handler (link click /
+ * intent, popstate, `rivet:go`) first installs the router under `Symbol.for("rivet.router")` — `clear` (drop warmed
+ * route data) and `go` (`navigate.ts` `_go`) — so forms reach it without importing this module (their chunks share
+ * no router code with the App). The first install dispatches `rivet:router` on the document (forms waiting for the
+ * router to boot). Assigned each call: a re-instantiated router module (dev HMR) replaces the old entry points.
+ */
+export declare function _brand(go: typeof _go): void;
+/** Drop warmed route data (form submits and `invalidate()` do; call it after other mutations). */
+export declare function _clearPrefetch(): void;
+/** Navigation flag: keep the scroll position. */
+export declare const KEEP_SCROLL = 1, 
+/** Navigation flag: keep focus where it is. */
+KEEP_FOCUS = 2;
+/**
+ * @internal Generated `App`: start its route effects (nested level sync, `<Link active>` re-marking) once per
+ * router, from the first navigation entry point (link click, popstate, `rivet:go`) — not at load, so a resumed
+ * page loads no router code before a navigation (Z1). Each runs as an effect owned by the caller's owner.
+ */
+export declare function _arm(router: object, ...effects: (() => void | (() => void))[]): void;
+/**
+ * @internal Generated `App`: serve queued `navigate()` / `invalidate()` requests (`rivet:go` event).
+ * Server apps with layouts pass their layout state and table (`invalidate(key)` keeps loaders).
+ */
+export declare function _serve(router: Navigator, state?: Layouts, table?: LayoutTable): void;
+export { perform as _perform, dropPrefetch as _dropPrefetch };
+declare function perform(router: Navigator, request: NavigateRequest, state?: Layouts, table?: LayoutTable): void;