@rangojs/router 0.0.0-experimental.13 → 0.0.0-experimental.130

package/src/bin/rango.ts

@@ -1,24 +1,321 @@
-import { resolve } from "node:path";
-import { findTsFiles, writePerModuleRouteTypesForFile } from "../build/generate-route-types.ts";
+import { resolve, dirname } from "node:path";
+import { readFileSync, statSync, existsSync } from "node:fs";
+import {
+  findTsFiles,
+  writePerModuleRouteTypesForFile,
+  writeCombinedRouteTypes,
+  detectUnresolvableIncludes,
+  detectUnresolvableIncludesForUrlsFile,
+  findNestedRouterConflict,
+  formatNestedRouterConflictError,
+  type UnresolvableInclude,
+} from "../build/generate-route-types.ts";
 
-const [command, ...args] = process.argv.slice(2);
+const [command, ...rawArgs] = process.argv.slice(2);
 
-if (command === "extract-names") {
-  const dir = args[0] ?? "./src";
-  const resolvedDir = resolve(dir);
-  console.log(`[rango] Scanning ${resolvedDir} for url modules...`);
+if (command === "generate") {
+  // Parse flags
+  let mode: "default" | "runtime" | "static" = "default";
+  let configFile: string | undefined;
+  const positionalArgs: string[] = [];
+
+  for (let i = 0; i < rawArgs.length; i++) {
+    const arg = rawArgs[i];
+    if (arg === "--runtime") {
+      mode = "runtime";
+    } else if (arg === "--static") {
+      mode = "static";
+    } else if (arg === "--config") {
+      configFile = rawArgs[++i];
+      if (!configFile) {
+        console.error("[rango] --config requires a path argument");
+        process.exit(1);
+      }
+    } else if (arg.startsWith("--")) {
+      console.error(`[rango] Unknown flag: ${arg}`);
+      process.exit(1);
+    } else {
+      positionalArgs.push(arg);
+    }
+  }
+
+  if (positionalArgs.length === 0) {
+    console.error(
+      "[rango] Usage: rango generate <file|dir> [file2 ...] [--runtime|--static] [--config <path>]",
+    );
+    process.exit(1);
+  }
+
+  if (configFile && mode !== "runtime") {
+    console.warn("[rango] --config is only used with --runtime, ignoring");
+  }
+
+  if (mode === "runtime") {
+    // Runtime discovery: dynamically import to avoid loading Vite for static-only usage
+    runRuntimeDiscovery(positionalArgs, configFile).catch((err) => {
+      console.error(`[rango] Runtime discovery failed: ${err.message}`);
+      process.exit(1);
+    });
+  } else {
+    runStaticGeneration(positionalArgs, mode);
+  }
+} else {
+  if (
+    command &&
+    command !== "help" &&
+    command !== "--help" &&
+    command !== "-h"
+  ) {
+    console.error(`[rango] Unknown command: ${command}\n`);
+  }
+  console.log(`Usage: rango generate <file|dir> [file2 ...] [--runtime|--static] [--config <path>]
+
+  Auto-detects file type (createRouter, urls) and generates
+  the appropriate .gen.ts route type files.
+
+Modes:
+  (default)   Static parser with error on unresolvable includes
+  --runtime   Vite-based runtime discovery (100% coverage)
+              Requires vite and @vitejs/plugin-rsc
+  --static    Static parser, accept partial output with warnings
+
+Options:
+  --config <path>  Path to vite.config.ts (--runtime only, auto-detected if omitted)
+
+Examples:
+  rango generate src/router.tsx
+  rango generate src/router.tsx --runtime
+  rango generate src/ --static`);
+  process.exit(
+    command && command !== "help" && command !== "--help" && command !== "-h"
+      ? 1
+      : 0,
+  );
+}
+
+/**
+ * Walk up from a file path to find the project root (directory containing
+ * package.json or vite.config.ts).
+ */
+function findProjectRoot(fromPath: string): string {
+  let dir = dirname(resolve(fromPath));
+  while (dir !== dirname(dir)) {
+    if (
+      existsSync(resolve(dir, "package.json")) ||
+      existsSync(resolve(dir, "vite.config.ts")) ||
+      existsSync(resolve(dir, "vite.config.js"))
+    ) {
+      return dir;
+    }
+    dir = dirname(dir);
+  }
+  // Fallback to cwd if no project root found
+  return process.cwd();
+}
+
+function runStaticGeneration(args: string[], mode: "default" | "static") {
+  // Expand args: files are used directly, directories are scanned
+  const files: string[] = [];
+  for (const arg of args) {
+    const resolved = resolve(arg);
+    try {
+      if (statSync(resolved).isDirectory()) {
+        files.push(...findTsFiles(resolved));
+      } else {
+        files.push(resolved);
+      }
+    } catch {
+      console.warn(`[rango] Skipping ${arg}: not found`);
+    }
+  }
+
+  if (files.length === 0) {
+    console.log("[rango] No files to process");
+    process.exit(0);
+  }
+
+  // Phase 1: Classify files
+  const routerFiles: string[] = [];
+  const urlsFiles: string[] = [];
 
-  const files = findTsFiles(resolvedDir);
   for (const filePath of files) {
-    writePerModuleRouteTypesForFile(filePath);
+    try {
+      const source = readFileSync(filePath, "utf-8");
+      if (/\bcreateRouter\s*[<(]/.test(source)) {
+        routerFiles.push(filePath);
+      }
+      if (source.includes("urls(")) {
+        urlsFiles.push(filePath);
+      }
+    } catch (err) {
+      console.warn(
+        `[rango] Failed to process ${filePath}: ${(err as Error).message}`,
+      );
+    }
+  }
+
+  // Phase 2: Collect diagnostics from all files BEFORE writing anything
+  const allDiagnostics: Array<UnresolvableInclude & { routerFile: string }> =
+    [];
+
+  for (const routerFile of routerFiles) {
+    const diagnostics = detectUnresolvableIncludes(routerFile);
+    for (const d of diagnostics) {
+      allDiagnostics.push({ ...d, routerFile });
+    }
+  }
+
+  // Also check standalone urls files not covered by router-level detection
+  const routerFileSet = new Set(routerFiles);
+  for (const urlsFile of urlsFiles) {
+    if (routerFileSet.has(urlsFile)) continue;
+    const diagnostics = detectUnresolvableIncludesForUrlsFile(urlsFile);
+    for (const d of diagnostics) {
+      allDiagnostics.push({ ...d, routerFile: urlsFile });
+    }
   }
 
-  console.log(`[rango] Scanned ${files.length} file(s)`);
+  // Deduplicate diagnostics (router and urls detection may find the same issue)
+  const seen = new Set<string>();
+  const uniqueDiagnostics = allDiagnostics.filter((d) => {
+    const key = `${d.sourceFile}:${d.pathPrefix}:${d.reason}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+
+  if (uniqueDiagnostics.length > 0 && mode === "default") {
+    // Hard error: no files written
+    console.error("\n[rango] Unresolvable includes detected:\n");
+    formatDiagnostics(uniqueDiagnostics);
+    console.error(
+      "\nThe static parser cannot resolve these includes because they use " +
+        "factory functions or dynamic expressions.\n\n" +
+        "Options:\n" +
+        "  rango generate <path> --runtime   Use Vite-based discovery (requires vite)\n" +
+        "  rango generate <path> --static    Accept partial output (missing routes above)\n",
+    );
+    process.exit(1);
+  }
+
+  if (uniqueDiagnostics.length > 0 && mode === "static") {
+    // Warning: partial output accepted
+    console.warn(
+      "\n[rango] Warning: partial output (unresolvable includes):\n",
+    );
+    formatDiagnostics(uniqueDiagnostics);
+    console.warn("");
+  }
+
+  const nestedRouterConflict = findNestedRouterConflict(routerFiles);
+  if (nestedRouterConflict) {
+    console.error(
+      `\n${formatNestedRouterConflictError(nestedRouterConflict, "[rango]")}\n`,
+    );
+    process.exit(1);
+  }
+
+  // Phase 3: Write all outputs (only reached if diagnostics pass or --static)
+  for (const urlsFile of urlsFiles) {
+    writePerModuleRouteTypesForFile(urlsFile);
+  }
+
+  for (const routerFile of routerFiles) {
+    const projectRoot = findProjectRoot(routerFile);
+    writeCombinedRouteTypes(projectRoot, [routerFile]);
+  }
+
+  console.log(
+    `[rango] Processed ${files.length} file(s)${routerFiles.length ? ` (${routerFiles.length} router)` : ""}`,
+  );
   process.exit(0);
-} else {
-  console.log(`Usage: rango <command>
+}
+
+async function runRuntimeDiscovery(args: string[], configFile?: string) {
+  // Resolve the entry: find the router file from the arguments
+  const files: string[] = [];
+  for (const arg of args) {
+    const resolved = resolve(arg);
+    try {
+      if (statSync(resolved).isDirectory()) {
+        files.push(...findTsFiles(resolved));
+      } else {
+        files.push(resolved);
+      }
+    } catch {
+      console.warn(`[rango] Skipping ${arg}: not found`);
+    }
+  }
+
+  // Find router files among the inputs
+  const routerEntries: string[] = [];
+  for (const filePath of files) {
+    try {
+      const source = readFileSync(filePath, "utf-8");
+      if (/\bcreateRouter\s*[<(]/.test(source)) {
+        routerEntries.push(filePath);
+      }
+      // Also generate per-module types for urls files
+      if (source.includes("urls(")) {
+        writePerModuleRouteTypesForFile(filePath);
+      }
+    } catch {
+      // Skip unreadable files
+    }
+  }
+
+  if (routerEntries.length === 0) {
+    console.error("[rango] No router files found in the provided paths");
+    process.exit(1);
+  }
+
+  const nestedRouterConflict = findNestedRouterConflict(routerEntries);
+  if (nestedRouterConflict) {
+    console.error(
+      `\n${formatNestedRouterConflictError(nestedRouterConflict, "[rango]")}\n`,
+    );
+    process.exit(1);
+  }
+
+  let discoverAndWriteRouteTypes: typeof import("../build/runtime-discovery.ts").discoverAndWriteRouteTypes;
+  try {
+    const mod = await import("../build/runtime-discovery.ts");
+    discoverAndWriteRouteTypes = mod.discoverAndWriteRouteTypes;
+  } catch (err: any) {
+    if (
+      err.code === "ERR_MODULE_NOT_FOUND" ||
+      err.code === "MODULE_NOT_FOUND"
+    ) {
+      console.error(
+        "[rango] Runtime discovery requires 'vite' and '@vitejs/plugin-rsc'.\n" +
+          "Install them with: pnpm add -D vite @vitejs/plugin-rsc",
+      );
+    } else {
+      console.error(`[rango] Failed to load runtime discovery: ${err.message}`);
+    }
+    process.exit(1);
+  }
 
-Commands:
-  extract-names [dir]  Extract route names from url modules (default: ./src)`);
-  process.exit(command ? 1 : 0);
+  for (const entry of routerEntries) {
+    const projectRoot = findProjectRoot(entry);
+    const result = await discoverAndWriteRouteTypes({
+      root: projectRoot,
+      configFile,
+      entry,
+    });
+    console.log(
+      `[rango] Runtime discovery: ${result.routerCount} router(s), ${result.routeCount} route(s)`,
+    );
+  }
+}
+
+function formatDiagnostics(
+  diagnostics: Array<UnresolvableInclude & { routerFile: string }>,
+) {
+  for (const d of diagnostics) {
+    const prefix = d.namePrefix ? `${d.namePrefix}.*` : `${d.pathPrefix}*`;
+    console.error(`  ${prefix}`);
+    console.error(`    Reason:  ${d.reason} -- ${d.detail}`);
+    console.error(`    Source:  ${d.sourceFile}`);
+  }
 }

package/src/browser/action-coordinator.ts

@@ -0,0 +1,114 @@
+import type { ActionEntry } from "./event-controller.js";
+
+/**
+ * Post-reconciliation action outcome (discriminated union). Error and
+ * full-update-unsupported cases are handled inline in the bridge before
+ * reconciliation; this only covers successfully-reconciled partial responses.
+ */
+type ActionScenario =
+  | {
+      type: "navigated-away";
+      historyKeyChanged: boolean;
+      onInterceptRoute: boolean;
+    }
+  | { type: "hmr-missing" }
+  | { type: "consolidation-needed"; segmentIds: string[] }
+  | { type: "concurrent-skip"; otherFetchingCount: number }
+  | { type: "normal" };
+
+/**
+ * Plain data inputs for classifying a post-reconciliation action outcome.
+ * No browser objects or controller references — all values are snapshots.
+ */
+export interface ActionOutcomeInput {
+  /** This action's unique instance ID */
+  handleId: string;
+  /** All in-flight action entries (snapshot from event controller) */
+  inflightActions: Map<string, ActionEntry>;
+  /** Whether any concurrent actions occurred (controller-level shared flag) */
+  hadAnyConcurrentActions: boolean;
+  /** Segments revalidated by concurrent actions (from tracking set) */
+  revalidatedSegments: Set<string>;
+  /** window.location.pathname captured at action start */
+  actionStartPathname: string;
+  /** window.location.pathname at classification time */
+  currentPathname: string;
+  /** window.history.state?.key captured at action start */
+  actionStartLocationKey: string | undefined;
+  /** window.history.state?.key at classification time */
+  currentLocationKey: string | undefined;
+  /** Number of segments after reconciliation */
+  reconciledSegmentCount: number;
+  /** Number of matched segment IDs from server */
+  matchedCount: number;
+  /** Current intercept source URL (null when not on intercept route) */
+  currentInterceptSource: string | null;
+}
+
+// Segment IDs to re-fetch when concurrent actions each revalidated different
+// parts of the tree; null when consolidation does not apply. Returns null while
+// any action is still fetching — consolidation must wait for all to land.
+function computeConsolidationSegments(
+  input: ActionOutcomeInput,
+): string[] | null {
+  if (!input.hadAnyConcurrentActions) return null;
+  if (input.revalidatedSegments.size === 0) return null;
+
+  const stillFetchingCount = [...input.inflightActions.values()].filter(
+    (a) => a.phase === "fetching",
+  ).length;
+  if (stillFetchingCount > 0) return null;
+
+  return Array.from(input.revalidatedSegments);
+}
+
+function countOtherFetchingActions(input: ActionOutcomeInput): number {
+  let count = 0;
+  for (const [, a] of input.inflightActions) {
+    if (a.phase === "fetching" && a.id !== input.handleId) {
+      count++;
+    }
+  }
+  return count;
+}
+
+/**
+ * Classify a post-reconciliation action outcome. Ordered priority chain: each
+ * case assumes the earlier ones are false (e.g. concurrent-skip only applies on
+ * the still-current route, consolidation only once no action is still fetching).
+ * The bridge calls this to decide whether to render, skip, consolidate, or refetch.
+ */
+export function classifyActionOutcome(
+  input: ActionOutcomeInput,
+): ActionScenario {
+  if (
+    input.currentPathname !== input.actionStartPathname ||
+    input.currentLocationKey !== input.actionStartLocationKey
+  ) {
+    return {
+      type: "navigated-away",
+      historyKeyChanged:
+        input.currentLocationKey !== input.actionStartLocationKey,
+      onInterceptRoute: input.currentInterceptSource !== null,
+    };
+  }
+
+  if (input.reconciledSegmentCount < input.matchedCount) {
+    return { type: "hmr-missing" };
+  }
+
+  const consolidationSegments = computeConsolidationSegments(input);
+  if (consolidationSegments && consolidationSegments.length > 0) {
+    return { type: "consolidation-needed", segmentIds: consolidationSegments };
+  }
+
+  const otherFetchingActionCount = countOtherFetchingActions(input);
+  if (otherFetchingActionCount > 0) {
+    return {
+      type: "concurrent-skip",
+      otherFetchingCount: otherFetchingActionCount,
+    };
+  }
+
+  return { type: "normal" };
+}

package/src/browser/action-fence.ts

@@ -0,0 +1,47 @@
+/**
+ * Action fence: a refcounted flag that is raised while a server action is in
+ * flight and lowered when it resolves.
+ *
+ * It replaces the eager cache clear the action bridge used to do at action
+ * start. While the fence is up, the decision of whether the action invalidated
+ * anything is deferred to the response:
+ *
+ * - prefetch consumption is suspended (a queued prefetch result is not served),
+ * - a genuine navigation during the flight fetches with `cache: "no-store"` so
+ *   it cannot be served stale bytes from the browser's Vary-keyed HTTP cache,
+ * - popstate reads are treated as stale-while-revalidate.
+ *
+ * Nothing is wiped, rotated, or broadcast while the fence is up — that is what
+ * keeps a sibling tab from seeing a pre-commit signal. Refcounted so concurrent
+ * actions compose: each action raises and lowers its own reference, and the
+ * fence is down only when the count reaches zero.
+ *
+ * The refcount is a single module-level counter, not keyed by routerId.
+ * Consumers (navigation-client.ts, prefetch/fetch.ts, navigation-bridge.ts)
+ * read it unscoped, so an action in one router would suppress another router's
+ * navigation/prefetch caches. This is correct only because two routers cannot
+ * coexist in one live document: an SPA navigation crossing a host-router
+ * boundary forces a full document reload (src/router/request-classification.ts
+ * app-switch terminal), so there is always exactly one live router per
+ * document. A future multi-router-in-one-document feature must not silently
+ * inherit this global, cross-router cache suppression.
+ */
+
+let fenceCount = 0;
+
+export function enterActionFence(): void {
+  fenceCount++;
+}
+
+export function exitActionFence(): void {
+  if (fenceCount > 0) fenceCount--;
+}
+
+export function isActionFenceActive(): boolean {
+  return fenceCount > 0;
+}
+
+/** Test-only: reset the refcount between cases. */
+export function __resetActionFence(): void {
+  fenceCount = 0;
+}

package/src/browser/app-shell.ts

@@ -0,0 +1,39 @@
+import type { ComponentType, ReactNode } from "react";
+
+/**
+ * App-shell metadata: the per-router fields describing the "envelope" around
+ * the current app's segment tree — the rootLayout (Document), basename,
+ * version, and router identity. Set once from the initial RSC payload and read
+ * through the AppShellRef when rendering segments.
+ *
+ * This is a per-document value. A navigation that crosses a host-router app
+ * boundary is a full document load (the server returns X-RSC-Reload for it;
+ * see request-classification.ts, mode "app-switch"), so the target app's shell
+ * — along with everything else document-level (theme, warmup, prefetch-TTL) —
+ * is established fresh by the target app's own load. The shell is never swapped
+ * in place within a session.
+ */
+export interface AppShell {
+  /** Router identity. Used to namespace per-app client state (e.g. the
+   *  rango-state localStorage key) so sibling apps on the same origin
+   *  cannot observe each other's cache invalidations. */
+  routerId?: string;
+  rootLayout?: ComponentType<{ children: ReactNode }>;
+  basename?: string;
+  version?: string;
+}
+
+/**
+ * Container for the active app shell. Read-through via `get()` so closures
+ * (e.g. the segment renderer) capture the ref and read the shell at call time
+ * rather than closing over a stale snapshot.
+ */
+export interface AppShellRef {
+  get(): AppShell;
+}
+
+export function createAppShellRef(initial: AppShell): AppShellRef {
+  return {
+    get: () => initial,
+  };
+}

package/src/browser/app-version.ts

@@ -0,0 +1,14 @@
+/**
+ * Mutable app version — updated after HMR revalidation.
+ * Read by prefetch, navigation, and context code.
+ */
+
+let currentVersion: string | undefined;
+
+export function getAppVersion(): string | undefined {
+  return currentVersion;
+}
+
+export function setAppVersion(version: string | undefined): void {
+  currentVersion = version;
+}

package/src/browser/cookie-name.ts

@@ -0,0 +1,140 @@
+/**
+ * Rango state cookie: value codec and attribute serialization.
+ *
+ * Shared by the client (the document.cookie writer in rango-state.ts) and the
+ * server (the Set-Cookie writer in invalidateClientCache). Environment-agnostic:
+ * no window/document access and no name composition.
+ *
+ * Name RESOLUTION deliberately lives elsewhere (router init, see
+ * router/state-cookie-name.ts). Keeping composition out of this shared module
+ * is what lets the client read the server-resolved name verbatim and compose
+ * nothing.
+ */
+
+/** Default prefix when `stateCookiePrefix` is unset or empty after sanitization. */
+export const DEFAULT_STATE_COOKIE_PREFIX = "rango-state";
+
+/** Internal response header carrying the keepClientCache() directive. */
+export const KEEP_CACHE_HEADER = "x-rango-keep-cache";
+
+// Per-client signal headers (lower-case) that a SHARED response cache must never
+// store or replay (Finding #3): a `Set-Cookie` (rango state rotation, or any
+// cookie a loader set) and the keepClientCache() directive. Strip-all-Set-Cookie
+// is deliberate — a shared store can't know the resolved cookie name, and any
+// per-client cookie in a cacheable document is the hazard. Single source for the
+// predicate, presence check, and strip below.
+const PER_CLIENT_SIGNAL_HEADERS: readonly string[] = [
+  "set-cookie",
+  KEEP_CACHE_HEADER,
+];
+
+/** True for a per-client signal header. */
+export function isPerClientSignalHeader(name: string): boolean {
+  return PER_CLIENT_SIGNAL_HEADERS.includes(name.toLowerCase());
+}
+
+/** True if `headers` carries any per-client signal. */
+export function hasPerClientSignal(headers: Headers): boolean {
+  return PER_CLIENT_SIGNAL_HEADERS.some((name) => headers.has(name));
+}
+
+/** Remove every per-client signal header from `headers` in place. */
+export function stripPerClientSignals(headers: Headers): void {
+  for (const name of PER_CLIENT_SIGNAL_HEADERS) headers.delete(name);
+}
+
+/**
+ * Read the raw, UNDECODED value of a single cookie from a cookie string (a
+ * `document.cookie` jar or a request `Cookie` header). Shared by both seats so
+ * the client mirror and the server monotonic-guard read the SAME jar entry —
+ * their agreement is the guard's contract. First match wins (the entry the
+ * client's mirror holds); exact name boundary via the `=`; an empty value
+ * (`name=`) returns null (treated as absent, not a usable prior value).
+ */
+export function getRawCookieValue(
+  cookieString: string | null,
+  name: string,
+): string | null {
+  if (!cookieString) return null;
+  const target = name + "=";
+  for (const part of cookieString.split(";")) {
+    const trimmed = part.trim();
+    if (trimmed.startsWith(target)) {
+      const value = trimmed.slice(target.length);
+      return value === "" ? null : value;
+    }
+  }
+  return null;
+}
+
+/**
+ * Encode a state value for the wire: `encodeURIComponent(version):timestamp`.
+ * Only the build-derived version is encoded (it is arbitrary); the `:`
+ * separator and numeric timestamp stay raw, so the `{version}:{timestamp}`
+ * shape survives and `:` is a legal cookie-value octet.
+ */
+export function encodeStateValue(version: string, timestamp: number): string {
+  return `${encodeURIComponent(version)}:${timestamp}`;
+}
+
+/** Parsed state value. `version` is decoded; `timestamp` is the raw integer. */
+export interface StateValue {
+  version: string;
+  timestamp: number;
+}
+
+/**
+ * Decode a wire value back into `{version, timestamp}`. Returns null for a
+ * malformed value (no `:`, empty version, or non-numeric timestamp) so callers
+ * mint fresh instead of trusting garbage.
+ */
+export function decodeStateValue(raw: string): StateValue | null {
+  const colon = raw.indexOf(":");
+  if (colon <= 0) return null;
+  const timestamp = Number(raw.slice(colon + 1));
+  if (!Number.isFinite(timestamp)) return null;
+  let version: string;
+  try {
+    version = decodeURIComponent(raw.slice(0, colon));
+  } catch {
+    // A malformed percent-escape (e.g. "%:1") must mint fresh, not throw —
+    // a thrown URIError here would 500 the server seat or fail client boot.
+    return null;
+  }
+  return { version, timestamp };
+}
+
+/**
+ * Mint a fresh state value whose timestamp is strictly greater than the previous
+ * one, so a re-mint inside the same millisecond (or a backward clock step) still
+ * differs from the current value. `prevRaw` is the current wire value (the
+ * client's in-memory mirror, or the server's inbound header/cookie) or null; its
+ * timestamp is the floor. Shared by both seats so the monotonic guard lives once.
+ */
+export function mintStateValue(
+  version: string,
+  prevRaw: string | null,
+): string {
+  const prevTs = prevRaw ? (decodeStateValue(prevRaw)?.timestamp ?? 0) : 0;
+  const ts = Math.max(Date.now(), prevTs + 1);
+  return encodeStateValue(version, ts);
+}
+
+/**
+ * Attribute string for the state cookie. Session cookie (no Max-Age/Expires),
+ * Path=/ (whole app), SameSite=Lax (sent on top-level navigations), and Secure
+ * only on https so the document.cookie write does not silently fail on plain
+ * http dev. Never HttpOnly (the client reads and writes it).
+ */
+export function stateCookieAttributes(secure: boolean): string {
+  return `; Path=/; SameSite=Lax${secure ? "; Secure" : ""}`;
+}
+
+/** Serialize a full `name=value` cookie string with the state attributes. */
+export function serializeStateCookie(
+  name: string,
+  value: string,
+  secure: boolean,
+): string {
+  return `${name}=${value}${stateCookieAttributes(secure)}`;
+}