### Start VitePress Development Server

Source: https://github.com/owlsdepartment/flyva/blob/main/AGENTS.md

Starts the VitePress development server for the documentation site.

```bash
pnpm dev:docs
```

--------------------------------

### Start Nuxt Playground

Source: https://github.com/owlsdepartment/flyva/blob/main/AGENTS.md

Launches the Nuxt playground development server.

```bash
pnpm dev:nuxt
```

--------------------------------

### Install @flyva/next and @flyva/shared

Source: https://github.com/owlsdepartment/flyva/blob/main/packages/next/README.md

Install the necessary packages and add them to transpilePackages in your Next.js configuration.

```bash
pnpm add @flyva/next @flyva/shared
```

```typescript
// next.config.ts
export default {
  transpilePackages: ['@flyva/next', '@flyva/shared'],
};
```

--------------------------------

### Flyva Development Commands

Source: https://github.com/owlsdepartment/flyva/blob/main/README.md

Commands to install dependencies, start development servers for Next.js and Nuxt playgrounds, and run the documentation development server.

```bash
pnpm install
pnpm dev:next    # Start Next.js playground
pnpm dev:nuxt    # Start Nuxt playground
pnpm docs:dev    # Start docs dev server
```

--------------------------------

### Start Next.js Playground

Source: https://github.com/owlsdepartment/flyva/blob/main/AGENTS.md

Launches the Next.js playground development server.

```bash
pnpm dev:next
```

--------------------------------

### Install Dependencies with pnpm

Source: https://github.com/owlsdepartment/flyva/blob/main/AGENTS.md

Run this command after cloning the repository to install all project dependencies using pnpm.

```bash
pnpm install
```

--------------------------------

### Install Dependencies with pnpm

Source: https://github.com/owlsdepartment/flyva/blob/main/docs/about/contributing.md

Enable corepack for pnpm and install project dependencies.

```bash
corepack enable
pnpm install
```

--------------------------------

### Start Nuxt View Transitions Playground

Source: https://github.com/owlsdepartment/flyva/blob/main/AGENTS.md

Launches the Nuxt playground specifically for View Transitions demos.

```bash
pnpm dev:nuxt:vt
```

--------------------------------

### Start Next.js View Transitions Playground

Source: https://github.com/owlsdepartment/flyva/blob/main/AGENTS.md

Launches the Next.js playground specifically for View Transitions demos.

```bash
pnpm dev:next:vt
```

--------------------------------

### Install Flyva for Next.js or Nuxt

Source: https://context7.com/owlsdepartment/flyva/llms.txt

Install the framework adapter and shared core package together for Next.js or Nuxt projects.

```bash
# Next.js
pnpm add @flyva/next @flyva/shared

# Nuxt
pnpm add @flyva/nuxt @flyva/shared
```

--------------------------------

### Run Playground Applications

Source: https://github.com/owlsdepartment/flyva/blob/main/docs/about/contributing.md

Start the development servers for the Nuxt and Next.js playgrounds to test changes.

```bash
# Nuxt playground
pnpm dev:nuxt

# Next.js playground
pnpm dev:next
```

--------------------------------

### Install Flyva for Nuxt

Source: https://github.com/owlsdepartment/flyva/blob/main/README.md

Use this command to add the necessary Flyva packages for your Nuxt project.

```bash
pnpm add @flyva/nuxt @flyva/shared
```

--------------------------------

### Install Flyva for Next.js

Source: https://github.com/owlsdepartment/flyva/blob/main/README.md

Use this command to add the necessary Flyva packages for your Next.js project.

```bash
pnpm add @flyva/next @flyva/shared
```

--------------------------------

### Commit Message Examples

Source: https://github.com/owlsdepartment/flyva/blob/main/docs/about/contributing.md

Examples of commit messages adhering to the Conventional Commits specification. Use these formats for your commits.

```bash
git commit -m "feat(nuxt): add custom transition resolver"
```

```bash
git commit -m "fix(shared): handle missing transition key gracefully"
```

--------------------------------

### Run Next.js Development Server

Source: https://github.com/owlsdepartment/flyva/blob/main/playground/next/README.md

Use these commands to start the local development server for your Next.js application. Open http://localhost:3000 in your browser to view the running application.

```bash
npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev
```

--------------------------------

### Install Playwright Browsers

Source: https://github.com/owlsdepartment/flyva/blob/main/docs/about/contributing.md

Download the necessary browsers for Playwright end-to-end tests. This command shares a cache between packages.

```bash
pnpm playwright:install
```

--------------------------------

### Example CSS for Transitions

Source: https://github.com/owlsdepartment/flyva/blob/main/docs/guide/modes/css-mode.md

This CSS demonstrates how to style the generated classes for leave and enter transitions. Target the content root element animated by the adapter. Adjust `transition` properties for desired effects.

```css
.slideTransition-leave-active,
.slideTransition-enter-active {
  transition: opacity 0.35s ease, transform 0.35s ease;
}

.slideTransition-leave-from,
.slideTransition-enter-to {
  opacity: 1;
  transform: translateX(0);
}

.slideTransition-leave-to,
.slideTransition-enter-from {
  opacity: 0;
  transform: translateX(12px);
}
```

--------------------------------

### Example Index Page with FlyvaLink

Source: https://github.com/owlsdepartment/flyva/blob/main/docs/guide/nuxt/index.md

A simple index page (`pages/index.vue`) demonstrating the use of `<FlyvaLink>` for navigation, which integrates with Flyva's transition system.

```vue
<!-- pages/index.vue -->
<template>
  <div>
    <h1>Home</h1>
    <FlyvaLink to="/about">Go to About</FlyvaLink>
  </div>
</template>
```

--------------------------------

### Nuxt.js Setup with Module and FlyvaPage

Source: https://context7.com/owlsdepartment/flyva/llms.txt

Configures Flyva in a Nuxt.js project by registering the module and replacing `<NuxtPage />` with `<FlyvaPage />`. Transitions are auto-discovered from `transitionsDir`.

```typescript
// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@flyva/nuxt'],
  flyva: {
    defaultKey: 'defaultTransition',   // fallback when no condition matches
    transitionsDir: 'page-transitions', // relative to project root
    useNamedExports: true,             // each named export = one transition
    viewTransition: false,             // set true to enable View Transitions API
  },
});
```

```vue
<!-- app.vue -->
<template>
  <NuxtLayout>
    <!-- Replaces <NuxtPage /> — coordinates leave/enter with Nuxt page hooks -->
    <FlyvaPage />
  </NuxtLayout>
</template>
```

--------------------------------

### Next.js Setup with FlyvaProvider

Source: https://context7.com/owlsdepartment/flyva/llms.txt

Sets up Flyva in a Next.js application using `FlyvaRoot` for context and `FlyvaTransitionWrapper` to register the swapping subtree. `FlyvaRoot` must be in a 'use client' component.

```tsx
// src/components/FlyvaProvider.tsx
'use client';
import { FlyvaRoot } from '@flyva/next';
import { fadeTransition } from '@/page-transitions/fadeTransition';
import { slideTransition } from '@/page-transitions/slideTransition';

// Transition map — keys become the transition names referenced by FlyvaLink
const transitions = { fadeTransition, slideTransition };

export function FlyvaProvider({ children }: React.PropsWithChildren) {
  return (
    <FlyvaRoot
      transitions={transitions}
      config={{ defaultKey: 'fadeTransition', lifecycleClassPrefix: 'flyva' }}
    >
      {children}
    </FlyvaRoot>
  );
}

// src/app/layout.tsx
import { FlyvaProvider } from '@/components/FlyvaProvider';
import { FlyvaTransitionWrapper } from '@flyva/next';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <FlyvaProvider>
          <nav>…</nav>
          <main>
            {/* Wrap the swapping segment — hooks receive context.container pointing here */}
            <FlyvaTransitionWrapper>{children}</FlyvaTransitionWrapper>
          </main>
        </FlyvaProvider>
      </body>
    </html>
  );
}

// next.config.ts — required so Next compiles the TS sources
export default {
  transpilePackages: ['@flyva/next', '@flyva/shared'],
};
```

--------------------------------

### Define a Custom Page Transition

Source: https://github.com/owlsdepartment/flyva/blob/main/docs/guide/nuxt/index.md

Create a transition file in your specified transitions directory. This example defines a fade-in/fade-out transition using anime.js.

```typescript
// page-transitions/defaultTransition.ts
import { animate } from 'animejs';
import { defineTransition } from '@flyva/shared';

export const defaultTransition = defineTransition({
  beforeLeave(ctx) {
    const el = ctx.container;
    if (!el) return;
    el.style.pointerEvents = 'none';
  },

  async leave(ctx) {
    const el = ctx.container;
    if (!el) return;
    await animate(el, { opacity: 0, duration: 400, ease: 'inQuad' });
  },

  afterLeave(ctx) {
    const el = ctx.container;
    if (!el) return;
    el.style.pointerEvents = '';
  },

  beforeEnter(ctx) {
    const el = ctx.container;
    if (!el) return;
    el.style.opacity = '0';
  },

  async enter(ctx) {
    const el = ctx.container;
    if (!el) return;
    await animate(el, { opacity: 1, duration: 400, ease: 'outQuad' });
  },
});
```

--------------------------------

### Transition Leave Hook with Options

Source: https://github.com/owlsdepartment/flyva/blob/main/docs/guide/nuxt/flyva-link.md

Example of a transition's `leave` hook utilizing options passed via `:flyva-options` to control animation direction.

```typescript
// Inside your transition
async leave(context) {
  const el = context.container;
  if (!el) return;
  const dir = context.options.direction === 'left' ? '100%' : '-100%';
  await animate(el, { translateX: dir, duration: 500 });
}
```

--------------------------------

### Nuxt View Transitions Lifecycle (`flyva.viewTransition`)

Source: https://github.com/owlsdepartment/flyva/blob/main/docs/guide/modes/lifecycle.md

Explains how Flyva integrates with the browser's View Transitions API in Nuxt. It shows how `FlyvaLink` initiates `startViewTransition`, and how `page:start` and `page:finish` short-circuit Flyva's normal hooks when a View Transition is active.

```mermaid
sequenceDiagram
  participant L as FlyvaLink
  participant M as PageTransitionManager
  participant VT as startViewTransition
  participant N as Nuxt page hooks

  L->>M: prepare
  L->>VT: navigate inside callback
  VT->>N: navigateTo
  N->>N: page:start (vt → early exit)
  N->>N: page:finish → resolveDomSwap
  VT-->>L: vt.finished
  L->>M: cleanup + finishTransition
```

--------------------------------

### Define a Fade Transition

Source: https://github.com/owlsdepartment/flyva/blob/main/docs/guide/next/index.md

Create a custom page transition using `defineTransition` from `@flyva/shared`. This example uses `animejs` to animate opacity for leaving and entering pages.

```typescript
// src/page-transitions/fadeTransition.ts
import { animate } from 'animejs';
import { defineTransition } from '@flyva/shared';

export const fadeTransition = defineTransition({
  beforeLeave(ctx) {
    const el = ctx.container;
    if (!el) return;
    el.style.pointerEvents = 'none';
  },

  async leave(ctx) {
    const el = ctx.container;
    if (!el) return;
    await animate(el, { opacity: 0, duration: 400, ease: 'inQuad' });
  },

  afterLeave(ctx) {
    const el = ctx.container;
    if (!el) return;
    el.style.pointerEvents = '';
  },

  beforeEnter(ctx) {
    const el = ctx.container;
    if (!el) return;
    el.style.opacity = '0';
  },

  async enter(ctx) {
    const el = ctx.container;
    if (!el) return;
    await animate(el, { opacity: 1, duration: 400, ease: 'outQuad' });
  },
});
```

--------------------------------

### Define a Fade Transition with Anime.js

Source: https://github.com/owlsdepartment/flyva/blob/main/docs/guide/next/index.md

Create a custom transition using `defineTransition`. This example uses `animejs` to animate the opacity of the container during the leave and enter phases.

```typescript
// src/page-transitions/fadeTransition.ts
import { animate } from 'animejs';
import { defineTransition } from '@flyva/shared';

export const fadeTransition = defineTransition({
  async leave(ctx) {
    const el = ctx.container;
    if (!el) return;
    await animate(el, { opacity: 0, duration: 300 });
  },
  beforeEnter(ctx) {
    const el = ctx.container;
    if (!el) return;
    el.style.opacity = '0';
  },
  async enter(ctx) {
    const el = ctx.container;
    if (!el) return;
    await animate(el, { opacity: 1, duration: 300 });
  },
});
```

--------------------------------

### Programmatic Transition Control with `useFlyvaTransition` (Next.js)

Source: https://context7.com/owlsdepartment/flyva/llms.txt

Use `useFlyvaTransition` to programmatically control page transitions, suitable for custom navigation triggers. This example shows how to trigger a 'slideTransition' and navigate using `router.push`.

```tsx
'use client';
import { useFlyvaTransition } from '@flyva/next';
import { useRouter } from 'next/navigation';

function CustomNavButton() {
  const router = useRouter();
  const { prepare, leave, enter, isViewTransition } = useFlyvaTransition();

  async function handleClick() {
    await prepare('slideTransition', { direction: 'left' });
    await leave();
    router.push('/next-page');
    await enter();
  }

  return <button onClick={handleClick}>Next Page</button>;
}
```

--------------------------------

### Define a Slide Page Transition using a Class

Source: https://context7.com/owlsdepartment/flyva/llms.txt

Implement the `PageTransition` interface with a class for OOP patterns, private fields, or per-instance state. This example defines a slide animation with configurable direction using anime.js. The manager reuses a single instance across navigations.

```typescript
// page-transitions/slideTransition.ts
import { animate } from 'animejs';
import type { PageTransition, PageTransitionContext } from '@flyva/shared';

interface SlideOptions { direction?: 'left' | 'right' }

class SlideTransitionClass implements PageTransition<SlideOptions> {
  private content: HTMLElement | null = null;

  async prepare(ctx: PageTransitionContext<SlideOptions>) {
    this.content = ctx.container ?? null;
  }

  async leave(ctx: PageTransitionContext<SlideOptions>) {
    const el = this.content ?? ctx.container ?? null;
    if (!el) return;
    const dir = ctx.options.direction === 'left' ? '100%' : '-100%';
    await animate(el, { translateX: dir, opacity: 0, duration: 500, ease: 'inOutCubic' });
  }

  beforeEnter(ctx: PageTransitionContext<SlideOptions>) {
    this.content = ctx.container ?? null;
    if (!this.content) return;
    const dir = ctx.options.direction === 'left' ? '-100%' : '100%';
    this.content.style.transform = `translateX(${dir})`;
    this.content.style.opacity = '0';
  }

  async enter(ctx: PageTransitionContext<SlideOptions>) {
    const el = this.content ?? ctx.container ?? null;
    if (!el) return;
    await animate(el, { translateX: '0%', opacity: 1, duration: 500, ease: 'inOutCubic' });
  }

  cleanup() {
    if (this.content) {
      this.content.style.transform = '';
      this.content.style.opacity = '';
    }
    this.content = null;
  }
}

// Export one shared instance — the manager reuses it across navigations
export const slideTransition = new SlideTransitionClass();

```

--------------------------------

### Build Documentation

Source: https://github.com/owlsdepartment/flyva/blob/main/AGENTS.md

Compiles the documentation site to verify it builds correctly.

```bash
pnpm docs:build
```

--------------------------------

### Create a Client Provider Component

Source: https://github.com/owlsdepartment/flyva/blob/main/packages/next/README.md

Set up a client component to provide FlyvaRoot, enabling transitions. Pass your defined transitions to the FlyvaRoot component.

```tsx
// src/components/FlyvaProvider.tsx
'use client';

import { FlyvaRoot } from '@flyva/next';
import { fadeTransition } from '@/page-transitions/fadeTransition';

const transitions = { fadeTransition };

export function FlyvaProvider({ children }) {
  return <FlyvaRoot transitions={transitions}>{children}</FlyvaRoot>;
}
```

--------------------------------

### FLIP Transition: Prepare Element

Source: https://github.com/owlsdepartment/flyva/blob/main/docs/guide/nuxt/writing-transitions.md

Clones the trigger element and positions it fixed in the DOM before the transition starts. This is used for the 'leave' animation.

```typescript
async prepare(context: PageTransitionContext) {
  this.content = context.container ?? null;

  if (context.el instanceof HTMLElement) {
    const rect = context.el.getBoundingClientRect();
    this.clone = context.el.cloneNode(true) as HTMLElement;
    this.clone.classList.add('flyva-clone');
    Object.assign(this.clone.style, {
      position: 'fixed',
      top: `${rect.top}px`,
      left: `${rect.left}px`,
      width: `${rect.width}px`,
      height: `${rect.height}px`,
      zIndex: '10000',
      margin: '0',
    });
    document.body.appendChild(this.clone);
  }
}
```

--------------------------------

### Get Flyva Configuration with useFlyvaConfig

Source: https://github.com/owlsdepartment/flyva/blob/main/docs/api/next.md

Retrieve the current Flyva configuration object. This hook must be called within a FlyvaRoot component.

```typescript
const config = useFlyvaConfig();
config.defaultKey // 'defaultTransition'
```

--------------------------------

### Build Packages

Source: https://github.com/owlsdepartment/flyva/blob/main/AGENTS.md

Runs the build script for the packages, typically to compile code for distribution.

```bash
pnpm build
```

--------------------------------

### FlyvaLink with Transition and Options

Source: https://github.com/owlsdepartment/flyva/blob/main/docs/api/next.md

Replace next/link with FlyvaLink for transition support. Specify a transition key with `flyvaTransition` and pass custom data via `flyvaOptions`. Callbacks are available for various transition stages.

```tsx
<FlyvaLink
  href="/about"
  flyvaTransition="slideTransition"
  flyvaOptions={{ direction: 'left' }}
  onTransitionStart={() => console.log('starting')}
>
  About
</FlyvaLink>
```

--------------------------------

### Get Transition Controller with useFlyvaTransition

Source: https://github.com/owlsdepartment/flyva/blob/main/docs/api/next.md

Use this hook to access the transition controller functions. It's primarily used internally by FlyvaLink but can be called directly for programmatic transitions.

```typescript
const {
  prepare,
  leave,
  enter,
  leaveWithViewTransition,
  hasTransitioned,
  isConcurrent,
  isViewTransition,
} = useFlyvaTransition();
```

--------------------------------

### Next.js Default Transition - Sequence Diagram

Source: https://github.com/owlsdepartment/flyva/blob/main/docs/guide/next/transition-modes.md

Illustrates the default sequential JavaScript transition flow in Next.js, where leave hooks are awaited before router.push.

```mermaid
sequenceDiagram
  participant L as FlyvaLink
  participant T as useFlyvaTransition
  participant M as PageTransitionManager
  participant R as App Router
  participant W as FlyvaTransitionWrapper

  L->>T: prepare
  T->>M: run → prepare hook
  L->>T: await leave
  T->>M: beforeLeave / leave / afterLeave
  L->>R: router.push
  R-->>W: new pathname commit
  W->>T: enter (async tick)
  T->>M: beforeEnter / enter / afterEnter
  M->>M: cleanup + finishTransition
```

--------------------------------

### PageTransitionManager Usage

Source: https://github.com/owlsdepartment/flyva/blob/main/packages/shared/README.md

Demonstrates how to instantiate and run a transition using the PageTransitionManager.

```typescript
const manager = new PageTransitionManager(transitions, reactiveFactory);
manager.run('fadeTransition', { fromHref: '/', toHref: '/about' });
```

--------------------------------

### Retrieve Entire Ref Stack with globalGetRefStack

Source: https://github.com/owlsdepartment/flyva/blob/main/docs/api/next.md

Get the entire global ref stack as a record of string keys to ref objects. This can be useful for debugging or when you need to iterate over all registered refs.

```typescript
globalGetRefStack()
```

--------------------------------

### Flyva Transition Lifecycle - Mermaid Diagram

Source: https://github.com/owlsdepartment/flyva/blob/main/docs/guide/next/transition-modes.md

Visualizes the sequential execution of Flyva's transition hooks during a single navigation event.

```mermaid
flowchart TD
  subgraph preparePhase[Prepare]
    P[prepare]
  end
  subgraph leavePhase[Leave]
    direction TB
    BL[beforeLeave] --> L[leave] --> AL[afterLeave]
  end
  subgraph swap[Framework]
    N[Route / page swap]
  end
  subgraph enterPhase[Enter]
    direction TB
    BE[beforeEnter] --> E[enter] --> AE[afterEnter]
  end
  CU[cleanup]
  P --> BL
  AL --> N
  N --> BE
  AE --> CU
```

--------------------------------

### Wrap Layout with FlyvaTransitionWrapper

Source: https://github.com/owlsdepartment/flyva/blob/main/docs/guide/next/index.md

Integrate Flyva into the root layout by wrapping the main content with `FlyvaProvider` and `FlyvaTransitionWrapper`. This enables Flyva's transition management for the application.

```tsx
// src/app/layout.tsx
import { FlyvaProvider } from '@/components/FlyvaProvider';
import { FlyvaTransitionWrapper } from '@flyva/next';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <FlyvaProvider>
          <nav>...</nav>
          <main>
            <FlyvaTransitionWrapper>{children}</FlyvaTransitionWrapper>
          </main>
        </FlyvaProvider>
      </body>
    </html>
  );
}
```

--------------------------------

### Capturing Clicked Element for Transitions

Source: https://github.com/owlsdepartment/flyva/blob/main/docs/guide/nuxt/writing-transitions.md

Demonstrates how to capture the clicked element using `context.el` within the `prepare` hook. This is useful for shared element transitions by getting the element's bounding rectangle.

```typescript
async prepare(context: PageTransitionContext) {
  if (context.el instanceof HTMLElement) {
    const rect = context.el.getBoundingClientRect();
    const snapshot = { top: rect.top, left: rect.left, width: rect.width, height: rect.height };
    // on a class / defineTransition instance, assign to fields for leave/enter (e.g. this.snapshot = snapshot)
  }
}
```

--------------------------------

### Get PageTransitionManager Instance with useFlyvaManager

Source: https://github.com/owlsdepartment/flyva/blob/main/docs/api/next.md

Access the raw PageTransitionManager instance. This hook requires being called inside FlyvaRoot and is useful for inspecting the manager's state or directly invoking lifecycle methods.

```typescript
const manager = useFlyvaManager();
manager.isRunning  // boolean
manager.stage      // PageTransitionStage
```

--------------------------------

### Flyva Monorepo Structure

Source: https://github.com/owlsdepartment/flyva/blob/main/README.md

Overview of the directory structure for the Flyva monorepo, including shared core, framework adapters, playgrounds, and documentation.

```bash
packages/
  shared/     Framework-agnostic transition manager
  next/       Next.js (App Router) adapter
  nuxt/       Nuxt 4 module
playground/
  next/       Next.js test playground
  nuxt/       Nuxt test playground
docs/         VitePress documentation
```

--------------------------------

### Basic FlyvaLink Usage

Source: https://github.com/owlsdepartment/flyva/blob/main/docs/guide/next/flyva-link.md

Import FlyvaLink and use it like a standard Next.js Link for navigation with transitions.

```tsx
import { FlyvaLink } from '@flyva/next';

<FlyvaLink href="/about">About</FlyvaLink>
```

--------------------------------

### Mount Overlay Components with `useDetachedRoot` (Nuxt)

Source: https://context7.com/owlsdepartment/flyva/llms.txt

Similar to the Next.js version, this Nuxt example uses `useDetachedRoot` with a Vue render function to mount overlays. Call `destroy()` in cleanup. Requires `h` from 'vue'.

```ts
import { h } from 'vue';
import { useDetachedRoot } from '@flyva/nuxt/composables';

type OverlayRefs = { root: HTMLDivElement | null };

const { refs, waitForRender, destroy } = useDetachedRoot<OverlayRefs>(r =>
  h('div', { ref: r.root, class: 'overlay', role: 'presentation' }),
);

await waitForRender();
// refs.root.value — animate …
destroy(); // call in cleanup()
```

--------------------------------

### Nuxt Concurrent Lifecycle (`concurrent: true`)

Source: https://github.com/owlsdepartment/flyva/blob/main/docs/guide/modes/lifecycle.md

Details the concurrent JavaScript lifecycle in Nuxt where `page:start` skips manager leave hooks, and manager enter hooks run during `page:finish`. This allows for overlapping leave and enter transitions.

```mermaid
sequenceDiagram
  participant M as PageTransitionManager
  participant N as Nuxt page hooks
  participant V as Vue Transition

  N->>N: page:loading:start
  N->>N: page:start
  N->>V: resolveLeave (no manager leave yet)
  V->>M: onLeave → beforeLeave leave afterLeave
  V->>V: await getEnterPromise
  N->>N: page:finish
  N->>M: beforeEnter / enter / afterEnter
  N->>V: finish
  V-->>V: onLeave completes
```

--------------------------------

### Choosing a Transition Per Link

Source: https://github.com/owlsdepartment/flyva/blob/main/docs/guide/next/flyva-link.md

Specify a transition to run for a specific link using the `flyvaTransition` prop. If omitted, Flyva uses `matchTransitionKey` to determine the transition.

```tsx
<FlyvaLink href="/work" flyvaTransition="slideTransition">Work</FlyvaLink>
```

--------------------------------

### Next.js CSS Mode Transition - Sequence Diagram

Source: https://github.com/owlsdepartment/flyva/blob/main/docs/guide/next/transition-modes.md

Outlines the CSS mode transition flow in Next.js, utilizing CSS class phases for leave and enter animations after router.push.

```mermaid
sequenceDiagram
  participant L as FlyvaLink
  participant T as useFlyvaTransition
  participant M as PageTransitionManager
  participant R as App Router
  participant W as FlyvaTransitionWrapper

  L->>T: prepare
  L->>T: await leave
  T->>T: applyCssStageClasses leave
  L->>R: router.push
  R-->>W: new pathname
  W->>W: add *-enter-from on content
  W->>T: enter
  T->>T: applyCssStageClasses enter
  M->>M: finishTransition + cleanup
```

--------------------------------

### Run Unit Tests

Source: https://github.com/owlsdepartment/flyva/blob/main/AGENTS.md

Executes unit tests for the `@flyva/shared` package using Vitest.

```bash
pnpm test:unit
```

--------------------------------

### View Transition Helpers

Source: https://github.com/owlsdepartment/flyva/blob/main/docs/api/shared.md

Provides utilities for managing browser View Transitions API and CSS class-based animations. Includes functions to check support, apply/clear names, wait for animations, and apply CSS stage classes.

```typescript
supportsViewTransitions()
```

```typescript
applyViewTransitionNames(names, context)
```

```typescript
clearViewTransitionNames(names)
```

```typescript
waitForAnimation(el)
```

```typescript
applyCssStageClasses(el, name, phase)
```

--------------------------------

### Configure FlyvaRoot with Transitions

Source: https://github.com/owlsdepartment/flyva/blob/main/docs/guide/next/index.md

Pass transition definitions and configuration options to FlyvaRoot. The `defaultKey` sets the initial transition, and `viewTransition: true` enables the native browser View Transition API.

```tsx
<FlyvaRoot
  transitions={transitions}
  config={{ defaultKey: 'fadeTransition', viewTransition: true }}
>
```

--------------------------------

### Module Configuration

Source: https://github.com/owlsdepartment/flyva/blob/main/docs/api/nuxt.md

Configure the @flyva/nuxt module by adding it to your `nuxt.config.ts` and setting the desired options.

```APIDOC
## Module Options

Configured under the `flyva` key in `nuxt.config.ts`:

```ts
export default defineNuxtConfig({
  modules: ['@flyva/nuxt'],
  flyva: {
    defaultKey: 'defaultTransition',
    transitionsDir: 'page-transitions',
    useNamedExports: true,
    viewTransition: true,
  },
});
```

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `defaultKey` | `string` | `'defaultTransition'` | Fallback map key after `matchTransitionKey` when no `condition` matches (and when the link omits `flyva-transition`) |
| `transitionsDir` | `string` | `'flyva-transitions'` | Directory containing transition files (relative to project root) |
| `useNamedExports` | `boolean` | `true` | If `true`, each named export becomes a separate transition. If `false`, the default export is used. |
| `viewTransition` | `boolean` | `undefined` | Enables `document.startViewTransition` in `FlyvaLink` when the browser supports it |
```

--------------------------------

### Using Link Options for Transition Customization

Source: https://github.com/owlsdepartment/flyva/blob/main/docs/guide/nuxt/writing-transitions.md

Shows how to pass custom options like `direction` and `color` via `:flyva-options` on a `FlyvaLink` component. These options are then accessible within the transition's lifecycle hooks via `context.options`.

```vue
<FlyvaLink to="/work" :flyva-options="{ direction: 'left', color: '#000' }">
  Back
</FlyvaLink>
```

--------------------------------

### Define a Custom Page Transition

Source: https://github.com/owlsdepartment/flyva/blob/main/packages/nuxt/README.md

Create a transition file in the specified directory (e.g., page-transitions/defaultTransition.ts) using defineTransition from @flyva/shared.

```typescript
import { animate } from 'animejs';
import { defineTransition } from '@flyva/shared';

export const defaultTransition = defineTransition({
  async leave(ctx) {
    const el = ctx.container;
    if (!el) return;
    await animate(el, { opacity: 0, duration: 400 });
  },
  beforeEnter(ctx) {
    const el = ctx.container;
    if (!el) return;
    el.style.opacity = '0';
  },
  async enter(ctx) {
    const el = ctx.container;
    if (!el) return;
    await animate(el, { opacity: 1, duration: 400 });
  },
});
```

--------------------------------

### useFlyvaLifecycle (Blocking Mode)

Source: https://github.com/owlsdepartment/flyva/blob/main/docs/api/next.md

Demonstrates the use of `useFlyvaLifecycle` with `blocking: true` to ensure transitions and their hooks complete before the lifecycle step finishes. This is useful when a component's animation must be fully rendered before proceeding.

```APIDOC
## useFlyvaLifecycle (Blocking Mode)

### Description
Use `blocking: true` to ensure `prepare`, `leave`, and `enter` are awaited together with the transition’s hooks. This is useful when a component must finish its own animation before the lifecycle step completes.

If the component unmounts mid-transition, the hook unregisters and in-flight cancellable work is settled so the transition is not left hanging.

### Method
`useFlyvaLifecycle({ async leave(ctx) { await animateProgressBar(ctx); } }, { blocking: true });`
```

--------------------------------

### Access Flyva Transition Controller

Source: https://github.com/owlsdepartment/flyva/blob/main/docs/api/nuxt.md

Use the `useFlyvaTransition` composable to access the transition controller. This provides methods and reactive states to manage and monitor page transitions, including `prepare`, `isRunning`, `stage`, and `hasTransitioned`.

```typescript
const { prepare, isRunning, stage, hasTransitioned } = useFlyvaTransition();
```

--------------------------------

### Wrap Layout with Flyva Providers

Source: https://github.com/owlsdepartment/flyva/blob/main/packages/next/README.md

Integrate FlyvaProvider and FlyvaTransitionWrapper into your root layout to manage page transitions.

```tsx
// src/app/layout.tsx
import { FlyvaProvider } from '@/components/FlyvaProvider';
import { FlyvaTransitionWrapper } from '@flyva/next';

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <FlyvaProvider>
          <main>
            <FlyvaTransitionWrapper>{children}</FlyvaTransitionWrapper>
          </main>
        </FlyvaProvider>
      </body>
    </html>
  );
}
```

--------------------------------

### useFlyvaTransition Composable

Source: https://github.com/owlsdepartment/flyva/blob/main/docs/api/nuxt.md

The `useFlyvaTransition` composable provides access to the transition controller, allowing programmatic control over transitions.

```APIDOC
## Composables

All composables are auto-imported by the module.

### useFlyvaTransition()

Returns the transition controller.

```ts
const { prepare, isRunning, stage, hasTransitioned } = useFlyvaTransition();
```

| Field | Type | Description |
|-------|------|-------------|
| `prepare(name, options, el?)` | `(string, PageTransitionOptions, Element?) => Promise<void>` | Start a transition by key |
| `isRunning` | `ComputedRef<boolean>` | Reactive flag - `true` while a transition is active |
| `stage` | `ComputedRef<PageTransitionStage>` | Current lifecycle stage (reactive) |
| `hasTransitioned` | `boolean` (getter) | `true` after the first transition |
```

--------------------------------

### Nuxt Default Lifecycle (Sequential JS)

Source: https://github.com/owlsdepartment/flyva/blob/main/docs/guide/modes/lifecycle.md

Explains the sequential JavaScript lifecycle for page transitions in Nuxt with Flyva, detailing the order of hooks like `beforeLeave`, `leave`, `afterLeave`, `beforeEnter`, `enter`, and `afterEnter`. It highlights how Vue's `<Transition>` component interacts with Flyva's promises for a smooth out-in effect.

```mermaid
sequenceDiagram
  participant L as FlyvaLink
  participant M as PageTransitionManager
  participant N as Nuxt page hooks
  participant V as Vue Transition

  L->>M: prepare
  L->>N: navigateTo
  N->>N: page:loading:start
  V->>V: onLeave starts
  V->>V: await getLeavePromise
  N->>N: page:start
  N->>M: beforeLeave / leave / afterLeave
  N->>V: resolveLeave
  V-->>V: leave promise done
  V->>V: DOM swap out-in
  V->>M: onBeforeEnter / onEnter
  M->>M: beforeEnter / enter / afterEnter
  V->>V: finish
  N->>N: page:finish (no manager enter)
```

--------------------------------

### useFlyvaLifecycle(callbacks, options?)

Source: https://github.com/owlsdepartment/flyva/blob/main/docs/api/next.md

Allows components to subscribe to transition lifecycle events. Callbacks are registered with the PageTransitionManager, ensuring they execute within the transition pipeline.

```APIDOC
## useFlyvaLifecycle(callbacks, options?)

### Description
Subscribe to transition lifecycle events from any component inside `FlyvaRoot`. The hook **always** registers with `PageTransitionManager` as an active hook, so your callbacks run in the same pipeline as transition implementations (including `prepare` on `run()`).

### Usage
```ts
useFlyvaLifecycle({
  beforeLeave(ctx) { console.log('leaving', ctx.name); },
  afterEnter(ctx)  { console.log('entered', ctx.name); },
});
```

### Parameters

- **`callbacks`** (`FlyvaLifecycleCallbacks`)
  - Description: An object containing functions to be called at different stages of the transition lifecycle.
  - **`prepare`**: `(context: PageTransitionContext) => void | Promise<void>` - With `blocking: false`, the manager does not wait for returned promises.
  - **`beforeLeave`**: `(context: PageTransitionContext) => void` - Sync only (matches `PageTransition`).
  - **`leave`**: `(context: PageTransitionContext) => void | Promise<void>` - With `blocking: true`, awaited in parallel with the transition’s `leave`.
  - **`afterLeave`**: `(context: PageTransitionContext) => void` - Sync only.
  - **`beforeEnter`**: `(context: PageTransitionContext) => void` - Sync only.
  - **`enter`**: `(context: PageTransitionContext) => void | Promise<void>` - With `blocking: true`, awaited in parallel with the transition’s `enter`.
  - **`afterEnter`**: `(context: PageTransitionContext) => void` - Sync only.
  - **`cleanup`**: `() => void` - Sync only; no context (matches `PageTransition.cleanup`).

- **`options`** (`UseFlyvaLifecycleOptions`, optional)
  - Description: Configuration options for the lifecycle hook.
  - **`blocking`** (`boolean`, default: `false`)
    - Description: When `false`, `prepare` / `leave` / `enter` callbacks run asynchronously without blocking the transition. When `true`, these callbacks (including async work) are awaited, and in-flight work is cleared on unmount.
```

--------------------------------

### Clone Flyva Repository

Source: https://github.com/owlsdepartment/flyva/blob/main/docs/about/contributing.md

Clone the Flyva repository to your local machine and navigate into the project directory.

```bash
git clone git@github.com:owlsdepartment/flyva.git
cd flyva
```

--------------------------------

### PageTransitionOptions Interface

Source: https://github.com/owlsdepartment/flyva/blob/main/docs/api/shared.md

Base interface for page transition options.

```APIDOC
## `PageTransitionOptions`

### Description
Base interface for page transition options.

### Fields
- `[key: string]: any` - Allows for arbitrary key-value pairs.
```