npm - @rangojs/router - Versions diffs - 0.0.0-experimental.0f44aca1 - Mend

@rangojs/router 0.0.0-experimental.0f44aca1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (305) hide show

package/AGENTS.md +5 -0
package/README.md +899 -0
package/dist/bin/rango.js +1601 -0
package/dist/vite/index.js +5214 -0
package/package.json +176 -0
package/skills/breadcrumbs/SKILL.md +250 -0
package/skills/cache-guide/SKILL.md +262 -0
package/skills/caching/SKILL.md +220 -0
package/skills/composability/SKILL.md +172 -0
package/skills/debug-manifest/SKILL.md +112 -0
package/skills/document-cache/SKILL.md +182 -0
package/skills/fonts/SKILL.md +167 -0
package/skills/hooks/SKILL.md +704 -0
package/skills/host-router/SKILL.md +218 -0
package/skills/intercept/SKILL.md +313 -0
package/skills/layout/SKILL.md +310 -0
package/skills/links/SKILL.md +239 -0
package/skills/loader/SKILL.md +596 -0
package/skills/middleware/SKILL.md +339 -0
package/skills/mime-routes/SKILL.md +128 -0
package/skills/parallel/SKILL.md +305 -0
package/skills/prerender/SKILL.md +643 -0
package/skills/rango/SKILL.md +118 -0
package/skills/response-routes/SKILL.md +411 -0
package/skills/route/SKILL.md +385 -0
package/skills/router-setup/SKILL.md +439 -0
package/skills/tailwind/SKILL.md +129 -0
package/skills/theme/SKILL.md +79 -0
package/skills/typesafety/SKILL.md +623 -0
package/skills/use-cache/SKILL.md +324 -0
package/src/__internal.ts +273 -0
package/src/bin/rango.ts +321 -0
package/src/browser/action-coordinator.ts +97 -0
package/src/browser/action-response-classifier.ts +99 -0
package/src/browser/event-controller.ts +899 -0
package/src/browser/history-state.ts +80 -0
package/src/browser/index.ts +18 -0
package/src/browser/intercept-utils.ts +52 -0
package/src/browser/link-interceptor.ts +141 -0
package/src/browser/logging.ts +55 -0
package/src/browser/merge-segment-loaders.ts +134 -0
package/src/browser/navigation-bridge.ts +645 -0
package/src/browser/navigation-client.ts +215 -0
package/src/browser/navigation-store.ts +806 -0
package/src/browser/navigation-transaction.ts +295 -0
package/src/browser/network-error-handler.ts +61 -0
package/src/browser/partial-update.ts +550 -0
package/src/browser/prefetch/cache.ts +146 -0
package/src/browser/prefetch/fetch.ts +135 -0
package/src/browser/prefetch/observer.ts +65 -0
package/src/browser/prefetch/policy.ts +42 -0
package/src/browser/prefetch/queue.ts +88 -0
package/src/browser/rango-state.ts +112 -0
package/src/browser/react/Link.tsx +360 -0
package/src/browser/react/NavigationProvider.tsx +386 -0
package/src/browser/react/ScrollRestoration.tsx +94 -0
package/src/browser/react/context.ts +59 -0
package/src/browser/react/filter-segment-order.ts +11 -0
package/src/browser/react/index.ts +52 -0
package/src/browser/react/location-state-shared.ts +162 -0
package/src/browser/react/location-state.ts +107 -0
package/src/browser/react/mount-context.ts +37 -0
package/src/browser/react/nonce-context.ts +23 -0
package/src/browser/react/shallow-equal.ts +27 -0
package/src/browser/react/use-action.ts +218 -0
package/src/browser/react/use-client-cache.ts +58 -0
package/src/browser/react/use-handle.ts +162 -0
package/src/browser/react/use-href.tsx +40 -0
package/src/browser/react/use-link-status.ts +135 -0
package/src/browser/react/use-mount.ts +31 -0
package/src/browser/react/use-navigation.ts +99 -0
package/src/browser/react/use-params.ts +65 -0
package/src/browser/react/use-pathname.ts +47 -0
package/src/browser/react/use-router.ts +63 -0
package/src/browser/react/use-search-params.ts +56 -0
package/src/browser/react/use-segments.ts +171 -0
package/src/browser/response-adapter.ts +73 -0
package/src/browser/rsc-router.tsx +431 -0
package/src/browser/scroll-restoration.ts +400 -0
package/src/browser/segment-reconciler.ts +216 -0
package/src/browser/segment-structure-assert.ts +83 -0
package/src/browser/server-action-bridge.ts +667 -0
package/src/browser/shallow.ts +40 -0
package/src/browser/types.ts +538 -0
package/src/browser/validate-redirect-origin.ts +29 -0
package/src/build/generate-manifest.ts +438 -0
package/src/build/generate-route-types.ts +36 -0
package/src/build/index.ts +35 -0
package/src/build/route-trie.ts +265 -0
package/src/build/route-types/ast-helpers.ts +25 -0
package/src/build/route-types/ast-route-extraction.ts +98 -0
package/src/build/route-types/codegen.ts +102 -0
package/src/build/route-types/include-resolution.ts +411 -0
package/src/build/route-types/param-extraction.ts +48 -0
package/src/build/route-types/per-module-writer.ts +128 -0
package/src/build/route-types/router-processing.ts +469 -0
package/src/build/route-types/scan-filter.ts +78 -0
package/src/build/runtime-discovery.ts +231 -0
package/src/cache/background-task.ts +34 -0
package/src/cache/cache-key-utils.ts +44 -0
package/src/cache/cache-policy.ts +125 -0
package/src/cache/cache-runtime.ts +338 -0
package/src/cache/cache-scope.ts +382 -0
package/src/cache/cf/cf-cache-store.ts +540 -0
package/src/cache/cf/index.ts +25 -0
package/src/cache/document-cache.ts +369 -0
package/src/cache/handle-capture.ts +81 -0
package/src/cache/handle-snapshot.ts +41 -0
package/src/cache/index.ts +43 -0
package/src/cache/memory-segment-store.ts +328 -0
package/src/cache/profile-registry.ts +73 -0
package/src/cache/read-through-swr.ts +134 -0
package/src/cache/segment-codec.ts +256 -0
package/src/cache/taint.ts +98 -0
package/src/cache/types.ts +342 -0
package/src/client.rsc.tsx +85 -0
package/src/client.tsx +601 -0
package/src/component-utils.ts +76 -0
package/src/components/DefaultDocument.tsx +27 -0
package/src/context-var.ts +86 -0
package/src/debug.ts +243 -0
package/src/default-error-boundary.tsx +88 -0
package/src/deps/browser.ts +8 -0
package/src/deps/html-stream-client.ts +2 -0
package/src/deps/html-stream-server.ts +2 -0
package/src/deps/rsc.ts +10 -0
package/src/deps/ssr.ts +2 -0
package/src/errors.ts +365 -0
package/src/handle.ts +135 -0
package/src/handles/MetaTags.tsx +246 -0
package/src/handles/breadcrumbs.ts +66 -0
package/src/handles/index.ts +7 -0
package/src/handles/meta.ts +264 -0
package/src/host/cookie-handler.ts +165 -0
package/src/host/errors.ts +97 -0
package/src/host/index.ts +53 -0
package/src/host/pattern-matcher.ts +214 -0
package/src/host/router.ts +352 -0
package/src/host/testing.ts +79 -0
package/src/host/types.ts +146 -0
package/src/host/utils.ts +25 -0
package/src/href-client.ts +222 -0
package/src/index.rsc.ts +233 -0
package/src/index.ts +277 -0
package/src/internal-debug.ts +11 -0
package/src/loader.rsc.ts +89 -0
package/src/loader.ts +64 -0
package/src/network-error-thrower.tsx +23 -0
package/src/outlet-context.ts +15 -0
package/src/outlet-provider.tsx +45 -0
package/src/prerender/param-hash.ts +37 -0
package/src/prerender/store.ts +185 -0
package/src/prerender.ts +463 -0
package/src/reverse.ts +330 -0
package/src/root-error-boundary.tsx +289 -0
package/src/route-content-wrapper.tsx +196 -0
package/src/route-definition/dsl-helpers.ts +934 -0
package/src/route-definition/helper-factories.ts +200 -0
package/src/route-definition/helpers-types.ts +430 -0
package/src/route-definition/index.ts +52 -0
package/src/route-definition/redirect.ts +93 -0
package/src/route-definition.ts +1 -0
package/src/route-map-builder.ts +275 -0
package/src/route-name.ts +53 -0
package/src/route-types.ts +259 -0
package/src/router/content-negotiation.ts +116 -0
package/src/router/debug-manifest.ts +72 -0
package/src/router/error-handling.ts +287 -0
package/src/router/find-match.ts +158 -0
package/src/router/handler-context.ts +451 -0
package/src/router/intercept-resolution.ts +395 -0
package/src/router/lazy-includes.ts +234 -0
package/src/router/loader-resolution.ts +420 -0
package/src/router/logging.ts +248 -0
package/src/router/manifest.ts +267 -0
package/src/router/match-api.ts +620 -0
package/src/router/match-context.ts +266 -0
package/src/router/match-handlers.ts +440 -0
package/src/router/match-middleware/background-revalidation.ts +223 -0
package/src/router/match-middleware/cache-lookup.ts +634 -0
package/src/router/match-middleware/cache-store.ts +295 -0
package/src/router/match-middleware/index.ts +81 -0
package/src/router/match-middleware/intercept-resolution.ts +306 -0
package/src/router/match-middleware/segment-resolution.ts +192 -0
package/src/router/match-pipelines.ts +179 -0
package/src/router/match-result.ts +219 -0
package/src/router/metrics.ts +282 -0
package/src/router/middleware-cookies.ts +55 -0
package/src/router/middleware-types.ts +222 -0
package/src/router/middleware.ts +748 -0
package/src/router/pattern-matching.ts +563 -0
package/src/router/prerender-match.ts +402 -0
package/src/router/preview-match.ts +170 -0
package/src/router/revalidation.ts +289 -0
package/src/router/router-context.ts +316 -0
package/src/router/router-interfaces.ts +452 -0
package/src/router/router-options.ts +592 -0
package/src/router/router-registry.ts +24 -0
package/src/router/segment-resolution/fresh.ts +570 -0
package/src/router/segment-resolution/helpers.ts +263 -0
package/src/router/segment-resolution/loader-cache.ts +198 -0
package/src/router/segment-resolution/revalidation.ts +1239 -0
package/src/router/segment-resolution/static-store.ts +67 -0
package/src/router/segment-resolution.ts +21 -0
package/src/router/segment-wrappers.ts +289 -0
package/src/router/telemetry-otel.ts +299 -0
package/src/router/telemetry.ts +300 -0
package/src/router/timeout.ts +148 -0
package/src/router/trie-matching.ts +239 -0
package/src/router/types.ts +170 -0
package/src/router.ts +1002 -0
package/src/rsc/handler-context.ts +45 -0
package/src/rsc/handler.ts +1089 -0
package/src/rsc/helpers.ts +198 -0
package/src/rsc/index.ts +36 -0
package/src/rsc/loader-fetch.ts +209 -0
package/src/rsc/manifest-init.ts +86 -0
package/src/rsc/nonce.ts +32 -0
package/src/rsc/origin-guard.ts +141 -0
package/src/rsc/progressive-enhancement.ts +379 -0
package/src/rsc/response-error.ts +37 -0
package/src/rsc/response-route-handler.ts +347 -0
package/src/rsc/rsc-rendering.ts +235 -0
package/src/rsc/runtime-warnings.ts +42 -0
package/src/rsc/server-action.ts +348 -0
package/src/rsc/ssr-setup.ts +128 -0
package/src/rsc/types.ts +263 -0
package/src/search-params.ts +230 -0
package/src/segment-system.tsx +454 -0
package/src/server/context.ts +591 -0
package/src/server/cookie-store.ts +190 -0
package/src/server/fetchable-loader-store.ts +37 -0
package/src/server/handle-store.ts +308 -0
package/src/server/loader-registry.ts +133 -0
package/src/server/request-context.ts +914 -0
package/src/server/root-layout.tsx +10 -0
package/src/server/tsconfig.json +14 -0
package/src/server.ts +51 -0
package/src/ssr/index.tsx +365 -0
package/src/static-handler.ts +114 -0
package/src/theme/ThemeProvider.tsx +297 -0
package/src/theme/ThemeScript.tsx +61 -0
package/src/theme/constants.ts +62 -0
package/src/theme/index.ts +48 -0
package/src/theme/theme-context.ts +44 -0
package/src/theme/theme-script.ts +155 -0
package/src/theme/types.ts +182 -0
package/src/theme/use-theme.ts +44 -0
package/src/types/boundaries.ts +158 -0
package/src/types/cache-types.ts +198 -0
package/src/types/error-types.ts +192 -0
package/src/types/global-namespace.ts +100 -0
package/src/types/handler-context.ts +687 -0
package/src/types/index.ts +88 -0
package/src/types/loader-types.ts +183 -0
package/src/types/route-config.ts +170 -0
package/src/types/route-entry.ts +102 -0
package/src/types/segments.ts +148 -0
package/src/types.ts +1 -0
package/src/urls/include-helper.ts +197 -0
package/src/urls/index.ts +53 -0
package/src/urls/path-helper-types.ts +339 -0
package/src/urls/path-helper.ts +329 -0
package/src/urls/pattern-types.ts +95 -0
package/src/urls/response-types.ts +106 -0
package/src/urls/type-extraction.ts +372 -0
package/src/urls/urls-function.ts +98 -0
package/src/urls.ts +1 -0
package/src/use-loader.tsx +354 -0
package/src/vite/discovery/bundle-postprocess.ts +184 -0
package/src/vite/discovery/discover-routers.ts +344 -0
package/src/vite/discovery/prerender-collection.ts +385 -0
package/src/vite/discovery/route-types-writer.ts +258 -0
package/src/vite/discovery/self-gen-tracking.ts +47 -0
package/src/vite/discovery/state.ts +110 -0
package/src/vite/discovery/virtual-module-codegen.ts +203 -0
package/src/vite/index.ts +16 -0
package/src/vite/plugin-types.ts +131 -0
package/src/vite/plugins/cjs-to-esm.ts +93 -0
package/src/vite/plugins/client-ref-dedup.ts +115 -0
package/src/vite/plugins/client-ref-hashing.ts +105 -0
package/src/vite/plugins/expose-action-id.ts +365 -0
package/src/vite/plugins/expose-id-utils.ts +287 -0
package/src/vite/plugins/expose-ids/export-analysis.ts +296 -0
package/src/vite/plugins/expose-ids/handler-transform.ts +179 -0
package/src/vite/plugins/expose-ids/loader-transform.ts +74 -0
package/src/vite/plugins/expose-ids/router-transform.ts +110 -0
package/src/vite/plugins/expose-ids/types.ts +45 -0
package/src/vite/plugins/expose-internal-ids.ts +569 -0
package/src/vite/plugins/refresh-cmd.ts +65 -0
package/src/vite/plugins/use-cache-transform.ts +323 -0
package/src/vite/plugins/version-injector.ts +83 -0
package/src/vite/plugins/version-plugin.ts +254 -0
package/src/vite/plugins/version.d.ts +12 -0
package/src/vite/plugins/virtual-entries.ts +123 -0
package/src/vite/plugins/virtual-stub-plugin.ts +29 -0
package/src/vite/rango.ts +510 -0
package/src/vite/router-discovery.ts +785 -0
package/src/vite/utils/ast-handler-extract.ts +517 -0
package/src/vite/utils/banner.ts +36 -0
package/src/vite/utils/bundle-analysis.ts +137 -0
package/src/vite/utils/manifest-utils.ts +70 -0
package/src/vite/utils/package-resolution.ts +121 -0
package/src/vite/utils/prerender-utils.ts +189 -0
package/src/vite/utils/shared-utils.ts +169 -0

package/src/handles/MetaTags.tsx ADDED Viewed

@@ -0,0 +1,246 @@
+"use client";
+/**
+ * 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 type { MetaDescriptor, MetaDescriptorBase } from "../router/types.js";
+import { useThemeContext } from "../theme/theme-context.js";
+import { generateThemeScript } from "../theme/theme-script.js";
+import { useNonce } from "../browser/react/nonce-context.js";
+// Type guards for MetaDescriptorBase variants
+function hasCharSet(d: MetaDescriptorBase): d is { charSet: "utf-8" } {
+  return "charSet" in d && d.charSet === "utf-8";
+}
+function hasTitle(d: MetaDescriptorBase): d is { title: string } {
+  return "title" in d && typeof (d as { title?: unknown }).title === "string";
+}
+function hasNameContent(
+  d: MetaDescriptorBase,
+): d is { name: string; content: string } {
+  return (
+    "name" in d &&
+    "content" in d &&
+    typeof (d as { name?: unknown }).name === "string" &&
+    typeof (d as { content?: unknown }).content === "string"
+  );
+}
+function hasPropertyContent(
+  d: MetaDescriptorBase,
+): d is { property: string; content: string } {
+  return (
+    "property" in d &&
+    "content" in d &&
+    typeof (d as { property?: unknown }).property === "string" &&
+    typeof (d as { content?: unknown }).content === "string"
+  );
+}
+function hasHttpEquivContent(
+  d: MetaDescriptorBase,
+): d is { httpEquiv: string; content: string } {
+  return (
+    "httpEquiv" in d &&
+    "content" in d &&
+    typeof (d as { httpEquiv?: unknown }).httpEquiv === "string" &&
+    typeof (d as { content?: unknown }).content === "string"
+  );
+}
+function hasScriptLdJson(
+  d: MetaDescriptorBase,
+): d is { "script:ld+json": object } {
+  return "script:ld+json" in d;
+}
+function hasTagName(
+  d: MetaDescriptorBase,
+): d is { tagName: "meta" | "link"; [name: string]: string } {
+  return (
+    "tagName" in d &&
+    ((d as { tagName?: unknown }).tagName === "meta" ||
+      (d as { tagName?: unknown }).tagName === "link")
+  );
+}
+/**
+ * Check if a value is a Promise.
+ */
+function isPromise(value: unknown): value is Promise<unknown> {
+  return value !== null && typeof value === "object" && "then" in value;
+}
+/**
+ * Render a single meta descriptor as a React element.
+ */
+function renderMetaDescriptor(
+  descriptor: MetaDescriptorBase,
+  index: number,
+): React.ReactNode {
+  // charset
+  if (hasCharSet(descriptor)) {
+    return <meta key="charSet" charSet={descriptor.charSet} />;
+  }
+  // title
+  if (hasTitle(descriptor)) {
+    return <title key="title">{descriptor.title}</title>;
+  }
+  // name + content (description, viewport, etc.)
+  if (hasNameContent(descriptor)) {
+    return (
+      <meta
+        key={`name-${descriptor.name}`}
+        name={descriptor.name}
+        content={descriptor.content}
+      />
+    );
+  }
+  // property + content (Open Graph, etc.)
+  if (hasPropertyContent(descriptor)) {
+    return (
+      <meta
+        key={`property-${descriptor.property}`}
+        property={descriptor.property}
+        content={descriptor.content}
+      />
+    );
+  }
+  // http-equiv + content
+  if (hasHttpEquivContent(descriptor)) {
+    return (
+      <meta
+        key={`httpEquiv-${descriptor.httpEquiv}`}
+        httpEquiv={descriptor.httpEquiv}
+        content={descriptor.content}
+      />
+    );
+  }
+  // JSON-LD structured data
+  if (hasScriptLdJson(descriptor)) {
+    const json = JSON.stringify(descriptor["script:ld+json"]);
+    return (
+      <script
+        key={`ld-json-${index}`}
+        type="application/ld+json"
+        dangerouslySetInnerHTML={{ __html: json }}
+      />
+    );
+  }
+  // Custom tagName (meta or link with arbitrary attributes)
+  if (hasTagName(descriptor)) {
+    const { tagName, ...rest } = descriptor;
+    if (tagName === "link") {
+      return (
+        <link
+          key={`link-${index}`}
+          {...(rest as React.LinkHTMLAttributes<HTMLLinkElement>)}
+        />
+      );
+    }
+    if (tagName === "meta") {
+      return (
+        <meta
+          key={`meta-${index}`}
+          {...(rest as React.MetaHTMLAttributes<HTMLMetaElement>)}
+        />
+      );
+    }
+  }
+  // Fallback: treat as meta attributes
+  return (
+    <meta
+      key={`meta-fallback-${index}`}
+      {...(descriptor as React.MetaHTMLAttributes<HTMLMetaElement>)}
+    />
+  );
+}
+/**
+ * Wrapper component to resolve a Promise<MetaDescriptorBase> using use().
+ */
+function AsyncMetaTag({
+  promise,
+  index,
+}: {
+  promise: Promise<MetaDescriptorBase>;
+  index: number;
+}): React.ReactNode {
+  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(): React.ReactNode {
+  const descriptors = useHandle(Meta) as MetaDescriptor[];
+  const themeConfig = useThemeContext()?.config ?? null;
+  const nonce = useNonce();
+  return (
+    <>
+      {/* Theme script must be first to prevent FOUC */}
+      {themeConfig && (
+        <script
+          nonce={nonce}
+          dangerouslySetInnerHTML={{ __html: generateThemeScript(themeConfig) }}
+        />
+      )}
+      {descriptors.map((descriptor, index) => {
+        if (isPromise(descriptor)) {
+          return (
+            <AsyncMetaTag
+              key={`async-${index}`}
+              promise={descriptor}
+              index={index}
+            />
+          );
+        }
+        return renderMetaDescriptor(descriptor, index);
+      })}
+    </>
+  );
+}

package/src/handles/breadcrumbs.ts ADDED Viewed

@@ -0,0 +1,66 @@
+/**
+ * Built-in Breadcrumbs handle for accumulating breadcrumb items across route segments.
+ *
+ * Each layout/route pushes breadcrumb items via `ctx.use(Breadcrumbs)`.
+ * Items are collected in parent-to-child order with automatic deduplication
+ * by `href` (last item for each href wins).
+ *
+ * @example
+ * ```tsx
+ * // In route handler
+ * route("/blog/:slug", (ctx) => {
+ *   const breadcrumb = ctx.use(Breadcrumbs);
+ *   breadcrumb({ label: "Blog", href: "/blog" });
+ *   breadcrumb({ label: post.title, href: `/blog/${ctx.params.slug}` });
+ * });
+ *
+ * // In client component (consume with useHandle)
+ * const crumbs = useHandle(Breadcrumbs);
+ * crumbs.map((c) => <a href={c.href}>{c.label}</a>);
+ * ```
+ */
+import type { ReactNode } from "react";
+import { createHandle, type Handle } from "../handle.js";
+/**
+ * A single breadcrumb item.
+ *
+ * @property label - Display text for the breadcrumb
+ * @property href - URL the breadcrumb links to
+ * @property content - Optional extra content (sync or async) rendered alongside the label
+ */
+export interface BreadcrumbItem {
+  label: string;
+  href: string;
+  content?: ReactNode | Promise<ReactNode>;
+}
+/**
+ * Collect function for Breadcrumbs handle.
+ * Flattens segments in parent-to-child order with deduplication by href
+ * (last item for each href wins).
+ */
+function collectBreadcrumbs(segments: BreadcrumbItem[][]): BreadcrumbItem[] {
+  const all = segments.flat();
+  const seen = new Map<string, number>();
+  for (let i = 0; i < all.length; i++) {
+    seen.set(all[i].href, i);
+  }
+  // Return items in order, keeping only the last occurrence per href
+  return all.filter((item, index) => seen.get(item.href) === index);
+}
+/**
+ * Built-in handle for accumulating breadcrumb navigation items.
+ *
+ * Use `ctx.use(Breadcrumbs)` in route handlers to push breadcrumb items.
+ * Use `useHandle(Breadcrumbs)` in client components to consume them.
+ */
+export const Breadcrumbs: Handle<BreadcrumbItem, BreadcrumbItem[]> =
+  createHandle<BreadcrumbItem, BreadcrumbItem[]>(
+    collectBreadcrumbs,
+    "__rsc_router_breadcrumbs__",
+  );

package/src/handles/index.ts ADDED Viewed

@@ -0,0 +1,7 @@
+/**
+ * Built-in handles for rsc-router.
+ */
+export { Meta } from "./meta.ts";
+export { MetaTags } from "./MetaTags.tsx";
+export { Breadcrumbs, type BreadcrumbItem } from "./breadcrumbs.ts";

package/src/handles/meta.ts ADDED Viewed

@@ -0,0 +1,264 @@
+/**
+ * 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 { createHandle, type Handle } from "../handle.js";
+import type {
+  MetaDescriptor,
+  TitleDescriptor,
+  UnsetDescriptor,
+} from "../router/types.js";
+/**
+ * Type guard for unset descriptor
+ */
+function isUnsetDescriptor(
+  descriptor: MetaDescriptor,
+): descriptor is UnsetDescriptor {
+  return (
+    typeof descriptor === "object" &&
+    descriptor !== null &&
+    "unset" in descriptor &&
+    typeof (descriptor as UnsetDescriptor).unset === "string"
+  );
+}
+/**
+ * Type guard for title descriptor (any form)
+ */
+function isTitleDescriptor(
+  descriptor: MetaDescriptor,
+): descriptor is { title: TitleDescriptor } {
+  return (
+    typeof descriptor === "object" &&
+    descriptor !== null &&
+    "title" in descriptor
+  );
+}
+/**
+ * Type guard for title template descriptor
+ */
+function isTitleTemplate(
+  title: TitleDescriptor,
+): title is { template: string; default: string } {
+  return (
+    typeof title === "object" &&
+    title !== null &&
+    "template" in title &&
+    "default" in title
+  );
+}
+/**
+ * Type guard for absolute title descriptor
+ */
+function isAbsoluteTitle(
+  title: TitleDescriptor,
+): title is { absolute: string } {
+  return typeof title === "object" && title !== null && "absolute" in title;
+}
+/**
+ * Get a unique key for a meta descriptor for deduplication.
+ * Returns undefined for descriptors that shouldn't be deduplicated.
+ */
+function getMetaKey(descriptor: MetaDescriptor): string | undefined {
+  // Skip unset descriptors - they are processed separately
+  if (isUnsetDescriptor(descriptor)) {
+    return undefined;
+  }
+  if ("charSet" in descriptor) {
+    return "charSet";
+  }
+  if ("title" in descriptor) {
+    return "title";
+  }
+  if ("name" in descriptor && "content" in descriptor) {
+    return `name:${descriptor.name}`;
+  }
+  if ("property" in descriptor && "content" in descriptor) {
+    return `property:${descriptor.property}`;
+  }
+  if ("httpEquiv" in descriptor && "content" in descriptor) {
+    return `httpEquiv:${descriptor.httpEquiv}`;
+  }
+  if ("script:ld+json" in descriptor) {
+    // JSON-LD scripts can have multiple, don't dedupe by default
+    return undefined;
+  }
+  if ("tagName" in descriptor) {
+    // For link tags, dedupe by rel if present
+    if (descriptor.tagName === "link" && "rel" in descriptor) {
+      // Some link rels should be unique (canonical), others not (stylesheet)
+      const uniqueRels = ["canonical", "icon", "apple-touch-icon"];
+      if (uniqueRels.includes(descriptor.rel as string)) {
+        return `link:${descriptor.rel}`;
+      }
+    }
+    return undefined;
+  }
+  return undefined;
+}
+/**
+ * Default meta descriptors included automatically.
+ * These can be overridden by route handlers.
+ */
+const defaultMetaDescriptors: MetaDescriptor[] = [
+  { charSet: "utf-8" },
+  { name: "viewport", content: "width=device-width, initial-scale=1" },
+];
+/**
+ * Helper to add or replace a descriptor in the result array
+ */
+function addOrReplace(
+  result: MetaDescriptor[],
+  keyToIndex: Map<string, number>,
+  descriptor: MetaDescriptor,
+  key: string | undefined,
+): void {
+  if (key !== undefined && keyToIndex.has(key)) {
+    result[keyToIndex.get(key)!] = descriptor;
+  } else {
+    if (key !== undefined) {
+      keyToIndex.set(key, result.length);
+    }
+    result.push(descriptor);
+  }
+}
+/**
+ * Helper to update indices after removing an element
+ */
+function updateIndicesAfterRemoval(
+  keyToIndex: Map<string, number>,
+  removedIndex: number,
+): void {
+  for (const [key, index] of keyToIndex) {
+    if (index > removedIndex) {
+      keyToIndex.set(key, index - 1);
+    }
+  }
+}
+/**
+ * Collect function for Meta handle.
+ * Includes default meta descriptors, then deduplicates by key with later routes overriding earlier ones.
+ * Supports title templates, absolute titles, and unset descriptors.
+ */
+function collectMeta(segments: MetaDescriptor[][]): MetaDescriptor[] {
+  const result: MetaDescriptor[] = [];
+  const keyToIndex = new Map<string, number>();
+  let titleTemplate: string | undefined;
+  // Add defaults first so they can be overridden
+  for (const descriptor of defaultMetaDescriptors) {
+    const key = getMetaKey(descriptor);
+    if (key !== undefined) {
+      keyToIndex.set(key, result.length);
+    }
+    result.push(descriptor);
+  }
+  for (const descriptors of segments) {
+    for (const descriptor of descriptors) {
+      // Handle unset descriptors
+      if (isUnsetDescriptor(descriptor)) {
+        const keyToRemove = descriptor.unset;
+        if (keyToIndex.has(keyToRemove)) {
+          const idx = keyToIndex.get(keyToRemove)!;
+          result.splice(idx, 1);
+          keyToIndex.delete(keyToRemove);
+          updateIndicesAfterRemoval(keyToIndex, idx);
+        }
+        continue;
+      }
+      // Handle title descriptors with template/absolute support
+      if (isTitleDescriptor(descriptor)) {
+        const titleValue = descriptor.title;
+        if (isTitleTemplate(titleValue)) {
+          // Store template for subsequent title descriptors in child segments
+          titleTemplate = titleValue.template;
+          // Set the default title
+          addOrReplace(
+            result,
+            keyToIndex,
+            { title: titleValue.default },
+            "title",
+          );
+          continue;
+        }
+        if (isAbsoluteTitle(titleValue)) {
+          // Absolute title bypasses any template
+          addOrReplace(
+            result,
+            keyToIndex,
+            { title: titleValue.absolute },
+            "title",
+          );
+          continue;
+        }
+        // String title - apply template if one exists
+        const finalTitle = titleTemplate
+          ? titleTemplate.replace("%s", titleValue as string)
+          : titleValue;
+        addOrReplace(
+          result,
+          keyToIndex,
+          { title: finalTitle as string },
+          "title",
+        );
+        continue;
+      }
+      // Handle all other descriptors
+      const key = getMetaKey(descriptor);
+      addOrReplace(result, keyToIndex, descriptor, key);
+    }
+  }
+  return result;
+}
+/**
+ * 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 const Meta: Handle<MetaDescriptor, MetaDescriptor[]> = createHandle<
+  MetaDescriptor,
+  MetaDescriptor[]
+>(collectMeta, "__rsc_router_meta__");