@k8ordo/framework 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Koki Sakano
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,177 @@
-# Temporary Holding Version
+# @k8ordo/framework
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Turns `src/routes/` into an application of React Server Components, built
+with Vite, and lets the same routes run with or without a server.
+`mode: 'static'` renders every page at build time into files any static host
+serves. `mode: 'server'` renders per request, which is what gives an
+application Server Actions, guards, cookies and a real 404. The routes, the
+boundaries and the request handler are the same in both.
+
+Like every [k8ordo](https://ordo.k8o.me) package it assumes React 19 and Server
+Components, uses only what has reached Baseline newly available, and ships no
+polyfills or legacy fallbacks.
+
+- **Documentation**: https://ordo.k8o.me/en/framework
+- **Design guide**: [docs/GUIDE.md](docs/GUIDE.md) — shipped inside this package
+
+## Installation
+
+```bash
+npm install react react-dom server-only
+npm install -D @k8ordo/framework @k8ordo/router vite typescript @types/node @types/react @types/react-dom
+# or
+pnpm add react react-dom server-only
+pnpm add -D @k8ordo/framework @k8ordo/router vite typescript @types/node @types/react @types/react-dom
+```
+
+`@k8ordo/router` is a required peer, so the application and the framework
+share one copy, but the application imports from `@k8ordo/framework`, which
+re-exports what it needs (`href`, `notFound`, `PageProps`, …). Both are dev
+dependencies in either mode: the build bundles what the application runs.
+
+## Peer Dependencies
+
+<!-- peers -->
+
+| Package          | Version | Required | Needed for                                 |
+| ---------------- | ------- | -------- | ------------------------------------------ |
+| `@k8ordo/router` | ^1.0.0  | yes      | routing, re-exported by the framework      |
+| `react`          | ≥19.3.0 | yes      | rendering                                  |
+| `react-dom`      | ≥19.3.0 | yes      | rendering                                  |
+| `vite`           | ≥8.0.0  | yes      | the build (`framework()` is a Vite plugin) |
+
+<!-- /peers -->
+
+## Quick Start
+
+```ts
+// vite.config.ts
+import { framework } from '@k8ordo/framework/vite';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  plugins: [
+    framework({
+      mode: 'static',
+      paths: () => ['/products/1', '/products/2'], // for routes with parameters
+      site: 'https://example.com', // and a sitemap.xml
+    }),
+  ],
+});
+// or: framework({ mode: 'server' }) — rendered per request
+```
+
+```
+src/routes/
+  layout.tsx            <html> and <body>; wraps everything through `children`
+  page.tsx              /
+  not-found.tsx         static: 404.html — server: a real 404
+  error.tsx             shown in place of what is below when it throws
+  products/[id]/
+    page.tsx            /products/:id — `export const paramsSchema` types :id
+    fallback.tsx        static: the shell for the ids paths does not list
+  old/redirect.ts       /old sends the visitor elsewhere
+  feed.xml/route.ts     /feed.xml answered by its GET — a Response, not a page
+  admin/guard.ts        server mode: runs before everything under /admin
+```
+
+```tsx
+// src/routes/products/[id]/page.tsx
+import { notFound } from '@k8ordo/framework';
+import type { PageProps } from '@k8ordo/framework';
+
+export default async function ProductPage({
+  params,
+}: PageProps<'/products/:id'>) {
+  const product = await findProduct(params.id);
+  if (product === undefined) notFound();
+  return <h1>{product.name}</h1>;
+}
+```
+
+```bash
+vite dev     # renders per request, with Fast Refresh
+vite build   # static: dist/client/ is the site
+```
+
+Under `mode: 'server'` the build is a `dist/` that runs on its own — every
+dependency bundled in, nothing to install where it is deployed — a form
+posts to a Server Action, and a page receives `request`, the headers and the
+cookies, read-only:
+
+```bash
+vite build
+PORT=3000 node dist/server.js
+```
+
+```ts
+// src/lib/actions.ts
+'use server';
+
+import { href } from '@k8ordo/framework';
+import { redirect } from '@k8ordo/framework/server';
+
+export async function createTalk(_previous: FormState, formData: FormData) {
+  const parsed = parseForm(talkSchema, formData);
+  if (!parsed.success) return parsed.state;
+  await insertTalk(parsed.data);
+  redirect(href('/talks')); // 303 without JavaScript, a navigation with it
+}
+```
+
+The built handler, `dist/rsc/index.js`, is a plain
+`(request: Request) => Promise<Response>` that needs nothing from its runtime
+but `AsyncLocalStorage`, so Node.js, Bun, Deno and Cloudflare Workers
+(`nodejs_compat`) all run it, and `vercel()` from `@k8ordo/framework/vercel`
+writes a build for Vercel.
+
+Under `mode: 'static'` there is no request, so the build refuses by name
+whatever needs one — a `'use server'` module, a `guard.ts`, an import of
+`@k8ordo/framework/server` — in `vite dev` as well: `this application wants
+mode: 'server'`.
+
+A value `paths` does not list — a product added after the build — is
+answered by a `fallback.tsx` beside the page: the build writes it once as a
+shell, the layouts in HTML, and the browser draws the page from the URL.
+The build also writes the `_redirects` through which Netlify and Cloudflare
+reach the shell, and `vercel()` the same rewrites for Vercel.
+
+## AI Agent Documentation
+
+The docs ship **inside the package**, so an agent always reads the exact
+version you installed — there is no snapshot to copy or re-sync on upgrade.
+
+Point your agent at them once by pasting this into your project's `CLAUDE.md` /
+`AGENTS.md`:
+
+```markdown
+This application is built with `@k8ordo/framework` (see `mode` in
+`vite.config.ts`). Before adding or changing a route, read
+`node_modules/@k8ordo/framework/docs/GUIDE.md`, then only the
+`docs/references/*.md` it lists that the task needs. `src/routes/` is the
+pathname space and holds only page.tsx, layout.tsx, not-found.tsx,
+error.tsx, loading.tsx, fallback.tsx, redirect.ts, guard.ts and route.ts;
+components go in `src/components/` and every other module (Server Actions,
+schemas, state definitions, data, helpers) in `src/lib/`, since a
+`_`-prefixed directory there is a URL segment, not a private one. Never
+edit `.k8ordo/` — it is generated, with the `Register` augmentations: the
+route table's, and `@k8ordo/i18n`'s when `src/i18n.ts` exports the locale
+set by the name `locales` (write that one by hand only when the set lives
+elsewhere). Import from `@k8ordo/framework` (never
+`@k8ordo/router`), and the request API from `@k8ordo/framework/server`,
+which `mode: 'static'` refuses. Build links with `href()`; search params
+are `@k8ordo/state`'s.
+```
+
+What each surface gives an agent:
+
+| Surface                    | Where                                                 |
+| -------------------------- | ----------------------------------------------------- |
+| Design guide (entry point) | `node_modules/@k8ordo/framework/docs/GUIDE.md`        |
+| Reference docs             | `node_modules/@k8ordo/framework/docs/references/*.md` |
+| Docs index for LLMs        | `docs/llms.txt` · https://ordo.k8o.me/llms.txt        |
+| Markdown twin on the web   | https://ordo.k8o.me/framework/docs/GUIDE.md           |
+
+## License
+
+MIT License - see [LICENSE](https://github.com/k35o/k8ordo/blob/main/LICENSE) for details.

package/dist/generated.d.mts

@@ -0,0 +1,2 @@
+import { ErrorComponent, ParamsOf, ParamsSchemaFor, ParsedParams, ParsedParamsMap, Register, defineRoutes } from "@k8ordo/router";
+export { type ErrorComponent, type ParamsOf, type ParamsSchemaFor, type ParsedParams, type ParsedParamsMap, type Register, defineRoutes };

package/dist/generated.mjs

@@ -0,0 +1,2 @@
+import { defineRoutes } from "@k8ordo/router";
+export { defineRoutes };

package/dist/index.d.mts

@@ -0,0 +1,2 @@
+import { BoundLinks, BoundParams, ErrorProps, LayoutProps, MatchOptions, MatchablePattern, NavigateToOptions, PageProps, RegisteredNavigablePattern, RegisteredPageParams, RegisteredParams, RegisteredPattern, RouteContext, bindParams, href, isNotFound, matchPath, navigateTo, normalizePathname, notFound, useMatch, usePathname, usePendingPathname, withBase } from "@k8ordo/router";
+export { type BoundLinks, type BoundParams, type ErrorProps, type LayoutProps, type MatchOptions, type MatchablePattern, type NavigateToOptions, type PageProps, type RegisteredNavigablePattern, type RegisteredPageParams, type RegisteredParams, type RegisteredPattern, type RouteContext, bindParams, href, isNotFound, matchPath, navigateTo, normalizePathname, notFound, useMatch, usePathname, usePendingPathname, withBase };

package/dist/index.mjs

@@ -0,0 +1,2 @@
+import { bindParams, href, isNotFound, matchPath, navigateTo, normalizePathname, notFound, useMatch, usePathname, usePendingPathname, withBase } from "@k8ordo/router";
+export { bindParams, href, isNotFound, matchPath, navigateTo, normalizePathname, notFound, useMatch, usePathname, usePendingPathname, withBase };

package/dist/runtime/app-router.d.mts

@@ -0,0 +1,26 @@
+import { Payload } from "./payload.mjs";
+import { ReactNode } from "react";
+//#region src/runtime/app-router.d.ts
+export declare const setDocumentClient: (client: string) => void;
+/** What a Server Action's answer does to the document, once it is read. */
+export declare const answerAction: (payload: Payload) => Promise<unknown>;
+export declare const setPayloadReader: (read: (stream: ReadableStream<Uint8Array>) => Promise<Payload>) => void;
+/**
+ * The client half under the framework: the tree comes from the server, so
+ * there is no route table in the browser at all — only navigation. The
+ * router supplies that (interception, a deferred render, and resolving the
+ * platform's `finished` once the new tree is on screen); this component
+ * supplies what to load, which is the next page's RSC payload.
+ *
+ * A pathname the application does not have is still the server's answer: it
+ * renders `not-found.tsx` and this renders whatever came back.
+ */
+export declare function AppRouter({ pathname, search, tree, notFound }: {
+  pathname: string;
+  /** The search the page was rendered with, when it reads the search. */
+  search?: string | undefined;
+  tree: ReactNode;
+  /** A shell's not-found, when the tree is a shell. */
+  notFound?: ReactNode | undefined;
+}): ReactNode;
+//#endregion

package/dist/runtime/app-router.mjs

@@ -0,0 +1,272 @@
+"use client";
+import { payloadPathFor } from "./payload-path.mjs";
+import { ShowNotFound } from "./fallback-boundary.mjs";
+import { isPayload } from "./is-payload.mjs";
+import { createPrefetchCache, prefetchTargetOf } from "./prefetch.mjs";
+import { Recover, markNavigated, reloadInstead } from "./recover.mjs";
+import { NavigationGeneration, PathnameProvider, useInterceptedNavigation, withoutBase } from "@k8ordo/router";
+import { startTransition, useDeferredValue, useEffect, useRef, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/runtime/app-router.tsx
+/**
+* Where a Server Action's answer lands. The callback has to be registered
+* before any client component can call one, which is earlier than a component
+* can offer its own setter — so `answerAction` is module-level and the
+* mounted router lends it a way to apply what comes back, and to drop the
+* pages it fetched ahead, which the action may have changed.
+*/
+let mounted = null;
+/**
+* The client this document runs, as named by the payload its HTML was
+* rendered from — the same render that told the HTML which script to load.
+* A fact about the document, not about a component, which is why it is not
+* a prop.
+*/
+let documentClient;
+const setDocumentClient = (client) => {
+	documentClient = client;
+};
+/**
+* A payload rendered for another client comes from a deploy this document
+* predates, and may name client components its script has no entry for.
+* That fails only once the tree renders, where the page's `error.tsx` catches
+* it before `Recover` can — so it is decided before anything renders, and a
+* document load brings the script that can.
+*/
+const canRender = (payload) => payload.client === documentClient;
+/** What a Server Action's answer does to the document, once it is read. */
+const answerAction = async (payload) => {
+	mounted?.forgetPrefetched();
+	if (payload.redirect !== void 0) {
+		await navigation.navigate(payload.redirect).finished;
+		return;
+	}
+	if (!canRender(payload)) return reloadInstead();
+	mounted?.apply(payload);
+	return payload.returnValue;
+};
+let readPayload = () => Promise.reject(/* @__PURE__ */ new Error("k8ordo: payloads are read in the browser only"));
+const setPayloadReader = (read) => {
+	readPayload = read;
+};
+/**
+* The request each fetched payload is still streaming in on. A payload
+* resolves once its top arrives, and a page that awaits its data arrives
+* after — so once its tree is applied, what is still to come is part of a
+* page React is rendering. Cancelled then, the abort would be thrown inside
+* that page, where `Recover` takes it for a page that failed and loads the
+* document. The signal a payload was fetched under cancels it only until its
+* tree is applied (`keep`); after that, the router cancels it once another
+* tree has replaced it.
+*/
+const streams = /* @__PURE__ */ new WeakMap();
+/**
+* A page's payload, or `null` when what came back is not one — a file the
+* host serves, or a URL nothing answers. Reading it imports the client
+* components it names, so a prefetch has those in hand too.
+*/
+const fetchPage = async (payloadPath, signal) => {
+	signal.throwIfAborted();
+	const request = new AbortController();
+	const cancel = () => {
+		request.abort(signal.reason);
+	};
+	signal.addEventListener("abort", cancel, { once: true });
+	const response = await fetch(payloadPath, { signal: request.signal });
+	if (!isPayload(response)) return null;
+	const payload = await readPayload(response.body);
+	streams.set(payload, {
+		cancel: () => {
+			request.abort();
+		},
+		keep: () => {
+			signal.removeEventListener("abort", cancel);
+		}
+	});
+	return payload;
+};
+/** How many payloads this document has applied. It has one router. */
+let applies = 0;
+/**
+* Takes over the request of a payload whose tree is being applied, and
+* returns what applying it puts in state.
+*/
+const hold = (streaming, payload) => {
+	applies += 1;
+	const stream = streams.get(payload);
+	if (stream !== void 0) {
+		stream.keep();
+		streaming.push({
+			trees: payload.notFound === void 0 ? [payload.tree] : [payload.tree, payload.notFound],
+			cancel: stream.cancel,
+			order: applies
+		});
+	}
+	return {
+		tree: payload.tree,
+		notFound: payload.notFound,
+		order: applies
+	};
+};
+/**
+* The router's prefetch cache, made the first time it is asked for. It is
+* only ever asked for in an event or an effect; made as `useRef`'s initial
+* value it would be built, and thrown away, on every render.
+*/
+const cacheIn = (ref) => ref.current ??= createPrefetchCache((payloadPath, signal) => fetchPage(payloadPath, signal));
+/**
+* Where a page's payload is asked for: its path, with the URL's search. A page
+* that reads the search is rendered for it; for any other page the server
+* ignores it — and a static host, which has no such page, ignores it anyway.
+*/
+const payloadUrlFor = (url) => `${payloadPathFor(url.pathname)}${url.search}`;
+/** What starts a prefetch: a pointer onto a link, focus on one, a press. */
+const INTENTS = [
+	"pointerover",
+	"focusin",
+	"pointerdown"
+];
+/**
+* The client half under the framework: the tree comes from the server, so
+* there is no route table in the browser at all — only navigation. The
+* router supplies that (interception, a deferred render, and resolving the
+* platform's `finished` once the new tree is on screen); this component
+* supplies what to load, which is the next page's RSC payload.
+*
+* A pathname the application does not have is still the server's answer: it
+* renders `not-found.tsx` and this renders whatever came back.
+*/
+function AppRouter({ pathname, search, tree, notFound }) {
+	const [latest, setLatest] = useState(() => ({
+		tree,
+		notFound,
+		order: 0
+	}));
+	const current = useDeferredValue(latest);
+	const prefetched = useRef(null);
+	const searchApplied = useRef(search);
+	const streaming = useRef([]);
+	const loading = useRef(0);
+	useEffect(() => {
+		streaming.current = streaming.current.filter((entry) => {
+			if (entry.order > latest.order) return true;
+			if (entry.trees.includes(latest.tree) || entry.trees.includes(current.tree)) return true;
+			entry.cancel();
+			return false;
+		});
+	}, [latest, current]);
+	useEffect(() => {
+		mounted = {
+			apply: (payload) => {
+				searchApplied.current = payload.search;
+				const next = hold(streaming.current, payload);
+				startTransition(() => {
+					setLatest(next);
+				});
+			},
+			forgetPrefetched: () => {
+				cacheIn(prefetched).clear();
+			}
+		};
+		return () => {
+			mounted = null;
+		};
+	}, []);
+	useEffect(() => {
+		if (import.meta.hot === void 0) return void 0;
+		let inFlight;
+		const onServerUpdate = async () => {
+			inFlight?.abort();
+			const controller = new AbortController();
+			inFlight = controller;
+			cacheIn(prefetched).clear();
+			const url = location.href;
+			let payload;
+			try {
+				payload = await fetchPage(payloadUrlFor(new URL(url)), controller.signal);
+			} catch (error) {
+				if (controller.signal.aborted) return;
+				throw error;
+			}
+			if (payload === null || location.href !== url) return;
+			if (!canRender(payload)) return reloadInstead();
+			markNavigated();
+			const next = hold(streaming.current, payload);
+			searchApplied.current = payload.search;
+			startTransition(() => {
+				setLatest(next);
+			});
+		};
+		const listener = () => {
+			onServerUpdate();
+		};
+		import.meta.hot.on("rsc:update", listener);
+		return () => {
+			inFlight?.abort();
+			import.meta.hot?.off("rsc:update", listener);
+		};
+	}, []);
+	useEffect(() => {
+		const onIntent = (event) => {
+			const url = prefetchTargetOf(event.target);
+			if (url !== null) cacheIn(prefetched).prefetch(payloadUrlFor(url));
+		};
+		for (const type of INTENTS) document.addEventListener(type, onIntent, {
+			capture: true,
+			passive: true
+		});
+		return () => {
+			for (const type of INTENTS) document.removeEventListener(type, onIntent, { capture: true });
+		};
+	}, []);
+	const { generation } = useInterceptedNavigation({
+		claim: (url) => url.origin === location.origin && withoutBase(url.pathname) !== null,
+		load: async (url, signal) => {
+			loading.current += 1;
+			try {
+				const payloadPath = payloadUrlFor(url);
+				let payload;
+				try {
+					payload = await (cacheIn(prefetched).take(payloadPath, signal) ?? fetchPage(payloadPath, signal));
+				} catch (error) {
+					if (signal.aborted) throw error;
+					return await reloadInstead();
+				}
+				signal.throwIfAborted();
+				if (payload === null) return await reloadInstead();
+				if (!canRender(payload)) return await reloadInstead();
+				return payload;
+			} finally {
+				loading.current -= 1;
+			}
+		},
+		apply: (next) => {
+			markNavigated();
+			searchApplied.current = next.search;
+			setLatest(hold(streaming.current, next));
+		},
+		refresh: (url) => searchApplied.current !== void 0 && url.search !== searchApplied.current
+	});
+	const shown = current;
+	const show = () => {
+		if (loading.current > 0) return false;
+		setLatest((previous) => previous === shown ? {
+			tree: shown.notFound,
+			notFound: void 0,
+			order: shown.order
+		} : previous);
+		return true;
+	};
+	return /* @__PURE__ */ jsx(PathnameProvider, {
+		pathname,
+		children: /* @__PURE__ */ jsx(NavigationGeneration, {
+			value: generation,
+			children: /* @__PURE__ */ jsx(Recover, { children: /* @__PURE__ */ jsx(ShowNotFound, {
+				value: current.notFound === void 0 ? null : show,
+				children: current.tree
+			}) })
+		})
+	});
+}
+//#endregion
+export { AppRouter, answerAction, setDocumentClient, setPayloadReader };

package/dist/runtime/browser-payloads.d.mts

@@ -0,0 +1,8 @@
+//#region src/runtime/browser-payloads.d.ts
+/**
+ * Hands app-router the browser's Flight client: how a fetched payload is
+ * read, and where a Server Action is sent. Called by the browser entry
+ * before anything renders.
+ */
+export declare const connectAppRouter: () => void;
+//#endregion

package/dist/runtime/browser-payloads.mjs

@@ -0,0 +1,23 @@
+import { ACTION_ID_HEADER } from "./payload.mjs";
+import { answerAction, setPayloadReader } from "./app-router.mjs";
+import { createFromFetch, createFromReadableStream, createTemporaryReferenceSet, encodeReply, setServerCallback } from "@vitejs/plugin-rsc/browser";
+//#region src/runtime/browser-payloads.ts
+/**
+* Hands app-router the browser's Flight client: how a fetched payload is
+* read, and where a Server Action is sent. Called by the browser entry
+* before anything renders.
+*/
+const connectAppRouter = () => {
+	setPayloadReader((stream) => createFromReadableStream(stream));
+	setServerCallback(async (id, args) => {
+		const temporaryReferences = createTemporaryReferenceSet();
+		const payload = await createFromFetch(fetch(location.href, {
+			method: "POST",
+			headers: { [ACTION_ID_HEADER]: id },
+			body: await encodeReply(args, { temporaryReferences })
+		}), { temporaryReferences });
+		return answerAction(payload);
+	});
+};
+//#endregion
+export { connectAppRouter };

package/dist/runtime/cancel.d.mts

@@ -0,0 +1,11 @@
+//#region src/runtime/cancel.d.ts
+/**
+ * `stream` as its reader reads it, with `cancelled` told first when that
+ * reader gives up — a visitor who left, a navigation overtaken — before the
+ * cancellation reaches the render writing into `stream`. A render that is
+ * cancelled reports everything it was still rendering as failed, with the
+ * reason the host gave, and only what is told first can tell that apart from
+ * a page that failed.
+ */
+export declare const noticeCancel: <T>(stream: ReadableStream<T>, cancelled: (reason: unknown) => void) => ReadableStream<T>;
+//#endregion

package/dist/runtime/cancel.mjs

@@ -0,0 +1,25 @@
+//#region src/runtime/cancel.ts
+/**
+* `stream` as its reader reads it, with `cancelled` told first when that
+* reader gives up — a visitor who left, a navigation overtaken — before the
+* cancellation reaches the render writing into `stream`. A render that is
+* cancelled reports everything it was still rendering as failed, with the
+* reason the host gave, and only what is told first can tell that apart from
+* a page that failed.
+*/
+const noticeCancel = (stream, cancelled) => {
+	const reader = stream.getReader();
+	return new ReadableStream({
+		async pull(controller) {
+			const { done, value } = await reader.read();
+			if (done) controller.close();
+			else controller.enqueue(value);
+		},
+		cancel(reason) {
+			cancelled(reason);
+			return reader.cancel(reason);
+		}
+	});
+};
+//#endregion
+export { noticeCancel };

package/dist/runtime/cookies.d.mts

@@ -0,0 +1,50 @@
+//#region src/runtime/cookies.d.ts
+/**
+ * How a cookie is kept. The defaults are the ones a session wants: sent on
+ * every path, never readable from a page's script, only over HTTPS, and not
+ * on another site's POST.
+ */
+export type CookieOptions = {
+  /** Default `/`. */
+  readonly path?: string;
+  readonly domain?: string;
+  /** Seconds until it expires; `0` expires it now. */
+  readonly maxAge?: number;
+  readonly expires?: Date;
+  /** Default `true`: a page's script cannot read it. */
+  readonly httpOnly?: boolean;
+  /**
+   * Default `true`: sent only over HTTPS. On plain HTTP to this machine —
+   * `localhost`, `127.0.0.1` or `[::1]` — the default is `false`, because
+   * Safari drops a `Secure` cookie there. Say `false` for plain HTTP
+   * anywhere else.
+   */
+  readonly secure?: boolean;
+  /** Default `'lax'`. `'none'` needs `secure`, and defaults to it. */
+  readonly sameSite?: 'strict' | 'lax' | 'none';
+};
+/** Where a cookie lives, which is what deleting one has to name again. */
+export type CookieScope = Pick<CookieOptions, 'path' | 'domain'>;
+/**
+ * The request's cookies, and what this answer does to them. A read sees the
+ * writes made earlier in the same request; the browser sees them as
+ * `Set-Cookie` on the answer.
+ */
+export type Cookies = {
+  readonly get: (name: string) => string | undefined;
+  readonly has: (name: string) => boolean;
+  readonly set: (name: string, value: string, options?: CookieOptions) => void;
+  readonly delete: (name: string, scope?: CookieScope) => void;
+};
+/**
+ * The jar a request's answer writes through: the cookies the request
+ * carried, overlaid with what was set or deleted since, and the
+ * `Set-Cookie` lines that say so. A cookie set twice at the same path and
+ * domain is said once, the last way. `url` is the request's, which decides
+ * whether a cookie is `Secure` by default.
+ */
+export declare const createCookies: (incoming: ReadonlyMap<string, string>, url: URL) => {
+  readonly cookies: Cookies;
+  readonly lines: () => string[];
+};
+//#endregion