Navigate with Flight, keep client state.

Link

"use client";
import { Link } from "turtle/navigation";

export default function Menu() {
  return <nav><Link href="/docs">Docs</Link><Link href="/large" prefetch={false}>Large</Link></nav>;
}

Link renders an anchor with the Flight marker. It prefetches on hover by default and preserves any supplied mouse handler.

Imperative navigation

import { prefetch, push, refresh, replace, usePathname } from "turtle/navigation";

await prefetch("/docs");
await push("/docs");       // add history entry
await replace("/login");   // replace history entry
await refresh();            // refetch current Flight model
const pathname = usePathname();

Router behavior

• Same-origin marked links use /__flight; external links retain normal browser behavior.
• Prefetch responses have a 30-second TTL and a bounded 24-entry in-memory cache.
• Every new navigation aborts the prior request. A monotonically increasing sequence prevents stale responses from committing even if cancellation races.
• Push, replace, refresh, and popstate are distinct modes. Back/forward navigation re-renders Flight without adding history.
• Title and description update from encoded response headers.
• Route redirects are followed through a client-readable header.
• Invalid Flight responses, cross-origin targets, missing roots, and unexpected errors fall back to a hard document navigation.
• Scroll restoration is manual and history state records the current scroll position.

The cache is a navigation optimization, not a server data cache. Turtle currently provides no server cache contract; use application infrastructure with explicit scope, TTL, coalescing, and invalidation.