@pylonsync/react 0.3.307 → 0.3.309

package/dist/Link.d.ts

@@ -6,11 +6,19 @@ declare global {
             navigate: (href: string, opts?: {
                 push?: boolean;
                 replace?: boolean;
+                seed?: unknown;
             }) => 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>;
+            /** Seed the active navigation was started with (read by useRouteSeed).
+             *  A getter on the runtime side; null outside an optimistic nav. */
+            readonly seed?: unknown;
         };
+        /** WeakMap of <Link seed> anchor element → its seed value. Populated by
+         *  <Link> and read by the runtime's global click handler so it can pass the
+         *  seed to navigate() for an optimistic first paint. */
+        __pylonLinkSeeds?: WeakMap<Element, unknown>;
     }
 }
 export interface LinkProps extends Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, "href"> {
@@ -22,6 +30,19 @@ export interface LinkProps extends Omit<React.AnchorHTMLAttributes<HTMLAnchorEle
      * is unlikely to follow — pagination tail, etc.).
      */
     prefetch?: boolean;
+    /**
+     * Data you already have for the destination (e.g. the list item you clicked).
+     * When set, Pylon paints the destination page's Suspense fallback with this
+     * data the instant the link is clicked — before the SSR fetch resolves — so
+     * above-the-fold content appears immediately instead of a skeleton or a delay.
+     * Read it on the destination page with `useRouteSeed<T>()`.
+     *
+     * Degrades gracefully: no seed, or a route Pylon can't resolve on the client,
+     * simply falls back to normal navigation. Best for detail routes whose page
+     * keeps its `serverData` reads inside a `<Suspense>` (so the seeded fallback
+     * has somewhere to show).
+     */
+    seed?: unknown;
     children?: React.ReactNode;
 }
-export declare function Link({ href, prefetch, children, ...rest }: LinkProps): React.JSX.Element;
+export declare function Link({ href, prefetch, seed, children, ...rest }: LinkProps): React.JSX.Element;

package/dist/index.d.ts

@@ -7,7 +7,7 @@ export type { ImageProps } from "./Image";
 export { Form } from "./Form";
 export type { FormProps } from "./Form";
 export type { PageProps, PageAuth, ServerData, SsrResponse, SsrCookieOptions, Metadata, GenerateMetadata, Sitemap, SitemapEntry, Robots, RobotsRule, RouteSegmentConfig, ErrorBoundaryProps, NotFoundProps, FormFields, FormDb, FormRequest, RouteHandler, RawRouteHandler, RawResponse, } from "./ssr";
-export { useRouter, useSearchParams, usePathname, useParams, redirect, notFound, NotFoundError, } from "./useRouter";
+export { useRouter, useSearchParams, usePathname, useParams, useRouteSeed, useRouteData, redirect, notFound, NotFoundError, } from "./useRouter";
 export type { PylonRouter } from "./useRouter";
 import { type Storage as PylonStorage } from "@pylonsync/sync";
 export { useQuery, useQueryOne, useReactiveQuery, useMutation, useInfiniteQuery, usePaginatedQuery, useEntityMutation, useAction, useQueryRaw, useQueryOneRaw, useLiveList, useLiveRow, useInsert, useUpdate, useDelete, useFn, useAggregate, useSearch, } from "./hooks";

package/dist/useRouter.d.ts

@@ -27,6 +27,52 @@ export declare function usePathname(): string;
  * ```
  */
 export declare function useParams<T extends Record<string, string> = Record<string, string>>(): T;
+/**
+ * The seed passed to the `<Link seed>` that started the current navigation, for
+ * an instant optimistic first paint. Returns the seed while the destination's
+ * data is still loading, then `null` once the real server render lands (and on
+ * hard loads / seedless navs). Use it as the page's Suspense fallback so
+ * above-the-fold content shows immediately instead of a skeleton:
+ *
+ * ```tsx
+ * export default function Page({ params, serverData }: PageProps<{ slug: string }>) {
+ *   const seed = useRouteSeed<Product>();
+ *   return (
+ *     <Suspense fallback={seed ? <ProductView product={seed} pending /> : <Skeleton />}>
+ *       <ProductDetail serverData={serverData} slug={params.slug} />
+ *     </Suspense>
+ *   );
+ * }
+ * ```
+ */
+export declare function useRouteSeed<T = unknown>(): T | null;
+/**
+ * Load a page's primary data with an optimistic first paint from `<Link seed>`.
+ * This is the flash-free way to consume a seed — prefer it over reading
+ * `useRouteSeed()` into a Suspense fallback (a fallback→content transition
+ * remounts, which flickers).
+ *
+ * - Hard load / SSR (no seed): suspends on `loader()`, so the server renders +
+ *   streams the real content and the client hydrates from the pre-fulfilled
+ *   serverData cache. Wrap the calling component in `<Suspense>`.
+ * - Optimistic client nav (a `<Link seed>` was clicked): returns the seed
+ *   immediately as real content — NO Suspense fallback — then swaps to the
+ *   resolved `loader()` value IN PLACE (same component instance), so there is no
+ *   remount between the seed and the authoritative row. No flash.
+ *
+ * `deps` drive the background reload — pass the values `loader` closes over
+ * (e.g. `[serverData, slug]`). Key the component by its dynamic route param if
+ * it serves both seeded and hard-loaded requests, so each navigation mounts a
+ * fresh instance in the right mode.
+ *
+ * ```tsx
+ * function Detail({ serverData, slug }: { serverData: ServerData; slug: string }) {
+ *   const product = useRouteData(() => loadProduct(serverData, slug), [serverData, slug]);
+ *   return product ? <ProductView product={product} /> : <NotFound />;
+ * }
+ * ```
+ */
+export declare function useRouteData<T>(loader: () => Promise<T> | T, deps: readonly unknown[]): T | null;
 /**
  * Client-side redirect — replaces the current history entry with `href`.
  * Drop-in for Next's `redirect` when called from a client component

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.3.307",
+  "version": "0.3.309",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./dist/index.d.ts",
@@ -13,8 +13,8 @@
     "prepack": "bun run build"
   },
   "dependencies": {
-    "@pylonsync/sdk": "0.3.307",
-    "@pylonsync/sync": "0.3.307"
+    "@pylonsync/sdk": "0.3.309",
+    "@pylonsync/sync": "0.3.309"
   },
   "peerDependencies": {
     "react": ">=19.0.0"

package/src/Link.tsx

@@ -32,12 +32,19 @@ declare global {
       prefetch: (href: string) => Promise<void>;
       navigate: (
         href: string,
-        opts?: { push?: boolean; replace?: boolean },
+        opts?: { push?: boolean; replace?: boolean; seed?: unknown },
       ) => 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>;
+      /** Seed the active navigation was started with (read by useRouteSeed).
+       *  A getter on the runtime side; null outside an optimistic nav. */
+      readonly seed?: unknown;
     };
+    /** WeakMap of <Link seed> anchor element → its seed value. Populated by
+     *  <Link> and read by the runtime's global click handler so it can pass the
+     *  seed to navigate() for an optimistic first paint. */
+    __pylonLinkSeeds?: WeakMap<Element, unknown>;
   }
 }
 
@@ -51,17 +58,47 @@ export interface LinkProps
    * is unlikely to follow — pagination tail, etc.).
    */
   prefetch?: boolean;
+  /**
+   * Data you already have for the destination (e.g. the list item you clicked).
+   * When set, Pylon paints the destination page's Suspense fallback with this
+   * data the instant the link is clicked — before the SSR fetch resolves — so
+   * above-the-fold content appears immediately instead of a skeleton or a delay.
+   * Read it on the destination page with `useRouteSeed<T>()`.
+   *
+   * Degrades gracefully: no seed, or a route Pylon can't resolve on the client,
+   * simply falls back to normal navigation. Best for detail routes whose page
+   * keeps its `serverData` reads inside a `<Suspense>` (so the seeded fallback
+   * has somewhere to show).
+   */
+  seed?: unknown;
   children?: React.ReactNode;
 }
 
 export function Link({
   href,
   prefetch = true,
+  seed,
   children,
   ...rest
 }: LinkProps) {
   const ref = useRef<HTMLAnchorElement>(null);
 
+  // Register the seed keyed by this anchor element so the runtime's global
+  // click handler can find it and hand it to navigate(). A WeakMap keeps it
+  // GC-safe (no leak when the link unmounts) and off the DOM node itself.
+  useEffect(() => {
+    if (typeof window === "undefined") return;
+    const el = ref.current;
+    if (!el || seed === undefined) return;
+    const reg =
+      window.__pylonLinkSeeds ||
+      (window.__pylonLinkSeeds = new WeakMap<Element, unknown>());
+    reg.set(el, seed);
+    return () => {
+      reg.delete(el);
+    };
+  }, [seed]);
+
   useEffect(() => {
     if (!prefetch || !ref.current) return;
     if (typeof window === "undefined") return;

package/src/index.ts

@@ -41,6 +41,8 @@ export {
   useSearchParams,
   usePathname,
   useParams,
+  useRouteSeed,
+  useRouteData,
   redirect,
   notFound,
   NotFoundError,

package/src/useRouter.ts

@@ -12,7 +12,7 @@
 // `searchParams` PROPS the runtime already hands every page (see PageProps);
 // the hooks exist for deep children that need to react to client navigation
 // without prop-drilling.
-import { useMemo, useSyncExternalStore } from "react";
+import { use, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 
 // `Window.__pylon` is globally augmented in ./Link (same package, ambient).
 
@@ -114,6 +114,99 @@ export function useParams<
   ) as T;
 }
 
+// The seed for the active navigation, stashed on `window.__pylon.seed` by the
+// runtime when a <Link seed> is clicked. A stable reference for the whole nav
+// (set once at nav start), which useSyncExternalStore requires. Null otherwise.
+function seedClientSnapshot(): unknown {
+  return (typeof window !== "undefined" && window.__pylon?.seed) || null;
+}
+function seedServerSnapshot(): unknown {
+  return null;
+}
+
+/**
+ * The seed passed to the `<Link seed>` that started the current navigation, for
+ * an instant optimistic first paint. Returns the seed while the destination's
+ * data is still loading, then `null` once the real server render lands (and on
+ * hard loads / seedless navs). Use it as the page's Suspense fallback so
+ * above-the-fold content shows immediately instead of a skeleton:
+ *
+ * ```tsx
+ * export default function Page({ params, serverData }: PageProps<{ slug: string }>) {
+ *   const seed = useRouteSeed<Product>();
+ *   return (
+ *     <Suspense fallback={seed ? <ProductView product={seed} pending /> : <Skeleton />}>
+ *       <ProductDetail serverData={serverData} slug={params.slug} />
+ *     </Suspense>
+ *   );
+ * }
+ * ```
+ */
+export function useRouteSeed<T = unknown>(): T | null {
+  return useSyncExternalStore(
+    subscribe,
+    seedClientSnapshot,
+    seedServerSnapshot,
+  ) as T | null;
+}
+
+/**
+ * Load a page's primary data with an optimistic first paint from `<Link seed>`.
+ * This is the flash-free way to consume a seed — prefer it over reading
+ * `useRouteSeed()` into a Suspense fallback (a fallback→content transition
+ * remounts, which flickers).
+ *
+ * - Hard load / SSR (no seed): suspends on `loader()`, so the server renders +
+ *   streams the real content and the client hydrates from the pre-fulfilled
+ *   serverData cache. Wrap the calling component in `<Suspense>`.
+ * - Optimistic client nav (a `<Link seed>` was clicked): returns the seed
+ *   immediately as real content — NO Suspense fallback — then swaps to the
+ *   resolved `loader()` value IN PLACE (same component instance), so there is no
+ *   remount between the seed and the authoritative row. No flash.
+ *
+ * `deps` drive the background reload — pass the values `loader` closes over
+ * (e.g. `[serverData, slug]`). Key the component by its dynamic route param if
+ * it serves both seeded and hard-loaded requests, so each navigation mounts a
+ * fresh instance in the right mode.
+ *
+ * ```tsx
+ * function Detail({ serverData, slug }: { serverData: ServerData; slug: string }) {
+ *   const product = useRouteData(() => loadProduct(serverData, slug), [serverData, slug]);
+ *   return product ? <ProductView product={product} /> : <NotFound />;
+ * }
+ * ```
+ */
+export function useRouteData<T>(
+  loader: () => Promise<T> | T,
+  deps: readonly unknown[],
+): T | null {
+  const seed = useRouteSeed<T>();
+  // Fix the mode at first render so the hook calls below stay stable even if the
+  // seed changes on a later same-instance nav (rules of hooks). `use()` may be
+  // called conditionally, but useState/useEffect may not — hence the ref.
+  const optimistic = useRef(seed != null).current;
+  const [data, setData] = useState<T | null>(optimistic ? seed : null);
+  useEffect(() => {
+    if (!optimistic) return;
+    let live = true;
+    Promise.resolve(loader()).then((v) => {
+      if (live && v != null) setData(v as T);
+    });
+    return () => {
+      live = false;
+    };
+    // loader is intentionally excluded; `deps` are the reload trigger.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, deps);
+  if (!optimistic) {
+    // SSR + hard load + non-seeded nav: suspend so the server streams the real
+    // content and the client hydrates it synchronously from the pre-fulfilled
+    // serverData cache (matches the server HTML — no mismatch).
+    return use(Promise.resolve(loader())) as T;
+  }
+  return data ?? seed;
+}
+
 /**
  * Client-side redirect — replaces the current history entry with `href`.
  * Drop-in for Next's `redirect` when called from a client component