@real-router/svelte 0.10.1 → 0.11.0

package/README.md

@@ -61,11 +61,13 @@ npm install @real-router/svelte @real-router/core @real-router/browser-plugin
 
 All composables must be called during component initialization (not inside `$effect` or event handlers). Reactive composables return `{ current: T }` getter objects — read `.current` inside a template or `$derived` to register a reactive dependency.
 
+`useRoute()` returns a **non-nullable** `route.current` (typed as `State<P>`) and throws when the router has no active state (unstarted, stopped, disposed). `useRouteNode(name)` keeps its nullable `current` — node inactivity is a legitimate business state, not a lifecycle error.
+
 | Composable              | Returns                                                         | Reactive?                                  |
 | ----------------------- | --------------------------------------------------------------- | ------------------------------------------ |
 | `useRouter()`           | `Router`                                                        | Never                                      |
 | `useNavigator()`        | `Navigator`                                                     | Never (stable ref, safe to use directly)   |
-| `useRoute()`            | `{ navigator, route: { current }, previousRoute: { current } }` | `.current` on every navigation             |
+| `useRoute()`            | `{ navigator, route: { current: State<P> }, previousRoute: { current } }` — throws if no active state | `.current` on every navigation             |
 | `useRouteNode(name)`    | `{ navigator, route: { current }, previousRoute: { current } }` | `.current` when node activates/deactivates |
 | `useRouteUtils()`       | `RouteUtils`                                                    | Never                                      |
 | `useRouterTransition()` | `{ current: RouterTransitionSnapshot }`                         | `.current` on transition start/end         |
@@ -118,7 +120,9 @@ All composables must be called during component initialization (not inside `$eff
 <script lang="ts">
   import { useRouteExit } from "@real-router/svelte";
 
-  let el: HTMLDivElement;
+  // `let el = $state<HTMLDivElement | null>(null)` under Svelte 5 strict mode —
+  // the `bind:this` target must be reactive for binding to land.
+  let el = $state<HTMLDivElement | null>(null);
 
   useRouteExit(async ({ signal }) => {
     if (!el) return;
@@ -239,14 +243,26 @@ Declarative route matching. Renders the snippet whose name matches the active ro
 
 **Props:**
 
-| Prop        | Type      | Description                                 |
-| ----------- | --------- | ------------------------------------------- |
-| `nodeName`  | `string`  | Route node to match against. `""` for root. |
-| `notFound`  | `Snippet` | Rendered when route is `UNKNOWN_ROUTE`      |
-| `[segment]` | `Snippet` | Named snippet matching a route segment      |
+| Prop        | Type      | Description                                                                                  |
+| ----------- | --------- | -------------------------------------------------------------------------------------------- |
+| `nodeName`  | `string`  | Route node to match against. `""` for root.                                                  |
+| `self`      | `Snippet` | Rendered when the active route is exactly `nodeName` (no descendant segments)                |
+| `notFound`  | `Snippet` | Rendered when route is `UNKNOWN_ROUTE`                                                       |
+| `[segment]` | `Snippet` | Named snippet matching a route segment                                                       |
 
 Snippet names must be valid JavaScript identifiers and match the first segment of the active route after `nodeName`. For a route `users.profile` with `nodeName=""`, the snippet named `users` matches.
 
+**`self` snippet:** distinguishes the exact-match case from any descendant. With `nodeName="users"`, the `users` segment snippet matches `users`, `users.list`, `users.profile`, etc. — but `{#snippet self()}` only renders when the active route is `"users"` exactly. Both `self` and `notFound` are **reserved** snippet names: a literal route named `notFound` or `self` is never matched as a regular segment.
+
+```svelte
+<!-- nested: render UsersIndex on /users, list on /users/list -->
+<RouteView nodeName="users">
+  {#snippet self()}<UsersIndex /> {/snippet}
+  {#snippet list()}<UsersList /> {/snippet}
+  {#snippet profile()}<UserProfile /> {/snippet}
+</RouteView>
+```
+
 > **Note:** `keepAlive` is not supported. Svelte has no equivalent of React's `<Activity>` API or Vue's `<KeepAlive>`. Components are destroyed when navigating away.
 
 ### `<RouterErrorBoundary>`
@@ -281,6 +297,33 @@ Auto-resets on next successful navigation. Works with both `<Link>` and imperati
 
 **`onError` signature:** `(error, toRoute, fromRoute) => void`. Receives the `RouterError`, the attempted destination (`State | null`), and the previously active route (`State | null`). A throwing `onError` is caught by the boundary, logged via `console.error`, and never breaks reactivity.
 
+### `<ClientOnly>` / `<ServerOnly>`
+
+Paired SSR-aware boundaries. `<ClientOnly>` renders the `fallback` snippet on the server (and on the client first paint, to match SSR HTML), then swaps in the `children` snippet after mount. `<ServerOnly>` is the symmetric inverse.
+
+```svelte
+<script lang="ts">
+  import { ClientOnly, ServerOnly } from "@real-router/svelte";
+</script>
+
+<ClientOnly>
+  {#snippet children()}
+    <BrowserApiWidget />
+  {/snippet}
+  {#snippet fallback()}
+    <Skeleton />
+  {/snippet}
+</ClientOnly>
+
+<ServerOnly>
+  {#snippet children()}
+    <SeoMetaStrip />
+  {/snippet}
+</ServerOnly>
+```
+
+Implementation: `$state(false)` + `$effect(() => mounted = true)`. The Svelte compiler emits the rune as a no-op on the server, so server-side rendering naturally lands on the SSR-side branch. End-to-end dogfooding lives in [`examples/web/svelte/ssr-examples/ssr/`](../../examples/web/svelte/ssr-examples/ssr/) (see `e2e/ssr-boundaries.spec.ts`).
+
 ## Actions
 
 ### `createLinkAction`
@@ -302,7 +345,10 @@ Factory function that creates a low-level action for adding navigation to any el
   Go Home
 </button>
 
-<div use:link={{ name: "settings", params: {}, options: { replace: true } }} role="link" tabindex="0">
+<!-- For non-anchor / non-button elements you can omit role="link" + tabindex="0":
+     applyLinkA11y adds them automatically. Explicit attrs in the example below are
+     redundant but harmless. -->
+<div use:link={{ name: "settings", params: {}, options: { replace: true } }}>
   Settings
 </div>
 ```
@@ -315,7 +361,9 @@ Factory function that creates a low-level action for adding navigation to any el
 | `params`  | `Params` | `{}`    | Route parameters                   |
 | `options` | `object` | `{}`    | Navigation options (replace, etc.) |
 
-The action automatically adds `role="link"` + `tabindex="0"` to non-interactive elements for accessibility. It handles click events and Enter key navigation.
+The action automatically adds `role="link"` + `tabindex="0"` to non-interactive elements for accessibility (skipping `<a>` / `<button>` which already convey link semantics). It handles click events and Enter key navigation.
+
+> **Hash asymmetry vs `<Link hash>`:** `createLinkAction` does **not** accept a `hash` parameter; `<Link hash="x">` does (#532). Use `<Link>` when a hash-aware variant is needed (tab-style UIs, same-route different-fragment navigation through `navigateWithHash`). For pure `use:link` callers, attach a click handler that calls `router.navigate(name, params, { force: true, hash: "x" })` manually if hash control is required.
 
 ## Reactive Primitives
 
@@ -448,9 +496,13 @@ Full documentation: [Wiki](https://github.com/greydragon888/real-router/wiki)
 
 ## Examples
 
-16 runnable examples — each is a standalone Vite app. Run: `cd examples/web/svelte/basic && pnpm dev`
+24 runnable examples — each is a standalone Vite app. Run: `cd examples/web/svelte/basic && pnpm dev`
+
+**Core:** [basic](../../examples/web/svelte/basic) · [nested-routes](../../examples/web/svelte/nested-routes) · [auth-guards](../../examples/web/svelte/auth-guards) · [data-loading](../../examples/web/svelte/data-loading) · [lazy-loading](../../examples/web/svelte/lazy-loading) · [async-guards](../../examples/web/svelte/async-guards) · [hash-routing](../../examples/web/svelte/hash-routing) · [persistent-params](../../examples/web/svelte/persistent-params) · [error-handling](../../examples/web/svelte/error-handling) · [dynamic-routes](../../examples/web/svelte/dynamic-routes) · [link-action](../../examples/web/svelte/link-action) · [lazy-loading-svelte](../../examples/web/svelte/lazy-loading-svelte) · [snippets-routing](../../examples/web/svelte/snippets-routing) · [reactive-source](../../examples/web/svelte/reactive-source) · [search-schema](../../examples/web/svelte/search-schema) · [combined](../../examples/web/svelte/combined)
+
+**Animations:** [motion-animations](../../examples/web/svelte/animation-examples/motion-animations) · [page-animations](../../examples/web/svelte/animation-examples/page-animations) · [route-animations](../../examples/web/svelte/animation-examples/route-animations) · [view-transitions](../../examples/web/svelte/animation-examples/view-transitions)
 
-[basic](../../examples/web/svelte/basic) · [nested-routes](../../examples/web/svelte/nested-routes) · [auth-guards](../../examples/web/svelte/auth-guards) · [data-loading](../../examples/web/svelte/data-loading) · [lazy-loading](../../examples/web/svelte/lazy-loading) · [async-guards](../../examples/web/svelte/async-guards) · [hash-routing](../../examples/web/svelte/hash-routing) · [persistent-params](../../examples/web/svelte/persistent-params) · [error-handling](../../examples/web/svelte/error-handling) · [dynamic-routes](../../examples/web/svelte/dynamic-routes) · [link-action](../../examples/web/svelte/link-action) · [lazy-loading-svelte](../../examples/web/svelte/lazy-loading-svelte) · [snippets-routing](../../examples/web/svelte/snippets-routing) · [reactive-source](../../examples/web/svelte/reactive-source) · [search-schema](../../examples/web/svelte/search-schema) · [combined](../../examples/web/svelte/combined)
+**Server-side rendering:** [ssr](../../examples/web/svelte/ssr-examples/ssr) · [ssr-streaming](../../examples/web/svelte/ssr-examples/ssr-streaming) · [ssr-mixed](../../examples/web/svelte/ssr-examples/ssr-mixed) · [ssg](../../examples/web/svelte/ssr-examples/ssg)
 
 ## Related Packages
 

package/dist/RouterProvider.svelte

@@ -47,9 +47,18 @@
 
   $effect(() => {
     if (!srEnabled) return;
-    // Read scrollRestoration object props via `untrack` for non-primitive
-    // refs that naturally change each render. Primitive $derived memos
-    // (mode/anchor/behavior/storageKey) drive re-runs.
+    // Pin primitive $derived deps as explicit dependencies of this effect
+    // BEFORE constructing the utility. The four `void srX` reads make
+    // intent unambiguous: even if `createScrollRestoration` throws after
+    // partial argument evaluation (e.g. invalid `mode` rejected), every
+    // srMode/srAnchor/srBehavior/srStorageKey is already in this effect's
+    // dependency set — the next change to any of them re-runs the effect
+    // and the utility gets rebuilt. Without these reads, the dependency
+    // tracking would depend on Svelte's argument-evaluation order inside
+    // the factory call, which is brittle. Non-primitive refs (like
+    // `scrollContainer` — a DOM element that changes ref every render but
+    // is identity-equal in practice) are deliberately read via `untrack`
+    // to keep this effect from re-running on every parent re-render.
     void srMode;
     void srAnchor;
     void srBehavior;

package/dist/components/Await.svelte

@@ -0,0 +1,48 @@
+<!--
+  @component
+  Reads `useDeferred(name)` and renders the `children` snippet with the
+  resolved value via Svelte's native `{#await}` block. Optional `fallback`
+  snippet shown while the promise is pending; rejection bubbles to the
+  nearest `{:catch}` handler in the surrounding `{#await}` chain (or
+  `<Streamed>`).
+
+  ```svelte
+  <Await name="reviews">
+    {#snippet children(reviews)}
+      <ReviewList items={reviews} />
+    {/snippet}
+    {#snippet fallback()}
+      <Spinner />
+    {/snippet}
+  </Await>
+  ```
+-->
+<script lang="ts" generics="T">
+  import { useDeferred } from "../composables/useDeferred.svelte";
+
+  import type { Snippet } from "svelte";
+
+  interface Props {
+    /** Deferred key declared in the loader's `defer({ deferred: { <name>: ... } })`. */
+    name: string;
+    /** Render snippet for the resolved value. */
+    children: Snippet<[T]>;
+    /** Snippet shown while the promise is pending. */
+    fallback?: Snippet;
+  }
+
+  let { name, children, fallback }: Props = $props();
+
+  // `useDeferred(name)` reads `state.context.ssrDataDeferred[name]` —
+  // wrap in `$derived` so a dynamic `name` prop re-resolves the promise
+  // (vs. capturing the initial value at component init).
+  const promise = $derived(useDeferred<T>(name));
+</script>
+
+{#await promise}
+  {#if fallback}
+    {@render fallback()}
+  {/if}
+{:then value}
+  {@render children(value)}
+{/await}

package/dist/components/Await.svelte.d.ts

@@ -0,0 +1,50 @@
+import type { Snippet } from "svelte";
+declare function $$render<T>(): {
+    props: {
+        /** Deferred key declared in the loader's `defer({ deferred: { <name>: ... } })`. */
+        name: string;
+        /** Render snippet for the resolved value. */
+        children: Snippet<[T]>;
+        /** Snippet shown while the promise is pending. */
+        fallback?: Snippet;
+    };
+    exports: {};
+    bindings: "";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<T> {
+    props(): ReturnType<typeof $$render<T>>['props'];
+    events(): ReturnType<typeof $$render<T>>['events'];
+    slots(): ReturnType<typeof $$render<T>>['slots'];
+    bindings(): "";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <T>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<T>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<T>['props']>, ReturnType<__sveltets_Render<T>['events']>, ReturnType<__sveltets_Render<T>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<T>['bindings']>;
+    } & ReturnType<__sveltets_Render<T>['exports']>;
+    <T>(internal: unknown, props: ReturnType<__sveltets_Render<T>['props']> & {}): ReturnType<__sveltets_Render<T>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+/**
+ * Reads `useDeferred(name)` and renders the `children` snippet with the
+ * resolved value via Svelte's native `{#await}` block. Optional `fallback`
+ * snippet shown while the promise is pending; rejection bubbles to the
+ * nearest `{:catch}` handler in the surrounding `{#await}` chain (or
+ * `<Streamed>`).
+ *
+ * ```svelte
+ * <Await name="reviews">
+ *   {#snippet children(reviews)}
+ *     <ReviewList items={reviews} />
+ *   {/snippet}
+ *   {#snippet fallback()}
+ *     <Spinner />
+ *   {/snippet}
+ * </Await>
+ * ```
+ */
+declare const Await: $$IsomorphicComponent;
+type Await<T> = InstanceType<typeof Await<T>>;
+export default Await;

package/dist/components/ClientOnly.svelte

@@ -0,0 +1,22 @@
+<script lang="ts">
+  import type { Snippet } from "svelte";
+
+  interface Props {
+    children: Snippet;
+    fallback?: Snippet;
+  }
+
+  let { children, fallback }: Props = $props();
+
+  let mounted = $state(false);
+
+  $effect(() => {
+    mounted = true;
+  });
+</script>
+
+{#if mounted}
+  {@render children()}
+{:else if fallback}
+  {@render fallback()}
+{/if}

package/dist/components/ClientOnly.svelte.d.ts

@@ -0,0 +1,8 @@
+import type { Snippet } from "svelte";
+interface Props {
+    children: Snippet;
+    fallback?: Snippet;
+}
+declare const ClientOnly: import("svelte").Component<Props, {}, "">;
+type ClientOnly = ReturnType<typeof ClientOnly>;
+export default ClientOnly;

package/dist/components/HttpStatusCode.svelte

@@ -0,0 +1,63 @@
+<!--
+  @component
+  Render-time HTTP status declaration. Mount inside a route component (typical
+  use case: a glob `*` route's NotFound page) when the status is decided by
+  the rendered tree rather than a loader.
+
+  Writes `code` to the nearest `<HttpStatusProvider>`'s sink during component
+  init and renders nothing. With no provider mounted (the standard
+  client-side case) the component is a silent no-op — same component tree
+  hydrates without touching the DOM or warning about mismatches.
+
+  Loader-driven errors (`LoaderNotFound` → 404, `LoaderRedirect` → 30x) keep
+  working as before; this component covers render-time decisions only.
+
+  Last write wins when several `<HttpStatusCode />` instances mount in the
+  same render pass — sink reflects the last component that ran.
+
+  ```svelte
+  <HttpStatusCode code={404} />
+  ```
+
+  **Streaming SSR ({#await}):** Svelte 5 stable does NOT chunk-stream HTTP
+  for `{#await}` — the server emits the pending branch and returns the full
+  response immediately, async resolution happens client-side. So the sink
+  is always written by the time `await render(App, ...)` resolves, regardless
+  of where `<HttpStatusCode />` is mounted. (This is RSC-like, not React 19
+  / Solid streaming.) No ordering concern.
+
+  **Hydration symmetry:** Svelte 5's hydration walker tolerates `{#if}`-branch
+  asymmetry between server and client (verified by `ssr/` e2e — no warnings
+  fire when SSR has the wrapper but CSR doesn't). The example's `App.svelte`
+  uses `{#if httpStatusSink}` so the wrapper is server-only; this is safe in
+  Svelte but would be a hydration mismatch in Vue/Solid.
+
+  **Valid `code` range:** Node's `res.end()` throws `Invalid status code` on
+  `NaN`, `0`, negative values, or values `> 999` — this surfaces as a 5xx /
+  dropped connection, not silent corruption. Pass a real HTTP status integer
+  (commonly 4xx/5xx; 100-999 is what Node accepts).
+-->
+<script lang="ts">
+  import { getContext } from "svelte";
+
+  import { HTTP_STATUS_KEY } from "../context";
+
+  import type { HttpStatusSink } from "../utils/createHttpStatusSink";
+
+  interface Props {
+    /** HTTP status to apply to the response. Common values: 404, 410, 451, 503. */
+    code: number;
+  }
+
+  let { code }: Props = $props();
+
+  const sink = getContext<HttpStatusSink | undefined>(HTTP_STATUS_KEY);
+
+  if (sink) {
+    // svelte-ignore state_referenced_locally
+    // Intentional one-time write at component init: the sink is read by the
+    // server after `await render()` and a single value is the contract.
+    // Consumers that need to update the code mid-render should remount.
+    sink.code = code;
+  }
+</script>

package/dist/components/HttpStatusCode.svelte.d.ts

@@ -0,0 +1,45 @@
+interface Props {
+    /** HTTP status to apply to the response. Common values: 404, 410, 451, 503. */
+    code: number;
+}
+/**
+ * Render-time HTTP status declaration. Mount inside a route component (typical
+ * use case: a glob `*` route's NotFound page) when the status is decided by
+ * the rendered tree rather than a loader.
+ *
+ * Writes `code` to the nearest `<HttpStatusProvider>`'s sink during component
+ * init and renders nothing. With no provider mounted (the standard
+ * client-side case) the component is a silent no-op — same component tree
+ * hydrates without touching the DOM or warning about mismatches.
+ *
+ * Loader-driven errors (`LoaderNotFound` → 404, `LoaderRedirect` → 30x) keep
+ * working as before; this component covers render-time decisions only.
+ *
+ * Last write wins when several `<HttpStatusCode />` instances mount in the
+ * same render pass — sink reflects the last component that ran.
+ *
+ * ```svelte
+ * <HttpStatusCode code={404} />
+ * ```
+ *
+ * **Streaming SSR ({#await}):** Svelte 5 stable does NOT chunk-stream HTTP
+ * for `{#await}` — the server emits the pending branch and returns the full
+ * response immediately, async resolution happens client-side. So the sink
+ * is always written by the time `await render(App, ...)` resolves, regardless
+ * of where `<HttpStatusCode />` is mounted. (This is RSC-like, not React 19
+ * / Solid streaming.) No ordering concern.
+ *
+ * **Hydration symmetry:** Svelte 5's hydration walker tolerates `{#if}`-branch
+ * asymmetry between server and client (verified by `ssr/` e2e — no warnings
+ * fire when SSR has the wrapper but CSR doesn't). The example's `App.svelte`
+ * uses `{#if httpStatusSink}` so the wrapper is server-only; this is safe in
+ * Svelte but would be a hydration mismatch in Vue/Solid.
+ *
+ * **Valid `code` range:** Node's `res.end()` throws `Invalid status code` on
+ * `NaN`, `0`, negative values, or values `> 999` — this surfaces as a 5xx /
+ * dropped connection, not silent corruption. Pass a real HTTP status integer
+ * (commonly 4xx/5xx; 100-999 is what Node accepts).
+ */
+declare const HttpStatusCode: import("svelte").Component<Props, {}, "">;
+type HttpStatusCode = ReturnType<typeof HttpStatusCode>;
+export default HttpStatusCode;

package/dist/components/HttpStatusProvider.svelte

@@ -0,0 +1,45 @@
+<!--
+  @component
+  Wraps an SSR tree with a render-scoped `HttpStatusSink`. `<HttpStatusCode />`
+  reads the sink via `getContext` and writes its `code` to it during component
+  init. Read `sink.code` after `await render()` to set the HTTP response
+  status.
+
+  ```svelte
+  <script lang="ts">
+    import {
+      HttpStatusProvider,
+      createHttpStatusSink,
+    } from "@real-router/svelte/ssr";
+
+    const sink = createHttpStatusSink();
+  </script>
+
+  <HttpStatusProvider {sink}>
+    <App />
+  </HttpStatusProvider>
+  ```
+-->
+<script lang="ts">
+  import { setContext } from "svelte";
+
+  import { HTTP_STATUS_KEY } from "../context";
+
+  import type { HttpStatusSink } from "../utils/createHttpStatusSink";
+  import type { Snippet } from "svelte";
+
+  interface Props {
+    sink: HttpStatusSink;
+    children: Snippet;
+  }
+
+  let { sink, children }: Props = $props();
+
+  // svelte-ignore state_referenced_locally
+  // The sink reference is captured once at provider init — replacing the sink
+  // mid-render isn't a supported usage pattern (the server reads it once
+  // after `await render()`).
+  setContext(HTTP_STATUS_KEY, sink);
+</script>
+
+{@render children()}

package/dist/components/HttpStatusProvider.svelte.d.ts

@@ -0,0 +1,30 @@
+import type { HttpStatusSink } from "../utils/createHttpStatusSink";
+import type { Snippet } from "svelte";
+interface Props {
+    sink: HttpStatusSink;
+    children: Snippet;
+}
+/**
+ * Wraps an SSR tree with a render-scoped `HttpStatusSink`. `<HttpStatusCode />`
+ * reads the sink via `getContext` and writes its `code` to it during component
+ * init. Read `sink.code` after `await render()` to set the HTTP response
+ * status.
+ *
+ * ```svelte
+ * <script lang="ts">
+ *   import {
+ *     HttpStatusProvider,
+ *     createHttpStatusSink,
+ *   } from "@real-router/svelte/ssr";
+ *
+ *   const sink = createHttpStatusSink();
+ * </script>
+ *
+ * <HttpStatusProvider {sink}>
+ *   <App />
+ * </HttpStatusProvider>
+ * ```
+ */
+declare const HttpStatusProvider: import("svelte").Component<Props, {}, "">;
+type HttpStatusProvider = ReturnType<typeof HttpStatusProvider>;
+export default HttpStatusProvider;

package/dist/components/RouteView.helpers.d.ts

@@ -0,0 +1 @@
+export declare function getActiveSegment(routeName: string, node: string, snippets: Record<string, unknown>): string;

package/dist/components/RouteView.helpers.js

@@ -0,0 +1,16 @@
+import { startsWithSegment } from "@real-router/route-utils";
+// Snippet names reserved by RouteView for non-segment slots. Iteration in
+// `getActiveSegment` skips these so they don't accidentally match a route.
+const RESERVED_SLOT_NAMES = new Set(["self", "notFound"]);
+export function getActiveSegment(routeName, node, snippets) {
+    const prefix = node ? `${node}.` : "";
+    for (const segment in snippets) {
+        if (RESERVED_SLOT_NAMES.has(segment)) {
+            continue;
+        }
+        if (startsWithSegment(routeName, prefix + segment)) {
+            return segment;
+        }
+    }
+    return "";
+}

package/dist/components/RouteView.svelte

@@ -1,32 +1,8 @@
-<script lang="ts" module>
-  import { startsWithSegment } from "@real-router/route-utils";
-
-  // Snippet names reserved by RouteView for non-segment slots. Iteration in
-  // `getActiveSegment` skips these so they don't accidentally match a route.
-  const RESERVED_SLOT_NAMES = new Set(["self", "notFound"]);
-
-  export function getActiveSegment(
-    routeName: string,
-    node: string,
-    snippets: Record<string, unknown>,
-  ): string {
-    const prefix = node ? `${node}.` : "";
-
-    for (const segment in snippets) {
-      if (RESERVED_SLOT_NAMES.has(segment)) continue;
-      if (startsWithSegment(routeName, prefix + segment)) {
-        return segment;
-      }
-    }
-
-    return "";
-  }
-</script>
-
 <script lang="ts">
   import { UNKNOWN_ROUTE } from "@real-router/core";
 
   import { useRouteNode } from "../composables/useRouteNode.svelte";
+  import { getActiveSegment } from "./RouteView.helpers";
 
   import type { Snippet } from "svelte";
 

package/dist/components/RouteView.svelte.d.ts

@@ -1,4 +1,3 @@
-export declare function getActiveSegment(routeName: string, node: string, snippets: Record<string, unknown>): string;
 import type { Snippet } from "svelte";
 type $$ComponentProps = {
     nodeName: string;

package/dist/components/ServerOnly.svelte

@@ -0,0 +1,22 @@
+<script lang="ts">
+  import type { Snippet } from "svelte";
+
+  interface Props {
+    children: Snippet;
+    fallback?: Snippet;
+  }
+
+  let { children, fallback }: Props = $props();
+
+  let mounted = $state(false);
+
+  $effect(() => {
+    mounted = true;
+  });
+</script>
+
+{#if !mounted}
+  {@render children()}
+{:else if fallback}
+  {@render fallback()}
+{/if}

package/dist/components/ServerOnly.svelte.d.ts

@@ -0,0 +1,8 @@
+import type { Snippet } from "svelte";
+interface Props {
+    children: Snippet;
+    fallback?: Snippet;
+}
+declare const ServerOnly: import("svelte").Component<Props, {}, "">;
+type ServerOnly = ReturnType<typeof ServerOnly>;
+export default ServerOnly;

package/dist/components/Streamed.svelte

@@ -0,0 +1,37 @@
+<!--
+  @component
+  Cross-adapter alias for Svelte's `{#await}` boundary. Renders the `fallback`
+  snippet while a `pending` Promise prop is unresolved, then `children` (with
+  the resolved value) once it settles. Symmetric naming with the
+  React/Preact/Solid/Vue/Angular `<Streamed>` components — pick `<Streamed>`
+  for cross-framework consistency, or use `{#await}` directly when team
+  conventions prefer that.
+
+  Svelte 5 has **no progressive HTTP-flush** in SSR (one TCP frame, late-
+  resolving promises ship in the final body) — the `{#await}` block on the
+  client retains its native streaming-after-hydration semantics. See
+  `examples/web/svelte/ssr-examples/ssr-streaming/README.md` for the
+  end-to-end story.
+-->
+<script lang="ts" generics="T">
+  import type { Snippet } from "svelte";
+
+  interface Props {
+    /** Promise to await — typically `useDeferred(key)`. */
+    pending: Promise<T>;
+    /** Render snippet for the resolved value. */
+    children: Snippet<[T]>;
+    /** Snippet shown while the promise is pending. */
+    fallback?: Snippet;
+  }
+
+  let { pending, children, fallback }: Props = $props();
+</script>
+
+{#await pending}
+  {#if fallback}
+    {@render fallback()}
+  {/if}
+{:then value}
+  {@render children(value)}
+{/await}

package/dist/components/Streamed.svelte.d.ts

@@ -0,0 +1,46 @@
+import type { Snippet } from "svelte";
+declare function $$render<T>(): {
+    props: {
+        /** Promise to await — typically `useDeferred(key)`. */
+        pending: Promise<T>;
+        /** Render snippet for the resolved value. */
+        children: Snippet<[T]>;
+        /** Snippet shown while the promise is pending. */
+        fallback?: Snippet;
+    };
+    exports: {};
+    bindings: "";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<T> {
+    props(): ReturnType<typeof $$render<T>>['props'];
+    events(): ReturnType<typeof $$render<T>>['events'];
+    slots(): ReturnType<typeof $$render<T>>['slots'];
+    bindings(): "";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <T>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<T>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<T>['props']>, ReturnType<__sveltets_Render<T>['events']>, ReturnType<__sveltets_Render<T>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<T>['bindings']>;
+    } & ReturnType<__sveltets_Render<T>['exports']>;
+    <T>(internal: unknown, props: ReturnType<__sveltets_Render<T>['props']> & {}): ReturnType<__sveltets_Render<T>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+/**
+ * Cross-adapter alias for Svelte's `{#await}` boundary. Renders the `fallback`
+ * snippet while a `pending` Promise prop is unresolved, then `children` (with
+ * the resolved value) once it settles. Symmetric naming with the
+ * React/Preact/Solid/Vue/Angular `<Streamed>` components — pick `<Streamed>`
+ * for cross-framework consistency, or use `{#await}` directly when team
+ * conventions prefer that.
+ *
+ * Svelte 5 has **no progressive HTTP-flush** in SSR (one TCP frame, late-
+ * resolving promises ship in the final body) — the `{#await}` block on the
+ * client retains its native streaming-after-hydration semantics. See
+ * `examples/web/svelte/ssr-examples/ssr-streaming/README.md` for the
+ * end-to-end story.
+ */
+declare const Streamed: $$IsomorphicComponent;
+type Streamed<T> = InstanceType<typeof Streamed<T>>;
+export default Streamed;