@real-router/vue 0.12.1 → 0.14.0

package/src/components/Link.ts

@@ -1,4 +1,4 @@
-import { createActiveRouteSource } from "@real-router/sources";
+import { canonicalJson, createActiveRouteSource } from "@real-router/sources";
 import { defineComponent, h, computed, shallowRef, watch } from "vue";
 
 import { useRouter } from "../composables/useRouter";
@@ -18,6 +18,13 @@ type OnClickHandler = (evt: MouseEvent) => void;
 /**
  * Vue's compiled template binds multiple `@click` handlers as an array.
  * Single render-function `onClick` is a function. Both must be invoked.
+ *
+ * The function-branch deliberately omits a `defaultPrevented` check: the
+ * single call short-circuits naturally and control returns to the caller
+ * (`handleClick`), which then re-reads `evt.defaultPrevented` on the same
+ * MouseEvent. The array-branch needs the per-iteration check because the
+ * caller cannot observe intermediate handlers — without it, later handlers
+ * would still run after an earlier one called `preventDefault()`.
  */
 function invokeAttributesOnClick(value: unknown, evt: MouseEvent): void {
   if (typeof value === "function") {
@@ -96,24 +103,37 @@ export const Link = defineComponent({
 
     const isActive = shallowRef(false);
 
-    // watch with an explicit dep getter recreates the source ONLY when
-    // routeName/routeParams/strict/ignoreQueryParams change — not on every
-    // reactive read inside the source factory (the watchEffect alternative
-    // would also re-subscribe whenever isActive itself changed).
+    // watch with an explicit dep getter recreates the source ONLY when the
+    // structural identity of routeName/routeParams/strict/ignoreQueryParams/
+    // hash changes — not on every parent rerender that hands a fresh
+    // `routeParams` literal with the same shape.
+    //
+    // Hot-path note: inline `:routeParams="{ id: 1 }"` in a parent template
+    // allocates a new object each render. Comparing by reference would
+    // tear down + recreate the ActiveRouteSource subscription on every
+    // unrelated parent state change. `canonicalJson(routeParams)` collapses
+    // structurally-equal objects to the same key-order-stable string, so the
+    // subscription persists across re-renders that don't change shape.
+    // (The source's own per-router cache uses the same canonical key under
+    // the hood — this watch dep just mirrors it at the consumer layer.)
     watch(
       () =>
         [
           props.routeName,
-          props.routeParams,
+          canonicalJson(props.routeParams),
           props.activeStrict,
           props.ignoreQueryParams,
           props.hash,
         ] as const,
       (
-        [routeName, routeParams, activeStrict, ignoreQueryParams, hash],
+        [routeName, _paramsKey, activeStrict, ignoreQueryParams, hash],
         _prev,
         onCleanup,
       ) => {
+        // Re-read the raw `routeParams` ref when constructing the source —
+        // canonicalJson was only used for change-detection above, the source
+        // factory still wants the live object.
+        const routeParams = props.routeParams;
         // Hash-aware active (#532): pass hash through so tab links with the
         // same routeName but different `hash` props don't all light up.
         const source = createActiveRouteSource(
@@ -182,13 +202,13 @@ export const Link = defineComponent({
       // double-invoke user handlers when combined with our explicit `onClick`.
       // We invoke the original attrs.onClick manually inside handleClick so the
       // preventDefault contract is preserved.
-      const restAttributes: Record<string, unknown> = {};
+      //
+      // Spread + delete avoids the per-key copy loop on every render — one
+      // allocation + one property deletion instead of N iterations across
+      // data-*, aria-*, role, etc. Hot-path optimisation for Link-heavy pages.
+      const restAttributes = { ...attrs };
 
-      for (const key of Object.keys(attrs)) {
-        if (key !== "onClick") {
-          restAttributes[key] = (attrs as Record<string, unknown>)[key];
-        }
-      }
+      delete restAttributes.onClick;
 
       return h(
         "a",

package/src/components/RouteView/RouteView.ts

@@ -8,7 +8,11 @@ import {
 } from "vue";
 
 import { Match, NotFound, Self } from "./components";
-import { buildRenderList, collectElements } from "./helpers";
+import {
+  buildRenderList,
+  collectElements,
+  isKeepAliveEnabled,
+} from "./helpers";
 import { useRouteNode } from "../../composables/useRouteNode";
 
 import type { Component, VNode } from "vue";
@@ -66,14 +70,23 @@ function wrapWithSuspense(content: VNode, fallback: unknown): VNode {
   );
 }
 
-const emptyKeepAlivePlaceholder = markRaw(
-  defineComponent({
-    name: "KeepAlive-placeholder",
-    render() {
-      return null;
-    },
-  }),
-);
+// Lazy-initialised — only allocated when a per-Match keepAlive path needs to
+// keep the cache slot "occupied" with a no-render placeholder. Apps without
+// keepAlive never pay the markRaw + defineComponent allocation at import.
+let emptyKeepAlivePlaceholderInstance: Component | null = null;
+
+function getEmptyKeepAlivePlaceholder(): Component {
+  emptyKeepAlivePlaceholderInstance ??= markRaw(
+    defineComponent({
+      name: "KeepAlive-placeholder",
+      render() {
+        return null;
+      },
+    }),
+  );
+
+  return emptyKeepAlivePlaceholderInstance;
+}
 
 function renderWithRootKA(
   activeChild: VNode,
@@ -92,17 +105,6 @@ function renderWithRootKA(
   return wrapWithSuspense(keepAliveContent, fallback);
 }
 
-// Vue compiles boolean-shorthand template attributes (`<Match keepAlive>`) to
-// an empty string instead of `true`, and converts them to `true` only when the
-// receiving component's prop is declared with `type: Boolean`. `Match` is a
-// marker component (`render: null`) — its props are inspected on the VNode
-// without ever going through Vue's prop-casting pipeline, so the raw `""` (or
-// the hyphenated attribute name) reaches us here. Accept the same trio Vue's
-// runtime does.
-function isKeepAliveEnabled(value: unknown): boolean {
-  return value === true || value === "" || value === "keep-alive";
-}
-
 function renderWithPerMatchKA(
   activeChild: VNode,
   wrapperCache: Map<string, Component>,
@@ -137,7 +139,9 @@ function renderWithPerMatchKA(
   /* v8 ignore stop */
 
   return h(Fragment, [
-    h(KeepAlive, null, { default: () => h(emptyKeepAlivePlaceholder) }),
+    h(KeepAlive, null, {
+      default: () => h(getEmptyKeepAlivePlaceholder()),
+    }),
     wrapWithSuspense(h(Fragment, content), fallback),
   ]);
 }
@@ -158,33 +162,6 @@ const RouteViewComponent = defineComponent({
     const routeContext = useRouteNode(props.nodeName);
     const wrapperCache = new Map<string, Component>();
 
-    // Cache per-Match `keepAlive` detection by slot output identity. Slot
-    // contents change reference only when the parent re-renders with new
-    // children, so steady-state navigations skip the O(n) `.some(...)` scan.
-    let lastSlotOutput: unknown = null;
-    let lastHasPerMatchKA = false;
-
-    function detectPerMatchKA(elements: VNode[], slotOutput: unknown): boolean {
-      /* v8 ignore next 3 -- @preserve: Vue's compiled slot wrapper allocates a
-         new array per render call in JSDOM tests; identity-cache hits in
-         production where parent compiled templates share slot output, but
-         is unobservable through TestBed-style assertions. */
-      if (slotOutput === lastSlotOutput) {
-        return lastHasPerMatchKA;
-      }
-
-      lastSlotOutput = slotOutput;
-      lastHasPerMatchKA = elements.some(
-        (element) =>
-          element.type === Match &&
-          isKeepAliveEnabled(
-            (element.props as { keepAlive?: unknown } | null)?.keepAlive,
-          ),
-      );
-
-      return lastHasPerMatchKA;
-    }
-
     return (): VNode | null => {
       const route = routeContext.route.value;
 
@@ -197,7 +174,11 @@ const RouteViewComponent = defineComponent({
 
       collectElements(slotOutput, elements);
 
-      const { rendered, fallback } = buildRenderList(
+      // `hasPerMatchKA` is a side-channel produced by the same pipeline pass
+      // that builds `rendered` — closes the audit §8.1 "double iteration"
+      // finding. The previous identity-cache on `slotOutput` is no longer
+      // needed: per-render cost is one O(n) walk instead of two.
+      const { rendered, fallback, hasPerMatchKA } = buildRenderList(
         elements,
         route.name,
         props.nodeName,
@@ -223,8 +204,6 @@ const RouteViewComponent = defineComponent({
       }
       /* v8 ignore stop */
 
-      const hasPerMatchKA = detectPerMatchKA(elements, slotOutput);
-
       if (hasPerMatchKA) {
         return renderWithPerMatchKA(activeChild, wrapperCache, fallback);
       }

package/src/components/RouteView/helpers.ts

@@ -14,7 +14,7 @@ interface FallbackSlots {
   notFoundChildren: unknown;
 }
 
-function isSegmentMatch(
+export function isSegmentMatch(
   routeName: string,
   fullSegmentName: string,
   exact: boolean,
@@ -26,6 +26,17 @@ function isSegmentMatch(
   return startsWithSegment(routeName, fullSegmentName);
 }
 
+// Vue compiles boolean-shorthand template attributes (`<Match keepAlive>`) to
+// an empty string instead of `true`, and converts them to `true` only when the
+// receiving component's prop is declared with `type: Boolean`. `Match` is a
+// marker component (`render: null`) — its props are inspected on the VNode
+// without ever going through Vue's prop-casting pipeline, so the raw `""` (or
+// the hyphenated attribute name) reaches us here. Accept the same trio Vue's
+// runtime does.
+export function isKeepAliveEnabled(value: unknown): boolean {
+  return value === true || value === "" || value === "keep-alive";
+}
+
 function normalizeChildren(children: unknown): VNode[] {
   if (Array.isArray(children)) {
     const result: VNode[] = [];
@@ -137,6 +148,14 @@ export function buildRenderList(
   rendered: VNode[];
   activeMatchFound: boolean;
   fallback?: FallbackType;
+  /**
+   * True iff any `<Match>` child in the input has its `keepAlive` prop set
+   * to one of Vue's accepted boolean-shorthand forms. Surfaced as a
+   * side-channel from the single pipeline pass so the caller doesn't have
+   * to re-iterate `elements` after `buildRenderList` returns — closes a MED
+   * code-quality finding (audit §8.1).
+   */
+  hasPerMatchKA: boolean;
 } {
   const slots: FallbackSlots = {
     selfVNode: null,
@@ -145,9 +164,21 @@ export function buildRenderList(
   };
   let activeMatchFound = false;
   let fallback: FallbackType = undefined;
+  let hasPerMatchKA = false;
   const rendered: VNode[] = [];
 
   for (const child of elements) {
+    // Match-only side-channel: scan for the keepAlive shorthand in the same
+    // pass that already inspects every child. Short-circuits once a positive
+    // is found to avoid redundant prop reads in big slot trees.
+    if (!hasPerMatchKA && child.type === Match) {
+      const matchProps = child.props as { keepAlive?: unknown } | null;
+
+      if (isKeepAliveEnabled(matchProps?.keepAlive)) {
+        hasPerMatchKA = true;
+      }
+    }
+
     if (recordFallback(child, slots)) {
       continue;
     }
@@ -169,5 +200,5 @@ export function buildRenderList(
     fallback = appendFallback(rendered, routeName, nodeName, slots, elements);
   }
 
-  return { rendered, activeMatchFound, fallback };
+  return { rendered, activeMatchFound, fallback, hasPerMatchKA };
 }

package/src/components/ServerOnly.ts

@@ -0,0 +1,16 @@
+import { defineComponent, onMounted, ref } from "vue";
+
+export const ServerOnly = defineComponent({
+  name: "ServerOnly",
+  setup(_, { slots }) {
+    const mounted = ref(false);
+
+    onMounted(() => {
+      mounted.value = true;
+    });
+
+    return () => (mounted.value ? slots.fallback?.() : slots.default?.());
+  },
+});
+
+export type ServerOnlyProps = InstanceType<typeof ServerOnly>["$props"];

package/src/components/Streamed.ts

@@ -0,0 +1,31 @@
+import { defineComponent, h, Suspense } from "vue";
+
+/**
+ * Cross-adapter alias for Vue's native `<Suspense>`. Symmetric naming with
+ * the React/Preact/Solid/Svelte/Angular `<Streamed>` components.
+ *
+ * Slots:
+ * - `default` — content (may contain `<Await>` or `async setup()` children).
+ * - `fallback` — shown while any descendant suspends.
+ *
+ * Vue's `<Suspense>` is **blocking** under SSR (no out-of-order placeholder
+ * resolution) — render of HTML after `<Streamed>` waits for every
+ * `async setup()` inside. This matches Vue 3's stable streaming behaviour
+ * (vs React 19 / Solid which support OOO resolution).
+ */
+export const Streamed = defineComponent({
+  name: "Streamed",
+  setup(_, { slots }) {
+    return () =>
+      h(
+        Suspense,
+        {},
+        {
+          default: () => slots.default?.(),
+          fallback: () => slots.fallback?.(),
+        },
+      );
+  },
+});
+
+export type StreamedProps = InstanceType<typeof Streamed>["$props"];

package/src/composables/useDeferred.ts

@@ -0,0 +1,37 @@
+import { useRoute } from "./useRoute";
+
+interface DeferredContext {
+  ssrDataDeferred?: Record<string, Promise<unknown>>;
+}
+
+const NEVER_PROMISE = new Promise<never>(() => {
+  // Intentionally never resolves — surfaces a forever-pending Suspense boundary
+  // when a key is requested that the loader never declared.
+});
+
+/**
+ * Read a deferred promise published by `defer({ deferred: { <key>: Promise } })`
+ * inside an SSR data loader. Returns the Promise for use inside `async setup()`
+ * (Vue's native Suspense pattern) or paired with `<Await name="key">`.
+ *
+ * ```ts
+ * // Vue async setup pattern
+ * export default defineComponent({
+ *   async setup() {
+ *     const reviews = await useDeferred<Review[]>("reviews");
+ *     return () => h("div", reviews.map(...));
+ *   },
+ * });
+ * ```
+ *
+ * Returns a forever-pending promise when the key is missing — surfaces
+ * loader/consumer key drift as a visible Suspense fallback rather than a
+ * silent runtime error.
+ */
+export function useDeferred<T = unknown>(key: string): Promise<T> {
+  const { route } = useRoute();
+  const context = route.value.context as DeferredContext;
+  const deferred = context.ssrDataDeferred;
+
+  return (deferred?.[key] ?? NEVER_PROMISE) as Promise<T>;
+}

package/src/composables/useIsActiveRoute.ts

@@ -6,14 +6,44 @@ import { useRouter } from "./useRouter";
 import type { Params } from "@real-router/core";
 import type { ShallowRef } from "vue";
 
+/**
+ * Options object for `useIsActiveRoute`. Replaces the previous trailing
+ * positional booleans (`strict`, `ignoreQueryParams`) — positional flags at
+ * call sites read as magic numbers and the order was easy to swap silently.
+ *
+ * The composable is `@internal` (consumed by `<Link>` and tests only), so
+ * the signature changes without a deprecation cycle.
+ */
+export interface UseIsActiveRouteOptions {
+  /**
+   * Match the route name exactly (no descendant match). Default: `false`.
+   */
+  strict?: boolean;
+  /**
+   * Ignore query params when comparing the active route. Default: `true`.
+   */
+  ignoreQueryParams?: boolean;
+  /**
+   * Hash-aware active state (#532) — when provided, the route is active only
+   * if `state.context.url.hash` equals this value. Default: `undefined`
+   * (hash is ignored).
+   */
+  hash?: string;
+}
+
+/**
+ * @internal Consumed by `<Link>` via `createActiveRouteSource`. Not exported
+ * from `@real-router/vue`.
+ */
 export function useIsActiveRoute(
   routeName: string,
   params?: Params,
-  strict = false,
-  ignoreQueryParams = true,
-  hash?: string,
+  options?: UseIsActiveRouteOptions,
 ): ShallowRef<boolean> {
   const router = useRouter();
+  const strict = options?.strict ?? false;
+  const ignoreQueryParams = options?.ignoreQueryParams ?? true;
+  const hash = options?.hash;
 
   // The `hash` argument (#532) participates in the cache key when defined.
   // exactOptionalPropertyTypes forbids `{ hash: undefined }` literally — we

package/src/composables/useRoute.ts

@@ -6,10 +6,18 @@ import type { RouteContext } from "../types";
 import type { Params, State } from "@real-router/core";
 import type { Ref } from "vue";
 
-export const useRoute = <P extends Params = Params>(): Omit<
+/**
+ * Return shape for `useRoute()` — `RouteContext<P>` with `route` narrowed
+ * to the non-nullable variant. The composable throws when `route.value`
+ * would be `undefined`, so consumers can read `.value.params.x` without a
+ * nullable guard. Extracted from inline duplication at two call sites.
+ */
+export type UseRouteReturn<P extends Params = Params> = Omit<
   RouteContext<P>,
   "route"
-> & { route: Readonly<Ref<State<P>>> } => {
+> & { route: Readonly<Ref<State<P>>> };
+
+export const useRoute = <P extends Params = Params>(): UseRouteReturn<P> => {
   const routeContext = inject(RouteKey);
 
   if (!routeContext) {
@@ -22,7 +30,5 @@ export const useRoute = <P extends Params = Params>(): Omit<
     );
   }
 
-  return routeContext as Omit<RouteContext<P>, "route"> & {
-    route: Readonly<Ref<State<P>>>;
-  };
+  return routeContext as UseRouteReturn<P>;
 };

package/src/context.ts

@@ -1,4 +1,5 @@
 import type { RouteContext as RouteContextType } from "./types";
+import type { HttpStatusSink } from "./utils/createHttpStatusSink";
 import type { Router, Navigator } from "@real-router/core";
 import type { InjectionKey } from "vue";
 
@@ -7,3 +8,6 @@ export const RouterKey: InjectionKey<Router> = Symbol("RouterKey");
 export const NavigatorKey: InjectionKey<Navigator> = Symbol("NavigatorKey");
 
 export const RouteKey: InjectionKey<RouteContextType> = Symbol("RouteKey");
+
+export const HTTP_STATUS_KEY: InjectionKey<HttpStatusSink> =
+  Symbol("HttpStatusSink");

package/src/directives/vLink.ts

@@ -42,7 +42,11 @@ export function pushDirectiveRouter(router: Router): () => void {
 /**
  * Backwards-compatible alias. Replaces the active router unconditionally and
  * does NOT participate in the stack — use {@link pushDirectiveRouter} from
- * provider code instead. Kept for tests and direct callers.
+ * provider code instead. Not exported from the package entry; retained for
+ * unit tests and rare standalone-directive setups (where v-link is mounted
+ * outside any RouterProvider).
+ *
+ * @internal
  */
 export function setDirectiveRouter(router: Router | null): void {
   if (router === null) {
@@ -174,6 +178,19 @@ export const vLink: Directive<HTMLElement, LinkDirectiveValue> = {
   },
 
   updated(element, binding) {
+    // Hot-path guard: Vue invokes `updated` on every parent re-render even
+    // when the directive's binding value reference has not changed. Without
+    // this short-circuit, every parent rerender (which is the common case on
+    // Link-heavy pages — any unrelated state change triggers the parent's
+    // render fn) would detach + reattach the click/keydown listeners.
+    // Comparing references is enough: when consumers pass a stable
+    // `LinkDirectiveValue` object (the recommended pattern, since Vue's
+    // template compiler hoists `v-link="{ name: 'home' }"` to a stable
+    // literal), this guard collapses the work to zero.
+    if (binding.value === binding.oldValue) {
+      return;
+    }
+
     const router = getDirectiveRouter();
 
     detachHandlers(element);

package/src/index.ts

@@ -34,7 +34,7 @@ export { RouterProvider } from "./RouterProvider";
 export { RouterKey, NavigatorKey, RouteKey } from "./context";
 
 // Types
-export type { LinkProps } from "./types";
+export type { RouteContext, LinkProps } from "./types";
 
 export type { RouterErrorBoundaryProps } from "./components/RouterErrorBoundary";
 
@@ -43,6 +43,7 @@ export type { LinkDirectiveValue } from "./directives/vLink";
 export type {
   RouteViewProps,
   RouteViewMatchProps,
+  RouteViewSelfProps,
   RouteViewNotFoundProps,
 } from "./components/RouteView";
 

package/src/ssr.ts

@@ -0,0 +1,39 @@
+// SSR-feature entry — Vue 3.3+
+//
+// Server-side and SSR-aware components/composables. Mirror of `@real-router/react/ssr`
+// — same exports, Vue-native idioms (defineComponent + h(), async setup()
+// for Await, native Suspense for Streamed).
+
+// Components
+export { ClientOnly } from "./components/ClientOnly";
+
+export { ServerOnly } from "./components/ServerOnly";
+
+export { Await } from "./components/Await";
+
+export { Streamed } from "./components/Streamed";
+
+export { HttpStatusCode } from "./components/HttpStatusCode";
+
+export { HttpStatusProvider } from "./components/HttpStatusProvider";
+
+// Composables
+export { useDeferred } from "./composables/useDeferred";
+
+// Utilities
+export { createHttpStatusSink } from "./utils/createHttpStatusSink";
+
+// Types
+export type { ClientOnlyProps } from "./components/ClientOnly";
+
+export type { ServerOnlyProps } from "./components/ServerOnly";
+
+export type { AwaitProps } from "./components/Await";
+
+export type { StreamedProps } from "./components/Streamed";
+
+export type { HttpStatusCodeProps } from "./components/HttpStatusCode";
+
+export type { HttpStatusProviderProps } from "./components/HttpStatusProvider";
+
+export type { HttpStatusSink } from "./utils/createHttpStatusSink";

package/src/types.ts

@@ -27,4 +27,14 @@ export interface LinkProps<P extends Params = Params> {
   activeStrict?: boolean;
   ignoreQueryParams?: boolean;
   target?: string;
+  /**
+   * URL fragment (#532). Decoded, no leading `#`. Tri-state:
+   * - `undefined` (default) — preserves current `state.context.url.hash` on click.
+   * - `""` — clears the hash.
+   * - `"value"` — sets the hash; click routes through `navigateWithHash`,
+   *   which auto-adds `force: true, hashChange: true` for same-route hash
+   *   transitions (bypasses core's SAME_STATES check).
+   * Active state is hash-aware when `hash` is set.
+   */
+  hash?: string;
 }

package/src/utils/createHttpStatusSink.ts

@@ -0,0 +1,31 @@
+/**
+ * Render-scoped HTTP status sink. Created per request on the server, passed to
+ * `<HttpStatusProvider :sink="...">`, and read after `renderToString` /
+ * `renderToWebStream` to apply the value to the HTTP response.
+ *
+ * Last write wins: if the rendered tree mounts more than one
+ * `<HttpStatusCode />`, the value reflects the last component that ran during
+ * the render pass.
+ *
+ * No-op on the client — `<HttpStatusCode />` reads the optional injected sink
+ * and skips the write when no provider is mounted, so the same component tree
+ * can be hydrated without changing behaviour.
+ *
+ * Constraints:
+ * - **Per-request only.** Don't share a sink across requests; the rendered
+ *   tree mutates `code` in place. Module-level singletons leak status
+ *   between concurrent requests.
+ * - **Don't `Object.freeze` the sink.** The component writes to `.code`;
+ *   freezing makes the assignment throw under ESM strict mode.
+ * - **Hydration symmetry:** mount `<HttpStatusProvider>` on both server and
+ *   client (with a throwaway client sink). Vue emits `<!--[-->` / `<!--]-->`
+ *   fragment markers around the provider's slot; an extra provider on one
+ *   side trips Vue with "Hydration completed but contains mismatches".
+ */
+export interface HttpStatusSink {
+  code: number | undefined;
+}
+
+export function createHttpStatusSink(): HttpStatusSink {
+  return { code: undefined };
+}