@rangojs/router 0.0.0-experimental.tapabs3 → 0.1.1

package/dist/types/context-var.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Typed context variables for ctx.set() / ctx.get().
+ *
+ * createVar<T>() produces a typed token that handlers set and layouts/middleware
+ * read. The token carries a unique Symbol used as the property key on the
+ * per-request variables object — no build-time processing, no IDs.
+ *
+ * @example
+ * ```ts
+ * import { createVar } from "@rangojs/router";
+ *
+ * interface PaginationData { current: number; total: number }
+ * export const Pagination = createVar<PaginationData>();
+ *
+ * // Non-cacheable var — ctx.get(User) throws inside a cache() boundary
+ * export const User = createVar<UserData>({ cache: false });
+ *
+ * // handler
+ * ctx.set(Pagination, { current: 1, total: 4 });
+ *
+ * // layout
+ * const pg = ctx.get(Pagination); // PaginationData | undefined
+ * ```
+ */
+export interface ContextVar<T> {
+    readonly __brand: "context-var";
+    readonly key: symbol;
+    /** When false, ctx.get(var) throws inside a cache() boundary. */
+    readonly cache: boolean;
+    /** Phantom field to carry the type parameter. Never set at runtime. */
+    readonly __type?: T;
+}
+export interface ContextVarOptions {
+    /**
+     * When false, marks this variable as non-cacheable.
+     * Reading this var with ctx.get() inside a cache() boundary throws. Use for
+     * inherently request-specific data (user sessions, auth tokens, etc.) that
+     * must never be baked into cached segments.
+     *
+     * @default true
+     */
+    cache?: boolean;
+}
+/**
+ * Create a typed context variable token.
+ *
+ * The returned object is used with ctx.set(token, value) and ctx.get(token)
+ * for compile-time-checked data flow between handlers, layouts, and middleware.
+ */
+export declare function createVar<T>(options?: ContextVarOptions): ContextVar<T>;
+/**
+ * Type guard: is the value a ContextVar token?
+ */
+export declare function isContextVar(value: unknown): value is ContextVar<unknown>;
+/**
+ * Does a variables object hold any entries? Counts both string keys and the
+ * symbol-keyed entries (context vars are stored under symbols), so an object
+ * carrying only symbol-keyed vars is still reported as non-empty.
+ */
+export declare function hasContextVars(variables: object): boolean;
+/**
+ * Check if a variable value is non-cacheable (either var-level or write-level).
+ */
+export declare function isNonCacheable(variables: any, keyOrVar: string | ContextVar<any>): boolean;
+/**
+ * Read a variable from the variables store.
+ * Accepts either a string key (legacy) or a ContextVar token (typed).
+ */
+export declare function contextGet(variables: any, keyOrVar: string | ContextVar<any>): any;
+export interface ContextSetOptions {
+    /**
+     * When false, marks this specific write as non-cacheable.
+     * "Least cacheable wins" — if either the var definition or this option
+     * says cache: false, the value is non-cacheable.
+     *
+     * @default true (inherits from createVar)
+     */
+    cache?: boolean;
+}
+/**
+ * Write a variable to the variables store.
+ * Accepts either a string key (legacy) or a ContextVar token (typed).
+ */
+export declare function contextSet(variables: any, keyOrVar: string | ContextVar<any>, value: any, options?: ContextSetOptions): void;

package/dist/types/debug.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Debug utilities for manifest inspection and comparison
+ */
+import { type EntryData } from "./server/context";
+/**
+ * Serialized entry for debug output
+ */
+export interface SerializedEntry {
+    id: string;
+    shortCode: string;
+    type: string;
+    parentShortCode: string | null;
+    pattern?: string;
+    hasLoader: boolean;
+    hasMiddleware: boolean;
+    hasErrorBoundary: boolean;
+    parallelCount: number;
+    interceptCount: number;
+}
+/**
+ * Serialized manifest structure
+ */
+export interface SerializedManifest {
+    routes: Record<string, SerializedEntry>;
+    layouts: Record<string, SerializedEntry>;
+    totalRoutes: number;
+    totalLayouts: number;
+}
+/**
+ * Serialize a manifest Map into a JSON-friendly structure
+ */
+export declare function serializeManifest(manifest: Map<string, EntryData>): SerializedManifest;
+/**
+ * Compare two manifests and return differences
+ */
+export declare function compareManifests(oldManifest: SerializedManifest, newManifest: SerializedManifest): {
+    addedRoutes: string[];
+    removedRoutes: string[];
+    changedRoutes: Array<{
+        key: string;
+        field: string;
+        old: any;
+        new: any;
+    }>;
+    addedLayouts: string[];
+    removedLayouts: string[];
+    changedLayouts: Array<{
+        key: string;
+        field: string;
+        old: any;
+        new: any;
+    }>;
+};
+/**
+ * Format manifest diff as a human-readable string
+ */
+export declare function formatManifestDiff(diff: ReturnType<typeof compareManifests>): string;

package/dist/types/decode-loader-results.d.ts

@@ -0,0 +1,5 @@
+import type { ReactNode } from "react";
+export declare function decodeLoaderResults(resolvedData: any[], loaderIds: string[]): {
+    loaderData: Record<string, any>;
+    errorFallback: ReactNode;
+};

package/dist/types/default-error-boundary.d.ts

@@ -0,0 +1,10 @@
+import type { ReactNode } from "react";
+import type { ErrorBoundaryFallbackProps } from "./types.js";
+/**
+ * Default error boundary fallback component
+ *
+ * This is rendered when an error occurs and no custom error boundary
+ * is defined in the route tree. Shows a simple "Internal Server Error"
+ * message with the error details in development.
+ */
+export declare function DefaultErrorFallback({ error, }: ErrorBoundaryFallbackProps): ReactNode;

package/dist/types/defer.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Deferred handle values — "decide synchronously, resolve late".
+ *
+ * A handle is pushed from code that holds `ctx` (a route/layout handler), so the
+ * decision to push lands before the handles stream seals. But the value often
+ * isn't known there — it may come from a deep async component far from the
+ * handler. `ctx.use(Handle).defer()` reserves the handle's slot now (synchronous,
+ * so ordering and the pre-seal timing hold) and returns a resolver with the SAME
+ * signature as the push: you call it later, anywhere in the render, with the same
+ * value you would have passed to the push.
+ *
+ *   const breadcrumb = ctx.use(Breadcrumbs);   // (item) => void  &  .defer()
+ *   const resolve = breadcrumb.defer({ timeoutMs: 5000, else: null });
+ *   // deep async component, far from ctx:
+ *   resolve({ label, href, content });          // identical call, just deferred
+ *
+ * Under the hood the reserved slot is a Promise. Handle values are resolved
+ * before any consumer sees them (resolve-by-default: the full render resolves
+ * server-side, navigation resolves client-side before apply), so `useHandle`
+ * receives the resolved value, never the Promise. The hazard that guards against
+ * bugs: a deferred slot whose resolver is never called would keep the render —
+ * and the HTTP response — waiting forever. So a deferred auto-resolves to `else`
+ * after `timeoutMs` (default {@link DEFAULT_DEFER_TIMEOUT_MS}) if the resolver is
+ * never called, degrading gracefully (and warning in dev) instead of hanging.
+ */
+/** Default auto-resolve window. Long enough for genuine deep async work, short
+ *  enough that a forgotten resolve does not hang the response indefinitely. */
+export declare const DEFAULT_DEFER_TIMEOUT_MS = 10000;
+/** Options for `ctx.use(Handle).defer()`. */
+export interface DeferOptions<TData> {
+    /**
+     * Auto-resolve to `else` after this many ms if the resolver is never called,
+     * so a forgotten resolve cannot hold the Flight stream — and thus the HTTP
+     * response — open. Defaults to {@link DEFAULT_DEFER_TIMEOUT_MS}. `0` or
+     * `Infinity` disable the timeout intentionally (not recommended on a request
+     * path). Any other non-finite or negative value is treated as a mistake and
+     * falls back to the default rather than silently disabling the safety net.
+     * Named `timeoutMs` to match the router's `*Ms` duration convention.
+     */
+    timeoutMs?: number;
+    /**
+     * Value the slot resolves to if the timeout fires before the resolver is
+     * called. Defaults to `undefined` (the deferred item is skipped/empty). For
+     * renderable handle content, `null` is the usual graceful fallback, so the
+     * type admits `null` even when `TData` does not.
+     */
+    else?: TData | null;
+}
+/**
+ * The call signature shared by a handle push and the resolver returned by
+ * `.defer()`: a concrete value, a `Promise` of the value (Flight streams it as a
+ * late row), or a thunk returning a `Promise` (called immediately).
+ */
+export type HandlePushFn<TData> = (data: TData | Promise<TData> | (() => Promise<TData>)) => void;
+/**
+ * The push function returned by `ctx.use(Handle)`. Call it to push a value now,
+ * or call `.defer()` to reserve the slot now and resolve the value later (e.g.
+ * from a deep async component) with a timeout safety net.
+ */
+export type HandlePush<TData> = HandlePushFn<TData> & {
+    /**
+     * Reserve this handle's slot synchronously and return a resolver that is
+     * push-equal: it takes the same argument shapes as the push (value, Promise, or
+     * thunk) and behaves identically. Two things the resolver adds over a direct
+     * push: a timeout (if the resolver is never called, the slot auto-resolves to
+     * `options.else` after `options.timeoutMs`; calling the resolver cancels it),
+     * and — on the action/revalidation path only — a thunk it runs does NOT
+     * re-enter the deadlock-guard push-callback scope a direct push thunk gets,
+     * because a deferred resolver fires after the handler phase has closed.
+     *
+     * The reserved slot is resolved before any consumer reads it
+     * (resolve-by-default), so `useHandle` receives the resolved value (or the
+     * `else` fallback on timeout), never a Promise.
+     */
+    defer(options?: DeferOptions<TData>): HandlePushFn<TData>;
+};
+export declare function createDeferred<T>(options?: {
+    timeoutMs?: number;
+    fallback?: T | null;
+}): {
+    promise: Promise<T | null | undefined>;
+    resolve: (value: T | null | undefined) => void;
+};
+/**
+ * Attach `.defer()` to a handle push function. The deferred slot is reserved by
+ * pushing the deferred promise through the same push (so ordering, sealing, and
+ * Flight streaming all reuse the existing path); the returned resolver settles it.
+ */
+export declare function withDefer<TData>(push: HandlePushFn<TData>): HandlePush<TData>;

package/dist/types/deps/browser.d.ts

@@ -0,0 +1 @@
+export { createFromReadableStream, createFromFetch, setServerCallback, encodeReply, createTemporaryReferenceSet, } from "@vitejs/plugin-rsc/browser";

package/dist/types/deps/html-stream-client.d.ts

@@ -0,0 +1 @@
+export { rscStream } from "rsc-html-stream/client";

package/dist/types/deps/html-stream-server.d.ts

@@ -0,0 +1 @@
+export { injectRSCPayload } from "rsc-html-stream/server";

package/dist/types/deps/rsc.d.ts

@@ -0,0 +1 @@
+export { renderToReadableStream, decodeReply, createTemporaryReferenceSet, loadServerAction, decodeAction, decodeFormState, } from "@vitejs/plugin-rsc/rsc";

package/dist/types/deps/ssr.d.ts

@@ -0,0 +1 @@
+export { createFromReadableStream, setOnClientReference, } from "@vitejs/plugin-rsc/ssr";

package/dist/types/dev-discovery-protocol.d.ts

@@ -0,0 +1,5 @@
+export declare const DEV_DISCOVERY_READY_EVENT = "rango:dev-discovery-ready";
+export declare const DEV_DISCOVERY_QUERY_EVENT = "rango:dev-discovery-query";
+export declare const DEV_DISCOVERY_PROBE_HEADER = "x-rango-dev-discovery-probe";
+export declare const DEV_DISCOVERY_EPOCH_HEADER = "x-rango-dev-discovery-epoch";
+export declare function isValidDevDiscoveryEpoch(value: unknown): value is number;

package/dist/types/encode-kv.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Shared key=value serialization core.
+ *
+ * One encode+join rule shared by every deterministic query-string serializer
+ * in the codebase (cache keys, route-param strings, search-param strings,
+ * prerender param hashes). Each call site differs only in how it pre-filters
+ * and orders the pairs it hands in, plus whether it sorts; the encoding itself
+ * (`encodeURIComponent(k)=encodeURIComponent(v)` joined by `&`) is identical.
+ *
+ * Dependency-free leaf module so any layer (build-time prerender hashing,
+ * runtime cache keys, client search-param serialization) can import it without
+ * pulling in cache/router internals.
+ */
+export interface EncodeKVOptions {
+    /**
+     * Sort pairs by key in codepoint (byte) order before joining. Byte order via
+     * the `<` operator, NOT localeCompare, so the result is identical across
+     * Node, Workers, and browsers regardless of runtime locale.
+     *
+     * Defaults to false (insertion order preserved).
+     */
+    sort?: boolean;
+}
+/**
+ * Serialize an array of [key, value] pairs to a deterministic query string
+ * (no leading `?`). Both key and value are passed through encodeURIComponent
+ * so a key/value containing `&` or `=` cannot collide with a structurally
+ * different pair set.
+ *
+ * Callers are responsible for any filtering (e.g. dropping reserved params) and
+ * any value coercion (e.g. String(v), skipping null/undefined) BEFORE calling.
+ * This function never inspects or skips values; it encodes exactly what it is
+ * given so each call site keeps its own existing output.
+ */
+export declare function encodeKV(pairs: Iterable<readonly [string, string]>, options?: EncodeKVOptions): string;

package/dist/types/errors.d.ts

@@ -0,0 +1,226 @@
+/**
+ * Custom error classes for Rango
+ *
+ * All errors include:
+ * - Descriptive names for easy identification
+ * - Cause property for structured debugging data
+ */
+/**
+ * Options for error construction
+ */
+interface ErrorOptions {
+    cause?: unknown;
+}
+/**
+ * Thrown when no route matches the requested pathname
+ */
+export declare class RouteNotFoundError extends Error {
+    name: "RouteNotFoundError";
+    cause?: unknown;
+    constructor(message: string, options?: ErrorOptions);
+}
+export declare function isRouteNotFoundError(error: unknown): error is RouteNotFoundError;
+/**
+ * Thrown when data is not found (e.g., product with ID doesn't exist)
+ * Use this in handlers/loaders to trigger the nearest notFoundBoundary
+ *
+ * @example
+ * ```typescript
+ * route("products.detail", async (ctx) => {
+ *   const product = await db.products.get(ctx.params.slug);
+ *   if (!product) throw new DataNotFoundError("Product not found");
+ *   return <ProductDetail product={product} />;
+ * });
+ * ```
+ */
+export declare class DataNotFoundError extends Error {
+    name: "DataNotFoundError";
+    cause?: unknown;
+    constructor(message?: string, options?: ErrorOptions);
+}
+/**
+ * Convenience function to throw a DataNotFoundError
+ * Shorter syntax for common not-found scenarios
+ *
+ * @example
+ * ```typescript
+ * const product = await db.products.get(slug);
+ * if (!product) throw notFound("Product not found");
+ * // or simply:
+ * if (!product) throw notFound();
+ * ```
+ */
+export declare function notFound(message?: string): never;
+/**
+ * Thrown when middleware execution fails
+ */
+export declare class MiddlewareError extends Error {
+    name: "MiddlewareError";
+    cause?: unknown;
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * Thrown when a route handler fails
+ */
+export declare class HandlerError extends Error {
+    name: "HandlerError";
+    cause?: unknown;
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * Thrown when segment building fails
+ */
+export declare class BuildError extends Error {
+    name: "BuildError";
+    cause?: unknown;
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * Thrown when a route-definition DSL helper (route/layout/loader/cache/…) is
+ * called outside an active urls()/map() builder, so there is no
+ * AsyncLocalStorage build context to attach to. The message names the specific
+ * helper and how to fix it; the `cause` records the mechanical reason so the
+ * failure mode is identifiable (not conflated with an unrelated throw).
+ */
+export declare class DslContextError extends Error {
+    name: "DslContextError";
+    cause?: unknown;
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * Thrown when a network request fails (server unreachable, no internet, etc.)
+ * This error triggers the root error boundary with retry capability.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await fetch(url);
+ * } catch (error) {
+ *   if (error instanceof TypeError) {
+ *     throw new NetworkError("Unable to connect to server", { cause: error });
+ *   }
+ *   throw error;
+ * }
+ * ```
+ */
+export declare class NetworkError extends Error {
+    name: "NetworkError";
+    cause?: unknown;
+    /** The URL that failed to fetch */
+    url?: string;
+    /** Whether this was during an action, navigation, or revalidation */
+    operation?: "action" | "navigation" | "revalidation";
+    constructor(message?: string, options?: ErrorOptions & {
+        url?: string;
+        operation?: "action" | "navigation" | "revalidation";
+    });
+}
+/**
+ * Check if an error is a network-level failure (server unreachable, no internet)
+ * These are typically TypeError from fetch when the network request itself fails.
+ */
+export declare function isNetworkError(error: unknown): boolean;
+/**
+ * Structured error for JSON response routes.
+ * Thrown by handlers to return a typed error envelope with a specific HTTP status.
+ *
+ * Unlike standard Error, RouterError messages are always exposed to the client
+ * (the developer intentionally crafted them for consumers).
+ *
+ * @example
+ * ```typescript
+ * path("/products/:id", (ctx) => {
+ *   const product = products.find(p => p.id === ctx.params.id);
+ *   if (!product) throw new RouterError("NOT_FOUND", "Product not found", { status: 404 });
+ *   return product;
+ * }, { name: "productDetail" })
+ * ```
+ */
+export declare class RouterError extends Error {
+    name: "RouterError";
+    code: string;
+    status: number;
+    cause?: unknown;
+    constructor(code: string, message: string, options?: {
+        status?: number;
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown inside a Prerender or Static handler at build time to signal
+ * "skip this entry, log it, and continue with the rest."
+ *
+ * When thrown, the entry is excluded from the pre-render manifest
+ * but the build continues normally. Regular throws (non-Skip)
+ * stop all further pre-rendering and fail the build.
+ *
+ * @example
+ * ```typescript
+ * export const BlogPost = Prerender(
+ *   async () => allPosts.map(p => ({ slug: p.slug })),
+ *   async (ctx) => {
+ *     const post = await getPost(ctx.params.slug);
+ *     if (post.draft) throw new Skip(`"${ctx.params.slug}" is a draft`);
+ *     return <PostPage post={post} />;
+ *   },
+ * );
+ * ```
+ */
+export declare class Skip extends Error {
+    name: "Skip";
+    cause?: unknown;
+    constructor(message?: string, options?: ErrorOptions);
+}
+/**
+ * Type guard to check if a thrown value is a Skip signal.
+ */
+export declare function isSkip(value: unknown): value is Skip;
+/**
+ * Thrown by the partial updater when the server responds with a redirect payload
+ * that carries location state. Caught by navigate() to re-navigate to the
+ * redirect target with the server-set state merged into history.pushState.
+ *
+ * Not an Error subclass -- this is a control flow signal, not a failure.
+ */
+export declare class ServerRedirect {
+    readonly url: string;
+    readonly state: Record<string, unknown> | undefined;
+    readonly name = "ServerRedirect";
+    constructor(url: string, state: Record<string, unknown> | undefined);
+}
+/**
+ * Thrown when route handler returns invalid type
+ */
+export declare class InvalidHandlerError extends Error {
+    name: "InvalidHandlerError";
+    cause?: unknown;
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * Internal invariant assertion for development-time checks
+ *
+ * @internal
+ * @param condition - Condition that must be true
+ * @param message - Error message to throw if condition is false
+ * @throws {Error} If condition is false
+ *
+ * @example
+ * ```typescript
+ * invariant(user !== null, 'User must be defined');
+ * invariant(node.type === 'layout', `Expected layout, got ${node.type}`);
+ * ```
+ */
+export declare function invariant(condition: any, message: string): asserts condition;
+/**
+ * Sanitize errors for production - prevents leaking sensitive information
+ *
+ * SECURITY CRITICAL:
+ * - In production: NEVER send stack traces, file paths, or internal state
+ * - In development: Show full error details for debugging
+ * - ALWAYS consume error.stack to prevent memory leaks
+ *
+ * @param error - Error to sanitize
+ * @returns Response suitable for sending to client
+ */
+export declare function sanitizeError(error: unknown): Response;
+export {};

package/dist/types/escape-script.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Escape a JSON (or JSON-derived) string for safe embedding inside an HTML
+ * <script> element via dangerouslySetInnerHTML. Without this a value containing
+ * "</script>" closes the tag early — the rest of the page leaks as raw HTML, and
+ * in an executable script the trailing content runs. Escaping "<" defeats the
+ * early close; ">" and "&" are escaped for completeness so the serialized payload
+ * can never form HTML syntax. The result is still valid JSON and a valid JS
+ * string literal (\uXXXX escapes are legal in both) and re-parses identically.
+ *
+ * Used by every site that interpolates JSON.stringify(...) into inline <script>
+ * content: the JSON-LD meta descriptors (handles/MetaTags) and the FOUC theme
+ * init script (theme/theme-script).
+ */
+export declare function escapeJsonForScript(json: string): string;
+/**
+ * Escape an inline <script> body so it cannot terminate or corrupt the document.
+ * Two sequences are rewritten, each via a JS escape that is valid in string,
+ * template, regex (including the `u`/`v` flags), and JSON contexts — so the body
+ * still parses identically as code AND as JSON (application/json, ld+json):
+ * - "</script" -> "<\/script": stops a literal close tag inside the body from
+ *   ending the element early. `\/` is a valid JSON escape and a valid regex escape.
+ * - "<!--": the "!" (U+0021) is emitted as a unicode escape (see the replacement
+ *   string below), so the literal "<!--" token never reaches the HTML parser. A
+ *   literal "<!--" puts the parser into the "script data escaped" state and a
+ *   following "<script" into "script data DOUBLE escaped", where the real
+ *   "</script>" no longer closes the element — `var x = "<!--<script>"` would
+ *   swallow the rest of the document. The unicode-escape form decodes back to "!"
+ *   in string/template/JSON/regex contexts, unlike "\!" (invalid JSON, invalid
+ *   /u-regex escape).
+ * Real operators such as `a < b` and `a && b` are untouched (unlike
+ * escapeJsonForScript, which \u-escapes every "<", "&", ">").
+ *
+ * GUARANTEE / LIMITATION: value-preserving for the contexts where these sequences
+ * legitimately appear — string/template literals, regexes (incl. `u`/`v`), and
+ * JSON. It is NOT source-text-preserving (e.g. String.raw`</script>` sees the
+ * extra backslash), and it cannot rewrite "</script"/"<!--" that appear as bare
+ * code (a legacy `<!--` line comment, or `</script` outside any literal) — neither
+ * occurs in valid script payloads. Not a general sanitizer for arbitrary UNTRUSTED
+ * source; for untrusted dynamic data, JSON-encode it and read it back, rather than
+ * inlining it as code.
+ *
+ * Used by the Script handle's <Scripts> renderer for inline `children`.
+ */
+export declare function escapeScriptBody(js: string): string;

package/dist/types/handle.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Handle definition for accumulating data across route segments.
+ *
+ * Handles allow server-side route handlers to pass accumulated data to client
+ * components. Unlike loaders (which fetch data for specific routes), handles
+ * accumulate data across all matched route segments.
+ *
+ * @example
+ * ```ts
+ * // Define a handle (name auto-generated from file + export).
+ * // Default collect is the identity: one array per segment that pushed.
+ * export const Breadcrumbs = createHandle<BreadcrumbItem, BreadcrumbItem[]>(
+ *   (segments) => segments.flat(), // opt into a single flat list
+ * );
+ *
+ * // Use in handler
+ * const push = ctx.use(Breadcrumbs);
+ * push({ label: "Home", href: "/" });
+ *
+ * // Consume on client
+ * const crumbs = useHandle(Breadcrumbs);
+ * ```
+ */
+export interface Handle<TData, TAccumulated = TData[][]> {
+    /**
+     * Brand to distinguish handles from loaders in ctx.use()
+     */
+    readonly __brand: "handle";
+    /**
+     * Auto-generated unique ID for this handle (used as key in storage)
+     * Format: "filePath#ExportName" in dev, "hash#ExportName" in production
+     */
+    readonly $$id: string;
+}
+export declare function getCollectFn(id: string): ((segments: unknown[][]) => unknown) | undefined;
+/**
+ * Create a handle definition for accumulating data across route segments.
+ *
+ * The $$id is auto-generated by the Vite exposeInternalIds plugin based on
+ * file path and export name. No manual naming required.
+ *
+ * @param collect - Optional collect function. Default: pass the per-segment data
+ *   through as-is (one array per segment that pushed, in segment order). Lossless,
+ *   so a consumer can tell which/how-many segments contributed. Opt into a single
+ *   flat list with `(segments) => segments.flat()`.
+ * @param __injectedId - Auto-injected by Vite plugin, do not provide manually
+ *
+ * @example
+ * ```ts
+ * // Default: per-segment grouping, as-is
+ * export const Pushed = createHandle<string>();
+ * // Result type: string[][]  (e.g. [["a"], ["b", "c"]])
+ *
+ * // Opt into a single flat list
+ * export const Breadcrumbs = createHandle<BreadcrumbItem, BreadcrumbItem[]>(
+ *   (segments) => segments.flat()
+ * );
+ * // Result type: BreadcrumbItem[]
+ *
+ * // Custom: last value wins
+ * export const PageTitle = createHandle<string, string>(
+ *   (segments) => segments.flat().at(-1) ?? "Default Title"
+ * );
+ * // Result type: string
+ *
+ * // Custom: object merge
+ * export const Meta = createHandle<Partial<MetaTags>, MetaTags>(
+ *   (segments) => Object.assign({ robots: "index,follow" }, ...segments.flat())
+ * );
+ * // Result type: MetaTags
+ *
+ * // Custom: dedupe by href (TAccumulated must be given — a custom collect that
+ * // returns a flat array no longer matches the default TData[][])
+ * export const Breadcrumbs = createHandle<BreadcrumbItem, BreadcrumbItem[]>(
+ *   (segments) => {
+ *     const all = segments.flat();
+ *     return all.filter((item, i) => all.findIndex(x => x.href === item.href) === i);
+ *   }
+ * );
+ * ```
+ */
+export declare function createHandle<TData, TAccumulated = TData[][]>(collect?: (segments: TData[][]) => TAccumulated, __injectedId?: string): Handle<TData, TAccumulated>;
+export declare function isHandle(value: unknown): value is Handle<unknown, unknown>;
+/**
+ * Collect handle data from a HandleData map, applying the handle's collect
+ * function over segments in order. Shared between server-side rendered()
+ * reads and client-side useHandle().
+ *
+ * @param handle - The handle to collect data for
+ * @param data - Full handle data map (handleName -> segmentId -> entries[])
+ * @param segmentOrder - Segment IDs in parent -> child resolution order
+ */
+export declare function collectHandleData<TData, TAccumulated>(handle: Handle<TData, TAccumulated>, data: Record<string, Record<string, unknown[]>>, segmentOrder: string[]): TAccumulated;