@ssgoi/svelte 7.4.1 → 7.5.0-beta.0

package/README.md

@@ -12,14 +12,13 @@ npm install @ssgoi/svelte
 
 Agent setup guide: https://ssgoi.dev/llms/svelte.txt
 
-## Router helpers
+## Router wiring
 
-Install this framework package once; router helpers are optional subpaths.
-These router helpers are experimental APIs and may change.
+Install this framework package once. The root entry never imports a router:
+pass the router members SSGOI needs through `<Ssgoi framework>`.
 
-| Router    | Import                    | API                  |
-| --------- | ------------------------- | -------------------- |
-| SvelteKit | `@ssgoi/svelte/sveltekit` | `SsgoiRouteBoundary` |
+The `@ssgoi/svelte/sveltekit` subpath (`SsgoiRouteBoundary`) is deprecated.
+Use `SsgoiLayoutBoundary` from `@ssgoi/svelte` with `framework` instead.
 
 See the [framework guide](https://ssgoi.dev/docs/frameworks/svelte) for wiring and limits.
 
@@ -28,6 +27,8 @@ See the [framework guide](https://ssgoi.dev/docs/frameworks/svelte) for wiring a
 ```svelte
 <!-- src/routes/+layout.svelte -->
 <script lang="ts">
+  import { onNavigate } from "$app/navigation";
+  import { page } from "$app/state";
   import { Ssgoi } from "@ssgoi/svelte";
   import { drill } from "@ssgoi/svelte/view-transitions";
 
@@ -39,7 +40,13 @@ See the [framework guide](https://ssgoi.dev/docs/frameworks/svelte) for wiring a
 </script>
 
 <main class="ssgoi-shell">
-  <Ssgoi {config}>
+  <Ssgoi
+    {config}
+    framework={{
+      getRoute: () => ({ pathname: page.url.pathname }),
+      onNavigate,
+    }}
+  >
     {@render children()}
   </Ssgoi>
 </main>
@@ -54,6 +61,26 @@ See the [framework guide](https://ssgoi.dev/docs/frameworks/svelte) for wiring a
 }
 ```
 
+SvelteKit before 2.12 has no `$app/state`; read the store instead:
+
+```svelte
+<script lang="ts">
+  import { get } from "svelte/store";
+  import { onNavigate } from "$app/navigation";
+  import { page } from "$app/stores";
+</script>
+
+<Ssgoi
+  {config}
+  framework={{
+    getRoute: () => ({ pathname: get(page).url.pathname }),
+    onNavigate,
+  }}
+>
+  {@render children()}
+</Ssgoi>
+```
+
 ## Route boundary
 
 Mark each route root:
@@ -84,6 +111,59 @@ inner boundaries:
 SvelteKit keeps the layout DOM during child navigation. Leaving the layout
 uses the outer boundary; changing a child route uses the child boundary.
 
+`SsgoiLayoutBoundary` does this for you. Declare the layout tree once in
+`config.layouts`, and put a prop-less boundary in each layout:
+
+```ts
+const TOP_LEVEL = ["/home", "/search", "/profile"];
+
+const config = {
+  transitions: [
+    /* ... */
+  ],
+  layouts: [
+    { paths: TOP_LEVEL },
+    {
+      paths: "/**",
+      except: TOP_LEVEL,
+      layouts: [{ paths: "/products/:category/**" }],
+    },
+  ],
+};
+```
+
+```svelte
+<!-- src/routes/+layout.svelte, inside <Ssgoi>: depth 0 -->
+<SsgoiLayoutBoundary>
+  {@render children()}
+</SsgoiLayoutBoundary>
+```
+
+```svelte
+<!-- src/routes/(top-level)/+layout.svelte: depth 1 -->
+<script lang="ts">
+  import { SsgoiLayoutBoundary } from "@ssgoi/svelte";
+
+  let { children } = $props();
+</script>
+
+<SsgoiLayoutBoundary as="section">
+  {@render children()}
+</SsgoiLayoutBoundary>
+<BottomNav />
+```
+
+Here top-level tabs swap only the depth-1 content, while opening a detail page
+moves the whole depth-0 boundary, bottom nav included. A boundary's depth is the
+number of boundaries around it. At depth N it stays mounted while navigation
+stays inside the same depth-N scope, and remounts (keeping the outgoing DOM
+intact for the transition) when the scope changes. Siblings take the first scope
+that matches, `except` excludes paths, and single-segment captures (`*`, `:id`,
+`[id]`) are part of a scope instance, so `/products/shoes/1` and
+`/products/shoes/2` share one while `/products/bags` does not. Below the
+declared tree, or without `layouts`, a boundary remounts on every pathname
+change. Its `data-ssgoi-transition` id is always the pathname.
+
 Use a keyed block only when the router reuses the same DOM node and a new
 boundary must be forced:
 

package/dist/context.d.ts

@@ -1,7 +1,31 @@
 import { type Readable } from "svelte/store";
-import type { SsgoiContext, SsgoiTransitionState } from "./types.js";
+import type { SsgoiConfig, SsgoiContext, SsgoiFramework, SsgoiTransitionState } from "./types.js";
 export declare function setSsgoiContext(context: SsgoiContext): void;
 export declare function getSsgoiContext(): SsgoiContext;
+type LayoutBoundaryState = {
+    id: string;
+    key: string | number;
+};
+type BoundaryAt = (depth: number) => LayoutBoundaryState;
+/** Where a layout boundary reads its current and next `{ id, key }`. */
+export interface LayoutRoutes {
+    current: BoundaryAt;
+    /** Registers for the calling component's lifetime. */
+    onNavigate: (listener: (next: BoundaryAt) => void | (() => void)) => void;
+}
+/**
+ * Resolves routes once for every boundary under the provider: the id is the
+ * pathname and a depth-N boundary keys by the depth-N `layouts` scope, falling
+ * back to the pathname.
+ */
+export declare function setSsgoiLayoutRoutes(framework: SsgoiFramework | undefined, layouts: SsgoiConfig["layouts"]): void;
+/** Routes for the next layout boundary only; its descendants use the provider's. */
+export declare function setSsgoiLayoutOverride(routes: LayoutRoutes): void;
+/** Reads a layout boundary's routes and depth, and nests its descendants. */
+export declare function enterSsgoiLayoutBoundary(): {
+    routes: LayoutRoutes;
+    depth: number;
+};
 /**
  * Store of the provider's transition lifecycle: whether a page transition is
  * preparing or playing, and which routes it joins.
@@ -12,3 +36,4 @@ export declare function getSsgoiContext(): SsgoiContext;
  * Must be called during component initialisation, under `<Ssgoi>`.
  */
 export declare function getSsgoiTransition(): Readable<SsgoiTransitionState>;
+export {};

package/dist/context.js

@@ -1,16 +1,67 @@
-import { getContext, setContext } from "svelte";
+import { getContext, onDestroy, setContext } from "svelte";
 import { readable } from "svelte/store";
-var SSGOI_CONTEXT_KEY = Symbol("ssgoi");
+import { resolveLayoutChain } from "@ssgoi/core/internal";
+const SSGOI_CONTEXT_KEY = Symbol("ssgoi");
+const SSGOI_LAYOUT_ROUTES_KEY = Symbol("ssgoi-layout-routes");
+const SSGOI_LAYOUT_OVERRIDE_KEY = Symbol("ssgoi-layout-override");
+const SSGOI_LAYOUT_DEPTH_KEY = Symbol("ssgoi-layout-depth");
 export function setSsgoiContext(context) {
     setContext(SSGOI_CONTEXT_KEY, context);
 }
 export function getSsgoiContext() {
-    var context = getContext(SSGOI_CONTEXT_KEY);
+    const context = getContext(SSGOI_CONTEXT_KEY);
     if (!context) {
         throw new Error("getSsgoiContext must be called within Ssgoi component");
     }
     return context;
 }
+/**
+ * Resolves routes once for every boundary under the provider: the id is the
+ * pathname and a depth-N boundary keys by the depth-N `layouts` scope, falling
+ * back to the pathname.
+ */
+export function setSsgoiLayoutRoutes(framework, layouts) {
+    if (!framework)
+        return;
+    const boundaryAt = (path) => {
+        const chain = resolveLayoutChain(layouts, path);
+        return (depth) => ({ id: path, key: chain[depth] ?? path });
+    };
+    const listeners = new Set();
+    framework.onNavigate((navigation) => {
+        if (!navigation.to)
+            return;
+        const next = boundaryAt(navigation.to.url.pathname);
+        const finish = Array.from(listeners, (listener) => listener(next));
+        return () => {
+            for (const callback of finish)
+                callback?.();
+        };
+    });
+    setContext(SSGOI_LAYOUT_ROUTES_KEY, {
+        current: (depth) => boundaryAt(framework.getRoute().pathname)(depth),
+        onNavigate: (listener) => {
+            listeners.add(listener);
+            onDestroy(() => listeners.delete(listener));
+        },
+    });
+}
+/** Routes for the next layout boundary only; its descendants use the provider's. */
+export function setSsgoiLayoutOverride(routes) {
+    setContext(SSGOI_LAYOUT_OVERRIDE_KEY, routes);
+}
+/** Reads a layout boundary's routes and depth, and nests its descendants. */
+export function enterSsgoiLayoutBoundary() {
+    const routes = getContext(SSGOI_LAYOUT_OVERRIDE_KEY) ??
+        getContext(SSGOI_LAYOUT_ROUTES_KEY);
+    if (!routes) {
+        throw new Error("SSGOI: SsgoiLayoutBoundary requires a framework. Pass it to <Ssgoi framework={{ getRoute: () => ({ pathname: page.url.pathname }), onNavigate }}>.");
+    }
+    const depth = getContext(SSGOI_LAYOUT_DEPTH_KEY) ?? 0;
+    setContext(SSGOI_LAYOUT_OVERRIDE_KEY, undefined);
+    setContext(SSGOI_LAYOUT_DEPTH_KEY, depth + 1);
+    return { routes, depth };
+}
 /**
  * Store of the provider's transition lifecycle: whether a page transition is
  * preparing or playing, and which routes it joins.
@@ -21,11 +72,11 @@ export function getSsgoiContext() {
  * Must be called during component initialisation, under `<Ssgoi>`.
  */
 export function getSsgoiTransition() {
-    var context = getContext(SSGOI_CONTEXT_KEY);
+    const context = getContext(SSGOI_CONTEXT_KEY);
     if (!context) {
         throw new Error("getSsgoiTransition must be called within Ssgoi component");
     }
-    return readable(context.getTransitionState(), function (set) {
+    return readable(context.getTransitionState(), (set) => {
         set(context.getTransitionState());
         return context.subscribe(set);
     });

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export { default as Ssgoi } from "./ssgoi.svelte";
+export { default as SsgoiLayoutBoundary } from "./ssgoi-layout-boundary.svelte";
 export { getSsgoiTransition } from "./context.js";
-/** @deprecated Set `data-ssgoi-transition` directly on an element inside `<Ssgoi>` instead. */
-export { default as SsgoiTransition } from "./ssgoi-transition.svelte";
+/** @deprecated Will be removed in 8.0.0. */
+export { default as SsgoiTransition } from "./legacy/ssgoi-transition.svelte";
 export * from "./types.js";
 export * from "@ssgoi/core";

package/dist/index.js

@@ -1,6 +1,7 @@
 export { default as Ssgoi } from "./ssgoi.svelte";
+export { default as SsgoiLayoutBoundary } from "./ssgoi-layout-boundary.svelte";
 export { getSsgoiTransition } from "./context.js";
-/** @deprecated Set `data-ssgoi-transition` directly on an element inside `<Ssgoi>` instead. */
-export { default as SsgoiTransition } from "./ssgoi-transition.svelte";
+/** @deprecated Will be removed in 8.0.0. */
+export { default as SsgoiTransition } from "./legacy/ssgoi-transition.svelte";
 export * from "./types.js";
 export * from "@ssgoi/core";

package/dist/{ssgoi-transition.svelte → legacy/ssgoi-transition.svelte}

@@ -1,11 +1,12 @@
+<!-- TODO(8.0.0): remove this entry (deprecated in 7.5.0). -->
+<!-- @component
+@deprecated Will be removed in 8.0.0.
+-->
 <script lang="ts">
   import type { Snippet } from "svelte";
-  import { getSsgoiContext } from "./context";
+  import { getSsgoiContext } from "../context";
 
-  /**
-   * @deprecated Set `data-ssgoi-transition` directly on the page boundary
-   * element inside `<Ssgoi>` instead.
-   */
+  /** @deprecated Will be removed in 8.0.0. */
   interface Props {
     id: string;
     children: Snippet;

package/dist/{ssgoi-transition.svelte.d.ts → legacy/ssgoi-transition.svelte.d.ts}

@@ -1,8 +1,5 @@
 import type { Snippet } from "svelte";
-/**
- * @deprecated Set `data-ssgoi-transition` directly on the page boundary
- * element inside `<Ssgoi>` instead.
- */
+/** @deprecated Will be removed in 8.0.0. */
 interface Props {
     id: string;
     children: Snippet;
@@ -10,6 +7,7 @@ interface Props {
     class?: string;
     [key: string]: unknown;
 }
+/** @deprecated Will be removed in 8.0.0. */
 declare const SsgoiTransition: import("svelte").Component<Props, {}, "">;
 type SsgoiTransition = ReturnType<typeof SsgoiTransition>;
 export default SsgoiTransition;

package/dist/{routers → legacy}/sveltekit/index.d.ts

@@ -1,3 +1,6 @@
-/** @experimental SvelteKit route boundary. The API may change. */
+/**
+ * @experimental SvelteKit route boundary.
+ * @deprecated Will be removed in 8.0.0. Use `SsgoiLayoutBoundary` from "@ssgoi/svelte" with `<Ssgoi framework={...}>` instead.
+ */
 export { default as SsgoiRouteBoundary } from "./ssgoi-route-boundary.svelte";
 export type { RouteBoundaryState, SveltekitRouteLocation, SsgoiRouteBoundaryProps, } from "./types.js";

package/dist/legacy/sveltekit/index.js

@@ -0,0 +1,6 @@
+// TODO(8.0.0): remove this entry (deprecated in 7.5.0).
+/**
+ * @experimental SvelteKit route boundary.
+ * @deprecated Will be removed in 8.0.0. Use `SsgoiLayoutBoundary` from "@ssgoi/svelte" with `<Ssgoi framework={...}>` instead.
+ */
+export { default as SsgoiRouteBoundary } from "./ssgoi-route-boundary.svelte";

package/dist/legacy/sveltekit/ssgoi-route-boundary.svelte

@@ -0,0 +1,34 @@
+<!-- TODO(8.0.0): remove this entry (deprecated in 7.5.0). -->
+<!-- @component
+@deprecated Will be removed in 8.0.0. Use `SsgoiLayoutBoundary` from "@ssgoi/svelte" with
+`<Ssgoi framework={...}>` instead.
+-->
+<script lang="ts">
+  import { onNavigate } from "$app/navigation";
+  // Stores work throughout SvelteKit 2, including releases before $app/state.
+  import { page } from "$app/stores";
+  import { setSsgoiLayoutOverride } from "../../context.js";
+  import SsgoiLayoutBoundary from "../../ssgoi-layout-boundary.svelte";
+  import type { SsgoiRouteBoundaryProps } from "./types.js";
+
+  let { resolve, routeKey, ...props }: SsgoiRouteBoundaryProps = $props();
+
+  const getBoundary = (url: URL) => {
+    const boundary = resolve?.({ pathname: url.pathname, url }) ?? {
+      id: url.pathname,
+    };
+    return { id: boundary.id, key: routeKey ?? boundary.key ?? boundary.id };
+  };
+
+  setSsgoiLayoutOverride({
+    current: () => getBoundary($page.url),
+    onNavigate: (listener) =>
+      onNavigate((navigation) => {
+        if (!navigation.to) return;
+        const { url } = navigation.to;
+        return listener(() => getBoundary(url));
+      }),
+  });
+</script>
+
+<SsgoiLayoutBoundary {...props} />

package/dist/{routers → legacy}/sveltekit/ssgoi-route-boundary.svelte.d.ts

@@ -1,5 +1,8 @@
 import type { SsgoiRouteBoundaryProps } from "./types.js";
-/** @experimental SvelteKit route boundary. The API may change. */
+/**
+ * @deprecated Will be removed in 8.0.0. Use `SsgoiLayoutBoundary` from "@ssgoi/svelte" with
+ * `<Ssgoi framework={...}>` instead.
+ */
 declare const SsgoiRouteBoundary: import("svelte").Component<SsgoiRouteBoundaryProps, {}, "">;
 type SsgoiRouteBoundary = ReturnType<typeof SsgoiRouteBoundary>;
 export default SsgoiRouteBoundary;

package/dist/{routers → legacy}/sveltekit/types.d.ts

@@ -1,14 +1,16 @@
 import type { Snippet } from "svelte";
 import type { HTMLAttributes } from "svelte/elements";
+/** @deprecated Will be removed in 8.0.0. Use `SsgoiLayoutBoundary` from "@ssgoi/svelte" with `<Ssgoi framework={...}>` instead. */
 export interface RouteBoundaryState {
     id: string;
     key?: string | number;
 }
+/** @deprecated Will be removed in 8.0.0. Use `SsgoiLayoutBoundary` from "@ssgoi/svelte" with `<Ssgoi framework={...}>` instead. */
 export interface SveltekitRouteLocation {
     pathname: string;
     url: URL;
 }
-/** @experimental SvelteKit route boundary options. */
+/** @deprecated Will be removed in 8.0.0. Use `SsgoiLayoutBoundaryProps` from "@ssgoi/svelte" with `<Ssgoi framework={...}>` instead. */
 export interface SsgoiRouteBoundaryProps extends HTMLAttributes<HTMLElement> {
     children: Snippet;
     as?: keyof HTMLElementTagNameMap;

package/dist/{routers/sveltekit/ssgoi-route-boundary.svelte → ssgoi-layout-boundary.svelte}

@@ -1,29 +1,16 @@
 <!-- @component
-@experimental SvelteKit route boundary. The API may change.
+Route boundary for a layout. Keyed by `config.layouts` at its nesting depth.
 -->
 <script lang="ts">
-  import { onNavigate } from "$app/navigation";
-  // Stores work throughout SvelteKit 2, including releases before $app/state.
-  import { page } from "$app/stores";
   import { flushSync, onDestroy, untrack } from "svelte";
-  import type { SsgoiRouteBoundaryProps } from "./types.js";
+  import { enterSsgoiLayoutBoundary } from "./context.js";
+  import type { SsgoiLayoutBoundaryProps } from "./types.js";
 
-  let {
-    children,
-    as = "div",
-    routeKey,
-    resolve,
-    ...rest
-  }: SsgoiRouteBoundaryProps = $props();
+  let { children, as = "div", ...rest }: SsgoiLayoutBoundaryProps = $props();
 
-  const getBoundary = (url: URL) => {
-    const boundary = resolve?.({ pathname: url.pathname, url }) ?? {
-      id: url.pathname,
-    };
-    return { id: boundary.id, key: routeKey ?? boundary.key ?? boundary.id };
-  };
+  const { routes, depth } = enterSsgoiLayoutBoundary();
 
-  let current = $state(untrack(() => getBoundary($page.url)));
+  let current = $state(untrack(() => routes.current(depth)));
   let mounted = $state(true);
   let alive = true;
 
@@ -31,9 +18,9 @@
     alive = false;
   });
 
-  onNavigate((navigation) => {
-    if (!alive || !navigation.to) return;
-    const next = getBoundary(navigation.to.url);
+  routes.onNavigate((boundaryAt) => {
+    if (!alive) return;
+    const next = boundaryAt(depth);
 
     if (next.key === current.key) {
       // A persistent shell keeps its DOM, but its outgoing id must stay current.

package/dist/ssgoi-layout-boundary.svelte.d.ts

@@ -0,0 +1,5 @@
+import type { SsgoiLayoutBoundaryProps } from "./types.js";
+/** Route boundary for a layout. Keyed by `config.layouts` at its nesting depth. */
+declare const SsgoiLayoutBoundary: import("svelte").Component<SsgoiLayoutBoundaryProps, {}, "">;
+type SsgoiLayoutBoundary = ReturnType<typeof SsgoiLayoutBoundary>;
+export default SsgoiLayoutBoundary;

package/dist/ssgoi.svelte

@@ -2,7 +2,8 @@
   import type { Snippet } from "svelte";
   import type { SsgoiConfig } from "@ssgoi/core/types";
   import type { HostAnimation } from "@ssgoi/core/internal";
-  import { setSsgoiContext } from "./context";
+  import type { SsgoiFramework } from "./types.js";
+  import { setSsgoiContext, setSsgoiLayoutRoutes } from "./context";
   import {
     createSggoiTransitionContext,
     observeSsgoiTransitions,
@@ -12,13 +13,16 @@
   interface Props {
     config: SsgoiConfig;
     host?: HostAnimation;
+    /** Router members for `SsgoiLayoutBoundary`. */
+    framework?: SsgoiFramework;
     children: Snippet;
   }
 
-  let { config, host, children }: Props = $props();
+  let { config, host, framework, children }: Props = $props();
 
   const contextValue = createSggoiTransitionContext(config, { host });
   setSsgoiContext(contextValue);
+  setSsgoiLayoutRoutes(framework, config.layouts);
 
   let root: HTMLDivElement;
 

package/dist/ssgoi.svelte.d.ts

@@ -1,9 +1,12 @@
 import type { Snippet } from "svelte";
 import type { SsgoiConfig } from "@ssgoi/core/types";
 import type { HostAnimation } from "@ssgoi/core/internal";
+import type { SsgoiFramework } from "./types.js";
 interface Props {
     config: SsgoiConfig;
     host?: HostAnimation;
+    /** Router members for `SsgoiLayoutBoundary`. */
+    framework?: SsgoiFramework;
     children: Snippet;
 }
 declare const Ssgoi: import("svelte").Component<Props, {}, "">;

package/dist/types.d.ts

@@ -1 +1,30 @@
+import type { Snippet } from "svelte";
+import type { HTMLAttributes } from "svelte/elements";
 export * from "@ssgoi/core/types";
+/**
+ * Router members `<Ssgoi>` reads for `SsgoiLayoutBoundary`.
+ *
+ * SvelteKit 2.12+: `{ getRoute: () => ({ pathname: page.url.pathname }),
+ * onNavigate }` from `$app/state` and `$app/navigation`. Earlier SvelteKit 2:
+ * read `get(page).url` with `page` from `$app/stores`.
+ */
+export interface SsgoiFramework {
+    /** The route a boundary mounts on. */
+    getRoute: () => {
+        pathname: string;
+    };
+    onNavigate: (callback: (navigation: {
+        to: {
+            url: URL;
+        } | null;
+    }) => void | (() => void)) => void;
+}
+/**
+ * A boundary's id is the pathname; at depth N (counted through enclosing
+ * boundaries) it stays mounted while navigation stays inside the same depth-N
+ * scope of `config.layouts`.
+ */
+export interface SsgoiLayoutBoundaryProps extends HTMLAttributes<HTMLElement> {
+    children: Snippet;
+    as?: keyof HTMLElementTagNameMap;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ssgoi/svelte",
-  "version": "7.4.1",
+  "version": "7.5.0-beta.0",
   "description": "Native app-like page transitions for Svelte and SvelteKit. Make a web app, PWA or WebView app feel native.",
   "private": false,
   "main": "./dist/index.js",
@@ -14,7 +14,7 @@
   "types": "./dist/index.d.ts",
   "type": "module",
   "dependencies": {
-    "@ssgoi/core": "^7.4.1"
+    "@ssgoi/core": "^7.5.0-beta.0"
   },
   "peerDependencies": {
     "svelte": "^5.0.0",
@@ -100,9 +100,9 @@
       "import": "./dist/view-transitions.js"
     },
     "./sveltekit": {
-      "types": "./dist/routers/sveltekit/index.d.ts",
-      "svelte": "./dist/routers/sveltekit/index.js",
-      "import": "./dist/routers/sveltekit/index.js"
+      "types": "./dist/legacy/sveltekit/index.d.ts",
+      "svelte": "./dist/legacy/sveltekit/index.js",
+      "import": "./dist/legacy/sveltekit/index.js"
     }
   },
   "peerDependenciesMeta": {

package/dist/routers/sveltekit/index.js

@@ -1,2 +0,0 @@
-/** @experimental SvelteKit route boundary. The API may change. */
-export { default as SsgoiRouteBoundary } from "./ssgoi-route-boundary.svelte";