# MasonEffect - LLM Context Guide

> **Primary AI Agent Guide**: This file (llms.txt) is the main reference for AI agents. Read this first.

## Project Overview

MasonEffect is a collection of animation effects library that supports React, Vue, Svelte, and vanilla JavaScript with tree-shaking support. Version 2.0.21.

**Package Name:** masoneffect  
**Installation:** `npm install masoneffect`  
**Repository:** https://github.com/fe-hyunsu/masoneffect.git  
**Homepage:** https://masoneffect.com

## Key Features

- Tree-shaking support: Import only the effects you need
- Multiple effects: Various animation effects in one package
- Framework agnostic: Works with React, Vue, Svelte, and vanilla JS
- TypeScript: Full TypeScript support with included types
- Optimized: Automatic code splitting and optimization
- GPU optimization: All effects automatically pause when not visible (IntersectionObserver) or when tab is hidden (Page Visibility API)

## Available Effects

1. **TextToParticle**: Converts text into animated particles with morphing effects
   - Use cases: Hero section titles, loading screens, banner text, interactive text effects
   - Keywords: text, particle, morph, title, banner, hero

2. **Count**: Animated number counting with intersection observer support
   - Use cases: Statistics display, number counters, animated numbers, scroll-triggered counters
   - Keywords: number, count, counter, stat, statistic

3. **Typing**: Typing animation effect with Korean character decomposition
   - Use cases: Code demonstrations, terminal simulations, typing effects, text reveal animations
   - Keywords: typing, type, typewriter, terminal, code, korean, 한글
   - Special: Korean characters are decomposed into consonants and vowels for realistic typing effect

4. **ScrollFadeIn**: Scroll-triggered fade-in animation effect with direction control and scroll container support
   - Use cases: Content reveal animations, scroll-triggered animations, entrance effects, internal scroll container animations
   - Keywords: scroll, fade-in, reveal, entrance, animation, scroll-reveal, scroll-container
   - Special: Supports multiple directions (top, right, bottom, left), flexible distance units (px, rem, em, %, vh, vw), and custom scroll container via root option

5. **TextSpin**: Text animation effect that splits text into individual characters and reveals them randomly with a spin effect
   - Use cases: Title animations, text reveal effects, character-by-character animations, random text appearances
   - Keywords: text-spin, text-animation, character-animation, random-text, text-reveal
   - Special: Each character appears with a random delay and 3D rotation effect. Inherits parent styles by default.

## Project Structure

```
masoneffect/
├── src/
│   ├── core/              # Vanilla JS core implementations
│   │   ├── textToParticle/
│   │   ├── count/
│   │   ├── typing/
│   │   ├── scrollFadeIn/
│   │   ├── textSpin/
│   │   └── utils/         # Shared utilities
│   │       └── visibilityManager.ts  # IntersectionObserver + Page Visibility API
│   ├── react/             # React components
│   │   ├── textToParticle/
│   │   ├── count/
│   │   ├── typing/
│   │   ├── scrollFadeIn/
│   │   └── textSpin/
│   ├── vue/               # Vue components
│   │   ├── textToParticle/
│   │   ├── count/
│   │   ├── typing/
│   │   ├── scrollFadeIn/
│   │   └── textSpin/
│   └── svelte/            # Svelte components
│       ├── textToParticle/
│       ├── count/
│       ├── typing/
│       ├── scrollFadeIn/
│       └── textSpin/
├── dist/                  # Built files (not in repo)
├── config/                # Vite + Vitest configs (Vue/Svelte library builds)
│   ├── vite/              # vite.config.*.mjs (thin) + library-config.mjs (shared factory)
│   └── vitest.config.mjs
├── examples/              # Usage examples
├── scripts/               # Build and utility scripts
├── AI_SETUP_GUIDE.md      # AI agent setup guide (IMPORTANT)
├── README.md              # Main documentation
└── package.json
```

## Import Paths (Tree-shaking)

**Critical:** Always use direct import paths for tree-shaking:

- React: `masoneffect/react/{effect}`
- Vue: `masoneffect/vue/{effect}`
- Svelte: `masoneffect/svelte/{effect}`
- Vanilla: `masoneffect/{effect}`

**Effects:**
- TextToParticle: `{framework}/textToParticle`
- Count: `{framework}/count`
- Typing: `{framework}/typing`
- ScrollFadeIn: `{framework}/scrollFadeIn`
- TextSpin: `{framework}/textSpin`

**Example:**
```typescript
// ✅ Correct - Tree-shaking works
import { TextToParticle } from 'masoneffect/react/textToParticle';

// ❌ Wrong - Imports all effects
import { TextToParticle } from 'masoneffect';
```

## Important Files for AI Agents

1. **llms.txt** (THIS FILE) - Primary AI agent guide
   - Complete project context
   - Environment detection logic
   - Framework-specific setup
   - Effect recommendation
   - Code templates

2. **README.md** - Human-readable documentation
   - Installation instructions
   - Usage examples for all frameworks
   - API documentation

3. **context7.json** - Structured project metadata for Context7 tools

4. **package.json** - Contains `aiAgentGuide` field

Note: AI_SETUP_GUIDE.md exists but llms.txt is the primary reference.

## Environment Detection

AI agents should detect:
- Framework: Check package.json for react/vue/svelte dependencies
- TypeScript: Check for tsconfig.json or typescript in devDependencies
- Build tool: Check for vite.config.js, webpack.config.js, or next in dependencies

## Effect Recommendation

Based on user request keywords:
- Text/Particle/Morph → TextToParticle
- Number/Count/Stat → Count
- Typing/Typewriter/Terminal/Code/Korean → Typing
- Scroll/Reveal/Entrance/FadeIn → ScrollFadeIn
- TextSpin/CharacterAnimation/RandomText/TextReveal → TextSpin

## Build System

- Core: Rollup (rollup.config.mjs)
- Vue/Svelte: Vite (`config/vite/vite.config.*.mjs`)
- Output: ESM (.mjs), CJS (.cjs), TypeScript declarations (.d.ts)

## Visibility Management & GPU Optimization

All effects use a shared `VisibilityManager` utility that combines:
- **IntersectionObserver**: Automatically pauses effects when they're not visible in the viewport
- **Page Visibility API**: Automatically pauses effects when the browser tab is hidden

This ensures optimal GPU usage by stopping animations when they're not needed. The VisibilityManager is bundled with each effect for tree-shaking compatibility.

## TypeScript Support

- All import paths include TypeScript types
- No need for @types/masoneffect
- Use `import type` for type-only imports

## Framework-Specific Notes

**React:**
- Use `useRef` for component refs
- Props are camelCase
- Import: `masoneffect/react/{effect}`

**Vue:**
- Use `ref()` for component refs
- Props are kebab-case in templates
- Import: `masoneffect/vue/{effect}`

**Svelte:**
- Use `bind:this={ref}` for ref binding
- Props are camelCase
- Import: `masoneffect/svelte/{effect}`

**Vanilla JS:**
- Use `new` keyword for instantiation
- Pass DOM element as first argument
- Call `destroy()` for cleanup
- Import: `masoneffect/{effect}`

## Quick Start for AI Agents

1. Read this file (llms.txt) first
2. Detect environment (framework, TypeScript, build tool)
3. Recommend effect based on user request keywords
4. Use framework-specific direct import path for tree-shaking
5. Generate complete working example from templates below

## Environment Detection Functions

```javascript
// Framework Detection
function detectFramework() {
  const pkg = require('./package.json');
  const deps = { ...pkg.dependencies, ...pkg.devDependencies };
  if (deps.react || deps['react-dom']) return 'react';
  if (deps.vue) return 'vue';
  if (deps.svelte) return 'svelte';
  return 'vanilla';
}

// TypeScript Detection
function detectTypeScript() {
  const fs = require('fs');
  return fs.existsSync('./tsconfig.json') || 
         require('./package.json').devDependencies?.typescript;
}

// Effect Recommendation
function recommendEffect(userRequest) {
  const request = userRequest.toLowerCase();
  const textKeywords = ['text', 'particle', 'morph', 'title', 'banner', 'hero'];
  const countKeywords = ['number', 'count', 'counter', 'stat', 'statistic'];
  if (textKeywords.some(kw => request.includes(kw))) return 'textToParticle';
  if (countKeywords.some(kw => request.includes(kw))) return 'count';
  return 'textToParticle'; // default
}
```

## Complete Code Templates

### React + TypeScript + TextToParticle
```tsx
import React, { useRef } from 'react';
import { TextToParticle } from 'masoneffect/react/textToParticle';
import type { TextToParticleRef } from 'masoneffect/react/textToParticle';

function App() {
  const ref = useRef<TextToParticleRef>(null);
  return (
    <div style={{ width: '100%', height: '400px' }}>
      <TextToParticle ref={ref} text="Hello World" particleColor="#fff" fontSize={80} />
    </div>
  );
}
```

### React + TypeScript + Count
```tsx
import React, { useRef } from 'react';
import { Count } from 'masoneffect/react/count';
import type { CountRef } from 'masoneffect/react/count';
import { easingFunctions } from 'masoneffect/react/count';

function App() {
  const ref = useRef<CountRef>(null);
  return <Count ref={ref} targetValue={1000} duration={2000} easing={easingFunctions.easeOutCubic} />;
}
```

### Vue 3 + Composition API + TextToParticle
```vue
<script setup lang="ts">
import { ref } from 'vue';
import { TextToParticle } from 'masoneffect/vue/textToParticle';
import type { TextToParticleRef } from 'masoneffect/vue/textToParticle';
const textRef = ref<TextToParticleRef | null>(null);
</script>
<template>
  <div style="width: 100%; height: 400px;">
    <TextToParticle ref="textRef" text="Hello World" particle-color="#fff" :font-size="80" />
  </div>
</template>
```

### Vue 3 + Composition API + Count
```vue
<script setup lang="ts">
import { ref } from 'vue';
import { Count } from 'masoneffect/vue/count';
import type { CountRef } from 'masoneffect/vue/count';
import { easingFunctions } from 'masoneffect/vue/count';
const countRef = ref<CountRef | null>(null);
</script>
<template>
  <Count ref="countRef" :target-value="1000" :duration="2000" :easing="easingFunctions.easeOutCubic" />
</template>
```

### Svelte + TypeScript + TextToParticle
```svelte
<script lang="ts">
import { TextToParticle } from 'masoneffect/svelte/textToParticle';
import type { TextToParticleRef } from 'masoneffect/svelte/textToParticle';
let textRef: TextToParticleRef | null = null;
</script>
<div style="width: 100%; height: 400px;">
  <TextToParticle bind:this={textRef} text="Hello World" particleColor="#fff" fontSize={80} />
</div>
```

### Vanilla JS + TextToParticle
```javascript
import { TextToParticle } from 'masoneffect/textToParticle';
const container = document.querySelector('#container');
const effect = new TextToParticle(container, { text: 'Hello World', particleColor: '#fff', fontSize: 80 });
effect.morph({ text: 'New Text' });
effect.destroy();
```

### Vanilla JS + Count
```javascript
import { Count } from 'masoneffect/count';
import { easingFunctions } from 'masoneffect/count';
const container = document.querySelector('#count-container');
const count = new Count(container, {
  targetValue: 1000,
  duration: 2000,
  easing: easingFunctions.easeOutCubic,
  threshold: 0.5,
  triggerOnce: true
});
```

### React + TypeScript + Typing
```tsx
import React, { useRef } from 'react';
import { Typing } from 'masoneffect/react/typing';
import type { TypingRef } from 'masoneffect/react/typing';
function App() {
  const ref = useRef<TypingRef>(null);
  return <Typing ref={ref} text="Hello World 안녕하세요" speed={50} showCursor={true} />;
}
```

### Vue 3 + Composition API + Typing
```vue
<script setup lang="ts">
import { ref } from 'vue';
import { Typing } from 'masoneffect/vue/typing';
const typingRef = ref(null);
</script>
<template>
  <Typing ref="typingRef" text="Hello World 안녕하세요" :speed="50" :show-cursor="true" />
</template>
```

### Vanilla JS + Typing
```javascript
import { Typing } from 'masoneffect/typing';
const container = document.querySelector('#typing-container');
const typing = new Typing(container, {
  text: 'Hello World 안녕하세요',
  speed: 50,
  showCursor: true,
  cursorChar: '|'
});
```

### React + TypeScript + ScrollFadeIn
```tsx
import React, { useRef } from 'react';
import { ScrollFadeIn } from 'masoneffect/react/scrollFadeIn';
import type { ScrollFadeInRef } from 'masoneffect/react/scrollFadeIn';
function App() {
  const ref = useRef<ScrollFadeInRef>(null);
  return (
    <ScrollFadeIn ref={ref} direction="bottom" distance="50px" duration={800}>
      <div>Content that fades in on scroll</div>
    </ScrollFadeIn>
  );
}
```

### Vue 3 + Composition API + ScrollFadeIn
```vue
<script setup lang="ts">
import { ref } from 'vue';
import { ScrollFadeIn } from 'masoneffect/vue/scrollFadeIn';
const scrollFadeInRef = ref(null);
</script>
<template>
  <ScrollFadeIn direction="bottom" distance="50px" :duration="800">
    <div>Content that fades in on scroll</div>
  </ScrollFadeIn>
</template>
```

### Svelte + TypeScript + ScrollFadeIn
```svelte
<script lang="ts">
import { ScrollFadeIn } from 'masoneffect/svelte/scrollFadeIn';
let scrollFadeInRef: any = null;
</script>
<ScrollFadeIn bind:this={scrollFadeInRef} direction="bottom" distance="50px" duration={800}>
  <div>Content that fades in on scroll</div>
</ScrollFadeIn>
```

### Vanilla JS + ScrollFadeIn
```javascript
import { ScrollFadeIn } from 'masoneffect/scrollFadeIn';
const container = document.querySelector('#scroll-fade-in-container');
// For viewport-based scrolling (default)
const scrollFadeIn = new ScrollFadeIn(container, {
  direction: 'bottom',
  distance: '50px',
  duration: 800,
  threshold: 0.1,
  triggerOnce: false
});
// For internal scroll container
const scrollContainer = document.querySelector('.scroll-container');
const scrollFadeInInContainer = new ScrollFadeIn(container, {
  direction: 'bottom',
  distance: '50px',
  root: scrollContainer, // Specify scroll container element
  threshold: 0.1
});
```

### React + TypeScript + TextSpin
```tsx
import React, { useRef } from 'react';
import { TextSpin } from 'masoneffect/react/textSpin';
import type { TextSpinRef } from 'masoneffect/react/textSpin';

function App() {
  const ref = useRef<TextSpinRef>(null);
  return (
    <TextSpin
      ref={ref}
      text="Hello World"
      delay={0.2}
      duration={0.6}
      randomDelay={2}
      threshold={0.1}
      style={{ fontSize: '2rem', color: '#fff' }}
    />
  );
}
```

### Vue 3 + Composition API + TextSpin
```vue
<script setup lang="ts">
import { TextSpin } from 'masoneffect/vue/textSpin';
</script>

<template>
  <TextSpin
    text="Hello World"
    :delay="0.2"
    :duration="0.6"
    :random-delay="2"
    :threshold="0.1"
    style="font-size: 2rem; color: #fff"
  />
</template>
```

### Svelte + TypeScript + TextSpin
```svelte
<script lang="ts">
import { TextSpin } from 'masoneffect/svelte/textSpin';
</script>

<TextSpin
  text="Hello World"
  delay={0.2}
  duration={0.6}
  randomDelay={2}
  threshold={0.1}
  style="font-size: 2rem; color: #fff"
/>
```

### Vanilla JS + TextSpin
```javascript
import { TextSpin } from 'masoneffect/textSpin';
const container = document.querySelector('#text-spin-container');
const textSpin = new TextSpin(container, {
  text: 'Hello World',
  delay: 0.2,
  duration: 0.6,
  randomDelay: 2,
  threshold: 0.1,
  triggerOnce: false
});
// Update text
textSpin.updateText('New Text');
```

## Critical Rules

1. **Always use direct import paths for tree-shaking**
   - ✅ `import { TextToParticle } from 'masoneffect/react/textToParticle'`
   - ❌ `import { TextToParticle } from 'masoneffect'`

2. **Framework-specific import paths**
   - React: `masoneffect/react/{effect}`
   - Vue: `masoneffect/vue/{effect}`
   - Svelte: `masoneffect/svelte/{effect}`
   - Vanilla: `masoneffect/{effect}`

3. **TypeScript types are included** - No @types package needed

4. **Vue props are kebab-case in templates**, camelCase in script

## Version

Current version: 2.0.21

## License

MIT