@pylonsync/react 0.3.261 → 0.3.263

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.3.261",
+  "version": "0.3.263",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -12,8 +12,8 @@
     "check": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@pylonsync/sdk": "0.3.261",
-    "@pylonsync/sync": "0.3.261"
+    "@pylonsync/sdk": "0.3.263",
+    "@pylonsync/sync": "0.3.263"
   },
   "peerDependencies": {
     "react": ">=19.0.0"

package/src/Link.tsx

@@ -34,6 +34,9 @@ declare global {
         href: string,
         opts?: { push?: boolean; replace?: boolean },
       ) => Promise<void>;
+      /** Current route's dynamic params (read by useParams). A getter on the
+       *  runtime side, so it always reflects the latest navigation. */
+      readonly params?: Record<string, string>;
     };
   }
 }

package/src/index.ts

@@ -30,7 +30,15 @@ export type {
 } from "./ssr";
 
 // Client navigation hooks for SSR pages (Next-style).
-export { useRouter, useSearchParams, usePathname } from "./useRouter";
+export {
+  useRouter,
+  useSearchParams,
+  usePathname,
+  useParams,
+  redirect,
+  notFound,
+  NotFoundError,
+} from "./useRouter";
 export type { PylonRouter } from "./useRouter";
 
 import {

package/src/useRouter.test.ts

@@ -0,0 +1,82 @@
+// Contract coverage for the Next-compatible router primitives that back the
+// Pylon Cloud frontend migration off Next.js: `notFound()`, `redirect()`, and
+// the params snapshot read by `useParams`.
+//
+// We test the observable contracts directly instead of mounting React (the
+// package ships no renderer dep — same approach as useRoom.test.ts), and we
+// stub a minimal `globalThis.window` since bun:test has no DOM:
+//   - `notFound()` throws a branded error the SSR runtime recognizes by digest
+//     (the cross-package handshake in ssr-runtime's `asRouteControl`).
+//   - `redirect()` delegates to the client runtime's `navigate(_, {replace})`.
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+
+import { NotFoundError, notFound, redirect } from "./useRouter";
+
+describe("notFound() — branded for the SSR not-found boundary", () => {
+  test("throws a NotFoundError", () => {
+    expect(() => notFound()).toThrow(NotFoundError);
+  });
+
+  test("the thrown error carries the exact digest the runtime keys on", () => {
+    // This string is the cross-package contract: ssr-runtime.ts's
+    // `asRouteControl` matches `err.digest === "PYLON_NOT_FOUND"`. If this
+    // literal drifts on either side, server-render notFound() silently 500s
+    // instead of 404ing. Pin it on both sides so a drift breaks a test.
+    let caught: unknown;
+    try {
+      notFound();
+    } catch (e) {
+      caught = e;
+    }
+    expect(caught).toBeInstanceOf(NotFoundError);
+    expect((caught as NotFoundError).digest).toBe("PYLON_NOT_FOUND");
+  });
+
+  test("notFound() never returns (control always throws)", () => {
+    let reached = false;
+    try {
+      notFound();
+      reached = true;
+    } catch {
+      /* expected */
+    }
+    expect(reached).toBe(false);
+  });
+});
+
+describe("redirect() — client-side replace navigation", () => {
+  let calls: Array<{ href: string; opts?: unknown }>;
+  const hadWindow = "window" in globalThis;
+
+  beforeEach(() => {
+    calls = [];
+    // bun:test has no DOM — stand up a minimal window the module can see.
+    (globalThis as any).window = {
+      __pylon: {
+        prefetch: async () => {},
+        navigate: async (href: string, opts?: unknown) => {
+          calls.push({ href, opts });
+        },
+      },
+    };
+  });
+
+  afterEach(() => {
+    if (hadWindow) return;
+    delete (globalThis as any).window;
+  });
+
+  test("delegates to __pylon.navigate with replace:true (no history push)", () => {
+    redirect("/login");
+    expect(calls).toHaveLength(1);
+    expect(calls[0].href).toBe("/login");
+    expect(calls[0].opts).toEqual({ replace: true });
+  });
+
+  test("is a no-op (doesn't throw) when the client runtime isn't ready", () => {
+    (globalThis as any).window.__pylon = undefined;
+    expect(() => redirect("/login")).not.toThrow();
+    expect(calls).toHaveLength(0);
+  });
+});

package/src/useRouter.ts

@@ -79,6 +79,72 @@ export function usePathname(): string {
   return useSyncExternalStore(subscribe, pathClientSnapshot, pathServerSnapshot);
 }
 
+// The current route's dynamic params, stashed on `window.__pylon.params` by the
+// SSR client runtime at hydration + on every nav. A stable object reference
+// between navs (the runtime mints a fresh one per route), which
+// useSyncExternalStore requires.
+const EMPTY_OBJ: Record<string, string> = {};
+function paramsClientSnapshot(): Record<string, string> {
+  return (
+    (typeof window !== "undefined" && window.__pylon?.params) || EMPTY_OBJ
+  );
+}
+function paramsServerSnapshot(): Record<string, string> {
+  return EMPTY_OBJ;
+}
+
+/**
+ * The current route's dynamic params — e.g. `/dashboard/[projectId]` →
+ * `{ projectId: "p_1" }`. Reactive to client navigation, so a deep child gets
+ * the new params after a `<Link>` click without prop-drilling. Returns `{}`
+ * during SSR / first hydration — use the `params` page prop for server-side
+ * values. Drop-in for Next's `useParams`.
+ *
+ * ```tsx
+ * const { projectId } = useParams<{ projectId: string }>();
+ * ```
+ */
+export function useParams<
+  T extends Record<string, string> = Record<string, string>,
+>(): T {
+  return useSyncExternalStore(
+    subscribe,
+    paramsClientSnapshot,
+    paramsServerSnapshot,
+  ) as T;
+}
+
+/**
+ * Client-side redirect — replaces the current history entry with `href`.
+ * Drop-in for Next's `redirect` when called from a client component
+ * (effect/handler). For a redirect decided during a server render, use the
+ * `response.redirect()` API on the page's `PageProps` instead.
+ */
+export function redirect(href: string): void {
+  if (typeof window !== "undefined") {
+    void window.__pylon?.navigate(href, { replace: true });
+  }
+}
+
+/** Error thrown by {@link notFound}; the SSR not-found boundary renders it. */
+export class NotFoundError extends Error {
+  readonly digest = "PYLON_NOT_FOUND";
+  constructor() {
+    super("PYLON_NOT_FOUND");
+    this.name = "NotFoundError";
+  }
+}
+
+/**
+ * Render the nearest `not-found.tsx` boundary from a client component by
+ * throwing — drop-in for Next's `notFound`. For a 404 decided during a server
+ * render, prefer `response.notFound()` on the page's `PageProps` so the
+ * response carries a real 404 status.
+ */
+export function notFound(): never {
+  throw new NotFoundError();
+}
+
 /** Imperative navigation handle (Next-style `useRouter`). */
 export interface PylonRouter {
   /** Navigate to `href`, pushing a new history entry. */