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

@rangojs/router 0.0.0-experimental.2

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 (155) hide show

package/CLAUDE.md +7 -0
package/README.md +19 -0
package/dist/vite/index.js +1298 -0
package/package.json +140 -0
package/skills/caching/SKILL.md +319 -0
package/skills/document-cache/SKILL.md +152 -0
package/skills/hooks/SKILL.md +359 -0
package/skills/intercept/SKILL.md +292 -0
package/skills/layout/SKILL.md +216 -0
package/skills/loader/SKILL.md +365 -0
package/skills/middleware/SKILL.md +442 -0
package/skills/parallel/SKILL.md +255 -0
package/skills/route/SKILL.md +141 -0
package/skills/router-setup/SKILL.md +403 -0
package/skills/theme/SKILL.md +54 -0
package/skills/typesafety/SKILL.md +352 -0
package/src/__mocks__/version.ts +6 -0
package/src/__tests__/component-utils.test.ts +76 -0
package/src/__tests__/route-definition.test.ts +63 -0
package/src/__tests__/urls.test.tsx +436 -0
package/src/browser/event-controller.ts +876 -0
package/src/browser/index.ts +18 -0
package/src/browser/link-interceptor.ts +121 -0
package/src/browser/lru-cache.ts +69 -0
package/src/browser/merge-segment-loaders.ts +126 -0
package/src/browser/navigation-bridge.ts +893 -0
package/src/browser/navigation-client.ts +162 -0
package/src/browser/navigation-store.ts +823 -0
package/src/browser/partial-update.ts +559 -0
package/src/browser/react/Link.tsx +248 -0
package/src/browser/react/NavigationProvider.tsx +275 -0
package/src/browser/react/ScrollRestoration.tsx +94 -0
package/src/browser/react/context.ts +53 -0
package/src/browser/react/index.ts +52 -0
package/src/browser/react/location-state-shared.ts +120 -0
package/src/browser/react/location-state.ts +62 -0
package/src/browser/react/use-action.ts +240 -0
package/src/browser/react/use-client-cache.ts +56 -0
package/src/browser/react/use-handle.ts +178 -0
package/src/browser/react/use-href.tsx +208 -0
package/src/browser/react/use-link-status.ts +134 -0
package/src/browser/react/use-navigation.ts +150 -0
package/src/browser/react/use-segments.ts +188 -0
package/src/browser/request-controller.ts +164 -0
package/src/browser/rsc-router.tsx +353 -0
package/src/browser/scroll-restoration.ts +324 -0
package/src/browser/server-action-bridge.ts +747 -0
package/src/browser/shallow.ts +35 -0
package/src/browser/types.ts +464 -0
package/src/cache/__tests__/document-cache.test.ts +522 -0
package/src/cache/__tests__/memory-segment-store.test.ts +487 -0
package/src/cache/__tests__/memory-store.test.ts +484 -0
package/src/cache/cache-scope.ts +565 -0
package/src/cache/cf/__tests__/cf-cache-store.test.ts +428 -0
package/src/cache/cf/cf-cache-store.ts +428 -0
package/src/cache/cf/index.ts +19 -0
package/src/cache/document-cache.ts +340 -0
package/src/cache/index.ts +58 -0
package/src/cache/memory-segment-store.ts +150 -0
package/src/cache/memory-store.ts +253 -0
package/src/cache/types.ts +387 -0
package/src/client.rsc.tsx +88 -0
package/src/client.tsx +621 -0
package/src/component-utils.ts +76 -0
package/src/components/DefaultDocument.tsx +23 -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 +259 -0
package/src/handle.ts +120 -0
package/src/handles/MetaTags.tsx +193 -0
package/src/handles/index.ts +6 -0
package/src/handles/meta.ts +247 -0
package/src/href-client.ts +128 -0
package/src/href-context.ts +33 -0
package/src/href.ts +177 -0
package/src/index.rsc.ts +79 -0
package/src/index.ts +87 -0
package/src/loader.rsc.ts +204 -0
package/src/loader.ts +47 -0
package/src/network-error-thrower.tsx +21 -0
package/src/outlet-context.ts +15 -0
package/src/root-error-boundary.tsx +277 -0
package/src/route-content-wrapper.tsx +198 -0
package/src/route-definition.ts +1371 -0
package/src/route-map-builder.ts +146 -0
package/src/route-types.ts +198 -0
package/src/route-utils.ts +89 -0
package/src/router/__tests__/match-context.test.ts +104 -0
package/src/router/__tests__/match-pipelines.test.ts +537 -0
package/src/router/__tests__/match-result.test.ts +566 -0
package/src/router/__tests__/on-error.test.ts +935 -0
package/src/router/__tests__/pattern-matching.test.ts +577 -0
package/src/router/error-handling.ts +287 -0
package/src/router/handler-context.ts +158 -0
package/src/router/loader-resolution.ts +326 -0
package/src/router/manifest.ts +138 -0
package/src/router/match-context.ts +264 -0
package/src/router/match-middleware/background-revalidation.ts +236 -0
package/src/router/match-middleware/cache-lookup.ts +261 -0
package/src/router/match-middleware/cache-store.ts +266 -0
package/src/router/match-middleware/index.ts +81 -0
package/src/router/match-middleware/intercept-resolution.ts +268 -0
package/src/router/match-middleware/segment-resolution.ts +174 -0
package/src/router/match-pipelines.ts +214 -0
package/src/router/match-result.ts +214 -0
package/src/router/metrics.ts +62 -0
package/src/router/middleware.test.ts +1355 -0
package/src/router/middleware.ts +748 -0
package/src/router/pattern-matching.ts +272 -0
package/src/router/revalidation.ts +190 -0
package/src/router/router-context.ts +299 -0
package/src/router/types.ts +96 -0
package/src/router.ts +3876 -0
package/src/rsc/__tests__/helpers.test.ts +175 -0
package/src/rsc/handler.ts +1060 -0
package/src/rsc/helpers.ts +64 -0
package/src/rsc/index.ts +56 -0
package/src/rsc/nonce.ts +18 -0
package/src/rsc/types.ts +237 -0
package/src/segment-system.tsx +456 -0
package/src/server/__tests__/request-context.test.ts +171 -0
package/src/server/context.ts +417 -0
package/src/server/handle-store.ts +230 -0
package/src/server/loader-registry.ts +174 -0
package/src/server/request-context.ts +554 -0
package/src/server/root-layout.tsx +10 -0
package/src/server/tsconfig.json +14 -0
package/src/server.ts +146 -0
package/src/ssr/__tests__/ssr-handler.test.tsx +188 -0
package/src/ssr/index.tsx +234 -0
package/src/theme/ThemeProvider.tsx +291 -0
package/src/theme/ThemeScript.tsx +61 -0
package/src/theme/__tests__/theme.test.ts +120 -0
package/src/theme/constants.ts +55 -0
package/src/theme/index.ts +58 -0
package/src/theme/theme-context.ts +70 -0
package/src/theme/theme-script.ts +152 -0
package/src/theme/types.ts +182 -0
package/src/theme/use-theme.ts +44 -0
package/src/types.ts +1561 -0
package/src/urls.ts +726 -0
package/src/use-loader.tsx +346 -0
package/src/vite/__tests__/expose-loader-id.test.ts +117 -0
package/src/vite/expose-action-id.ts +344 -0
package/src/vite/expose-handle-id.ts +209 -0
package/src/vite/expose-loader-id.ts +357 -0
package/src/vite/expose-location-state-id.ts +177 -0
package/src/vite/index.ts +787 -0
package/src/vite/package-resolution.ts +125 -0
package/src/vite/version.d.ts +12 -0
package/src/vite/virtual-entries.ts +109 -0

package/src/handles/MetaTags.tsx ADDED Viewed

@@ -0,0 +1,193 @@
+"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.ts";
+import { Meta } from "./meta.ts";
+import type { MetaDescriptor, MetaDescriptorBase } from "../router/types.ts";
+import { getSSRThemeConfig } from "../theme/theme-context.js";
+import { generateThemeScript } from "../theme/theme-script.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 = getSSRThemeConfig();
+  return (
+    <>
+      {/* Theme script must be first to prevent FOUC */}
+      {themeConfig && (
+        <script
+          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/index.ts ADDED Viewed

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

package/src/handles/meta.ts ADDED Viewed

@@ -0,0 +1,247 @@
+/**
+ * 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.ts";
+import type {
+  MetaDescriptor,
+  TitleDescriptor,
+  UnsetDescriptor,
+} from "../router/types.ts";
+/**
+ * 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__"
+);

package/src/href-client.ts ADDED Viewed

@@ -0,0 +1,128 @@
+/**
+ * Client-safe type-safe href function
+ *
+ * This is a compile-time only href that validates paths against registered routes.
+ * No runtime route map lookup - just an identity function with TypeScript validation.
+ *
+ * @example
+ * ```typescript
+ * import { href } from "rsc-router/client";
+ *
+ * href("/blog/my-post");           // ✓ matches /blog/:slug
+ * href("/shop/product/widget");    // ✓ matches /shop/product/:slug
+ * href("/invalid");                // ✗ TypeScript error
+ * ```
+ */
+import type { GetRegisteredRoutes } from "./types.js";
+/**
+ * Parse constraint values into a union type for paths
+ * "a|b|c" → "a" | "b" | "c"
+ */
+type ParseConstraintPath<T extends string> =
+  T extends `${infer First}|${infer Rest}`
+    ? First | ParseConstraintPath<Rest>
+    : T;
+/**
+ * Convert a route pattern to a template literal type
+ *
+ * Supports:
+ * - Static: /about → "/about"
+ * - Dynamic: /blog/:slug → `/blog/${string}`
+ * - Optional: /:locale?/blog → "/blog" | `/${string}/blog`
+ * - Constrained: /:locale(en|gb)/blog → "/en/blog" | "/gb/blog"
+ * - Optional + Constrained: /:locale(en|gb)?/blog → "/blog" | "/en/blog" | "/gb/blog"
+ *
+ * @example
+ * PatternToPath<"/blog/:slug"> = `/blog/${string}`
+ * PatternToPath<"/:locale?/blog"> = "/blog" | `/${string}/blog`
+ * PatternToPath<"/:locale(en|gb)/blog"> = "/en/blog" | "/gb/blog"
+ * PatternToPath<"/:locale(en|gb)?/blog"> = "/blog" | "/en/blog" | "/gb/blog"
+ */
+export type PatternToPath<T extends string> =
+  // Optional + constrained param in middle: /:param(a|b)?/rest
+  T extends `${infer Before}:${infer _Name}(${infer Constraint})?/${infer After}`
+    ? PatternToPath<`${Before}${After}`> | `${Before}${ParseConstraintPath<Constraint>}/${PatternToPath<After>}`
+  // Optional + constrained param at end: /path/:param(a|b)?
+  : T extends `${infer Before}:${infer _Name}(${infer Constraint})?`
+    ? Before | `${Before}${ParseConstraintPath<Constraint>}`
+  // Constrained param in middle: /:param(a|b)/rest
+  : T extends `${infer Before}:${infer _Name}(${infer Constraint})/${infer After}`
+    ? `${Before}${ParseConstraintPath<Constraint>}/${PatternToPath<After>}`
+  // Constrained param at end: /path/:param(a|b)
+  : T extends `${infer Before}:${infer _Name}(${infer Constraint})`
+    ? `${Before}${ParseConstraintPath<Constraint>}`
+  // Optional param in middle: /:param?/rest
+  : T extends `${infer Before}:${infer _Param}?/${infer After}`
+    ? PatternToPath<`${Before}${After}`> | `${Before}${string}/${PatternToPath<After>}`
+  // Optional param at end: /path/:param?
+  : T extends `${infer Before}:${infer _Param}?`
+    ? Before | `${Before}${string}`
+  // Required param in middle: /:param/rest
+  : T extends `${infer Before}:${infer _Param}/${infer After}`
+    ? `${Before}${string}/${PatternToPath<After>}`
+  // Required param at end: /path/:param
+  : T extends `${infer Before}:${infer _Param}`
+    ? `${Before}${string}`
+  // Static path
+  : T;
+/**
+ * Allow optional query string (?...) and/or hash fragment (#...) suffix
+ *
+ * @example
+ * WithSuffix<"/about"> = "/about" | "/about?..." | "/about#..." | "/about?...#..."
+ */
+type WithSuffix<T extends string> =
+  | T
+  | `${T}?${string}`
+  | `${T}#${string}`
+  | `${T}?${string}#${string}`;
+/**
+ * Union of all valid paths from registered routes
+ *
+ * Generated from RSCRouter.RegisteredRoutes via module augmentation.
+ * Allows optional query strings and hash fragments.
+ */
+export type ValidPaths<TRoutes extends Record<string, string> = GetRegisteredRoutes> =
+  WithSuffix<PatternToPath<TRoutes[keyof TRoutes]>>;
+/**
+ * Type-safe href function for client-side use
+ *
+ * This is an identity function - it returns the path unchanged.
+ * The value is in TypeScript validation: invalid paths cause compile errors.
+ *
+ * Works with:
+ * - Static paths: href("/about")
+ * - Dynamic segments: href("/blog/my-post")
+ * - Multiple segments: href("/shop/product/widget/reviews/123")
+ *
+ * Does NOT validate:
+ * - Query strings (passed through as-is)
+ * - Hash fragments (passed through as-is)
+ *
+ * @param path - A valid path matching one of the registered route patterns
+ * @returns The path unchanged
+ *
+ * @example
+ * ```typescript
+ * // Valid paths (compile)
+ * href("/blog/hello");                    // matches /blog/:slug
+ * href("/shop/product/widget");           // matches /shop/product/:slug
+ * href("/shop/product/widget/reviews");   // matches /shop/product/:slug/reviews
+ *
+ * // Query strings and hashes pass through (not validated)
+ * href("/blog/hello?page=1");
+ * href("/about#contact");
+ *
+ * // Invalid paths (TypeScript error)
+ * href("/nonexistent");  // Error: not assignable to ValidPaths
+ * ```
+ */
+export function href<T extends ValidPaths>(path: T): T {
+  return path;
+}

package/src/href-context.ts ADDED Viewed

@@ -0,0 +1,33 @@
+"use client";
+/**
+ * Href Context for route name resolution
+ *
+ * This module is marked "use client" so it can be imported by both:
+ * - Server (segment-system): Gets a client reference for createElement
+ * - Client (useHref): Uses the actual context for useContext
+ *
+ * The context stores:
+ * - routeMap: Map of route names to URL patterns
+ * - routeName: Current matched route name (for local name resolution)
+ */
+import { createContext, type Context } from "react";
+/**
+ * Context value for href resolution
+ */
+export interface HrefContextValue {
+  /** Route map: route name -> URL pattern */
+  routeMap: Record<string, string>;
+  /** Current matched route name (includes name prefix from include()) */
+  routeName?: string;
+}
+/**
+ * Context for href resolution (route map and current route name)
+ *
+ * On the server: Populated by renderSegments() via HrefContext.Provider
+ * On the client: Populated by NavigationProvider from RSC metadata
+ */
+export const HrefContext: Context<HrefContextValue | null> =
+  createContext<HrefContextValue | null>(null);