@ssgoi/svelte 6.3.0 → 6.5.0

package/README.md

@@ -6,6 +6,16 @@ try this: [ssgoi.dev](https://ssgoi.dev)
 
 ![https://ssgoi.dev](https://ssgoi.dev/ssgoi.gif)
 
+## AI-Assisted Setup
+
+Using Claude, Cursor, ChatGPT, or another AI assistant? Point it at:
+
+```
+https://ssgoi.dev/llms.txt
+```
+
+It has the full setup guide, every transition, the API, and troubleshooting — everything an agent needs to wire SSGOI into your app.
+
 ## What is SSGOI?
 
 SSGOI brings native app-like page transitions to the web. Transform your static page navigations into smooth, delightful experiences that users love.
@@ -44,26 +54,25 @@ pnpm add @ssgoi/svelte
 </script>
 
 <Ssgoi {config}>
-  <!-- ⚠️ Important: position: relative is required! -->
-  <div style="position: relative; min-height: 100vh;">
+  <!-- ⚠️ Important: position: relative + z-index: 0 are required (the outgoing page is cloned with position:absolute). Add overflow-x-clip if you use horizontal transitions. -->
+  <div style="position: relative; z-index: 0; min-height: 100vh;">
     <slot />
   </div>
 </Ssgoi>
 ```
 
-### 2. Wrap your pages
+### 2. Mark your pages
 
 ```svelte
 <!-- +page.svelte -->
 <script>
-  import { SsgoiTransition } from "@ssgoi/svelte";
   import { page } from "$app/stores";
 </script>
 
-<SsgoiTransition id={$page.url.pathname}>
+<main data-ssgoi-transition={$page.url.pathname}>
   <h1>Welcome</h1>
   <!-- Page content -->
-</SsgoiTransition>
+</main>
 ```
 
 **That's it!** Your pages now transition smoothly with the configured effect.
@@ -114,7 +123,7 @@ The route helpers return path transition groups, so nested arrays are accepted i
 </script>
 
 <Ssgoi {config}>
-  <div style="position: relative; min-height: 100vh;">
+  <div style="position: relative; z-index: 0; min-height: 100vh;">
     <nav>
       <a href="/">Home</a>
       <a href="/about">About</a>
@@ -126,13 +135,12 @@ The route helpers return path transition groups, so nested arrays are accepted i
 
 <!-- +page.svelte -->
 <script>
-  import { SsgoiTransition } from '@ssgoi/svelte';
   import { page } from '$app/stores';
 </script>
 
-<SsgoiTransition id={$page.url.pathname}>
+<main data-ssgoi-transition={$page.url.pathname}>
   <!-- Your page content -->
-</SsgoiTransition>
+</main>
 ```
 
 ## API Reference
@@ -154,26 +162,34 @@ Props:
 - `config` - Transition configuration object
 - `host` - Optional external playback host for debug tooling
 
-#### `<SsgoiTransition>`
+#### `data-ssgoi-transition`
 
-Wrapper component for pages that should transition.
+Attribute for pages that should transition. Set it on the page boundary element
+inside `<Ssgoi>`.
 
 ```svelte
-<SsgoiTransition id="/page-id">
+<main data-ssgoi-transition="/page-id">
   <slot />
-</SsgoiTransition>
+</main>
 ```
 
 ## Built-in Transitions
 
 ### Page Transitions (`@ssgoi/svelte/view-transitions`)
 
-- `fade()` - Smooth opacity transition
-- `scroll()` - Vertical scrolling (up/down)
-- `drill()` - Drill in/out effect (enter/exit)
-- `hero()` - Shared element transitions
-- `slide()` - Ordered horizontal page transitions
-- `zoom()` - Shared element zoom transitions
+- `fade()` - Calm cross-fade. Safe default for unrelated pages
+- `drill()` - iOS-style hierarchical navigation (list → detail)
+- `slide()` - Horizontal push for tabs / sequential flows
+- `scroll()` - Vertical page scroll for onboarding / paginated views
+- `axis()` - Material/Flutter shared-axis swap for sibling/tab routes
+- `sheet()` - Bottom sheet that slides up (modal-like flows)
+- `hero()` - Shared element transition (matching `data-hero-enter-key` / `data-hero-exit-key`)
+- `zoom()` - Card-to-detail expansion (matching `data-zoom-enter-key` / `data-zoom-exit-key`)
+- `strip()` - 3D Y-axis perspective flip
+- `blind()` - Window-blinds wipe reveal
+- `film()` - Cinematic shrink + tile (gallery / lightbox)
+- `rotate()` - Card flip between siblings
+- `jaemin()` - Playful rotated zoom for special moments
 
 ## Typed Preset Configuration
 

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { default as Ssgoi } from "./ssgoi.svelte";
+/** @deprecated Set `data-ssgoi-transition` directly on an element inside `<Ssgoi>` instead. */
 export { default as SsgoiTransition } from "./ssgoi-transition.svelte";
 export * from "./types.js";
 export * from "@ssgoi/core";

package/dist/index.js

@@ -1,4 +1,5 @@
 export { default as Ssgoi } from "./ssgoi.svelte";
+/** @deprecated Set `data-ssgoi-transition` directly on an element inside `<Ssgoi>` instead. */
 export { default as SsgoiTransition } from "./ssgoi-transition.svelte";
 export * from "./types.js";
 export * from "@ssgoi/core";

package/dist/ssgoi-transition.svelte

@@ -2,6 +2,10 @@
   import type { Snippet } from "svelte";
   import { getSsgoiContext } from "./context";
 
+  /**
+   * @deprecated Set `data-ssgoi-transition` directly on the page boundary
+   * element inside `<Ssgoi>` instead.
+   */
   interface Props {
     id: string;
     children: Snippet;

package/dist/ssgoi-transition.svelte.d.ts

@@ -1,4 +1,8 @@
 import type { Snippet } from "svelte";
+/**
+ * @deprecated Set `data-ssgoi-transition` directly on the page boundary
+ * element inside `<Ssgoi>` instead.
+ */
 interface Props {
     id: string;
     children: Snippet;

package/dist/ssgoi.svelte

@@ -3,7 +3,11 @@
   import type { SsgoiConfig } from "@ssgoi/core/types";
   import type { HostAnimation } from "@ssgoi/core/internal";
   import { setSsgoiContext } from "./context";
-  import { createSggoiTransitionContext } from "@ssgoi/core/internal";
+  import {
+    createSggoiTransitionContext,
+    observeSsgoiTransitions,
+  } from "@ssgoi/core/internal";
+  import { onMount } from "svelte";
 
   interface Props {
     config: SsgoiConfig;
@@ -15,6 +19,12 @@
 
   const contextValue = createSggoiTransitionContext(config, { host });
   setSsgoiContext(contextValue);
+
+  let root: HTMLDivElement;
+
+  onMount(() => observeSsgoiTransitions(root, contextValue));
 </script>
 
-{@render children()}
+<div bind:this={root} data-ssgoi-root="" style="display: contents">
+  {@render children()}
+</div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ssgoi/svelte",
-  "version": "6.3.0",
+  "version": "6.5.0",
   "description": "Svelte bindings for SSGOI - Native app-like page transitions for Svelte and SvelteKit applications",
   "private": false,
   "main": "./dist/index.js",
@@ -14,7 +14,7 @@
   "types": "./dist/index.d.ts",
   "type": "module",
   "dependencies": {
-    "@ssgoi/core": "^6.3.0"
+    "@ssgoi/core": "^6.5.0"
   },
   "peerDependencies": {
     "svelte": "^5.0.0"