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

🎨 Current Features

• Grid-based ASCII Art Editor with full drawing toolset
• Animation Timeline for frame-by-frame editing and onion skinning
• Custom Color and Character Palettes including presets and import/export features
• Convert images or video assets to ASCII art, with fine-tuned rendering control
• Apply effects and filters to existing animations
• Generate animations using a selection of procedural animation tools.
• Multiple Export Formats: Images (PNG, JPEG, SVG), Videos (MP4, WebM), Text files, JSON, HTML, and full session export
• Publish to community gallery and explore what people are making.

🚀 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 (0.1.23 → 0.1.24)	Bug fixes, small updates, content changes
npm run deploy:major	Minor (0.1.23 → 0.2.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 (0.1.23 → 0.1.24)
npm run version:patch

# Increment minor version (0.1.23 → 0.2.0) 
npm run version:minor

# Increment major version (0.2.15 → 1.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 18 - UI framework
• TypeScript - Type safety
• Vite - Build tool and dev server
• Tailwind CSS - Styling
• Shadcn/ui - UI components
• Zustand - State management
• Lucide React - Icons

📦 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  
│   ├── tools/          # Tool-specific components
│   └── ui/             # Shadcn UI components
├── stores/             # Zustand state management
├── types/              # TypeScript definitions
├── hooks/              # Custom React hooks
├── utils/              # Utility functions
└── constants/          # App configuration

📋 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 Sonnet 4, with the occasional GPT-5 when Claude gets stumped. Please forgive any messy or unusal structure or vibe-code artifacts, I'm trying my best!

Where I'm at with the concept:

✅ Phase 1: Foundation & Core Editor (Complete)

• Project scaffolding and configuration
• State management architecture (Zustand stores: canvas, animation, tools)
• Type definitions and constants
• UI components and styling (Tailwind CSS + shadcn/ui)
• Canvas grid component with full rendering
• Complete drawing tool suite (pencil, eraser, paint bucket, rectangle, ellipse, selection, eyedropper)
• Zoom and navigation system (20%-400% zoom, pan controls, +/- hotkeys)
• Character palette interface
• Color picker
• Selection and advanced editing (copy/paste with visual preview)
• Undo/redo functionality
• Keyboard shortcuts (Cmd/Ctrl+C, V, Z, Shift+Z, Alt for temporary eyedropper, +/- for zoom)
• High-DPI canvas rendering - Crisp text quality on all displays
• Performance optimizations - 60fps rendering with batched updates
• Gap-free drawing tools - Smooth line interpolation for professional drawing
• Performance monitoring - Real-time metrics overlay (Ctrl+Shift+M)
• Theme system (dark/light mode)

✅ Phase 2: Animation System (Complete)

• Timeline component with frame management
• Playback controls with variable speed
• Frame thumbnails with visual indicators
• Onion skinning with performance caching
• Animation state management and synchronization
• Keyboard shortcuts (Shift+O for onion skinning, Ctrl+N for new frame, Ctrl+D for duplicate frame, Ctrl+Delete/Backspace for delete frame)

✅ Phase 3: Export/Import System (Complete)

• High-DPI image export (PNG, JPEG, SVG) with device pixel ratio scaling and quality controls
• SVG vector export with text-as-outlines, grid, background, and formatting options
• Complete session export/import (.asciimtn files with custom color & character palettes)
• Typography settings preservation (font size, spacing)
• Export UI with format-specific dialogs
• Import video/image files and convert to ASCII

✅ Phase 4: Advanced Tools (Next) (complete...for now

• Brush sizing and shape
• Advanced color palettes beyond ANSI
• Re-color brush (change colors without affecting characters)
• Gradient fill tool
• Figlet text system
• Draw boxes and tables with ascii characters

✅ Phase 5: Testing and bug bashing

• FIX ALL THE BUGS!!!
• Sweeten tool set with quality of life improvements
• Address accessibilty issues

💸 Phase 6: Setup database and auth

• Set up database for user account creation and project saving
• Version history for projects
• Set up paid tiers to cover server costs if we start getting traction????

🤝 Phase 7: Community and Marketing

• Build a community sharing site to share and remix projects
• Create live link sharing tools
• Make marketing site
• Create tutorial series
• Create help and tool tip for in product on boarding

📖 Documentation

• Product Requirements Document - Complete feature specifications
• Development Guide - Setup and project structure
• Copilot Instructions - Development guidelines
• Monorepo Setup Guide - Dual-license structure and migration
• Technical Documentation - Comprehensive implementation guides, plans, and feature documentation
• 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.

3. All your work happens in packages/core/:

   # Core package has its own dev server
   cd packages/core
   npm run dev

4. Development workflow:

   • Make changes in packages/core/src/
   • The dev server will hot-reload your changes
   • Test thoroughly before submitting PR
   • Follow existing code patterns and TypeScript conventions

Import Paths

When writing code in packages/core/, use these import patterns:

// ✅ Correct - Importing from core package
import { Button } from '@ascii-motion/core/components';
import { useCanvas } from '@ascii-motion/core/hooks';
import { CanvasStore } from '@ascii-motion/core/stores';

// ❌ Incorrect - Don't import from premium
import { AuthContext } from '@ascii-motion/premium/auth';

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

# Test from core package (recommended for contributors)
cd packages/core
npm run dev        # Opens Storybook or component sandbox
npm run test       # Run unit tests
npm run lint       # Check code style

# Test in full app (optional)
cd ../..           # Back to root
npm run dev        # Runs full app (may show warnings about missing premium)

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 are only in packages/core/ (no premium code)
• Code follows existing patterns and TypeScript conventions
• Tests pass (npm run test)
• No linting errors (npm run lint)
• Documentation updated if needed
• 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