Complete reference

Every public Turtle surface.

The package exposes four entry points and three CLI commands. Everything else is framework-private.

`turtle`

Export	Purpose
`defineConfig(config)`	Identity helper preserving configuration literals; runtime validation occurs when Turtle loads the config.
`TurtleConfig`	Application configuration type.
`AssetLoader`	`"file" \| "text" \| "wasm"`.
`Redirect`	Source, destination, and optional permanent flag.
`EndpointPolicy`	Full endpoint decision: session, verification, subscription, admin, rate limit.
`Metadata`	Title, description, canonical, and Open Graph fields.
`ResolvedMetadata`	Fully merged internal/public metadata shape passed to dynamic metadata parents.
`Viewport`	Width, initial scale, and theme color.

`turtle/navigation`

Export	Signature / behavior
`Link`	Anchor props plus `prefetch?: boolean`; marks same-origin client navigation.
`push(path)`	Flight navigation with a new history entry.
`replace(path)`	Flight navigation replacing history.
`refresh()`	Uncached Flight fetch of the current URL.
`prefetch(path)`	Populate the bounded Flight cache.
`usePathname()`	Subscribe to the current pathname and search string through React external-store semantics.

`turtle/runtime`

Export	Purpose
`headers()`	Copy of active Request headers.
`cookies()`	Read-only parsed cookie map.
`after(operation)`	Register request-owned best-effort post-response work.
`connection()`	Mark active render dynamic and yield once.
`redirect(location)`	Throw a typed same-origin 307 redirect signal.
`notFound()`	Throw a typed 404 signal rendered by the nearest boundary.
`RouteParameters`	Record of string or string-array params.
`RouteHandlerContext`	Object containing promised route params.
`RouteHandler`	Web Request + context to Response or Promise of Response.

`turtle/vercel`

createVercelHandler(handleRequest) projects a Turtle/Web handler into Vercel's { fetch } module shape. It adds no hidden policy or error handling.

CLI

Command	Behavior
`turtle build`	Clean deterministic production build.
`turtle dev`	Development build, HTTP server, recursive watcher, HMR event stream.
`turtle start`	Run an existing production build.

Generated protocols

/__flight?route=… is Turtle's same-origin GET transport with text/x-component. Redirect, title, and description use X-RSC-* headers. /__hmr exists only in development. /__runtime and /__assets exist only when diagnostics are enabled.

Deliberate non-features

No Server Actions or "use server" mutations.
No server cache contract.
No dynamic JSX-to-image renderer.
No optional catch-all routes or Next.js compatibility layer.
No implicit middleware authorization.
No hidden environment exposure.
No production minification until Bun proves the complete graphs valid.

Minimal types

type EndpointPolicy = {
  session: "none" | "required";
  verification: "none" | "required";
  subscription: "none" | "required";
  admin: "none" | "required";
  rateLimit: "none" | "standard" | "strict";
};

type RouteHandler = (
  request: Request,
  context: { params: Promise<Record<string, string | string[]>> },
) => Response | Promise<Response>;