@rangojs/router 0.1.1 → 0.4.0

package/dist/types/testing/shell-status.d.ts

@@ -2,7 +2,8 @@
  * PPR shell-status testing primitives for @rangojs/router consumers.
  *
  * Companion to `cache-status.ts` (segment/document cache): this module covers
- * the **shell axis** (`ppr` path option → `x-rango-shell: HIT | MISS`).
+ * the **shell axis** (`ppr` path option → `x-rango-shell: HIT | MISS`) and
+ * partial-navigation segment replay (`x-rango-ppr-replay: HIT`).
  *
  * ## Spike conclusions (plan 009)
  *
@@ -11,8 +12,9 @@
  *    + `ppr: true` on a response route is a no-op for shell serve/capture. The
  *    production path lives in `rsc/rsc-rendering.ts` + `rsc/shell-capture.ts`.
  *
- * 2. **Smallest HIT signal:** response header `x-rango-shell` (`HIT` | `MISS`),
- *    always on document GETs to a ppr route that the serve path considered.
+ * 2. **Smallest status signals:** `x-rango-shell` (`HIT` | `MISS`) on document
+ *    GETs, and `x-rango-ppr-replay` on partial requests to ppr routes. A replay
+ *    HIT is reported only when matching consumes the captured segment record.
  *    Secondary unit signal: `store.getShell(shellCacheKey(url))` after a real
  *    capture flush (background `putShell`). There is no Flight flag for shell HIT.
  *
@@ -27,8 +29,21 @@
  */
 /** Production header name (`rsc/shell-serve.ts` `SHELL_STATUS_HEADER`). */
 export declare const SHELL_STATUS_HEADER: string;
+/** Partial-navigation replay decision header from `rsc/rsc-rendering.ts`. */
+export declare const PPR_REPLAY_STATUS_HEADER: string;
 /** Values the serve path writes on `x-rango-shell`. */
 export type ShellStatus = "HIT" | "MISS";
+declare const PPR_REPLAY_BYPASS_REASONS: readonly ["method", "dynamic", "nonce", "store-unavailable", "passive-read-unsupported", "read-error", "no-entry", "invalid-version", "corrupt-entry", "handler-live-holes", "transition-when", "no-segment-snapshot", "snapshot-miss", "stale-build-entry"];
+/** Bounded reasons a PPR partial request can fall open to ordinary matching. */
+export type PprReplayBypassReason = (typeof PPR_REPLAY_BYPASS_REASONS)[number];
+/** Parsed `x-rango-ppr-replay` value. */
+export type PprReplayStatus = {
+    outcome: "HIT";
+    freshness: "fresh" | "stale";
+} | {
+    outcome: "BYPASS";
+    reason: PprReplayBypassReason;
+};
 /** A target carrying response headers (a Response or a `{ headers }` object). */
 export type ShellStatusTarget = Response | {
     headers: Headers;
@@ -56,3 +71,8 @@ export declare function parseShellStatus(target: ShellStatusTarget): ShellStatus
  * invent a HIT Response in unit tests — that fakes the serve path.
  */
 export declare function assertShellStatus(target: ShellStatusTarget, expected: ShellStatus): void;
+/** Parse the dedicated PPR partial-navigation replay decision header. */
+export declare function parsePprReplayStatus(target: ShellStatusTarget): PprReplayStatus | null;
+/** Assert a partial response's PPR replay outcome and freshness/reason. */
+export declare function assertPprReplayStatus(target: ShellStatusTarget, expected: PprReplayStatus): void;
+export {};

package/dist/types/types/segments.d.ts

@@ -12,11 +12,12 @@ export type ViewTransitionClass = Record<string, string> | string;
  *
  * It mirrors the {@link ShouldRevalidateFn} args a `revalidate()` predicate
  * gets — the same navigation/action metadata — so the two read the same shape,
- * plus `get`/`env` for post-handler reads. There is no full `HandlerContext`
+ * plus `get`/`env` for request-context reads. There is no full `HandlerContext`
  * here: the gate runs at the RSC-payload layer with the request context, not a
  * handler context, so handler-only sugar (`search`/`build`/`dev`/`headers`) is
- * absent by design. `get` is the way to read what the handler/middleware set
- * via `ctx.set(...)` this request.
+ * absent by design. On ordinary routes, `get` can read what handlers or
+ * middleware set via `ctx.set(...)`. On `ppr` routes the gate runs before route
+ * handlers, so only middleware-established values are available.
  *
  * Field availability (all source fields are optional — never fabricated):
  * - `currentUrl` / `currentParams` / `fromRouteName` (the navigation SOURCE) are
@@ -41,27 +42,30 @@ export type ViewTransitionClass = Record<string, string> | string;
  * time, so `currentUrl`/`currentParams`/`fromRouteName` reflect the page the
  * prefetch fired from, NOT necessarily the page the user actually navigates from
  * — the decision is baked into the stored Flight payload and replayed verbatim.
- * A `cache()`/prerender hit replays the stored transition with the predicate NOT
- * re-run at all. So a source-sensitive predicate can be frozen to prefetch-time
- * or store-time state. This is accepted (~99% of navigations match), but if your
- * gate must reflect the exact click-time source, source-scope the prefetch
- * (`<Link prefetchKey=":source">`) and do not `cache()` that segment.
+ * A non-PPR `cache()`/prerender hit replays the stored transition with the
+ * predicate NOT re-run. A `ppr` route instead evaluates the predicate before
+ * handlers on every match, including cache, prerender, and PPR replay. Prefetch
+ * still freezes the server decision into its Flight payload. If the gate must
+ * reflect the exact click-time source, source-scope the prefetch
+ * (`<Link prefetchKey=":source">`).
  */
 export type TransitionWhenContext<TParams = Record<string, string>, TEnv = unknown> = Partial<Pick<RevalidateParams<TParams, TEnv>, "currentUrl" | "currentParams" | "fromRouteName">> & Pick<RevalidateParams<TParams, TEnv>, "nextUrl" | "nextParams" | "toRouteName" | "actionId" | "actionUrl" | "actionResult" | "formData" | "method"> & Pick<HandlerContext<any, TEnv>, "get" | "env">;
 /**
  * Predicate that gates whether a transition() applies for the current request.
  *
- * Evaluated server-side AFTER the route's handler runs (so `get(...)` can read
- * handler/middleware-set state) and outside any cache scope. Return false to
- * drop this segment's transition for the request; return true to apply it. The
+ * Evaluated server-side outside any cache scope. On ordinary routes it runs
+ * AFTER the route's handler, so `get(...)` can read handler/middleware state. A
+ * route with `ppr` automatically hoists it before route handlers and reevaluates
+ * it on every cache/prerender/PPR replay; there `get(...)` can read middleware
+ * state, but not values set by route handlers. Return false to drop this
+ * segment's transition for the request; return true to apply it. The
  * context ({@link TransitionWhenContext}) carries the same navigation/action
  * metadata a `revalidate()` predicate sees plus `get`/`env`. If it throws, the
  * error is reported to the router's onError (phase "rendering") and the
  * transition is dropped (the navigation does not hold).
  *
  * Distinct from intercept()'s `when` config selector, which runs at MATCH time
- * over `{ from, to, params, segments, … }`; a transition `when` runs
- * post-handler over the resolved payload.
+ * over `{ from, to, params, segments, … }`.
  *
  * Scope: dropping a transition removes only THIS segment's contribution to the
  * navigation's hold. The startTransition hold is navigation-wide — it engages if
@@ -69,10 +73,10 @@ export type TransitionWhenContext<TParams = Record<string, string>, TEnv = unkno
  * navigation stream its loading fallback only when no other matched segment
  * keeps a transition (the common case: a single transition on the route).
  *
- * Evaluated on every fresh (cache-miss) resolution; it is NOT re-run when a
- * segment is replayed from the runtime cache or a build-time prerender, and a
- * prefetched navigation freezes it to prefetch-time state — see the caveat on
- * {@link TransitionWhenContext}.
+ * On non-PPR routes it runs only during fresh resolution. On PPR routes it runs
+ * before handlers for every match, including runtime cache, build-time
+ * prerender, and PPR segment replay. A prefetched navigation still freezes the
+ * result to prefetch time; see {@link TransitionWhenContext}.
  */
 export type TransitionWhenFn = (ctx: TransitionWhenContext) => boolean;
 /**
@@ -105,11 +109,12 @@ export interface TransitionConfig {
     viewTransition?: "auto" | false;
     /**
      * Optional server-side predicate that gates this transition per request. When
-     * present and it returns false (evaluated post-handler), the router drops this
-     * segment's transition for the request, so the navigation streams its loading
-     * fallback instead of holding. The predicate is server-only and never
-     * serialized to the client; only its resolved effect (transition kept or
-     * dropped) crosses. See {@link TransitionWhenFn}.
+     * present and it returns false, the router drops this segment's transition for
+     * the request, so the navigation streams its loading fallback instead of
+     * holding. PPR routes evaluate it before route handlers and on every replay;
+     * other routes evaluate it after handlers on fresh resolution. The predicate
+     * is server-only and never serialized to the client; only its resolved effect
+     * crosses. See {@link TransitionWhenFn}.
      */
     when?: TransitionWhenFn;
 }

package/dist/types/urls/path-helper-types.d.ts

@@ -183,9 +183,10 @@ export type PathHelpers<TEnv> = {
      * transition cannot fire without a startTransition. See
      * skills/view-transitions for the startTransition x ViewTransition matrix.
      *
-     * Pass `when: (ctx) => boolean` to gate the transition per request: it runs
-     * server-side after the route handler (can read `ctx.get(...)`), and returning
-     * false drops the transition so the navigation streams its loading() skeleton.
+     * Pass `when: (ctx) => boolean` to gate the transition per request. It normally
+     * runs after the route handler; `ppr` routes automatically run it before route
+     * handlers and on every replay, where `ctx.get(...)` sees middleware state but
+     * not handler-set values.
      */
     transition: {
         (): TransitionItem;

package/dist/types.backup/__internal.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Internal Types - Implementation Details
+ *
+ * @internal
+ * These types are for internal use only and should not be relied upon by consumers.
+ * They may change without notice between versions.
+ *
+ * If you find yourself needing these types, please open an issue to discuss
+ * adding them to the public API.
+ */
+/**
+ * @internal
+ * Internal representation of a resolved route segment.
+ * Used during route matching and rendering pipeline.
+ */
+export type { ResolvedSegment, SegmentMetadata } from "./types.js";
+/**
+ * @internal
+ * Internal match result from route resolution.
+ */
+export type { MatchResult, SlotState } from "./types.js";
+/**
+ * @internal
+ * Context for intercept route selection.
+ */
+export type { InterceptSelectorContext, InterceptSegmentsState, InterceptWhenFn, } from "./server/context.js";
+/**
+ * @internal
+ * RSC protocol payload structure.
+ */
+export type { RscPayload, ReactFormState } from "./rsc/types.js";
+/**
+ * @internal
+ * Internal navigation store interface.
+ */
+export type { NavigationStore, NavigationBridge, RscMetadata, ActionResult, InflightAction, NavigationState, TrackedActionState, ActionStateListener, SegmentCache, SegmentState, NavigationUpdate, } from "./browser/types.js";
+/**
+ * @internal
+ * Internal handle storage mechanism.
+ */
+export type { HandleStore, HandleData } from "./server/handle-store.js";
+/**
+ * @internal
+ * Segment handle data in cache.
+ */
+export type { SegmentHandleData } from "./cache/types.js";
+/**
+ * @internal
+ * Internal cache entry data structure.
+ */
+export type { CachedEntryData, CacheGetResult, SerializedSegmentData, CacheDefaults, } from "./cache/types.js";
+/**
+ * @internal
+ * Router context for AsyncLocalStorage.
+ */
+export type { RouterContext, RevalidationContext, InterceptResult, } from "./router/router-context.js";
+/**
+ * @internal
+ * Route match context during pipeline processing.
+ */
+export type { MatchContext, MatchPipelineState, } from "./router/match-context.js";
+/**
+ * @internal
+ * Pattern matching result.
+ */
+export type { RouteMatchResult } from "./router/pattern-matching.js";
+/**
+ * @internal
+ * Entry data during route traversal.
+ */
+export type { EntryData, InterceptEntry, MetricsStore, PerformanceMetric, EntryCacheConfig, EntryPropCommon, EntryPropDatas, LoaderEntry, EntryPropSegments, } from "./server/context.js";
+/**
+ * @internal
+ * Internal handler context with additional props for router internals.
+ * Includes `_currentSegmentId` and `_responseType`.
+ */
+export type { InternalHandlerContext } from "./types.js";
+/**
+ * @internal
+ * Builds React element trees from route segments.
+ */
+export { renderSegments } from "./segment-system.js";
+/**
+ * @internal
+ * Error sanitization and network error utilities.
+ */
+export { sanitizeError, NetworkError, isNetworkError } from "./errors.js";
+/**
+ * @internal
+ * Scoped view of GeneratedRouteMap for Handler<"localName", ScopedRouteMap<"prefix">>.
+ */
+export type { ScopedRouteMap } from "./types.js";
+/**
+ * @internal
+ * Type-level utilities for reverse URL generation.
+ */
+export type { MergeRoutes, SanitizePrefix } from "./reverse.js";
+/**
+ * @internal
+ * Individual telemetry event types.
+ */
+export type { RequestStartEvent, RequestEndEvent, RequestErrorEvent, RequestTimeoutEvent, LoaderStartEvent, LoaderEndEvent, LoaderErrorEvent, HandlerErrorEvent, CacheDecisionEvent, RevalidationDecisionEvent, } from "./router/telemetry.js";
+/**
+ * @internal
+ * Type guard for prerender handler definitions.
+ */
+export { isPrerenderHandler, isPassthroughHandler } from "./prerender.js";
+/**
+ * @internal
+ * Type guard for static handler definitions.
+ */
+export { isStaticHandler } from "./static-handler.js";
+/**
+ * @internal
+ * Sentinel used to tag response-type route entries.
+ */
+export { RESPONSE_TYPE } from "./urls.js";
+/**
+ * @internal
+ * Debug utilities for route matching performance analysis.
+ */
+export { enableMatchDebug, getMatchDebugStats, } from "./router/pattern-matching.js";
+/**
+ * @internal
+ * Debug utilities for manifest inspection and comparison.
+ */
+export { serializeManifest, compareManifests, formatManifestDiff, type SerializedEntry, type SerializedManifest, } from "./debug.js";

package/dist/types.backup/bin/rango.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types.backup/browser/action-coordinator.d.ts

@@ -0,0 +1,57 @@
+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;
+}
+/**
+ * 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 declare function classifyActionOutcome(input: ActionOutcomeInput): ActionScenario;
+export {};

package/dist/types.backup/browser/action-fence.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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.
+ */
+export declare function enterActionFence(): void;
+export declare function exitActionFence(): void;
+export declare function isActionFenceActive(): boolean;
+/** Test-only: reset the refcount between cases. */
+export declare function __resetActionFence(): void;

package/dist/types.backup/browser/app-shell.d.ts

@@ -0,0 +1,34 @@
+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 declare function createAppShellRef(initial: AppShell): AppShellRef;

package/dist/types.backup/browser/app-version.d.ts

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

package/dist/types.backup/browser/connection-warmup.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Connection warmup: keep TLS alive after idle periods.
+ *
+ * After IDLE_TIMEOUT of no user interaction the connection is marked "cold".
+ * On the next pointer/touch interaction or a visibility change, a HEAD request
+ * warms the TLS connection before the user actually clicks a link.
+ *
+ * Extracted from NavigationProvider so the idle/cold/warmup state machine is
+ * unit-testable with an injected environment (document, fetch, timers).
+ *
+ * Ordering bug this guards against: the warmup listeners (mousemove/touchstart)
+ * share events with the idle-reset listeners, and the idle-reset listener is
+ * registered first, so it clears the live "cold" flag before the warmup
+ * listener reads it on the same event. A separate coldLatch — set when the
+ * connection goes cold and cleared only when warmup fires or listeners detach,
+ * never by the idle reset — lets the warmup decision see the pre-reset cold
+ * state regardless of listener ordering.
+ */
+type TimerHandle = ReturnType<typeof setTimeout>;
+export interface WarmupEnv {
+    doc: Pick<Document, "addEventListener" | "removeEventListener" | "visibilityState">;
+    fetch: typeof fetch;
+    setTimeout: (fn: () => void, ms: number) => TimerHandle;
+    clearTimeout: (handle: TimerHandle | undefined) => void;
+}
+/**
+ * Start the connection-warmup state machine. Returns a cleanup function that
+ * cancels timers and removes all listeners.
+ */
+export declare function startConnectionWarmup(env?: WarmupEnv): () => void;
+export {};

package/dist/types.backup/browser/cookie-name.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 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 declare const DEFAULT_STATE_COOKIE_PREFIX = "rango-state";
+/** Internal response header carrying the keepClientCache() directive. */
+export declare const KEEP_CACHE_HEADER = "x-rango-keep-cache";
+/** True for a per-client signal header. */
+export declare function isPerClientSignalHeader(name: string): boolean;
+/** True if `headers` carries any per-client signal. */
+export declare function hasPerClientSignal(headers: Headers): boolean;
+/** Remove every per-client signal header from `headers` in place. */
+export declare function stripPerClientSignals(headers: Headers): void;
+/**
+ * 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 declare function getRawCookieValue(cookieString: string | null, name: string): string | 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 declare function encodeStateValue(version: string, timestamp: number): string;
+/** 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 declare function decodeStateValue(raw: string): StateValue | null;
+/**
+ * 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 declare function mintStateValue(version: string, prevRaw: string | null): string;
+/**
+ * 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 declare function stateCookieAttributes(secure: boolean): string;
+/** Serialize a full `name=value` cookie string with the state attributes. */
+export declare function serializeStateCookie(name: string, value: string, secure: boolean): string;