@rangojs/router 0.0.0-experimental.0b82333f

package/dist/errors.js

@@ -0,0 +1,241 @@
+/**
+ * Custom error classes for RSC Router
+ *
+ * All errors include:
+ * - Descriptive names for easy identification
+ * - Cause property for structured debugging data
+ */
+/**
+ * Thrown when no route matches the requested pathname
+ */
+export class RouteNotFoundError extends Error {
+    constructor(message, options) {
+        super(message);
+        this.name = "RouteNotFoundError";
+        Object.setPrototypeOf(this, RouteNotFoundError.prototype);
+        this.cause = options?.cause;
+    }
+}
+/**
+ * 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 class DataNotFoundError extends Error {
+    constructor(message = "Not found", options) {
+        super(message);
+        this.name = "DataNotFoundError";
+        Object.setPrototypeOf(this, DataNotFoundError.prototype);
+        this.cause = options?.cause;
+    }
+}
+/**
+ * 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 function notFound(message) {
+    throw new DataNotFoundError(message);
+}
+/**
+ * Thrown when middleware execution fails
+ */
+export class MiddlewareError extends Error {
+    constructor(message, options) {
+        super(message);
+        this.name = "MiddlewareError";
+        Object.setPrototypeOf(this, MiddlewareError.prototype);
+        this.cause = options?.cause;
+    }
+}
+/**
+ * Thrown when a route handler fails
+ */
+export class HandlerError extends Error {
+    constructor(message, options) {
+        super(message);
+        this.name = "HandlerError";
+        Object.setPrototypeOf(this, HandlerError.prototype);
+        this.cause = options?.cause;
+    }
+}
+/**
+ * Thrown when segment building fails
+ */
+export class BuildError extends Error {
+    constructor(message, options) {
+        super(message);
+        this.name = "BuildError";
+        Object.setPrototypeOf(this, BuildError.prototype);
+        this.cause = options?.cause;
+    }
+}
+/**
+ * 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 class NetworkError extends Error {
+    constructor(message = "Network request failed", options) {
+        super(message);
+        this.name = "NetworkError";
+        Object.setPrototypeOf(this, NetworkError.prototype);
+        this.cause = options?.cause;
+        this.url = options?.url;
+        this.operation = options?.operation;
+    }
+}
+/**
+ * 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 function isNetworkError(error) {
+    // NetworkError we throw ourselves
+    if (error instanceof NetworkError) {
+        return true;
+    }
+    // TypeError from fetch() when network fails (e.g., "Failed to fetch")
+    if (error instanceof TypeError) {
+        const message = error.message.toLowerCase();
+        return (message.includes("failed to fetch") ||
+            message.includes("network request failed") ||
+            message.includes("networkerror") ||
+            message.includes("load failed"));
+    }
+    // DOMException with network-related names
+    if (error instanceof DOMException) {
+        return error.name === "NetworkError";
+    }
+    return false;
+}
+/**
+ * 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 class RouterError extends Error {
+    constructor(code, message, options) {
+        super(message);
+        this.name = "RouterError";
+        Object.setPrototypeOf(this, RouterError.prototype);
+        this.code = code;
+        this.status = options?.status ?? 500;
+        this.type = options?.type;
+        this.cause = options?.cause;
+    }
+}
+/**
+ * Thrown when route handler returns invalid type
+ */
+export class InvalidHandlerError extends Error {
+    constructor(message, options) {
+        super(message);
+        this.name = "InvalidHandlerError";
+        Object.setPrototypeOf(this, InvalidHandlerError.prototype);
+        this.cause = options?.cause;
+    }
+}
+/**
+ * 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 function invariant(condition, message) {
+    if (!condition) {
+        throw new Error(`Invariant: ${message}`);
+    }
+}
+/**
+ * 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 function sanitizeError(error) {
+    // CRITICAL: Consume stack trace to prevent memory leaks
+    if (error && typeof error === "object" && "stack" in error) {
+        const _ = error.stack; // Force V8 to generate/consume stack trace
+    }
+    // Response objects are safe to return as-is
+    if (error instanceof Response) {
+        return error;
+    }
+    const isDev = import.meta.env?.DEV ?? true;
+    if (isDev) {
+        // Development: Send full error details for debugging
+        const errorDetails = {
+            name: error instanceof Error ? error.name : "Error",
+            message: error instanceof Error ? error.message : String(error),
+            stack: error instanceof Error ? error.stack : undefined,
+            cause: error && typeof error === "object" && "cause" in error
+                ? error.cause
+                : undefined,
+        };
+        return new Response(JSON.stringify(errorDetails, null, 2), {
+            status: 500,
+            headers: {
+                "Content-Type": "application/json",
+            },
+        });
+    }
+    // Production: Generic error only - NO internal details
+    // SECURITY: Never leak stack traces, file paths, or application state
+    return new Response("Internal Server Error", {
+        status: 500,
+        headers: {
+            "Content-Type": "text/plain",
+        },
+    });
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/handle.d.ts

@@ -0,0 +1,78 @@
+/**
+ * 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)
+ * export const Breadcrumbs = createHandle<BreadcrumbItem>();
+ *
+ * // 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;
+}
+/**
+ * Look up a collect function from the registry by handle $$id.
+ * Returns undefined if not registered (falls back to defaultCollect in useHandle).
+ */
+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: flatten into array)
+ * @param __injectedId - Auto-injected by Vite plugin, do not provide manually
+ *
+ * @example
+ * ```ts
+ * // Default: flatten into array
+ * export const Breadcrumbs = createHandle<BreadcrumbItem>();
+ * // 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
+ * export const Breadcrumbs = createHandle<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>;
+/**
+ * Type guard to check if a value is a Handle.
+ */
+export declare function isHandle(value: unknown): value is Handle<unknown, unknown>;
+//# sourceMappingURL=handle.d.ts.map

package/dist/handle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handle.d.ts","sourceRoot":"","sources":["../src/handle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,MAAM,CAAC,KAAK,EAAE,YAAY,GAAG,KAAK,EAAE;IACnD;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC;IAE3B;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CAEvB;AAcD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,CAAC,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,KAAK,OAAO,CAAC,GAAG,SAAS,CAEzF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,YAAY,GAAG,KAAK,EAAE,EACxD,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,KAAK,EAAE,EAAE,KAAK,YAAY,EAC/C,YAAY,CAAC,EAAE,MAAM,GACpB,MAAM,CAAC,KAAK,EAAE,YAAY,CAAC,CAwB7B;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,CAO1E"}

package/dist/handle.js

@@ -0,0 +1,82 @@
+/**
+ * Default collect function that flattens segment arrays into a single array.
+ */
+function defaultCollect(segments) {
+    return segments.flat();
+}
+// Module-level registry mapping $$id to collect functions.
+// Populated when createHandle() runs (both server and client).
+// Used by useHandle() to recover collect when handle is deserialized from RSC prop.
+const collectRegistry = new Map();
+/**
+ * Look up a collect function from the registry by handle $$id.
+ * Returns undefined if not registered (falls back to defaultCollect in useHandle).
+ */
+export function getCollectFn(id) {
+    return collectRegistry.get(id);
+}
+/**
+ * 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: flatten into array)
+ * @param __injectedId - Auto-injected by Vite plugin, do not provide manually
+ *
+ * @example
+ * ```ts
+ * // Default: flatten into array
+ * export const Breadcrumbs = createHandle<BreadcrumbItem>();
+ * // 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
+ * export const Breadcrumbs = createHandle<BreadcrumbItem>(
+ *   (segments) => {
+ *     const all = segments.flat();
+ *     return all.filter((item, i) => all.findIndex(x => x.href === item.href) === i);
+ *   }
+ * );
+ * ```
+ */
+export function createHandle(collect, __injectedId) {
+    const handleId = __injectedId ?? "";
+    if (!handleId && process.env.NODE_ENV !== "production") {
+        throw new Error("[rsc-router] Handle is missing $$id. " +
+            "Make sure the exposeInternalIds Vite plugin is enabled and " +
+            "the handle is exported with: export const MyHandle = createHandle(...)");
+    }
+    const collectFn = collect ??
+        defaultCollect;
+    // Register collect in module-level registry so useHandle() can recover it
+    // when the handle is deserialized from RSC props (toJSON strips collect).
+    if (handleId) {
+        collectRegistry.set(handleId, collectFn);
+    }
+    return {
+        __brand: "handle",
+        $$id: handleId,
+    };
+}
+/**
+ * Type guard to check if a value is a Handle.
+ */
+export function isHandle(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "__brand" in value &&
+        value.__brand === "handle");
+}
+//# sourceMappingURL=handle.js.map

package/dist/handle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handle.js","sourceRoot":"","sources":["../src/handle.ts"],"names":[],"mappings":"AAkCA;;GAEG;AACH,SAAS,cAAc,CAAI,QAAe;IACxC,OAAO,QAAQ,CAAC,IAAI,EAAE,CAAC;AACzB,CAAC;AAED,2DAA2D;AAC3D,+DAA+D;AAC/D,oFAAoF;AACpF,MAAM,eAAe,GAAG,IAAI,GAAG,EAA8C,CAAC;AAE9E;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,EAAU;IACrC,OAAO,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;AACjC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,UAAU,YAAY,CAC1B,OAA+C,EAC/C,YAAqB;IAErB,MAAM,QAAQ,GAAG,YAAY,IAAI,EAAE,CAAC;IAEpC,IAAI,CAAC,QAAQ,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY,EAAE,CAAC;QACvD,MAAM,IAAI,KAAK,CACb,uCAAuC;YACrC,6DAA6D;YAC7D,wEAAwE,CAC3E,CAAC;IACJ,CAAC;IAED,MAAM,SAAS,GAAG,OAAO;QACtB,cAAmE,CAAC;IAEvE,0EAA0E;IAC1E,0EAA0E;IAC1E,IAAI,QAAQ,EAAE,CAAC;QACb,eAAe,CAAC,GAAG,CAAC,QAAQ,EAAE,SAA+C,CAAC,CAAC;IACjF,CAAC;IAED,OAAO;QACL,OAAO,EAAE,QAAiB;QAC1B,IAAI,EAAE,QAAQ;KACf,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,SAAS,IAAI,KAAK;QACjB,KAA8B,CAAC,OAAO,KAAK,QAAQ,CACrD,CAAC;AACJ,CAAC"}

package/dist/handles/MetaTags.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Renders all collected meta descriptors from route handlers.
+ *
+ * Place this component inside the `<head>` element of your document.
+ * It will automatically update when meta descriptors change during navigation.
+ *
+ * When theme is enabled in router config, also renders the theme initialization
+ * script to prevent FOUC (flash of unstyled content).
+ *
+ * Async meta descriptors (Promise<MetaDescriptorBase>) are resolved using
+ * React's use() hook. RSC streaming handles the Promise resolution.
+ */
+export declare function MetaTags(): React.ReactNode;
+//# sourceMappingURL=MetaTags.d.ts.map

package/dist/handles/MetaTags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MetaTags.d.ts","sourceRoot":"","sources":["../../src/handles/MetaTags.tsx"],"names":[],"mappings":"AAgKA;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,IAAI,KAAK,CAAC,SAAS,CAoB1C"}

package/dist/handles/MetaTags.js

@@ -0,0 +1,136 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Component to render collected meta descriptors in the document head.
+ *
+ * Supports both sync and async meta descriptors. Async descriptors
+ * (Promise<MetaDescriptorBase>) are resolved using React's use() hook.
+ *
+ * When theme is enabled in the router config, MetaTags also renders
+ * the theme initialization script to prevent FOUC (flash of unstyled content).
+ *
+ * @example
+ * ```tsx
+ * function RootLayout() {
+ *   return (
+ *     <html lang="en" suppressHydrationWarning>
+ *       <head>
+ *         <MetaTags />
+ *       </head>
+ *       <body>...</body>
+ *     </html>
+ *   );
+ * }
+ * ```
+ */
+import { use } from "react";
+import { useHandle } from "../browser/react/use-handle.js";
+import { Meta } from "./meta.js";
+import { getSSRThemeConfig } from "../theme/theme-context.js";
+import { generateThemeScript } from "../theme/theme-script.js";
+// Type guards for MetaDescriptorBase variants
+function hasCharSet(d) {
+    return "charSet" in d && d.charSet === "utf-8";
+}
+function hasTitle(d) {
+    return "title" in d && typeof d.title === "string";
+}
+function hasNameContent(d) {
+    return "name" in d && "content" in d &&
+        typeof d.name === "string" &&
+        typeof d.content === "string";
+}
+function hasPropertyContent(d) {
+    return "property" in d && "content" in d &&
+        typeof d.property === "string" &&
+        typeof d.content === "string";
+}
+function hasHttpEquivContent(d) {
+    return "httpEquiv" in d && "content" in d &&
+        typeof d.httpEquiv === "string" &&
+        typeof d.content === "string";
+}
+function hasScriptLdJson(d) {
+    return "script:ld+json" in d;
+}
+function hasTagName(d) {
+    return "tagName" in d && (d.tagName === "meta" || d.tagName === "link");
+}
+/**
+ * Check if a value is a Promise.
+ */
+function isPromise(value) {
+    return value !== null && typeof value === "object" && "then" in value;
+}
+/**
+ * Render a single meta descriptor as a React element.
+ */
+function renderMetaDescriptor(descriptor, index) {
+    // charset
+    if (hasCharSet(descriptor)) {
+        return _jsx("meta", { charSet: descriptor.charSet }, "charSet");
+    }
+    // title
+    if (hasTitle(descriptor)) {
+        return _jsx("title", { children: descriptor.title }, "title");
+    }
+    // name + content (description, viewport, etc.)
+    if (hasNameContent(descriptor)) {
+        return (_jsx("meta", { name: descriptor.name, content: descriptor.content }, `name-${descriptor.name}`));
+    }
+    // property + content (Open Graph, etc.)
+    if (hasPropertyContent(descriptor)) {
+        return (_jsx("meta", { property: descriptor.property, content: descriptor.content }, `property-${descriptor.property}`));
+    }
+    // http-equiv + content
+    if (hasHttpEquivContent(descriptor)) {
+        return (_jsx("meta", { httpEquiv: descriptor.httpEquiv, content: descriptor.content }, `httpEquiv-${descriptor.httpEquiv}`));
+    }
+    // JSON-LD structured data
+    if (hasScriptLdJson(descriptor)) {
+        const json = JSON.stringify(descriptor["script:ld+json"]);
+        return (_jsx("script", { type: "application/ld+json", dangerouslySetInnerHTML: { __html: json } }, `ld-json-${index}`));
+    }
+    // Custom tagName (meta or link with arbitrary attributes)
+    if (hasTagName(descriptor)) {
+        const { tagName, ...rest } = descriptor;
+        if (tagName === "link") {
+            return _jsx("link", { ...rest }, `link-${index}`);
+        }
+        if (tagName === "meta") {
+            return _jsx("meta", { ...rest }, `meta-${index}`);
+        }
+    }
+    // Fallback: treat as meta attributes
+    return _jsx("meta", { ...descriptor }, `meta-fallback-${index}`);
+}
+/**
+ * Wrapper component to resolve a Promise<MetaDescriptorBase> using use().
+ */
+function AsyncMetaTag({ promise, index }) {
+    const resolved = use(promise);
+    return renderMetaDescriptor(resolved, index);
+}
+/**
+ * Renders all collected meta descriptors from route handlers.
+ *
+ * Place this component inside the `<head>` element of your document.
+ * It will automatically update when meta descriptors change during navigation.
+ *
+ * When theme is enabled in router config, also renders the theme initialization
+ * script to prevent FOUC (flash of unstyled content).
+ *
+ * Async meta descriptors (Promise<MetaDescriptorBase>) are resolved using
+ * React's use() hook. RSC streaming handles the Promise resolution.
+ */
+export function MetaTags() {
+    const descriptors = useHandle(Meta);
+    const themeConfig = getSSRThemeConfig();
+    return (_jsxs(_Fragment, { children: [themeConfig && (_jsx("script", { dangerouslySetInnerHTML: { __html: generateThemeScript(themeConfig) } })), descriptors.map((descriptor, index) => {
+                if (isPromise(descriptor)) {
+                    return _jsx(AsyncMetaTag, { promise: descriptor, index: index }, `async-${index}`);
+                }
+                return renderMetaDescriptor(descriptor, index);
+            })] }));
+}
+//# sourceMappingURL=MetaTags.js.map

package/dist/handles/MetaTags.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MetaTags.js","sourceRoot":"","sources":["../../src/handles/MetaTags.tsx"],"names":[],"mappings":"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"}

package/dist/handles/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Built-in handles for rsc-router.
+ */
+export { Meta } from "./meta.ts";
+export { MetaTags } from "./MetaTags.tsx";
+//# sourceMappingURL=index.d.ts.map

package/dist/handles/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/handles/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/handles/index.js

@@ -0,0 +1,6 @@
+/**
+ * Built-in handles for rsc-router.
+ */
+export { Meta } from "./meta.ts";
+export { MetaTags } from "./MetaTags.tsx";
+//# sourceMappingURL=index.js.map

package/dist/handles/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/handles/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/handles/meta.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Built-in Meta handle for managing document metadata across route segments.
+ *
+ * Provides automatic deduplication: later routes override earlier ones
+ * for the same meta key (title, name, property, etc.)
+ *
+ * @example
+ * ```tsx
+ * // In route handler
+ * route("product/:id", (ctx) => {
+ *   const meta = ctx.use(Meta);
+ *   meta({ title: "Product Details" });
+ *   meta({ name: "description", content: "..." });
+ *   meta({ property: "og:title", content: "..." });
+ * });
+ *
+ * // In layout (renders the collected meta tags)
+ * function RootLayout() {
+ *   return (
+ *     <html>
+ *       <head>
+ *         <MetaTags />
+ *       </head>
+ *       ...
+ *     </html>
+ *   );
+ * }
+ * ```
+ */
+import { type Handle } from "../handle.js";
+import type { MetaDescriptor } from "../router/types.js";
+/**
+ * Built-in handle for managing document metadata.
+ *
+ * Use `ctx.use(Meta)` in route handlers to push meta descriptors.
+ * Use `<MetaTags />` component to render them in the document head.
+ */
+export declare const Meta: Handle<MetaDescriptor, MetaDescriptor[]>;
+//# sourceMappingURL=meta.d.ts.map

package/dist/handles/meta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta.d.ts","sourceRoot":"","sources":["../../src/handles/meta.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,cAAc,CAAC;AACzD,OAAO,KAAK,EACV,cAAc,EAGf,MAAM,oBAAoB,CAAC;AA0M5B;;;;;GAKG;AACH,eAAO,MAAM,IAAI,EAAE,MAAM,CAAC,cAAc,EAAE,cAAc,EAAE,CAGzD,CAAC"}