@rangojs/router 0.0.0-experimental.8 → 0.0.0-experimental.80daa23e

package/dist/types/server/context.d.ts

@@ -0,0 +1,520 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { ReactNode } from "react";
+import type { PartialCacheOptions, ErrorBoundaryHandler, Handler, LoaderDefinition, MiddlewareFn, NotFoundBoundaryHandler, ShouldRevalidateFn, TransitionConfig } from "../types";
+import type { DefaultRouteName } from "../types/global-namespace.js";
+/**
+ * Performance metric entry for a single measured operation
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
+export interface PerformanceMetric {
+    label: string;
+    duration: number;
+    startTime: number;
+    depth?: number;
+    desc?: string;
+}
+/**
+ * Request-scoped metrics store
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
+export interface MetricsStore {
+    enabled: boolean;
+    requestStart: number;
+    metrics: PerformanceMetric[];
+}
+/**
+ * Cache configuration for an entry
+ * When set, this entry and its children will use this cache config
+ * unless overridden by a nested cache() call.
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
+export type EntryCacheConfig = {
+    /** Cache options (false means caching disabled for this entry) - ttl is optional, uses defaults */
+    options: PartialCacheOptions | false;
+};
+/**
+ * Entry data structure for manifest
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
+export type EntryPropCommon = {
+    id: string;
+    shortCode: string;
+    parent: EntryData | null;
+    /** Cache configuration for this entry (set by cache() DSL) */
+    cache?: EntryCacheConfig;
+    /** URL prefix from include() scope, used for MountContext on client */
+    mountPath?: string;
+};
+/**
+ * Attachments resolved by walking the parent chain, not owned by the entry:
+ * middleware composes downward; revalidate and the error/notFound boundaries are
+ * resolved by nearest-ancestor lookup. Inherited, not a single execution chain.
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
+export type EntryPropDatas = {
+    middleware: MiddlewareFn<any, any>[];
+    revalidate: ShouldRevalidateFn<any, any>[];
+    errorBoundary: (ReactNode | ErrorBoundaryHandler)[];
+    notFoundBoundary: (ReactNode | NotFoundBoundaryHandler)[];
+};
+/**
+ * Render-time presentation fields shared by every entry variant.
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
+export type EntryPropRender = {
+    loading?: ReactNode | false;
+    transition?: TransitionConfig;
+};
+/**
+ * Loader entry stored in EntryData
+ * Contains the loader definition and its revalidation rules
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
+export type LoaderEntry = {
+    loader: LoaderDefinition<any>;
+    revalidate: ShouldRevalidateFn<any, any>[];
+    /** Cache config for this specific loader (loaders are NOT cached by default) */
+    cache?: EntryCacheConfig;
+    /**
+     * Document renders await this loader before segment resolution returns
+     * (loader(Def, { ssr: false })), so its data, handle pushes, and
+     * thrown notFound()/redirect() deterministically precede first flush.
+     * Resolved at DSL-evaluation time from ctx.isSSR — entries are cached
+     * per-isSSR (router/manifest.ts cache key), so the flag is already
+     * request-mode-correct when resolveLoaders (fresh.ts) reads it and never
+     * appears on navigation-lane entries.
+     */
+    awaitBeforeFlush?: true;
+};
+/**
+ * Segments state for intercept context
+ * Matches the structure from useSegments() for consistency
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
+export type InterceptSegmentsState = {
+    /** URL path segments (e.g., /shop/products/123 → ["shop", "products", "123"]) */
+    path: readonly string[];
+    /** Matched segment IDs in order (layouts and routes only, e.g., ["L0", "L0L1", "L0L1R0"]) */
+    ids: readonly string[];
+};
+/**
+ * Context passed to intercept selector functions (when())
+ * Contains navigation context to determine if interception should occur.
+ *
+ * Note: when() is evaluated during route matching, BEFORE middleware runs.
+ * So ctx.get()/ctx.use() are not available, but env (platform bindings) is.
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
+export type InterceptSelectorContext<TEnv = any> = {
+    from: URL;
+    to: URL;
+    params: Record<string, string>;
+    request: Request;
+    env: TEnv;
+    segments: InterceptSegmentsState;
+    fromRouteName?: DefaultRouteName;
+    toRouteName?: DefaultRouteName;
+};
+/**
+ * Selector function for conditional interception
+ * Returns true to intercept, false to skip and fall through to route handler
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
+export type InterceptWhenFn<TEnv = any> = (ctx: InterceptSelectorContext<TEnv>) => boolean;
+/**
+ * Config object passed to intercept() (its 4th argument). `when` gates whether
+ * the intercept activates on a soft navigation — a single match-time selector or
+ * an array of them (ALL must return true; omit to always activate). This is the
+ * intercept counterpart to transition({ when }); both express conditional
+ * behavior as a config field rather than a separate DSL helper.
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
+export interface InterceptConfig<TEnv = any> {
+    when?: InterceptWhenFn<TEnv> | InterceptWhenFn<TEnv>[];
+}
+/**
+ * Intercept entry stored in EntryData
+ * Contains the slot name, route to intercept, and handler
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
+export type InterceptEntry = {
+    slotName: `@${string}`;
+    routeName: string;
+    handler: ReactNode | Handler<any, any, any>;
+    middleware: MiddlewareFn<any, any>[];
+    revalidate: ShouldRevalidateFn<any, any>[];
+    errorBoundary: (ReactNode | ErrorBoundaryHandler)[];
+    notFoundBoundary: (ReactNode | NotFoundBoundaryHandler)[];
+    loader: LoaderEntry[];
+    loading?: ReactNode | false;
+    transition?: TransitionConfig;
+    layout?: ReactNode | Handler<any, any, any>;
+    when: InterceptWhenFn[];
+};
+export interface ParallelEntryData extends EntryPropCommon, EntryPropDatas, EntryPropSegments, EntryPropRender {
+    type: "parallel";
+    handler: Record<`@${string}`, Handler<any, any, any> | ReactNode>;
+    /** Set when any parallel slot is a Static definition */
+    isStaticPrerender?: true;
+    /** Per-slot static handler $$ids for build-time store lookup */
+    staticHandlerIds?: Record<string, string>;
+}
+export type ParallelEntries = Partial<Record<`@${string}`, ParallelEntryData>>;
+/**
+ * This entry's own structural children plus its owned loaders. `loader` lives
+ * here (not in EntryPropDatas) because loaders are owned by the entry, not
+ * inherited from ancestors.
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
+export type EntryPropSegments = {
+    loader: LoaderEntry[];
+    layout: EntryData[];
+    parallel: ParallelEntries;
+    intercept: InterceptEntry[];
+};
+export type EntryData = ({
+    type: "route";
+    handler: Handler<any, any, any>;
+    /** URL pattern for this route (used by path() in urls()) */
+    pattern?: string;
+    /** Set when handler is a Prerender definition */
+    isPrerender?: true;
+    /** Original PrerenderHandlerDefinition (for build-time getParams access) */
+    prerenderDef?: {
+        getParams?: (ctx: any) => Promise<any[]> | any[];
+        options?: {
+            concurrency?: number;
+        };
+    };
+    /** Set when route is wrapped with Passthrough() — has a separate live handler */
+    isPassthrough?: true;
+    /** Live handler for runtime fallback (only set on Passthrough routes) */
+    liveHandler?: Handler<any, any, any>;
+    /** Set when handler is a Static definition (build-time only) */
+    isStaticPrerender?: true;
+    /** Static handler $$id for build-time store lookup */
+    staticHandlerId?: string;
+    /** Response type for non-RSC routes (json, text, image, any) */
+    responseType?: string;
+    /**
+     * PPR (partial pre-rendering) opt-in from the path() `ppr` option. A
+     * document-level property of the page route: `true` uses the default
+     * shell policy, an object carries ttl/swr/tags. Read by the integrated
+     * PPR serve path (rsc/shell-serve.ts resolvePprConfig).
+     */
+    ppr?: boolean | import("../urls/pattern-types.js").PartialPrerenderProps;
+} & EntryPropCommon & EntryPropDatas & EntryPropSegments & EntryPropRender) | ({
+    type: "layout";
+    handler: ReactNode | Handler<any, any, any>;
+    /** Set when handler is a Static definition (build-time only) */
+    isStaticPrerender?: true;
+    /** Static handler $$id for build-time store lookup */
+    staticHandlerId?: string;
+} & EntryPropCommon & EntryPropDatas & EntryPropSegments & EntryPropRender) | ParallelEntryData | ({
+    type: "cache";
+    /** Cache entries create cache boundaries and render like layouts (with Outlet) */
+    handler: ReactNode | Handler<any, any, any>;
+} & EntryPropCommon & EntryPropDatas & EntryPropSegments & EntryPropRender);
+/**
+ * Tracked include info for build-time manifest generation
+ */
+export interface TrackedInclude {
+    prefix: string;
+    fullPrefix: string;
+    namePrefix?: string;
+    patterns: unknown;
+    lazy: boolean;
+}
+/**
+ * Cached response-header write scope (issue #713). `kind` selects the error
+ * wording; `routeKey` names the route in the error.
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
+export type CachedHeaderScope = {
+    kind: "cache" | "ppr";
+    routeKey?: string;
+};
+/**
+ * Context stored in AsyncLocalStorage
+ */
+interface HelperContext {
+    manifest: Map<string, EntryData>;
+    namespace: string;
+    parent: EntryData | null;
+    counters: Record<string, number>;
+    forRoute?: string;
+    mountIndex?: number;
+    /** Owning router id, when known (threaded by generateManifestFull). Scopes
+     *  the search-schema/root-scope registries so same-named routes in
+     *  different routers don't clobber each other (route-map-builder.ts). */
+    routerId?: string;
+    metrics?: MetricsStore;
+    /** True when rendering for SSR (document requests) */
+    isSSR?: boolean;
+    /** URL patterns map for path() routes (route name -> pattern) */
+    patterns?: Map<string, string>;
+    /** URL patterns grouped by include prefix for separate entry creation */
+    patternsByPrefix?: Map<string, Map<string, string>>;
+    /** Trailing slash config per route name */
+    trailingSlash?: Map<string, "never" | "always" | "ignore">;
+    /** Search param schemas per route name */
+    searchSchemas?: Map<string, Record<string, string>>;
+    /** URL prefix from include() - applied to all path() patterns */
+    urlPrefix?: string;
+    /** Name prefix from include() - applied to all named routes */
+    namePrefix?: string;
+    /** True when this scope is at root level (no named include boundary above).
+     *  Routes at root scope allow dot-local reverse to fall back to bare names. */
+    rootScoped?: boolean;
+    /** Run helper for cleaner middleware code */
+    run?: <T>(fn: () => T | Promise<T>) => T | Promise<T>;
+    /** Tracked includes for build-time manifest generation */
+    trackedIncludes?: TrackedInclude[];
+    /** Cache profiles for DSL-time cache("profileName") resolution */
+    cacheProfiles?: Record<string, import("../cache/profile-registry.js").CacheProfile>;
+    /** True when resolving handlers inside a cache() DSL boundary.
+     *  Read by ctx.get() to guard non-cacheable variable reads. */
+    insideCacheScope?: boolean;
+    /**
+     * RULE (issue #713): in any cached scenario ONLY MIDDLEWARE writes response
+     * headers. Latched by the segment funnels, consulted by
+     * assertCachedHeaderWriteAllowed(); full doctrine in
+     * docs/design/ppr-shell-resume.md "The header doctrine".
+     */
+    cachedHeaderScope?: CachedHeaderScope;
+    /**
+     * Include scope string applied to direct-descendant shortCodes.
+     *
+     * Each `include(...)` call allocates a sibling-positional token like `I0`,
+     * `I1` from its parent's include counter and stores the composed scope
+     * (`${parentScope}I${idx}`) in its lazyContext. When the include's handler
+     * evaluates lazily, the store's `includeScope` is set from that context so
+     * every direct-descendant shortCode is generated as
+     * `${parent.shortCode}${includeScope}${prefix}${index}` — preventing
+     * collisions with siblings declared outside the include.
+     *
+     * The scope is NOT propagated through `store.run(...)`, so layouts /
+     * parallels / caches inside the include absorb the scope into their own
+     * shortCodes and their children start fresh.
+     */
+    includeScope?: string;
+}
+export declare const RangoContext: AsyncLocalStorage<HelperContext>;
+export declare const getContext: () => {
+    context: AsyncLocalStorage<HelperContext>;
+    getStore: () => HelperContext;
+    getParent: () => EntryData | null;
+    getOrCreateStore: (forRoute?: string) => HelperContext;
+    getNextIndex: (type: (string & {}) | "layout" | "parallel" | "middleware" | "revalidate") => string;
+    getShortCode: (type: "layout" | "parallel" | "route" | "loader" | "cache") => string;
+    run: <T>(namespace: string, parent: EntryData | null, callback: (...args: any[]) => T) => T;
+    runWithStore: <T>(store: HelperContext, namespace: string, parent: EntryData | null, callback: (...args: any[]) => T) => T;
+};
+/**
+ * Acquire the active DSL build context, throwing `message` if a helper was
+ * called outside a urls()/map() builder. Returns the store API and the live
+ * HelperContext so callers avoid a second getContext() lookup.
+ */
+export declare function requireDslContext(message: string): {
+    store: ReturnType<typeof getContext>;
+    ctx: HelperContext;
+};
+/**
+ * Run a callback with specific URL and name prefixes
+ * Used by include() to apply prefixes to nested patterns
+ */
+export declare function runWithPrefixes<T>(urlPrefix: string, namePrefix: string | undefined, callback: () => T): T;
+/**
+ * Get current URL prefix from context
+ */
+export declare function getUrlPrefix(): string;
+/**
+ * Get current name prefix from context
+ */
+export declare function getNamePrefix(): string | undefined;
+/**
+ * Get whether the current scope is at root level (no named include boundary above).
+ * Returns true at root or inside { name: "" } includes, false inside named includes.
+ */
+export declare function getRootScoped(): boolean;
+/**
+ * Stamp build-time scope identity onto a Static() definition at mount time.
+ * The bake collector (prerender-collection.ts) renders defs OUTSIDE any
+ * evaluation scope and used to iterate the registry first-non-null, so these
+ * are the ONLY reliable carriers of the def's owning router, root-scope, and
+ * full route name — a name-keyed registry lookup at bake time reproduces the
+ * cross-router collision #757/#762 fixed (and the collector's historical
+ * `$$routePrefix` argument is a name PREFIX, which the root-scope registry
+ * never contains, silently degrading to the dot-heuristic).
+ * A definition mounted more than once is stamped each time; the last mount wins.
+ */
+export declare function stampStaticDefScope(handler: unknown, routeName?: string): void;
+export type { HelperContext };
+/**
+ * Return an isolated copy of a lazy include's captured parent entry.
+ *
+ * DSL helpers (loader(), middleware(), etc.) mutate ctx.parent in place.
+ * Multiple include() scopes capture the *same* syntheticMapRoot as their
+ * parent, so without isolation one include's loaders/middleware leak into
+ * every other route that shares that root.
+ *
+ * The clone is shallow: only the mutable arrays are copied so each
+ * include pushes to its own list. The rest of the entry (id, shortCode,
+ * parent pointer, handler) stays shared, which is correct and cheap.
+ */
+export declare function getIsolatedLazyParent(captured: EntryData | null | undefined): EntryData | null;
+export declare function getParallelEntries(parallels: ParallelEntries | EntryData[] | undefined): ParallelEntryData[];
+export declare function getParallelSlotEntries(parallels: ParallelEntries | EntryData[] | undefined): Array<{
+    slot: `@${string}`;
+    entry: ParallelEntryData;
+}>;
+export declare function getParallelSlotCount(parallels: ParallelEntries | EntryData[] | undefined): number;
+/**
+ * Track performance of a code block (no-op if metrics not enabled)
+ * Returns a done() callback to mark completion and record duration
+ *
+ * @example
+ * ```typescript
+ * const done = track("route-matching");
+ * // ... do work ...
+ * done(); // Records duration
+ * ```
+ */
+export declare function track(label: string, depth?: number): () => void;
+/**
+ * Check if the current execution is inside a cache() DSL boundary.
+ * Returns false inside loader execution — loaders are always fresh
+ * (never cached), so non-cacheable reads are safe.
+ */
+export declare function isInsideCacheScope(): boolean;
+/**
+ * Check if the current execution is inside a DSL loader scope
+ * (wrapped by runInsideLoaderScope). Used by rendered() barrier
+ * to distinguish DSL loaders from handler-invoked loaders.
+ */
+export declare function isInsideLoaderScope(): boolean;
+/**
+ * Latch the cached header-write scope for the current request. First latch
+ * wins: a ppr route latched at the funnel top is not downgraded by a nested
+ * cache() entry (the document-scoped wording is the more useful one).
+ * Takes scalars so the already-latched path allocates nothing.
+ */
+export declare function latchCachedHeaderScope(kind: CachedHeaderScope["kind"], routeKey?: string): void;
+/**
+ * The one ppr opt-in predicate: a page route entry that DECLARED `ppr`
+ * (`false` and undefined mean plain axis 1). Shared by the serve path
+ * (rsc/shell-serve.ts resolvePprConfig) and the header-write latch below so
+ * the two layers can never drift on what counts as a ppr route.
+ */
+export declare function isPprEntry(entry: EntryData): entry is EntryData & {
+    type: "route";
+    ppr: true | import("../urls/pattern-types.js").PartialPrerenderProps;
+};
+/**
+ * Latch the ppr header-write scope when the entry chain about to resolve is a
+ * `ppr` page route's. Called at the TOP of every segment funnel — unlike
+ * cache() (positional: ancestors before the boundary stay writable), ppr is
+ * document-scoped: the root layout down to the page bakes into the shared
+ * shell, so the whole funnel is cached territory.
+ *
+ * Checks the LEAF entry only: `entries` is the traverseBack chain
+ * [root, ..., manifestEntry], and the serve path reads `ppr` off the same
+ * leaf (rsc-rendering.ts: resolvePprConfig(manifestEntry)) — guard and serve
+ * share the predicate (isPprEntry) AND the input, so they cannot drift.
+ */
+export declare function latchPprHeaderScopeForEntries(entries: EntryData[], routeKey?: string): void;
+/**
+ * Clear the ppr header-write latch for the remainder of this render (issue
+ * #735). Called by ctx.dynamic(): a dynamic() render opts off the SHELL axis
+ * (rsc-rendering.ts skips both the HIT commit and the MISS capture on
+ * `_dynamic`), so it is ALWAYS live — every request re-runs the handler and its
+ * header write lands identically each time. The guard's reason to forbid it
+ * (MISS/HIT divergence) evaporates, so the write is re-permitted.
+ *
+ * ONLY the ppr (shell) axis is dropped — dynamic() does NOT opt off the CACHE
+ * axis. Two cases:
+ * - Pure ppr funnel (no cache() boundary): clear the latch → writes re-permit.
+ * - ppr route nested under a cache() boundary: fresh.ts latches "ppr" at the
+ *   funnel top (first-wins), which MASKS the positional cache() latch, but the
+ *   handler still runs inside the cache scope (`insideCacheScope`). A cache()
+ *   HIT skips that handler, so the write is still non-deterministic — UNMASK to
+ *   "cache" instead of clearing, so the guard keeps throwing (accurate cache()
+ *   wording). This is why the check keys off `insideCacheScope`, not just kind.
+ *
+ * A subsequent cache() entered AFTER dynamic() on a pure-ppr funnel re-latches
+ * "cache" via latchCachedHeaderScope's `!store.cachedHeaderScope` guard (the
+ * field is undefined again once cleared). No-op when there is no funnel store or
+ * no ppr latch (dynamic() from middleware runs outside the funnel Store.run
+ * scope, so nothing is latched — the middleware exemption is unchanged).
+ */
+export declare function clearPprHeaderScope(): void;
+/**
+ * RULE (issue #713): in any cached scenario ONLY MIDDLEWARE writes response
+ * headers — handler and loader writes throw while a scope is latched; the one
+ * exemption is DSL (registered) loaders under plain cache(). A handler-invoked
+ * loader body (ctx.use from a handler, never registered with loader()) is
+ * skipped with its handler on a HIT and throws like a handler write (#725).
+ * A ctx.dynamic() render clears the ppr latch (clearPprHeaderScope, #735) so
+ * its always-live handler header writes are re-permitted. Full layer rules and
+ * rationale: docs/design/ppr-shell-resume.md "The header doctrine".
+ */
+export declare function assertCachedHeaderWriteAllowed(surface: string, surfaceProp?: string | symbol): void;
+/**
+ * Run `fn` inside a loader scope. While active, cache-scope guards
+ * are bypassed because loaders are always fresh (never cached) and
+ * their side effects (setCookie, header, etc.) are safe.
+ */
+export declare function runInsideLoaderScope<T>(fn: () => T): T;
+/**
+ * Run `fn` inside a loader BODY scope. Marks loader-function execution for the
+ * cache-purity guard only (isInsideCacheScope), WITHOUT affecting
+ * isInsideLoaderScope()/rendered() gating. Applied to every loader body (DSL
+ * and handler-invoked via ctx.use) so request-scoped reads inside a loader
+ * never trip the cache-scope guards — loaders always run fresh.
+ */
+export declare function runInsideLoaderBodyScope<T>(fn: () => T, loaderId?: string, handlerInvoked?: boolean): T;
+/**
+ * The $$id of the loader whose body is currently executing, or undefined
+ * outside any loader body. Used by the shell-capture identity guard
+ * (cookie-store.ts) so its refusal warning can name the loader that read
+ * cookies()/headers() instead of blaming a lane it cannot see — the old
+ * hardcoded "bake-lane loader" text misled a live-lane debugging session
+ * (issue #672, secondary).
+ */
+export declare function getCurrentLoaderBodyId(): string | undefined;
+/**
+ * True while a HANDLER-invoked loader body (`await ctx.use(Loader)` from a
+ * handler, not the DSL segment funnel) is executing. The consumption-lane
+ * rule keys off this: handler consumption yields a BAKED copy in every shared
+ * artifact — cache(), "use cache", and the PPR shell — so the shell-capture
+ * identity guard (cookie-store.ts) permits cookies()/headers() here, exactly
+ * like the cache-purity guards do. DSL segment loaders (live lane masked at
+ * capture, bake lane guarded) never set the flag.
+ */
+export declare function isInsideHandlerInvokedLoaderBody(): boolean;
+/**
+ * Check if the current execution is inside a handle push callback (sync or an
+ * async callback's continuation). Used by the handler-to-loader deadlock guard
+ * to exempt push-callback continuations.
+ */
+export declare function isInsidePushCallbackScope(): boolean;
+/**
+ * Run `fn` inside a push-callback scope. Wraps the invocation of a handle push
+ * callback so that any ctx.use(loader) it makes — including after one of its own
+ * awaits — is exempt from the deadlock guard.
+ */
+export declare function runInsidePushCallbackScope<T>(fn: () => T): T;

package/dist/types/server/cookie-parse.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Canonical inbound-Cookie-header parser.
+ *
+ * Kept as a dependency-free leaf so any consumer (request-context, the host
+ * dispatcher, tests) can share one implementation without pulling a heavier
+ * module's graph. A duplicate copy in middleware-cookies.ts was removed; the
+ * host copy in cookie-handler.ts was collapsed onto this one. Not part of the
+ * public export surface.
+ */
+export declare function parseCookiesFromHeader(cookieHeader: string | null): Record<string, string>;

package/dist/types/server/cookie-store.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Cookie Store — Next.js-style cookie facade backed by the response-derived model.
+ *
+ * `cookies()` returns a CookieStore scoped to the current request.
+ * Reads merge the original Cookie header with Set-Cookie mutations
+ * already queued on the response stub (last-write-wins).
+ * Writes append Set-Cookie to the response stub.
+ */
+import type { CookieOptions } from "../router/middleware-types.js";
+/**
+ * A single cookie entry returned by get() and getAll().
+ */
+export interface Cookie {
+    name: string;
+    value: string;
+}
+/**
+ * Request-scoped cookie store.
+ *
+ * Reads see the effective merged view (original request + same-request mutations).
+ * Writes append Set-Cookie headers to the shared response stub.
+ */
+export interface CookieStore {
+    /** Get a single cookie by name. Returns undefined if not set or deleted. */
+    get(name: string): Cookie | undefined;
+    /** Get all effective cookies, or all cookies with a given name. */
+    getAll(name?: string): Cookie[];
+    /** Check whether a cookie exists in the effective view. */
+    has(name: string): boolean;
+    /** Set a cookie (appends Set-Cookie to the response stub). */
+    set(name: string, value: string, options?: CookieOptions): void;
+    /** Delete a cookie (appends Set-Cookie with maxAge=0 to the response stub). */
+    delete(name: string, options?: Pick<CookieOptions, "domain" | "path">): void;
+}
+/**
+ * Get the request-scoped cookie store.
+ *
+ * Must be called inside a request context (middleware, handler, loader, action).
+ * Throws if called outside request scope.
+ *
+ * @example
+ * ```typescript
+ * import { cookies } from "@rangojs/router";
+ *
+ * // In a handler, loader, or action:
+ * const session = cookies().get("session")?.value;
+ * cookies().set("session", "new-token", { httpOnly: true });
+ * cookies().delete("session");
+ * ```
+ */
+export declare function cookies(): CookieStore;
+/**
+ * Read-only view of HTTP headers.
+ * Exposes only the read methods of the Headers API.
+ */
+export interface ReadonlyHeaders {
+    get(name: string): string | null;
+    has(name: string): boolean;
+    entries(): HeadersIterator<[string, string]>;
+    keys(): HeadersIterator<string>;
+    values(): HeadersIterator<string>;
+    forEach(callback: (value: string, name: string, parent: ReadonlyHeaders) => void): void;
+    [Symbol.iterator](): HeadersIterator<[string, string]>;
+}
+type HeadersIterator<T> = IterableIterator<T>;
+/**
+ * Get the original request headers (read-only).
+ *
+ * Must be called inside a request context.
+ * Returns a read-only view of the incoming request's headers.
+ * Mutation methods (set, append, delete) throw at runtime.
+ *
+ * @example
+ * ```typescript
+ * import { headers } from "@rangojs/router";
+ *
+ * const auth = headers().get("authorization");
+ * const contentType = headers().get("content-type");
+ * ```
+ */
+export declare function headers(): ReadonlyHeaders;
+/**
+ * Force the calling client's caches to miss from now on, from the server seat:
+ * write a rotated `Set-Cookie` for the rango state. The responding client
+ * applies it on receipt, and its history cache is marked stale by the
+ * jar-divergence observer at its next read. Per-client and lazy — it rotates
+ * only the client that receives this response, not every client.
+ *
+ * Idempotent within a request (one `Set-Cookie`). Inert (a dev warning) when
+ * called outside a request context. Like `cookies()`, it throws inside a
+ * `"use cache"` / `cache()` boundary, but is allowed from a loader (loaders are
+ * the dynamic holes of a cached document).
+ */
+export declare function invalidateClientCache(): void;
+/**
+ * Suppress a server action's automatic client-cache invalidation: tell the
+ * action bridge this action changed nothing a route renders, so it should leave
+ * the client's state and caches alone (no rotation, no prefetch wipe, no
+ * broadcast, no revalidation refetch). Per-response, not per-action-definition —
+ * only the execution knows whether anything changed.
+ *
+ * Sets an internal response header the bridge reads. Idempotent within a
+ * request. Inert (a dev warning) outside a request context — there is no
+ * automatic invalidation to suppress.
+ */
+export declare function keepClientCache(): void;
+export {};

package/dist/types/server/fetchable-loader-store.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Fetchable loader store - internal registry for fetchable loader functions.
+ *
+ * Extracted into its own module to avoid circular dependencies between
+ * loader.rsc.ts and request-context.ts. This module has no imports from
+ * either, so both can safely import from here.
+ *
+ * Populated by createLoader() in loader.rsc.ts.
+ * Read by request-context.ts (for ctx.use()) and loader-registry.ts (for GET-based fetching).
+ */
+import type { LoaderFn } from "../types.js";
+import type { MiddlewareFn } from "../router/middleware.js";
+export interface LoaderRegistryEntry {
+    fn: LoaderFn<any, any, any>;
+    middleware: MiddlewareFn[];
+    /** Whether this loader is fetchable via the _rsc_loader endpoint. */
+    fetchable: boolean;
+}
+export declare function registerFetchableLoader(id: string, fn: LoaderFn<any, any, any>, middleware: MiddlewareFn[], fetchable: boolean): void;
+export declare function getFetchableLoader(id: string): LoaderRegistryEntry | undefined;