Grout Studio & Library

A Text-to-Graphics Protocol for Procedural Pixel Art

Grout is a lightweight, AI-friendly graphics protocol that stores pixel art as JSON "recipes" instead of binary images. It includes both a library for rendering and a full-featured web-based editor.

Table of Contents

• Overview

• Features

• Quick Start

• Installation

• Documentation

• Examples

• Getting Help

• License

Overview

Grout is a text-based graphics protocol that stores pixel art as JSON instead of binary images. It is designed to be compact, easy for LLMs to generate, and flexible for runtime edits such as flips, rotations, or palette swaps.

Why Choose Grout?

Grout provides a comprehensive texture system (TEX) that outclasses other libraries with:

• Full-featured visual editor with timeline and animation support
• Multiple rendering backends (Canvas, WebGL, WebGPU)
• Advanced texture utilities including noise generation, pattern builders, and instant presets
• 32x32 texture optimization perfect for retro gaming (PS1/N64/DOOM aesthetics)
• Comprehensive documentation with migration guides and cookbooks
• Three.js integration with optimized examples
• Production-oriented local release checks for package, docs, and examples

Features

Grout Studio (Visual Editor)

• Drawing tools for pixels, lines, rectangles, and circles
• Multi-frame animation timeline with onion skinning
• Palette management integration
• Import/export workflows for JSON and PNG sprite sheets
• Dark theme with responsive design
• Undo/redo with keyboard shortcuts
• Live preview with multiple zoom levels
• Procedural variation system for randomized pixel art
• GroutPaintEngine — embeddable headless paint engine for use in any vanilla JS or React app (no framework required)

Grout Library (Core Rendering)

• Zero-dependency JavaScript core for rendering
• Canvas, WebGL, and WebGPU rendering backends
• Public grout-render/adapters helpers for Three.js, Phaser 3, and Phaser 4 texture payloads
• Public grout-render/worker helpers for versioned module-worker rendering, stale request suppression, and sync fallback
• Public grout-render/protocol helpers for format versioning, strict/compat parsing, and path-based validation errors
• Compact JSON shorthands for code golfing
• Multiple compact path formats for 60-75% size reduction
• Frame modifiers for rotation, flip, and hue shifting
• Advanced texture utilities for retro gaming
• TEX pattern generation functions
• Preset templates for instant 32x32 textures
• Variation engine for procedural generation with seeded random
• Sprite packing utilities for data compression and character count reduction
• Semantic color naming for LLM understanding (color to human-readable names)
• Font & Atlas optional module (grout-render/font-atlas, browser/ESM only) — TextureAtlas, SDFFont, sprite slicing, and WebGL/WebGPU SDF shaders
• Worker optional module (grout-render/worker, ESM only) — structured render requests, transferable buffers, and client helpers
• Protocol optional module (grout-render/protocol, ESM only) — CURRENT_FORMAT_VERSION, parseSpec(), validateSpec(), and migrateSpec()

Grout Tools (Utilities)

• SVG conversion utilities (SVG → Grout, Grout → SVG) with optional sprite packing

• Color palette extraction from images with semantic names

• Semantic color naming (RGB/hex → human-readable color names)

• Texture generation and procedural art tools

• Bezier curve utilities for smooth paths

• Sprite packing for efficient binary data compression (30-75% size reduction)

Quick Start

Follow the canonical guide in docs/GETTING_STARTED.md for a step-by-step walkthrough of running the studio or using the library in your project.

Quality gate

Run the repository-wide integrity check before major merges:

npm ci
npm run qa

npm ci uses the committed lockfile for reproducible dev tooling. npm run qa runs lint checks, the full headless browser suite, the Node-compatible coverage subset, and export/declaration parity validation in one command.

Runtime/package consumers remain supported on Node >=14.0.0. Local release tooling uses the locked dev toolchain and requires Node 20 LTS or Node 22+; .nvmrc records Node 22 as the default local release target.

Installation

For full installation options (CDN, npm, direct file copy, and studio setup), see docs/GETTING_STARTED.md.

Documentation

Getting Started

• Getting Started
• API Reference
• Rendering

Texture Creation

• 32x32 Texture Cookbook - Master retro texture creation
• Variation System - Procedural variation and randomization

Advanced Topics

• Color Utilities
• Sprite Packing - Data compression and character count reduction
• Naming Conventions
• Testing
• Performance
• Architecture
• Integrations
• LLM Cheat Sheet

Examples

• Examples Guide
• Examples Gallery

Getting Help

If you have questions or run into issues:

• Bug Reports: Open an issue with steps to reproduce
• Feature Requests: Open an issue describing your use case
• Questions: Check existing issues or start a discussion in GitHub Discussions
• Contributing: See CONTRIBUTING.md for guidelines
• Planned Work: See docs/dev/TODO.md for planned features and open discussion items

License

MIT License. See LICENSE.