read me

teXt.0w.nz

teXt0wnz is a web-based text-mode art editor for ANSI, ASCII, XBIN, NFO and more. Create, edit, and share text-based artwork in your browser—with full support for auto-save/restore with local storage, real-time collaborative editing, modern build tools, and automated testing.

Draw in your browser now!

Table o' Contents

• Features
• Supported File Types
• Project Documentation
• Drawing & Editing Tools
• Key-bindings & Mouse/Touch Controls
• Tips & Workflow
• Build & Development
• Collaborative Server
• Docker Containerization
• Testing Suite
• Troubleshooting
• Browser Support
• Project History
• License & Greetz

Features

• Web-based text art drawing, also works offline as a PWA
  • No install required!
  • But easily installed as a Progressive Web Application to your device
• Comprehensive keyboard shortcuts and mouse controls
  • Draw using the keyboard, mouse, or touch screen
• Classic and modern fonts
  • Over 100 fonts from IBM PCs, Amiga, C64, and many more vintage/custom
• Full suite of drawing tools:
  • Keyboard, freehand brushes, fills, shapes, selection, and color picker
• Advanced color management
  • 16-color ANSI, iCE colors, real-time preview, color conflict resolution
• Import/export:
  • ANSI, BIN, XBIN, UTF-8 TXT, NFO, PNG
• Canvas operations:
  • Undo/redo, resizing, grid overlay, font selection, and full SAUCE metadata support
• Auto Save/Restore
  • Editor Setting saved to local storage for a consistent drawing sessions
  • Artwork saved to IndexedDB as you draw, auto-reloaded when the app is opened
  • Optimized binary data storage packing for efficient canvas persistence
• Collaborative server mode
  • For real-time multi-user editing
  • Optional and opt-in by users. See: Privacy
• Build tools:
  • Bun, Vite, PostCSS
• Automated tests:
  • Playwright, Vitest, Testing Library
• Robust linting and formatting:
  • Eslint and Prettier

File Types

• *.ans: ANSI art
• *.utf8.ans: UTF-8 ANSI for terminals
• *.bin: DOS-era BIN
• *.xbin: Modern XBIN
• *.nfo: Scene/release NFO
• *.txt: ASCII or other plain text
• *.png: Image (export support only)

Project Documentation

• The docs folder of this repo contains the raw markdown documentation files as well as example artwork to view and play around with.
• The wiki renders these files into easier to read webpages. The wiki also hosts the documentation images to keep the repo size more manageable.

Application Guides

• Interface - Visual guide to the user interface and options
• Editor Client - Frontend text art editor application
  • Hotkeys - Editor shortcuts reference
• Collaboration Server - Backend real-time collaboration server
• Architecture - System architecture and design overview
• PWA Install - Guide to installing the app on multiple platforms
• Privacy Policy - Privacy and data handling policy

Development Guides

• Project Structure - File and module organization guide
• Building and Developing - Development workflow and build process
• Testing - Triple headed testing guide (unit, dom, & e2e)
• CI/CD Pipeline - Continuous integration and deployment
• Webserver Configuration - Webserver setup and configuration
• Docker - Container deployment guide
• Other Tools - Additional development and deployment tools

Technical Specifications

• SAUCE Format - SAUCE metadata format specification
• XBin Format - XBin file format specification

Supplemental

• Fonts - Complete font reference and previews
• Logos - ASCII art logos for the project
• Examples - Sample artwork to view and edit
  • ANSI artwork by xeR0
  • XBin artwork by Hellbeard

Drawing & Editing Tools

Key Bindings & Mouse/Touch Controls

> [!NOTE] > See: docs/editor-client for more info.

Main Shortcuts

Color & Character

File & Canvas

Canvas Editing

Navigation (Keyboard Mode)

Selection Tool

Mouse / Touch

• Click/Touch: Draw
• Drag: Draw/Shape
• Alt+Click: Sample color/alt draw

Tips & Workflow

1. Start with Keyboard Mode for layout
2. Use Grid for alignment
3. Freestyle for shading/art
4. Character Brush for textures
5. Fill Tool for color blocks
6. Selection Tool for moving/copying
7. Save often (Ctrl+S)
8. F-keys for quick block chars
9. Alt+Click to sample colors
10. Undo/Redo freely (up to 1000 ops)

Build & Development

Requirements:

• node.js (v22.19+)
• bun (recommended) or npm

Quick Start:

install bun

npm i -g bun

install, build, and serve the app:

bun i      # or npm install
bun bake   # or npm run bake
bun www    # or npm run www

> [!NOTE] > See: docs/building-and-developing for more info.

Scripts:

Build Process:

• Uses Vite + plugins for static copy, sitemap, PWA/offline support
• Output: dist/
• Files are hashed for cache busting (e.g., editor-[hash].js, stylez-[hash].css)
• Customizable options via .env variables:
  • VITE_DOMAIN='https://text.0w.nz'
  • VITE_UI_DIR='ui/'
  • VITE_WORKER_FILE='websocket.js'

Build Output Structure:

dist/
├── index.html              # Main entry point
├── site.webmanifest        # PWA manifest
├── service.js              # Service worker
├── workbox-[hash].js       # Workbox runtime for caching
├── robots.txt              # Search engine directives
├── sitemap.xml             # Site map
├── humans.txt              # Humans.txt file
├── favicon.ico             # Favicon
└── ui/                     # UI assets directory
    ├── stylez-[hash].css   # Minified CSS (hashed)
    ├── icons-[hash].svg    # Icon sprite (hashed)
    ├── topazplus_1200.woff2  # Font file
    ├── fonts/              # Bitmap fonts (PNG format)
    ├── img/                # Images and icons
    └── js/                 # JavaScript bundles (all hashed)
        ├── editor-[hash].js      # Main entry
        ├── core-[hash].js        # Core modules (state, storage, compression)
        ├── canvas-[hash].js      # Canvas rendering with lazy font loading
        ├── tools-[hash].js       # Drawing tools
        ├── fileops-[hash].js     # File operations
        ├── network-[hash].js     # Collaboration
        ├── palette-[hash].js     # Color palette
        └── websocket.js          # Web Worker (not hashed)

> [!IMPORTANT] > DOMAIN is only used for robots.txt and sitemap.xml generation, all app urls are relative

Collaborative Server

Enable real-time multi-user editing with the built-in server.

Features:

• Canvas/chat persistence
• SSL/HTTP support
• Custom session names, save intervals
• Minimal overhead for real-time editing

Starting the server:

bun server [port] [options]
# or
node src/js/server/main.js

> [!TIP] > The server starts on port 1337 by default. so elite

Command-Line Options

> [!NOTE] > See: docs/collaboration-server for more info.

Docker Containerization

text0wnz is fully containerized, offering a streamlined deployment experience across different environments and architectures. Our containerization approach focuses on several key areas:

• Multi-Stage Build Architecture
• Security Hardening
• Performance Optimization
• Service Orchestration

Registry Support

Prebuilt images are avalable in linux/amd64 & linux/arm64 flavors from multiple repositories:

DockerHub:

docker pull xerostyle/text0wnz:latest

GitHub Container Registry:

docker pull ghcr.io/xero/text0wnz:latest

Building Locally

To build the container locally, you'll need Docker with Buildx support:

# Standard build for your local architecture
docker buildx build -t text0wnz:latest .

# Multi-architecture build (requires buildx setup)
docker buildx create --name mybuilder --use
docker buildx build --platform linux/amd64,linux/arm64 -t yourname/text0wnz:latest --push .

Running in Development Mode

Development mode provides hot-reloading and detailed logging for an optimized development experience:

docker run \
    --cap-add=NET_BIND_SERVICE \
    -e NODE_ENV=development \
    -p 80:80 \
    text0wnz:latest

The application will be available at http://localhost with WebSocket collaboration features enabled.

Running in Production Mode

For production deployments, use this configuration with your domain and a secure session key:

docker run \
    --cap-add=NET_BIND_SERVICE \
    -e DOMAIN=your.cool.domain.tld \
    -e SESSION_KEY=secure-production-key \
    -e NODE_ENV=production \
    -p 80:80 -p 443:443 \
    text0wnz:latest

This setup enables:

• Automatic HTTPS via Caddy's built-in certificate management
• Production-optimized performance settings
• Stricter security headers and content policies

> [!NOTE] > See: docs/docker for more info and advanced setup examples.

Testing Suite

Triple-Headed:

• Vitest: Unit/integration
• Testing Library: DOM/component
• Playwright: E2E/browser

> [!TIP] > view the latest: unit coverage report & e2e testing report

bun test:unit  # Run unit tests
bun test:e2e   # Run end2end tests

All tests run automatically in CI/CD. See the CI/CD Pipeline documentation for details on the automated testing, building, and deployment process.

> [!NOTE] > See: docs/testing for more info.

Troubleshooting

Common Issues:

• Build fails: Check Node.js version, reinstall deps
• Port in use: Change server port or stop other process
• SSL fails: Check cert/key files and permissions
• Client can't connect: Check server, proxy, firewall settings
• WebSocket drops: Validate nginx headers, trailing slash in proxy_pass
• Session not saving: Check write permissions, save interval
• Permissions: Confirm systemd user access
• Wrong port: Sync client/server configs

Still stuck? Open an issue with error logs and platform details.

Tips:

• Always use a process manager (systemd, forever)
• Lower save interval for busy sessions
• Use SSL in production (Let's Encrypt via Certbot, ACME-nginx, etc)
• WebSocket debugging: browser dev tools
• Restore session: rename backups as needed
• Review logs for details

> [!NOTE] > See: docs/trouble_shooting for more help.

Browser Support

> Works on desktop and mobile!

• Chrome/Chromium 95+
• Firefox 93+
• Safari 15+
• Edge 95+

Project History

The story of this project traces back to 2018, when AndyH joined Blocktronics—the legendary masters of the ANSI art scene. During his early days there, he created the original “ansiedit,” laying the groundwork for this application. However, his focus soon shifted to developing a desktop-only editor, which evolved into Moebius.

Around that time, xeR0 (then a member of Impure!ASCii and a devoted PabloDraw user) joined Blocktronics shortly after ansiedit’s release. xeR0 played the role of testing and debugging the app alongside Andy as he learned the dark arts of the blocks.

Fast forward a decade: xeR0 found himself sad he was still unable to use the new MoebiusXBIN fork to create text art on his iPad. With Andy’s blessing, xeR0 decided to revive the project—reimagining it from the ground up as a modern Progressive Web App. New features like optimized off-screen canvas', dirty pixel rendering, local storage sync, were added. But without Andy's core math this project would not be possible.

License & Greetz

<img src="https://gist.githubusercontent.com/xero/cbcd5c38b695004c848b73e5c1c0c779/raw/6b32899b0af238b17383d7a878a69a076139e72d/kopimi-sm.png&quot; align="left" height="222">

mad love & respect to ▒ Andy Herbert^67 - Moebius ░ grmmxi^imp! - MoebiusXBIN ░ Curtis Wensley - PabloDraw ░ Skull Leader^ACiD - ACiDDRAW ▒ & the scene!

All files and scripts in this repo are released MIT / kopimi! In the spirit of freedom of information, I encourage you to fork, modify, change, share, or do whatever you like with this project! ^c^v