ASCII Motion

A web app for creating and animating ASCII/ANSI art.

Current deployed version: https://ascii-motion.app

See what people are making in the community gallery: https://ascii-motion.app/community

Learn more on the landing page: https://ascii-motion.com

Check the usage documentation at: https://docs.ascii-motion.com

🎨 Current Features

• Grid-based ASCII Art Editor with full drawing toolset (pencil, eraser, fill, rectangle, ellipse, bezier pen, text, gradient, and more)
• Convert images or video assets to ASCII art with fine-tuned rendering control and frame rate matching
• Custom Color and Character Palettes including presets and import/export
• Apply effects and filters to existing animations
• Generate animations using procedural animation tools
• Layer-Based Timeline with keyframe interpolation for position, scale, rotation, and anchor point
• Multi-Layer Compositing with z-order, visibility, solo, lock, and layer groups
• Keyframe Animation with cubic bezier easing editor and presets
• Export Formats: Images (PNG, JPEG, SVG), Videos (MP4, WebM), React Components, CLI Components (Ink, OpenTUI, BubbleTea), Text, HTML, and session files
• Publish to community gallery and explore what people are making
• MCP Server (ascii-motion-mcp) for AI-assisted animation creation

🚀 Quick Start

Prerequisites

• Node.js 18+
• npm or yarn

Installation

git clone https://github.com/cameronfoxly/Ascii-Motion.git
cd Ascii-Motion
npm install

Development

npm run dev

Build

npm run build

🚀 Deployment

This monorepo contains three separate deployable apps, each with its own Vercel project:

App	Domain	Deploy From	Command
Main App	ascii-motion.app	Root	npm run deploy
Marketing	ascii-motion.com	packages/web/marketing	npx vercel --prod
Docs	docs.ascii-motion.com	packages/web/docs-site	npx vercel --prod

Main App Deployment (Root)

The main ASCII art editor deploys with automated versioning:

Available Deployment Commands

Command	Version Increment	Use Case
npm run deploy	Patch (2.0.0 → 2.0.1)	Bug fixes, small updates
npm run deploy:major	Minor (2.0.1 → 2.1.0)	New features, significant improvements
npm run deploy:preview	None	Testing deployments, preview branches

Manual Version Commands

For version management without deployment:

# Increment patch version (2.0.0 → 2.0.1)
npm run version:patch

# Increment minor version (2.0.1 → 2.1.0) 
npm run version:minor

# Increment major version (2.1.0 → 3.0.0)
npm run version:major

Marketing & Docs Site Deployment

These deploy separately from the main app using the Vercel CLI:

# Marketing site (ascii-motion.com)
cd packages/web/marketing
npx vercel --prod

# Docs site (docs.ascii-motion.com)
cd packages/web/docs-site
npx vercel --prod

See the README in each package for detailed deployment instructions.

🏗️ Tech Stack

• React 19 - UI framework
• TypeScript - Type safety (strict mode)
• Vite - Build tool and dev server
• Tailwind CSS v3 - Styling
• Shadcn/ui - UI components
• Zustand - State management
• Lucide React - Icons
• Vitest - Testing framework

📦 Project Structure

This is a monorepo with dual licensing and separate deployment targets:

• packages/core/ - Open source core features (MIT License)

  • Canvas editor, drawing tools, animation system
  • Export features (PNG, SVG, GIF, MP4, etc.)
  • All UI components and utilities

• packages/premium/ - Premium features (Proprietary License)

  • User authentication (email-based)
  • Cloud project storage (Supabase)
  • Payment integration (future)

• packages/web/marketing/ - Marketing site (Proprietary License)

  • Deploys to ascii-motion.com
  • Next.js 16 + React 19
  • Has its own package.json and Vercel project

• packages/web/docs-site/ - Documentation site (Proprietary License)

  • Deploys to docs.ascii-motion.com
  • Next.js 15 + MDX
  • Has its own package.json and Vercel project

See docs/MONOREPO_SETUP_GUIDE.md for details.

🏛️ Core App Architecture

src/
├── components/
│   ├── common/         # Shared/reusable components
│   ├── features/       # Complex functional components (canvas, import/export)
│   │   └── timeline/   # Layer list, track area, keyframe editor, ruler
│   ├── tools/          # Tool-specific components
│   └── ui/             # Shadcn UI components
├── stores/
│   ├── timelineStore.ts   # PRIMARY: layers, content frames, keyframes, groups
│   ├── canvasStore.ts     # Working canvas buffer for active layer
│   ├── animationStore.ts  # Legacy compatibility adapter
│   └── toolStore.ts       # Tools, settings, undo/redo history
├── types/
│   ├── timeline.ts        # Layer, ContentFrame, Keyframe, PropertyTrack types
│   └── easing.ts          # Cubic bezier interpolation engine
├── hooks/              # Custom React hooks
├── utils/
│   ├── layerCompositing.ts    # Multi-layer compositing with transforms
│   ├── layerTransformUtils.ts # Screen↔local coordinate conversion
│   └── sessionMigration.ts    # v1→v2 format migration
├── constants/          # App configuration
└── pages/              # Page components

📋 Development Status

This is currently maintained entirely by me, an animator and brand designer with next to no experience with building tools. This has been vibe-coded into existence using GitHub Copilot in VScode, using mostly Claude Opus 4.6, with the occasional GPT-5.2-Codex when Claude gets stumped. Please forgive any messy or unusal structure or vibe-code artifacts, I'm trying my best!

Upcoming features planned

• Refactor of effects system to integrate with v2 timeline, so that effects are procedural and can be keyframed across time.
• Update the ellipse and rectangle tool to use the bezier pen tool's vector system
• Add a "find edges" algorithm to media import using ASCII line characters
• Update bezier tool and media import conversion functions to get more accurate shape edges
• Add a post processing shader effect layer for things like CRT Effects, Chromatic abberation, bloom, etc.

Got an idea for a new feature? Open an issue!

📖 Documentation

• Copilot Instructions - Architecture overview and development guidelines
• Contributing Guide - How to contribute
• Monorepo Setup Guide - Dual-license structure
• Layer Timeline Refactor Plan - v2.0.0 architecture design
• Technical Documentation - Implementation guides and feature documentation. Each .md file was created as a planning document when that feature was worked on and may not be currently still in date, but may be useful for contributors to understand the architecture and design decisions.
• Development Tools - Test scripts and debugging utilities

🤝 Contributing

We welcome contributions to the open-source core (packages/core/)!

For Open Source Contributors

What you can contribute:

• ✅ New drawing tools and brushes
• ✅ Animation features and effects
• ✅ Export formats and converters
• ✅ UI/UX improvements
• ✅ Bug fixes and performance optimizations
• ✅ Documentation and examples

What is proprietary:

• ❌ Authentication system (packages/premium/)
• ❌ Cloud storage features
• ❌ Payment integration

Monorepo Setup for Contributors

Important: This project uses a monorepo structure with a private Git submodule for premium features.

Project Structure

Ascii-Motion/               # Main repository (public)
├── packages/
│   ├── core/              # Open source (MIT) - You work here!
│   │   ├── src/
│   │   │   ├── components/
│   │   │   ├── stores/
│   │   │   ├── hooks/
│   │   │   └── utils/
│   │   └── package.json
│   └── premium/           # Private submodule (Proprietary)
│       └── (not accessible to contributors)
├── src/                   # Legacy code (being migrated to core)
└── package.json           # Root workspace config

Getting Started

1. Clone the repository:

   git clone https://github.com/cameronfoxly/Ascii-Motion.git
   cd Ascii-Motion
   npm install

2. The packages/premium/ folder will be empty - This is expected! You don't need it to contribute. The app runs without premium features.

3. Development:

   npm run dev          # Start dev server
   npm run test:run     # Run tests (343 tests)
   npm run lint         # Check code quality
   npm run build        # Production build

4. All source code lives in src/ — not in packages/core/ (which is a shared UI component library). Your contributions go directly in src/.

5. Key files to know:

   • src/stores/timelineStore.ts — Primary state (layers, keyframes, timeline)
   • src/hooks/useKeyboardShortcuts.ts — All keyboard shortcuts and undo/redo
   • src/components/features/ToolPalette.tsx — Tool UI and options
   • src/utils/exportRenderer.ts — All export format rendering
   • src/types/timeline.ts — Core type definitions

Import Paths

When writing code in src/, use these import patterns:

// Stores
import { useTimelineStore } from '../stores/timelineStore';
import { useCanvasStore } from '../stores/canvasStore';
import { useToolStore } from '../stores/toolStore';

// Utils
import { screenToLocal } from '../utils/layerTransformUtils';
import { compositeLayersAtFrame } from '../utils/layerCompositing';

// Types
import type { Layer, ContentFrame, KeyframeId } from '../types/timeline';

// UI Components
import { Button } from '../components/ui/button';

What Happens to Premium Code?

• The main app (src/ folder) imports from both core and premium
• When you run npm run dev from the root, both packages are built
• If packages/premium/ is missing, the app will still work but without auth/cloud features
• Your contributions to core are completely independent of premium features

Testing Your Changes

# Run the full test suite (343 tests)
npm run test:run

# Run tests in watch mode during development
npm test

# Lint check
npm run lint

# TypeScript type check
npx tsc --noEmit

# Production build verification
npm run build

Submitting Pull Requests

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-tool
3. Make your changes in packages/core/
4. Commit with clear messages: git commit -m "Add gradient brush tool"
5. Push to your fork: git push origin feature/amazing-tool
6. Open a Pull Request to the main branch

PR Checklist:

• Changes don't modify premium code (packages/premium/)
• Code follows existing patterns and TypeScript strict mode
• Tests pass (npm run test:run)
• No linting errors (npm run lint)
• Build succeeds (npm run build)
• New features include tests where applicable
• PR description explains what and why

See CONTRIBUTING.md for detailed guidelines.

📜 License

Dual License:

• Core Features (packages/core/) - MIT License

  • Free to use, modify, and distribute
  • No restrictions on commercial use

• Premium Features (packages/premium/) - Proprietary License

  • Authentication and cloud storage
  • Unauthorized copying or distribution prohibited

See individual LICENSE files for full details.

---

Made with ❤️ for the ASCII art community