feat: configurable passage transitions with outgoing phase support

CHANGELOG.md

@@ -9,6 +9,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Configurable passage transitions with outgoing phase support
+  - Four transition types: `none` (instant), `fade` (incoming only), `fade-through` (fade out, optional pause, fade in), `crossfade` (simultaneous overlap)
+  - `Story.setTransition(config)` sets a persistent default transition
+  - `Story.setNextTransition(config)` sets a one-shot transition for the next navigation only
+  - Per-passage transition via tags: `[transition:crossfade duration:600 pause:200]`
+  - Priority chain: passage tags > one-shot > persistent default > built-in default
+  - CSS custom properties (`--passage-in-duration`, `--passage-out-duration`, `--passage-pause`) for author styling
+  - `data-transition` attribute on `.passage` for CSS targeting per type
+  - `prefers-reduced-motion` support
 - `:storyready` DOM event dispatched after Spindle finishes loading and rendering
 - Escaped braces (`\{`, `\}`) to display literal `{` and `}` characters in passage text
 - String-aware expression transformer that preserves `$var`/`_var`/`@var` sigils inside string literals and template literal text, while still transforming code and `${…}` interpolations
@@ -18,6 +27,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Comprehensive e2e test suite covering edge cases (nested macros, widget locals, computed reactivity, timed/repeat macros, form inputs, and more)
 - Unit tests for expression transformer, interpolation engine, option-utils, and tokenizer
 
+### Changed
+
+- Default passage transition changed from incoming-only fade to `fade-through` (300ms fade out, 50ms pause, 300ms fade in). Use `Story.setTransition({ type: 'fade' })` to restore the old behavior.
+- Passage animation easing changed from `ease-in` to `ease`
+- `.passage` element is now wrapped in a `.passage-container` div
+
 ### Fixed
 
 - Allow array method/property access (e.g. `$inventory.push`, `$journal.find`) in story variable validation

docs/.vitepress/config.ts

@@ -103,6 +103,7 @@ export default defineConfig({
         items: [
           { text: 'Saves', link: '/saves' },
           { text: 'Settings', link: '/settings' },
+          { text: 'Transitions', link: '/transitions' },
           { text: 'Story API', link: '/story-api' },
         ],
       },

docs/story-api.md

@@ -74,6 +74,35 @@ Remove a named watcher.
 {/do}
 ```
 
+### `Story.setTransition(config)`
+
+Set the default transition used for all passage navigations. Pass `null` to revert to the built-in default (`fade-through`, 300ms, 50ms pause).
+
+| Property   | Type      | Default | Description                                             |
+| ---------- | --------- | ------- | ------------------------------------------------------- |
+| `type`     | `string`  | —       | `'none'`, `'fade'`, `'fade-through'`, `'crossfade'`     |
+| `duration` | `number?` | `300`   | Animation duration in milliseconds                      |
+| `pause`    | `number?` | `50`    | Pause between outgoing and incoming (fade-through only) |
+
+```
+{do}
+  Story.setTransition({ type: 'crossfade', duration: 600 });
+  Story.setTransition({ type: 'none' }); // disable transitions
+  Story.setTransition(null); // revert to default
+{/do}
+```
+
+### `Story.setNextTransition(config)`
+
+Set a one-shot transition for the next navigation only. Consumed automatically when any navigation occurs — even if passage tags override the visual result.
+
+```
+{do}
+  Story.setNextTransition({ type: 'none' }); // next navigation is instant
+  Story.goto("DroneAttack");
+{/do}
+```
+
 ### `Story.save()`
 
 Perform a quick save.