@tschk/moonshine-next 0.3.1 → 0.3.3

package/README.md

@@ -1,31 +1,139 @@
 # `@tschk/moonshine-next`
 
-Next.js adapter for Moonshine. Re-exports real Next.js libraries on subpaths
-plus moonshine signal bridges.
+Moonshine **reimplements the Next.js API surface**. It does not wrap, re-export,
+or depend on Next — `next` is not a dependency, a peer dependency, or a
+devDependency of this package. You keep writing `next/link`, `next/navigation`,
+`next/image`; moonshine provides them, on its own signal runtime and router.
 
 ```ts
 import { createSignal, useSignal } from "@tschk/moonshine-next";
-import { useRouter, usePathnameSignal } from "@tschk/moonshine-next/navigation";
+import { useRouter, usePathname } from "@tschk/moonshine-next/navigation";
 import Link from "@tschk/moonshine-next/link";
 import Image from "@tschk/moonshine-next/image";
-import { headers } from "@tschk/moonshine-next/headers";
-import { useFragmentShader } from "@tschk/moonshine-next/shaders";
+import { headers, cookies } from "@tschk/moonshine-next/headers";
 import { moonshineRoute, moonshineJson } from "@tschk/moonshine-next/server";
 ```
 
-| Subpath          | Host library                                       |
-| ---------------- | -------------------------------------------------- |
-| `.` / `./client` | moonshine signals + resources (`"use client"`)     |
-| `./navigation`   | `next/navigation` + pathname/search signals        |
-| `./link`         | `next/link`                                        |
-| `./image`        | `next/image`                                       |
-| `./headers`      | `next/headers` (server only)                       |
-| `./dynamic`      | `next/dynamic`                                     |
-| `./shaders`      | moonshine WebGL helpers                            |
-| `./server`       | `moonshineRoute` / `Json` / `Html` + pages helpers |
+Peers: `react` >= 18, `react-dom` >= 18. That is the whole runtime requirement.
 
-Peer: `next` >= 15, `react` >= 18, `react-dom` >= 18.
+## Drop-in: keep your existing imports
 
-Does **not** export `MoonshineRouter` — use the Next.js App Router.
+You do not have to rewrite a single import. Map the `next/*` specifiers onto
+this package at build time.
+
+### Bun
+
+```ts
+import { moonshineNextPlugin } from "@tschk/moonshine-next/aliases";
+
+await Bun.build({
+  entrypoints: ["./app/page.tsx"],
+  plugins: [moonshineNextPlugin()],
+});
+```
+
+For `bun run` / `bun test`, register it in a preload file:
+
+```ts
+// bun-preload.ts
+import { plugin } from "bun";
+import { moonshineNextPlugin } from "@tschk/moonshine-next/aliases";
+
+plugin(moonshineNextPlugin());
+```
+
+```toml
+# bunfig.toml
+preload = ["./bun-preload.ts"]
+```
+
+### TypeScript
+
+So the type checker follows the same mapping the bundler applies:
+
+```jsonc
+{
+  "compilerOptions": {
+    "paths": {
+      "next/link": ["@tschk/moonshine-next/link"],
+      "next/navigation": ["@tschk/moonshine-next/navigation"],
+      "next/image": ["@tschk/moonshine-next/image"],
+      "next/script": ["@tschk/moonshine-next/script"],
+      "next/headers": ["@tschk/moonshine-next/headers"],
+      "next/dynamic": ["@tschk/moonshine-next/dynamic"],
+      "next/font/google": ["@tschk/moonshine-next/font/google"],
+    },
+  },
+}
+```
+
+`tsconfigPaths()` from `@tschk/moonshine-next/aliases` returns exactly that
+object, and `nextAliases` is the raw specifier map if you need to feed another
+bundler (esbuild `alias`, Vite `resolve.alias`, webpack `resolve.alias`).
+
+## Supported
+
+| Subpath          | Provides                                                                                                                                              |
+| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `.` / `./client` | moonshine signals + resources (`"use client"`)                                                                                                        |
+| `./navigation`   | `useRouter` `usePathname` `useSearchParams` `useParams` `redirect` `permanentRedirect` `notFound` `useSelectedLayoutSegment(s)` + `usePathnameSignal` |
+| `./link`         | default `Link` — client navigation, hover/viewport prefetch                                                                                           |
+| `./image`        | default `Image` — `src` `alt` `width` `height` `fill` `priority` `loading` `sizes`                                                                    |
+| `./script`       | default `Script` — `strategy` mapped to `async`/`defer`                                                                                               |
+| `./headers`      | `headers()` `cookies()` `draftMode()` (server only)                                                                                                   |
+| `./dynamic`      | default `dynamic()` with `loading`, `ssr: false`, `.preload()`                                                                                        |
+| `./font/google`  | named family loaders returning `{ className, style, variable, href }`                                                                                 |
+| `./aliases`      | `next/*` → moonshine specifier mapping + Bun plugin                                                                                                   |
+| `./shaders`      | moonshine WebGL fragment helpers                                                                                                                      |
+| `./server`       | `moonshineRoute` / `moonshineJson` / `moonshineHtml` + page helpers                                                                                   |
+
+Behavioural notes where moonshine deliberately differs from Next:
+
+- **`Link` prefetch is a browser hint.** It appends `<link rel="prefetch">` on
+  hover and on viewport entry. There is no RSC payload to warm, so this is not
+  Next's prefetch cache — it only primes the HTTP cache.
+- **`Link` scroll follows the destination.** Next always jumps to the top;
+  moonshine only scrolls when the pathname or hash actually changes, so
+  query-only navigation (filters, pagination, tabs) keeps your scroll position.
+  Pass `scroll` explicitly to force either behaviour.
+- **`router.refresh()` and `router.prefetch()` are no-ops.** Moonshine
+  re-renders from its signal graph; there is no server round trip to invalidate.
+- **`redirect()` / `notFound()`** throw `RedirectError` / `NotFoundError`,
+  exported from `./navigation` so your renderer can catch them.
+- **`useSearchParams()`** reads the live query string. The moonshine router
+  stores only the pathname, so the query is recovered from `window.location`.
+
+## Not supported
+
+Be aware of these before migrating — none of them are stubbed to silently
+"work":
+
+- **No image optimizer.** `next/image` renders a plain `<img>`. `src` is served
+  exactly as authored; `quality` and `unoptimized` are accepted and ignored.
+  There is no resizing, no format negotiation, no `srcSet` generation, no
+  `loader` / `remotePatterns` config, no blur placeholder.
+- **No React Server Components.** No `"use server"`, no Server Actions, no
+  server-only component tree, no streaming RSC payload.
+- **No ISR / on-demand revalidation.** No `revalidate`, no `revalidatePath`, no
+  `revalidateTag`, no `unstable_cache`, no fetch cache semantics.
+- **No middleware.** `middleware.ts` is not read; there is no edge interception
+  layer. Use the moonshine server directly.
+- **No `next/font` self-hosting.** `next/font/google` does not download or
+  subset fonts at build time. It returns Next's `{ className, style, variable }`
+  shape plus an `href`, and you emit the Google Fonts `<link>` tags yourself via
+  `fontLinks()`. That means a third-party request at runtime, which is exactly
+  what Next's self-hosting avoids. `next/font/local` is not implemented.
+- **No file-system routing conventions.** `layout.tsx`, `loading.tsx`,
+  `error.tsx`, `template.tsx`, route groups, parallel and intercepting routes
+  are not interpreted. Use the moonshine router.
+- **No `next/headers` mutation.** `cookies()` is read-only — no `set()` or
+  `delete()`. `draftMode()` always reports disabled.
+- **Other `next/*` modules are absent**, including `next/server`
+  (`NextRequest` / `NextResponse`), `next/og`, `next/cache`, and
+  `next/navigation`'s `unstable_*` APIs. Route Handlers take and return plain
+  `Request` / `Response`; see `./server`.
+
+Does **not** export `MoonshineRouter` from the client entry — import it from
+`@tschk/moonshine/router` if you want the moonshine router directly.
 
 See [Moonshine README](../../README.md).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tschk/moonshine-next",
-  "version": "0.3.1",
-  "description": "Next.js adapter — moonshine signals + next/navigation|link|image|headers|shaders",
+  "version": "0.3.3",
+  "description": "Next.js API surface reimplemented on moonshine — drop Next, keep the imports",
   "license": "ISC",
   "type": "module",
   "main": "./src/index.ts",
@@ -13,16 +13,19 @@
     "./navigation": "./src/navigation.ts",
     "./link": "./src/link.ts",
     "./image": "./src/image.ts",
+    "./script": "./src/script.ts",
     "./headers": "./src/headers.ts",
     "./dynamic": "./src/dynamic.ts",
+    "./font/google": "./src/font/google.ts",
+    "./aliases": "./src/aliases.ts",
     "./shaders": "./src/shaders.ts"
   },
   "dependencies": {
-    "@tschk/moonshine": "^0.3.1",
-    "@tschk/moonshine-shaders": "^0.3.1"
+    "@tschk/moonshine": "^0.3.3",
+    "@tschk/moonshine-router": "^0.3.3",
+    "@tschk/moonshine-shaders": "^0.3.3"
   },
   "peerDependencies": {
-    "next": ">=15",
     "react": ">=18",
     "react-dom": ">=18"
   },
@@ -38,7 +41,7 @@
   "scripts": {
     "format": "bunx prettier --check .",
     "lint": "bunx oxlint .",
-    "typecheck": "exit 0",
+    "typecheck": "bunx tsc --noEmit",
     "test": "bun test"
   }
 }

package/src/aliases.ts

@@ -0,0 +1,67 @@
+/**
+ * Drop-in mapping from `next/*` specifiers onto this package.
+ *
+ * An existing Next app keeps writing `import Link from "next/link"` — the
+ * bundler rewrites the specifier, so no source import changes.
+ *
+ * ```ts
+ * import { moonshineNextPlugin } from "@tschk/moonshine-next/aliases";
+ * await Bun.build({ entrypoints: ["./app.tsx"], plugins: [moonshineNextPlugin()] });
+ * ```
+ */
+import { join } from "node:path";
+import type { BunPlugin } from "bun";
+
+/** Bare specifier each `next/*` subpath is served by. */
+export const nextAliases: Readonly<Record<string, string>> = {
+  "next/link": "@tschk/moonshine-next/link",
+  "next/navigation": "@tschk/moonshine-next/navigation",
+  "next/image": "@tschk/moonshine-next/image",
+  "next/script": "@tschk/moonshine-next/script",
+  "next/headers": "@tschk/moonshine-next/headers",
+  "next/dynamic": "@tschk/moonshine-next/dynamic",
+  "next/font/google": "@tschk/moonshine-next/font/google",
+};
+
+/** File in this package backing each alias, relative to `src/`. */
+const files: Readonly<Record<string, string>> = {
+  "next/link": "link.ts",
+  "next/navigation": "navigation.ts",
+  "next/image": "image.ts",
+  "next/script": "script.ts",
+  "next/headers": "headers.ts",
+  "next/dynamic": "dynamic.ts",
+  "next/font/google": "font/google.ts",
+};
+
+/**
+ * `compilerOptions.paths` block for an app's tsconfig, so the type checker
+ * follows the same mapping the bundler applies.
+ */
+export function tsconfigPaths(): Record<string, string[]> {
+  return Object.fromEntries(
+    Object.entries(nextAliases).map(([from, to]) => [from, [to]]),
+  );
+}
+
+/** Absolute path this package serves `specifier` from, if it is aliased. */
+export function resolveAlias(specifier: string): string | undefined {
+  const file = files[specifier];
+  return file === undefined ? undefined : join(import.meta.dir, file);
+}
+
+const filter =
+  /^next\/(link|navigation|image|script|headers|dynamic|font\/google)$/;
+
+/** Bun bundler/runtime plugin rewriting `next/*` to this package. */
+export function moonshineNextPlugin(): BunPlugin {
+  return {
+    name: "moonshine-next-aliases",
+    setup(build) {
+      build.onResolve({ filter }, (args) => {
+        const path = resolveAlias(args.path);
+        return path === undefined ? undefined : { path };
+      });
+    },
+  };
+}

package/src/dynamic.ts

@@ -1,6 +1,56 @@
 "use client";
 
 /**
- * next/dynamic re-export for lazy client islands.
+ * `next/dynamic` on React.lazy.
+ *
+ * ```ts
+ * const Chart = dynamic(() => import("./chart"), { ssr: false });
+ * ```
  */
-export { default } from "next/dynamic";
+import {
+  createElement,
+  lazy,
+  Suspense,
+  type ComponentType,
+  type ReactNode,
+} from "react";
+
+export type DynamicOptions = {
+  /** `false` renders the fallback until the component mounts on the client. */
+  ssr?: boolean;
+  loading?: ComponentType;
+};
+
+type Loader<P> = () => Promise<
+  { default: ComponentType<P> } | ComponentType<P>
+>;
+
+/** Next's `dynamic()` result also carries `preload()`, as does Solid's `lazy`. */
+export type DynamicComponent<P> = ComponentType<P> & {
+  preload(): Promise<{ default: ComponentType<P> }>;
+};
+
+export default function dynamic<P extends object>(
+  loader: Loader<P>,
+  options: DynamicOptions = {},
+): DynamicComponent<P> {
+  // Solid memoizes the import promise so `preload()` and the first render share
+  // one in-flight request instead of importing the chunk twice.
+  let pending: Promise<{ default: ComponentType<P> }> | undefined;
+  const load = (): Promise<{ default: ComponentType<P> }> =>
+    (pending ??= loader().then((mod) =>
+      "default" in mod ? mod : { default: mod },
+    ));
+
+  const Lazy = lazy(load);
+  const Loading = options.loading;
+  const fallback: ReactNode = Loading ? createElement(Loading) : null;
+
+  const DynamicComponent = (props: P): ReactNode => {
+    if (options.ssr === false && typeof window === "undefined") return fallback;
+    return createElement(Suspense, { fallback }, createElement(Lazy, props));
+  };
+  DynamicComponent.displayName = "DynamicComponent";
+  DynamicComponent.preload = load;
+  return DynamicComponent;
+}

package/src/font/google.ts

@@ -0,0 +1,116 @@
+/**
+ * `next/font/google` without the build-time download.
+ *
+ * Each loader returns the same `{ className, style, variable }` shape Next
+ * produces, plus the `<link>` hrefs to reach the family. Emit those with
+ * `fontLinks()` in the document head.
+ *
+ * ```ts
+ * const inter = Inter({ subsets: ["latin"] });
+ * <body className={inter.className}>
+ * ```
+ */
+export type FontOptions = {
+  subsets?: string[];
+  weight?: string | string[];
+  style?: string | string[];
+  display?: "auto" | "block" | "swap" | "fallback" | "optional";
+  variable?: string;
+  preload?: boolean;
+  fallback?: string[];
+};
+
+export type FontModule = {
+  className: string;
+  style: { fontFamily: string; fontWeight?: string; fontStyle?: string };
+  variable: string;
+  /** Stylesheet URL for this family; render it in the document head. */
+  href: string;
+};
+
+const registry = new Map<string, string>();
+
+function familyToCss(family: string, fallback?: string[]): string {
+  const quoted = `'${family}'`;
+  return [quoted, ...(fallback ?? [])].join(", ");
+}
+
+function slug(family: string): string {
+  return family.toLowerCase().replaceAll(/[^a-z\d]+/g, "-");
+}
+
+function buildHref(family: string, options: FontOptions): string {
+  const weights = Array.isArray(options.weight)
+    ? options.weight
+    : options.weight
+      ? [options.weight]
+      : [];
+  const axis = weights.filter((w) => w !== "variable").join(";");
+  const name = family.replaceAll(" ", "+");
+  const spec = axis ? `${name}:wght@${axis}` : name;
+  return `https://fonts.googleapis.com/css2?family=${spec}&display=${options.display ?? "swap"}`;
+}
+
+function loader(family: string) {
+  return (options: FontOptions = {}): FontModule => {
+    const href = buildHref(family, options);
+    registry.set(family, href);
+    const className = `__moonshine_font_${slug(family)}`;
+    return {
+      className,
+      variable: options.variable ?? className,
+      href,
+      style: {
+        fontFamily: familyToCss(family, options.fallback),
+        ...(typeof options.weight === "string" && options.weight !== "variable"
+          ? { fontWeight: options.weight }
+          : {}),
+      },
+    };
+  };
+}
+
+/** Stylesheet hrefs for every family loaded so far. */
+export function fontHrefs(): string[] {
+  return [...registry.values()];
+}
+
+/** `<link>` tags for every family loaded so far, for the document head. */
+export function fontLinks(): string {
+  return [
+    '<link rel="preconnect" href="https://fonts.googleapis.com" />',
+    '<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />',
+    ...fontHrefs().map((href) => `<link rel="stylesheet" href="${href}" />`),
+  ].join("\n");
+}
+
+/** CSS binding each generated class to its family. */
+export function fontStyles(): string {
+  return [...registry.keys()]
+    .map(
+      (family) =>
+        `.__moonshine_font_${slug(family)}{font-family:${familyToCss(family)}}`,
+    )
+    .join("");
+}
+
+export const Inter = loader("Inter");
+export const Roboto = loader("Roboto");
+export const Roboto_Mono = loader("Roboto Mono");
+export const Open_Sans = loader("Open Sans");
+export const Lato = loader("Lato");
+export const Montserrat = loader("Montserrat");
+export const Poppins = loader("Poppins");
+export const Source_Code_Pro = loader("Source Code Pro");
+export const JetBrains_Mono = loader("JetBrains Mono");
+export const IBM_Plex_Mono = loader("IBM Plex Mono");
+export const Space_Mono = loader("Space Mono");
+export const Space_Grotesk = loader("Space Grotesk");
+export const Chivo_Mono = loader("Chivo Mono");
+export const Geist = loader("Geist");
+export const Geist_Mono = loader("Geist Mono");
+
+/** Any family not exported above. */
+export function googleFont(family: string) {
+  return loader(family);
+}

package/src/headers.ts

@@ -1,8 +1,66 @@
 /**
- * next/headers re-export (Server Components / Route Handlers only).
+ * `next/headers` backed by the moonshine request context.
+ *
+ * Server only. The request is supplied by the renderer via
+ * `runWithRequest`, which the moonshine server calls per request.
  *
  * ```ts
  * import { headers, cookies } from "@tschk/moonshine-next/headers";
  * ```
  */
-export { cookies, draftMode, headers } from "next/headers";
+import { AsyncLocalStorage } from "node:async_hooks";
+
+const store = new AsyncLocalStorage<Request>();
+
+/** Runs `fn` with `request` visible to `headers()` and `cookies()`. */
+export function runWithRequest<T>(request: Request, fn: () => T): T {
+  return store.run(request, fn);
+}
+
+function current(): Request {
+  const request = store.getStore();
+  if (!request) {
+    throw new Error(
+      "headers() was called outside a request. Wrap the render in runWithRequest().",
+    );
+  }
+  return request;
+}
+
+export function headers(): Headers {
+  return current().headers;
+}
+
+export type CookieEntry = { name: string; value: string };
+
+function parseCookies(header: string | null): Map<string, string> {
+  const jar = new Map<string, string>();
+  if (!header) return jar;
+  for (const part of header.split(";")) {
+    const index = part.indexOf("=");
+    if (index === -1) continue;
+    const name = part.slice(0, index).trim();
+    if (name) jar.set(name, decodeURIComponent(part.slice(index + 1).trim()));
+  }
+  return jar;
+}
+
+export function cookies(): {
+  get(name: string): CookieEntry | undefined;
+  getAll(): CookieEntry[];
+  has(name: string): boolean;
+} {
+  const jar = parseCookies(current().headers.get("cookie"));
+  return {
+    get: (name) => {
+      const value = jar.get(name);
+      return value === undefined ? undefined : { name, value };
+    },
+    getAll: () => [...jar].map(([name, value]) => ({ name, value })),
+    has: (name) => jar.has(name),
+  };
+}
+
+export function draftMode(): { isEnabled: boolean } {
+  return { isEnabled: false };
+}

package/src/image.ts

@@ -1,11 +1,67 @@
-"use client";
-
 /**
- * next/image re-export for moonshine apps.
+ * `next/image` as a plain `<img>`.
+ *
+ * There is no image optimizer behind moonshine, so `src` is served as authored
+ * and the layout props map onto native attributes.
  *
  * ```ts
  * import Image from "@tschk/moonshine-next/image";
  * ```
  */
-export { default } from "next/image";
-export type { ImageProps } from "next/image";
+import {
+  createElement,
+  type CSSProperties,
+  type ImgHTMLAttributes,
+  type ReactNode,
+} from "react";
+
+export type ImageProps = Omit<
+  ImgHTMLAttributes<HTMLImageElement>,
+  "src" | "width" | "height" | "loading"
+> & {
+  src: string | { src: string; width?: number; height?: number };
+  alt: string;
+  width?: number | string;
+  height?: number | string;
+  fill?: boolean;
+  priority?: boolean;
+  quality?: number;
+  loading?: "eager" | "lazy";
+  unoptimized?: boolean;
+};
+
+const FILL_STYLE: CSSProperties = {
+  position: "absolute",
+  inset: 0,
+  width: "100%",
+  height: "100%",
+};
+
+export default function Image({
+  src,
+  alt,
+  width,
+  height,
+  fill,
+  priority,
+  quality,
+  loading,
+  unoptimized,
+  style,
+  ...rest
+}: ImageProps): ReactNode {
+  void quality;
+  void unoptimized;
+  const resolved = typeof src === "string" ? { src } : src;
+  return createElement("img", {
+    ...rest,
+    src: resolved.src,
+    alt,
+    width: fill ? undefined : (width ?? resolved.width),
+    height: fill ? undefined : (height ?? resolved.height),
+    loading: loading ?? (priority ? "eager" : "lazy"),
+    decoding: priority ? "sync" : "async",
+    fetchPriority: priority ? "high" : undefined,
+    style: fill ? { ...FILL_STYLE, ...style } : style,
+  });
+}

package/src/link.ts

@@ -1,11 +1,162 @@
 "use client";
 
 /**
- * next/link re-export for moonshine apps.
+ * `next/link` implemented on the moonshine router.
  *
  * ```ts
  * import Link from "@tschk/moonshine-next/link";
  * ```
  */
-export { default } from "next/link";
-export type { LinkProps } from "next/link";
+import {
+  createElement,
+  useCallback,
+  useEffect,
+  useRef,
+  useTransition,
+  type AnchorHTMLAttributes,
+  type MouseEvent,
+  type ReactNode,
+} from "react";
+import { navigate } from "@tschk/moonshine/router";
+
+export type LinkProps = Omit<
+  AnchorHTMLAttributes<HTMLAnchorElement>,
+  "href"
+> & {
+  href: string | { pathname?: string; query?: Record<string, string> };
+  replace?: boolean;
+  scroll?: boolean;
+  /**
+   * Emits a `<link rel="prefetch">` browser hint. Moonshine has no RSC payload
+   * to warm, so this is not Next's prefetch cache.
+   */
+  prefetch?: boolean | null;
+  children?: ReactNode;
+};
+
+function hrefToString(href: LinkProps["href"]): string {
+  if (typeof href === "string") return href;
+  const pathname = href.pathname ?? "";
+  const entries = Object.entries(href.query ?? {});
+  if (entries.length === 0) return pathname;
+  return `${pathname}?${new URLSearchParams(entries).toString()}`;
+}
+
+/** External and non-navigational targets must keep the browser's own handling. */
+function isExternal(href: string, target?: string): boolean {
+  if (target && target !== "_self") return true;
+  return (
+    /^[a-zA-Z][a-zA-Z\d+\-.]*:/.test(href) ||
+    href.startsWith("//") ||
+    href.startsWith("#")
+  );
+}
+
+const prefetched = new Set<string>();
+
+/** Warms the browser cache for `url` once, the way Waku prefetches a route. */
+function prefetchOnce(url: string): void {
+  if (prefetched.has(url) || typeof document === "undefined") return;
+  if (isCurrentUrl(url)) return;
+  prefetched.add(url);
+  const tag = document.createElement("link");
+  tag.rel = "prefetch";
+  tag.href = url;
+  document.head.append(tag);
+}
+
+/** True when `url` resolves to the page already showing. */
+function isCurrentUrl(url: string): boolean {
+  if (typeof window === "undefined") return false;
+  return new URL(url, window.location.href).href === window.location.href;
+}
+
+/**
+ * Next always jumps to the top; Waku only scrolls when the destination is a
+ * different document position. Following Waku keeps query-only navigations
+ * (filters, tabs) from throwing the reader back to the top of the page.
+ */
+function shouldScrollByDefault(url: string): boolean {
+  if (typeof window === "undefined") return false;
+  const next = new URL(url, window.location.href);
+  return (
+    next.pathname !== window.location.pathname ||
+    next.hash !== window.location.hash
+  );
+}
+
+export default function Link({
+  href,
+  replace,
+  scroll,
+  prefetch = true,
+  children,
+  onClick,
+  onMouseEnter,
+  ...rest
+}: LinkProps): ReactNode {
+  const url = hrefToString(href);
+  const external = isExternal(url, rest.target);
+  const ref = useRef<HTMLAnchorElement>(null);
+  // Navigation runs in a transition so a slow subtree cannot block the click.
+  const [, startTransition] = useTransition();
+
+  const warm = useCallback(() => {
+    if (prefetch !== false && !external) prefetchOnce(url);
+  }, [prefetch, external, url]);
+
+  useEffect(() => {
+    const node = ref.current;
+    if (!node || prefetch === false || external) return;
+    if (typeof IntersectionObserver === "undefined") return;
+    // Waku's threshold: a one-pixel sliver of a link is not intent to visit it.
+    const observer = new IntersectionObserver(
+      (entries) => {
+        for (const entry of entries) {
+          if (entry.isIntersecting) {
+            warm();
+            observer.disconnect();
+          }
+        }
+      },
+      { threshold: 0.1 },
+    );
+    observer.observe(node);
+    return () => observer.disconnect();
+  }, [warm, prefetch, external]);
+
+  return createElement(
+    "a",
+    {
+      ...rest,
+      ref,
+      href: url,
+      onMouseEnter: (event: MouseEvent<HTMLAnchorElement>) => {
+        onMouseEnter?.(event);
+        warm();
+      },
+      onClick: (event: MouseEvent<HTMLAnchorElement>) => {
+        onClick?.(event);
+        if (
+          event.defaultPrevented ||
+          event.button !== 0 ||
+          event.metaKey ||
+          event.altKey ||
+          event.ctrlKey ||
+          event.shiftKey ||
+          external
+        ) {
+          return;
+        }
+        event.preventDefault();
+        if (isCurrentUrl(url)) return;
+        const jump = scroll ?? shouldScrollByDefault(url);
+        startTransition(() => {
+          navigate(url, { replace });
+          if (jump) globalThis.scrollTo?.(0, 0);
+        });
+      },
+    },
+    children,
+  );
+}

package/src/navigation.ts

@@ -1,76 +1,139 @@
 "use client";
 
 /**
- * next/navigation + moonshine signal bridges.
+ * `next/navigation` implemented on the moonshine router.
  *
  * ```ts
- * import { usePathname, usePathnameSignal, useRouter } from "@tschk/moonshine-next/navigation";
+ * import { useRouter, usePathname } from "@tschk/moonshine-next/navigation";
  * ```
  */
-import { useEffect, useMemo, useRef } from "react";
+import { useMemo } from "react";
 import {
-  useParams as useNextParams,
-  usePathname as useNextPathname,
-  useRouter as useNextRouter,
-  useSearchParams as useNextSearchParams,
-  notFound,
-  permanentRedirect,
-  redirect,
-  useSelectedLayoutSegment,
-  useSelectedLayoutSegments,
-} from "next/navigation";
+  navigate,
+  useLocation,
+  useParams as useMoonshineParams,
+} from "@tschk/moonshine/router";
 import { createSignal, useSignal, type Signal } from "@tschk/moonshine/react";
 
-export {
-  useNextRouter as useRouter,
-  useNextPathname as usePathname,
-  useNextSearchParams as useSearchParams,
-  useNextParams as useParams,
-  redirect,
-  permanentRedirect,
-  notFound,
-  useSelectedLayoutSegment,
-  useSelectedLayoutSegments,
+export type AppRouterInstance = {
+  push(href: string, options?: { scroll?: boolean }): void;
+  replace(href: string, options?: { scroll?: boolean }): void;
+  back(): void;
+  forward(): void;
+  refresh(): void;
+  prefetch(href: string): void;
 };
 
-/** Pathname as a live moonshine signal (updates on App Router navigation). */
-export function usePathnameSignal(): Signal<string> {
-  const pathname = useNextPathname();
-  const signal = useMemo(() => createSignal(pathname), []);
-  const ref = useRef(signal);
-  ref.current = signal;
-  useEffect(() => {
-    ref.current.set(pathname);
-  }, [pathname]);
-  return signal;
+/** Splits `"/a/b?x=1"` into its pathname and its raw query string. */
+export function splitLocation(location: string): [string, string] {
+  const index = location.indexOf("?");
+  return index === -1
+    ? [location, ""]
+    : [location.slice(0, index), location.slice(index + 1)];
 }
 
-/** Search string `?a=1` as signal. */
-export function useSearchSignal(): Signal<string> {
-  const sp = useNextSearchParams();
-  const value = sp?.toString() ? `?${sp.toString()}` : "";
-  const signal = useMemo(() => createSignal(value), []);
-  useEffect(() => {
-    signal.set(value);
-  }, [value, signal]);
-  return signal;
+/**
+ * The moonshine router stores only the pathname, so a query string survives
+ * navigation on `window.location` but not in the location signal. Prefer the
+ * signal when it carries one (SSR / controlled paths) and fall back to the
+ * browser's own search.
+ */
+function readSearch(location: string): string {
+  const fromSignal = splitLocation(location)[1];
+  if (fromSignal) return fromSignal;
+  if (typeof window === "undefined") return "";
+  return window.location.search.replace(/^\?/, "");
 }
 
-/** Read a single search param as signal. */
-export function useSearchParamSignal(
-  name: string,
-  fallback = "",
-): Signal<string> {
-  const sp = useNextSearchParams();
-  const value = sp?.get(name) ?? fallback;
-  const signal = useMemo(() => createSignal(value), []);
-  useEffect(() => {
-    signal.set(value);
-  }, [value, signal]);
-  return signal;
+function shouldScrollByDefault(href: string): boolean {
+  if (typeof window === "undefined") return false;
+  const next = new URL(href, window.location.href);
+  return (
+    next.pathname !== window.location.pathname ||
+    next.hash !== window.location.hash
+  );
+}
+
+export function useRouter(): AppRouterInstance {
+  return useMemo(
+    () => ({
+      push: (href, options) => {
+        const jump = options?.scroll ?? shouldScrollByDefault(href);
+        navigate(href);
+        if (jump) globalThis.scrollTo?.(0, 0);
+      },
+      replace: (href, options) => {
+        const jump = options?.scroll ?? shouldScrollByDefault(href);
+        navigate(href, { replace: true });
+        if (jump) globalThis.scrollTo?.(0, 0);
+      },
+      back: () => globalThis.history?.back(),
+      forward: () => globalThis.history?.forward(),
+      // Moonshine re-renders from its signal graph, so there is no server
+      // round trip to invalidate.
+      refresh: () => {},
+      prefetch: () => {},
+    }),
+    [],
+  );
+}
+
+export function usePathname(): string {
+  return splitLocation(useLocation())[0];
+}
+
+export function useSearchParams(): URLSearchParams {
+  const query = readSearch(useLocation());
+  return useMemo(() => new URLSearchParams(query), [query]);
+}
+
+export function useParams(): Record<string, string> {
+  return useMoonshineParams();
+}
+
+export function useSelectedLayoutSegments(): string[] {
+  return usePathname().split("/").filter(Boolean);
+}
+
+export function useSelectedLayoutSegment(): string | null {
+  return useSelectedLayoutSegments()[0] ?? null;
+}
+
+/** Thrown to unwind rendering, matching Next's control-flow contract. */
+export class RedirectError extends Error {
+  constructor(
+    readonly url: string,
+    readonly permanent: boolean,
+  ) {
+    super(`redirect: ${url}`);
+    this.name = "RedirectError";
+  }
+}
+
+export class NotFoundError extends Error {
+  constructor() {
+    super("not found");
+    this.name = "NotFoundError";
+  }
+}
+
+export function redirect(url: string): never {
+  throw new RedirectError(url, false);
+}
+
+export function permanentRedirect(url: string): never {
+  throw new RedirectError(url, true);
+}
+
+export function notFound(): never {
+  throw new NotFoundError();
 }
 
-/** Convenience: useSignal(usePathnameSignal()). */
-export function useReactivePathname(): string {
-  return useSignal(usePathnameSignal());
+/** Pathname as a live moonshine signal. */
+export function usePathnameSignal(): Signal<string> {
+  const pathname = usePathname();
+  const signal = useMemo(() => createSignal(pathname), []);
+  if (signal() !== pathname) signal.set(pathname);
+  useSignal(signal);
+  return signal;
 }

package/src/script.ts

@@ -0,0 +1,33 @@
+/**
+ * `next/script` as a plain `<script>`.
+ *
+ * ```ts
+ * import Script from "@tschk/moonshine-next/script";
+ * ```
+ */
+import {
+  createElement,
+  type ReactNode,
+  type ScriptHTMLAttributes,
+} from "react";
+
+export type ScriptProps = ScriptHTMLAttributes<HTMLScriptElement> & {
+  /** Next's loading hints map onto `async` / `defer`. */
+  strategy?: "beforeInteractive" | "afterInteractive" | "lazyOnload" | "worker";
+};
+
+export default function Script({
+  strategy = "afterInteractive",
+  children,
+  ...rest
+}: ScriptProps): ReactNode {
+  return createElement(
+    "script",
+    {
+      ...rest,
+      async: rest.async ?? strategy === "lazyOnload",
+      defer: rest.defer ?? strategy === "afterInteractive",
+    },
+    children,
+  );
+}

package/src/shims.d.ts

@@ -1,86 +0,0 @@
-/** Ambient types so adapter builds without installing Next in every workspace. */
-declare module "next/navigation" {
-  export function useRouter(): {
-    push(href: string): void;
-    replace(href: string): void;
-    back(): void;
-    forward(): void;
-    refresh(): void;
-    prefetch(href: string): void;
-  };
-  export function usePathname(): string;
-  export function useSearchParams(): URLSearchParams;
-  export function useParams<
-    T extends Record<string, string | string[]> = Record<string, string>,
-  >(): T;
-  export function redirect(url: string): never;
-  export function notFound(): never;
-  export function permanentRedirect(url: string): never;
-  export function useSelectedLayoutSegment(): string | null;
-  export function useSelectedLayoutSegments(): string[];
-}
-
-declare module "next/link" {
-  import type {
-    ComponentType,
-    ReactNode,
-    CSSProperties,
-    MouseEventHandler,
-  } from "react";
-  export type LinkProps = {
-    href: string;
-    children?: ReactNode;
-    className?: string;
-    style?: CSSProperties;
-    replace?: boolean;
-    scroll?: boolean;
-    prefetch?: boolean;
-    onClick?: MouseEventHandler<HTMLAnchorElement>;
-    [key: string]: unknown;
-  };
-  const Link: ComponentType<LinkProps>;
-  export default Link;
-}
-
-declare module "next/image" {
-  import type { ComponentType, CSSProperties } from "react";
-  export type ImageProps = {
-    src: string | { src: string; height: number; width: number };
-    alt: string;
-    width?: number;
-    height?: number;
-    fill?: boolean;
-    className?: string;
-    style?: CSSProperties;
-    priority?: boolean;
-    quality?: number;
-    sizes?: string;
-    [key: string]: unknown;
-  };
-  const Image: ComponentType<ImageProps>;
-  export default Image;
-}
-
-declare module "next/headers" {
-  export function headers(): Headers;
-  export function cookies(): {
-    get(name: string): { name: string; value: string } | undefined;
-    getAll(): Array<{ name: string; value: string }>;
-    has(name: string): boolean;
-    set(name: string, value: string): void;
-    delete(name: string): void;
-  };
-  export function draftMode(): {
-    isEnabled: boolean;
-    enable(): void;
-    disable(): void;
-  };
-}
-
-declare module "next/dynamic" {
-  import type { ComponentType } from "react";
-  export default function dynamic<P = object>(
-    loader: () => Promise<{ default: ComponentType<P> } | ComponentType<P>>,
-    options?: { ssr?: boolean; loading?: ComponentType },
-  ): ComponentType<P>;
-}