@real-router/solid 0.6.0 → 0.8.0

package/dist/types/dom-utils/index.d.ts

@@ -1,6 +1,10 @@
+export { createDirectionTracker } from "./direction-tracker.js";
 export { createRouteAnnouncer } from "./route-announcer.js";
 export { createScrollRestoration } from "./scroll-restore.js";
+export { createViewTransitions } from "./view-transitions.js";
 export { shouldNavigate, buildHref, buildActiveClassName, shallowEqual, applyLinkA11y, } from "./link-utils.js";
 export type { RouteAnnouncerOptions } from "./route-announcer.js";
 export type { ScrollRestorationOptions, ScrollRestorationMode, } from "./scroll-restore.js";
+export type { DirectionTracker } from "./direction-tracker.js";
+export type { ViewTransitions } from "./view-transitions.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/types/dom-utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/dom-utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAE5D,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAE9D,OAAO,EACL,cAAc,EACd,SAAS,EACT,oBAAoB,EACpB,YAAY,EACZ,aAAa,GACd,MAAM,iBAAiB,CAAC;AAEzB,YAAY,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAElE,YAAY,EACV,wBAAwB,EACxB,qBAAqB,GACtB,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/dom-utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAEhE,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAE5D,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAE9D,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAE9D,OAAO,EACL,cAAc,EACd,SAAS,EACT,oBAAoB,EACpB,YAAY,EACZ,aAAa,GACd,MAAM,iBAAiB,CAAC;AAEzB,YAAY,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAElE,YAAY,EACV,wBAAwB,EACxB,qBAAqB,GACtB,MAAM,qBAAqB,CAAC;AAE7B,YAAY,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE/D,YAAY,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/types/dom-utils/view-transitions.d.ts

@@ -0,0 +1,6 @@
+import type { Router } from "@real-router/core";
+export interface ViewTransitions {
+    destroy: () => void;
+}
+export declare function createViewTransitions(router: Router): ViewTransitions;
+//# sourceMappingURL=view-transitions.d.ts.map

package/dist/types/dom-utils/view-transitions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"view-transitions.d.ts","sourceRoot":"","sources":["../../../src/dom-utils/view-transitions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAEhD,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAQD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,CAiIrE"}

package/dist/types/hooks/useRouteEnter.d.ts

@@ -0,0 +1,76 @@
+import type { State } from "@real-router/core";
+export interface RouteEnterContext {
+    /** The route that was just activated. */
+    route: State;
+    /** The route that was active immediately before this navigation. */
+    previousRoute: State;
+}
+export type RouteEnterHandler = (context: RouteEnterContext) => void;
+export interface UseRouteEnterOptions {
+    /**
+     * Skip the handler when `route.name === previousRoute.name`
+     * (sort/filter/query-only navigations on the same route). Default:
+     * `true`. Symmetric with `useRouteExit`'s same-name option.
+     */
+    skipSameRoute?: boolean;
+}
+/**
+ * Fire `handler` once when the component mounts as a result of a
+ * navigation. Mirror of `useRouteExit` for the entry side.
+ *
+ * What this hook covers that an ad-hoc `createEffect` + `useRoute()`
+ * doesn't:
+ *
+ *   - **Skip-initial**: handler is skipped when there is no
+ *     `transition.from` (i.e. first-load mount). Most consumers want to
+ *     fire side effects only on real navigations, not on hydration.
+ *   - **Same-route skip** (default): handler is skipped when
+ *     `route.transition.from === route.name`. Sort/filter/query-only
+ *     navigations re-trigger the effect (because the `route` reference
+ *     changes), but they are not "entries" in the animation / analytics
+ *     sense — the component instance has stayed mounted throughout.
+ *     Opt out with `skipSameRoute: false`.
+ *   - **Mount-time `route` / `previousRoute` snapshot**: the handler
+ *     receives the values that were live at the moment of effect
+ *     activation, not the latest ones (which may have moved on if the
+ *     user navigated again before the effect drained).
+ *
+ * **Handler reactivity (Solid)**: Solid components run **once** at mount;
+ * `handler` is captured in closure when the hook is called. If you need
+ * different behavior across renders, derive it from a signal inside the
+ * handler body — do not rely on swapping the handler reference.
+ *
+ * @example Direction-aware entry animation
+ * ```tsx
+ * useRouteEnter(({ route }) => {
+ *   const direction = route.context.browser?.direction;
+ *   ref?.classList.add(
+ *     direction === "back" ? "slide-from-left" : "slide-from-right",
+ *   );
+ * });
+ * ```
+ *
+ * @example Analytics page-enter event (skip-initial built-in)
+ * ```tsx
+ * useRouteEnter(({ route, previousRoute }) => {
+ *   analytics.track("page_enter", {
+ *     route: route.name,
+ *     from: previousRoute.name,
+ *   });
+ * });
+ * ```
+ *
+ * @example Reading rich transition metadata via `route.transition`
+ * ```tsx
+ * useRouteEnter(({ route }) => {
+ *   if (route.transition.redirected) {
+ *     showToast(`Redirected from ${route.transition.from}`);
+ *   }
+ *   if (route.transition.segments.activated.includes("products")) {
+ *     // products subtree just became active
+ *   }
+ * });
+ * ```
+ */
+export declare function useRouteEnter(handler: RouteEnterHandler, options?: UseRouteEnterOptions): void;
+//# sourceMappingURL=useRouteEnter.d.ts.map

package/dist/types/hooks/useRouteEnter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useRouteEnter.d.ts","sourceRoot":"","sources":["../../../src/hooks/useRouteEnter.tsx"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAE/C,MAAM,WAAW,iBAAiB;IAChC,yCAAyC;IACzC,KAAK,EAAE,KAAK,CAAC;IACb,oEAAoE;IACpE,aAAa,EAAE,KAAK,CAAC;CACtB;AAED,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,EAAE,iBAAiB,KAAK,IAAI,CAAC;AAErE,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,iBAAiB,EAC1B,OAAO,CAAC,EAAE,oBAAoB,GAC7B,IAAI,CA2CN"}

package/dist/types/hooks/useRouteExit.d.ts

@@ -0,0 +1,90 @@
+import type { State } from "@real-router/core";
+export interface RouteExitContext {
+    /** The route being left. */
+    route: State;
+    /** The route being navigated to. */
+    nextRoute: State;
+    /**
+     * AbortSignal that fires when this navigation is superseded by a later
+     * one (rapid clicks). Already filtered: when the handler runs,
+     * `signal.aborted` is guaranteed to be `false`. Use
+     * `signal.addEventListener("abort", cleanup, { once: true })` for
+     * cleanup that must run on cancellation.
+     */
+    signal: AbortSignal;
+}
+export interface UseRouteExitOptions {
+    /**
+     * Skip the handler when `route.name === nextRoute.name`
+     * (sort/filter/query-only navigations on the same route). Default:
+     * `true`.
+     */
+    skipSameRoute?: boolean;
+}
+export type RouteExitHandler = (context: RouteExitContext) => void | Promise<void>;
+/**
+ * Subscribe to the router's leave-window with the universal guards baked
+ * in. Wraps `router.subscribeLeave` so consumers don't repeat the same
+ * boilerplate every time:
+ *
+ *   - **Reentrant abort pre-check**: if `signal.aborted` is already `true`
+ *     when the handler would run (rapid navigation superseded a slower
+ *     one), the handler is skipped entirely. `signal.addEventListener(
+ *     "abort", ...)` does not fire retroactively, so without this guard
+ *     downstream cleanup would never trigger.
+ *   - **Same-route skip**: by default, `route.name === nextRoute.name`
+ *     short-circuits the handler — query-only navigations (sort, filter,
+ *     pagination) skip the work. Opt out with `skipSameRoute: false`.
+ *
+ * Returns nothing — the subscription's lifecycle is bound to the
+ * component via `onCleanup`.
+ *
+ * If the handler returns a Promise, the router blocks on it. If the
+ * Promise resolves, navigation proceeds. If it rejects, the router emits
+ * `TRANSITION_CANCELLED`.
+ *
+ * **Handler reactivity (Solid)**: Solid components run **once** at mount;
+ * `handler` is captured in closure at the call site. If you need
+ * different behavior across renders, derive it from a signal inside the
+ * handler body — do not rely on swapping the handler reference.
+ *
+ * @example Animation
+ * ```tsx
+ * let ref: HTMLDivElement | undefined;
+ *
+ * useRouteExit(async ({ signal }) => {
+ *   const el = ref;
+ *   if (!el) return;
+ *   el.classList.add("fade-out");
+ *   const cleanup = () => el.classList.remove("fade-out");
+ *   signal.addEventListener("abort", cleanup, { once: true });
+ *   try {
+ *     el.getBoundingClientRect();   // style flush
+ *     await Promise.allSettled(el.getAnimations().map((a) => a.finished));
+ *   } finally {
+ *     cleanup();
+ *   }
+ * });
+ * ```
+ *
+ * @example Auto-save form draft
+ * ```tsx
+ * useRouteExit(async ({ signal }) => {
+ *   if (formState.dirty) await api.saveDraft(formState, { signal });
+ * });
+ * ```
+ *
+ * @example Reading rich transition metadata via `nextRoute.transition`
+ * ```tsx
+ * useRouteExit(({ route, nextRoute }) => {
+ *   if (nextRoute.transition.segments.deactivated.includes("products")) {
+ *     productCache.clear();
+ *   }
+ *   if (nextRoute.transition.redirected) {
+ *     return;
+ *   }
+ * });
+ * ```
+ */
+export declare function useRouteExit(handler: RouteExitHandler, options?: UseRouteExitOptions): void;
+//# sourceMappingURL=useRouteExit.d.ts.map

package/dist/types/hooks/useRouteExit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useRouteExit.d.ts","sourceRoot":"","sources":["../../../src/hooks/useRouteExit.tsx"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAE/C,MAAM,WAAW,gBAAgB;IAC/B,4BAA4B;IAC5B,KAAK,EAAE,KAAK,CAAC;IACb,oCAAoC;IACpC,SAAS,EAAE,KAAK,CAAC;IACjB;;;;;;OAMG;IACH,MAAM,EAAE,WAAW,CAAC;CACrB;AAED,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,MAAM,gBAAgB,GAAG,CAC7B,OAAO,EAAE,gBAAgB,KACtB,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,gBAAgB,EACzB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,IAAI,CAqBN"}

package/dist/types/index.d.ts

@@ -10,6 +10,8 @@ export { useRouteNode } from "./hooks/useRouteNode";
 export { useRouteStore } from "./hooks/useRouteStore";
 export { useRouteNodeStore } from "./hooks/useRouteNodeStore";
 export { useRouterTransition } from "./hooks/useRouterTransition";
+export { useRouteExit } from "./hooks/useRouteExit";
+export { useRouteEnter } from "./hooks/useRouteEnter";
 export { RouterProvider } from "./RouterProvider";
 export { RouterContext, RouteContext } from "./context";
 export { createSignalFromSource } from "./createSignalFromSource";
@@ -17,7 +19,9 @@ export { createStoreFromSource } from "./createStoreFromSource";
 export type { LinkProps, RouteState } from "./types";
 export type { RouterErrorBoundaryProps } from "./components/RouterErrorBoundary";
 export type { LinkDirectiveOptions } from "./directives/link";
-export type { RouteViewProps, RouteViewMatchProps, RouteViewNotFoundProps, } from "./components/RouteView";
+export type { RouteViewProps, RouteViewMatchProps, RouteViewSelfProps, RouteViewNotFoundProps, } from "./components/RouteView";
+export type { RouteExitContext, RouteExitHandler, UseRouteExitOptions, } from "./hooks/useRouteExit";
+export type { RouteEnterContext, RouteEnterHandler, UseRouteEnterOptions, } from "./hooks/useRouteEnter";
 export type { Navigator } from "@real-router/core";
 export type { RouterTransitionSnapshot } from "@real-router/sources";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAEnD,OAAO,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAEzC,OAAO,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AAEvE,OAAO,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAEzC,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAE9C,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEpD,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAEtD,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE5C,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEpD,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAEtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAE9D,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAElE,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAExD,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAElE,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAEhE,YAAY,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAErD,YAAY,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAEjF,YAAY,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAE9D,YAAY,EACV,cAAc,EACd,mBAAmB,EACnB,sBAAsB,GACvB,MAAM,wBAAwB,CAAC;AAEhC,YAAY,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAEnD,YAAY,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAEnD,OAAO,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAEzC,OAAO,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AAEvE,OAAO,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAEzC,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAE9C,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEpD,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAEtD,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE5C,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEpD,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAEtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAE9D,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAElE,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEpD,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAEtD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAExD,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAElE,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAEhE,YAAY,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAErD,YAAY,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAEjF,YAAY,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAE9D,YAAY,EACV,cAAc,EACd,mBAAmB,EACnB,kBAAkB,EAClB,sBAAsB,GACvB,MAAM,wBAAwB,CAAC;AAEhC,YAAY,EACV,gBAAgB,EAChB,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,sBAAsB,CAAC;AAE9B,YAAY,EACV,iBAAiB,EACjB,iBAAiB,EACjB,oBAAoB,GACrB,MAAM,uBAAuB,CAAC;AAE/B,YAAY,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAEnD,YAAY,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@real-router/solid",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "type": "commonjs",
   "description": "Solid.js integration for Real-Router",
   "main": "./dist/cjs/index.js",
@@ -51,7 +51,7 @@
   "license": "MIT",
   "sideEffects": false,
   "dependencies": {
-    "@real-router/core": "^0.50.0",
+    "@real-router/core": "^0.50.2",
     "@real-router/route-utils": "^0.2.1",
     "@real-router/sources": "^0.7.2"
   },
@@ -71,7 +71,7 @@
     "solid-js": "1.9.12",
     "vite-plugin-solid": "2.11.11",
     "vitest": "4.1.0",
-    "@real-router/browser-plugin": "^0.14.0"
+    "@real-router/browser-plugin": "^0.16.0"
   },
   "peerDependencies": {
     "solid-js": ">=1.7.0"

package/src/RouterProvider.tsx

@@ -4,7 +4,11 @@ import { createSelector, onCleanup, onMount } from "solid-js";
 
 import { RouterContext, RouteContext } from "./context";
 import { createSignalFromSource } from "./createSignalFromSource";
-import { createRouteAnnouncer, createScrollRestoration } from "./dom-utils";
+import {
+  createRouteAnnouncer,
+  createScrollRestoration,
+  createViewTransitions,
+} from "./dom-utils";
 
 import type { ScrollRestorationOptions } from "./dom-utils";
 import type { Router } from "@real-router/core";
@@ -14,6 +18,7 @@ export interface RouteProviderProps {
   router: Router;
   announceNavigation?: boolean;
   scrollRestoration?: ScrollRestorationOptions;
+  viewTransitions?: boolean;
 }
 
 export function isRouteActive(
@@ -53,6 +58,18 @@ export function RouterProvider(
     });
   });
 
+  onMount(() => {
+    if (!props.viewTransitions) {
+      return;
+    }
+
+    const vt = createViewTransitions(props.router);
+
+    onCleanup(() => {
+      vt.destroy();
+    });
+  });
+
   const navigator = getNavigator(props.router);
   const routeSource = createRouteSource(props.router);
   const routeSignal = createSignalFromSource(routeSource);

package/src/components/RouteView/RouteView.tsx

@@ -1,6 +1,6 @@
 import { children as resolveChildren, createMemo } from "solid-js";
 
-import { Match, NotFound } from "./components";
+import { Match, NotFound, Self } from "./components";
 import { buildRenderList, collectElements } from "./helpers";
 import { useRouteNode } from "../../hooks/useRouteNode";
 
@@ -44,10 +44,15 @@ function RouteViewRoot(props: Readonly<RouteViewProps>): JSX.Element {
 
 RouteViewRoot.displayName = "RouteView";
 
-export const RouteView = Object.assign(RouteViewRoot, { Match, NotFound });
+export const RouteView = Object.assign(RouteViewRoot, {
+  Match,
+  Self,
+  NotFound,
+});
 
 export type {
   RouteViewProps,
   MatchProps as RouteViewMatchProps,
+  SelfProps as RouteViewSelfProps,
   NotFoundProps as RouteViewNotFoundProps,
 } from "./types";

package/src/components/RouteView/components.tsx

@@ -1,10 +1,12 @@
-import type { MatchProps, NotFoundProps } from "./types";
+import type { MatchProps, NotFoundProps, SelfProps } from "./types";
 import type { JSX } from "solid-js";
 
 // Local (non-global) Symbols — Symbol.for() would expose markers to spoofing
 // via the global Symbol registry. See Gotchas section "RouteView Marker Objects".
 export const MATCH_MARKER = Symbol("RouteView.Match");
 
+export const SELF_MARKER = Symbol("RouteView.Self");
+
 export const NOT_FOUND_MARKER = Symbol("RouteView.NotFound");
 
 export interface MatchMarker {
@@ -15,12 +17,18 @@ export interface MatchMarker {
   children: JSX.Element;
 }
 
+export interface SelfMarker {
+  $$type: typeof SELF_MARKER;
+  fallback?: JSX.Element;
+  children: JSX.Element;
+}
+
 export interface NotFoundMarker {
   $$type: typeof NOT_FOUND_MARKER;
   children: JSX.Element;
 }
 
-export type RouteViewMarker = MatchMarker | NotFoundMarker;
+export type RouteViewMarker = MatchMarker | SelfMarker | NotFoundMarker;
 
 export function Match(props: MatchProps): JSX.Element {
   const result: MatchMarker = {
@@ -41,6 +49,21 @@ export function Match(props: MatchProps): JSX.Element {
 
 Match.displayName = "RouteView.Match";
 
+export function Self(props: SelfProps): JSX.Element {
+  const result: SelfMarker = {
+    $$type: SELF_MARKER,
+    fallback: props.fallback,
+    get children(): JSX.Element {
+      return props.children;
+    },
+  };
+
+  // See Match for the marker-pattern rationale.
+  return result as unknown as JSX.Element;
+}
+
+Self.displayName = "RouteView.Self";
+
 export function NotFound(props: NotFoundProps): JSX.Element {
   const result: NotFoundMarker = {
     $$type: NOT_FOUND_MARKER,

package/src/components/RouteView/helpers.tsx

@@ -2,12 +2,13 @@ import { UNKNOWN_ROUTE } from "@real-router/core";
 import { startsWithSegment } from "@real-router/route-utils";
 import { Suspense } from "solid-js";
 
-import { MATCH_MARKER, NOT_FOUND_MARKER } from "./components";
+import { MATCH_MARKER, NOT_FOUND_MARKER, SELF_MARKER } from "./components";
 
 import type {
   MatchMarker,
   NotFoundMarker,
   RouteViewMarker,
+  SelfMarker,
 } from "./components";
 import type { JSX } from "solid-js";
 
@@ -32,6 +33,15 @@ function isMatchMarker(value: unknown): value is MatchMarker {
   );
 }
 
+function isSelfMarker(value: unknown): value is SelfMarker {
+  return (
+    value != null &&
+    typeof value === "object" &&
+    "$$type" in value &&
+    value.$$type === SELF_MARKER
+  );
+}
+
 function isNotFoundMarker(value: unknown): value is NotFoundMarker {
   return (
     value != null &&
@@ -57,16 +67,56 @@ export function collectElements(
     return;
   }
 
-  if (isMatchMarker(children) || isNotFoundMarker(children)) {
+  if (
+    isMatchMarker(children) ||
+    isSelfMarker(children) ||
+    isNotFoundMarker(children)
+  ) {
     result.push(children);
   }
 }
 
+// child.children is a getter — read it INSIDE the JSX expression so Solid
+// creates a reactive dependency. Pulling it into a variable freezes the
+// value at template-build time and breaks Suspense fallback transitions
+// (lazy() resolution).
+function renderMatch(child: MatchMarker): JSX.Element {
+  return child.fallback === undefined ? (
+    child.children
+  ) : (
+    <Suspense fallback={child.fallback}>{child.children}</Suspense>
+  );
+}
+
+function renderSelf(self: SelfMarker): JSX.Element {
+  return self.fallback === undefined ? (
+    self.children
+  ) : (
+    <Suspense fallback={self.fallback}>{self.children}</Suspense>
+  );
+}
+
+function processMatchChild(
+  child: MatchMarker,
+  routeName: string,
+  nodeName: string,
+): JSX.Element | null {
+  const { segment, exact } = child;
+  const fullSegmentName = nodeName ? `${nodeName}.${segment}` : segment;
+
+  if (!isSegmentMatch(routeName, fullSegmentName, exact)) {
+    return null;
+  }
+
+  return renderMatch(child);
+}
+
 export function buildRenderList(
   elements: RouteViewMarker[],
   routeName: string,
   nodeName: string,
 ): JSX.Element[] {
+  let selfMarker: SelfMarker | null = null;
   let notFoundChildren: JSX.Element | null = null;
   let activeMatchFound = false;
   const rendered: JSX.Element[] = [];
@@ -77,33 +127,29 @@ export function buildRenderList(
       continue;
     }
 
-    if (activeMatchFound) {
+    if (isSelfMarker(child)) {
+      selfMarker ??= child;
       continue;
     }
 
-    const { segment, exact, fallback } = child;
-    const fullSegmentName = nodeName ? `${nodeName}.${segment}` : segment;
-
-    if (!isSegmentMatch(routeName, fullSegmentName, exact)) {
+    if (activeMatchFound) {
       continue;
     }
 
-    activeMatchFound = true;
-    rendered.push(
-      fallback === undefined ? (
-        child.children
-      ) : (
-        <Suspense fallback={fallback}>{child.children}</Suspense>
-      ),
-    );
+    const matchRendered = processMatchChild(child, routeName, nodeName);
+
+    if (matchRendered !== null) {
+      activeMatchFound = true;
+      rendered.push(matchRendered);
+    }
   }
 
-  if (
-    !activeMatchFound &&
-    routeName === UNKNOWN_ROUTE &&
-    notFoundChildren !== null
-  ) {
-    rendered.push(notFoundChildren);
+  if (!activeMatchFound) {
+    if (selfMarker !== null && routeName === nodeName) {
+      rendered.push(renderSelf(selfMarker));
+    } else if (routeName === UNKNOWN_ROUTE && notFoundChildren !== null) {
+      rendered.push(notFoundChildren);
+    }
   }
 
   return rendered;

package/src/components/RouteView/index.ts

@@ -3,5 +3,6 @@ export { RouteView } from "./RouteView";
 export type {
   RouteViewProps,
   RouteViewMatchProps,
+  RouteViewSelfProps,
   RouteViewNotFoundProps,
 } from "./RouteView";

package/src/components/RouteView/types.ts

@@ -12,6 +12,13 @@ export interface MatchProps {
   readonly children: JSX.Element;
 }
 
+export interface SelfProps {
+  /** Fallback content while children are suspended. */
+  readonly fallback?: JSX.Element;
+  /** Content to render when the active route name equals the parent RouteView's nodeName. */
+  readonly children: JSX.Element;
+}
+
 export interface NotFoundProps {
   readonly children: JSX.Element;
 }

package/src/hooks/useRouteEnter.tsx

@@ -0,0 +1,129 @@
+import { createEffect } from "solid-js";
+
+import { useRoute } from "./useRoute";
+
+import type { State } from "@real-router/core";
+
+export interface RouteEnterContext {
+  /** The route that was just activated. */
+  route: State;
+  /** The route that was active immediately before this navigation. */
+  previousRoute: State;
+}
+
+export type RouteEnterHandler = (context: RouteEnterContext) => void;
+
+export interface UseRouteEnterOptions {
+  /**
+   * Skip the handler when `route.name === previousRoute.name`
+   * (sort/filter/query-only navigations on the same route). Default:
+   * `true`. Symmetric with `useRouteExit`'s same-name option.
+   */
+  skipSameRoute?: boolean;
+}
+
+/**
+ * Fire `handler` once when the component mounts as a result of a
+ * navigation. Mirror of `useRouteExit` for the entry side.
+ *
+ * What this hook covers that an ad-hoc `createEffect` + `useRoute()`
+ * doesn't:
+ *
+ *   - **Skip-initial**: handler is skipped when there is no
+ *     `transition.from` (i.e. first-load mount). Most consumers want to
+ *     fire side effects only on real navigations, not on hydration.
+ *   - **Same-route skip** (default): handler is skipped when
+ *     `route.transition.from === route.name`. Sort/filter/query-only
+ *     navigations re-trigger the effect (because the `route` reference
+ *     changes), but they are not "entries" in the animation / analytics
+ *     sense — the component instance has stayed mounted throughout.
+ *     Opt out with `skipSameRoute: false`.
+ *   - **Mount-time `route` / `previousRoute` snapshot**: the handler
+ *     receives the values that were live at the moment of effect
+ *     activation, not the latest ones (which may have moved on if the
+ *     user navigated again before the effect drained).
+ *
+ * **Handler reactivity (Solid)**: Solid components run **once** at mount;
+ * `handler` is captured in closure when the hook is called. If you need
+ * different behavior across renders, derive it from a signal inside the
+ * handler body — do not rely on swapping the handler reference.
+ *
+ * @example Direction-aware entry animation
+ * ```tsx
+ * useRouteEnter(({ route }) => {
+ *   const direction = route.context.browser?.direction;
+ *   ref?.classList.add(
+ *     direction === "back" ? "slide-from-left" : "slide-from-right",
+ *   );
+ * });
+ * ```
+ *
+ * @example Analytics page-enter event (skip-initial built-in)
+ * ```tsx
+ * useRouteEnter(({ route, previousRoute }) => {
+ *   analytics.track("page_enter", {
+ *     route: route.name,
+ *     from: previousRoute.name,
+ *   });
+ * });
+ * ```
+ *
+ * @example Reading rich transition metadata via `route.transition`
+ * ```tsx
+ * useRouteEnter(({ route }) => {
+ *   if (route.transition.redirected) {
+ *     showToast(`Redirected from ${route.transition.from}`);
+ *   }
+ *   if (route.transition.segments.activated.includes("products")) {
+ *     // products subtree just became active
+ *   }
+ * });
+ * ```
+ */
+export function useRouteEnter(
+  handler: RouteEnterHandler,
+  options?: UseRouteEnterOptions,
+): void {
+  const routeState = useRoute();
+  const skipSameRoute = options?.skipSameRoute ?? true;
+  let lastHandledRoute: State | null = null;
+
+  createEffect(() => {
+    const { route, previousRoute } = routeState();
+
+    // Early-exit guards, top-down:
+    //
+    //   - **Defensive**: `route` may be undefined during SSR or
+    //     pre-start hydration. Not testable from vitest (tests start
+    //     the router before render), so v8-ignored.
+    //   - **Skip-initial**: `state.transition.from` is undefined only
+    //     for the very first state committed by `router.start()`.
+    //   - **Skip-same-route**: query-only navigations have
+    //     `transition.from === route.name`. Opt-out via
+    //     `skipSameRoute: false`.
+    //   - **Defensive dedupe + missing `previousRoute`**: same `route`
+    //     ref between effect activations is unexpected on Solid (effects
+    //     run once per dependency change); `!previousRoute` is unreachable
+    //     once `transition.from` is set (the two are populated together by
+    //     core). Both kept for parity with React; v8-ignored.
+    /* v8 ignore start */
+    if (!route) {
+      return;
+    }
+    /* v8 ignore stop */
+    if (!route.transition.from) {
+      return;
+    }
+    if (skipSameRoute && route.transition.from === route.name) {
+      return;
+    }
+    /* v8 ignore start */
+    if (lastHandledRoute === route || !previousRoute) {
+      return;
+    }
+    /* v8 ignore stop */
+
+    lastHandledRoute = route;
+    handler({ route, previousRoute });
+  });
+}