CHROMALUM

CHROMALUM is a browser-based React/Vite app for pixel art and algebraic color theory, built around an eight-level GRB Binary Tone model. It combines canvas drawing, color remapping, glaze variants, gallery and Map analysis views, plus Theory and Music tabs that explore the same 4:2:1 GRB level structure through GF(2)^3, RGB cube geometry, the Fano plane, Hamming codes, and related polyhedral structures.

Demo: minoreality.github.io/chromalum

Screenshots

Glaze tab	Gallery tab

Theory tab	Music tab

Features

• Pixel-art drawing with brush, eraser, fill, line, rectangle, ellipse, undo, redo, pan, zoom, image import, PNG export, and mobile touch support.
• Eight-level GRB Binary Tone source model mapped into chromatic color variants.
• Glaze layer for per-pixel color-variant overrides without changing the source tone structure.
• Gallery generation for color-pattern variants, bookmarks, previews, and PNG exports.
• Map analysis views for composition, model tone, connected regions, gradients, boundary distance, isolation, and local diversity.
• Theory tab explaining the color system through binary levels, XOR, cube geometry, the Fano plane, Hamming codes, tetrahedra, octahedra, and compound polyhedra.
• Music tab connecting the same algebraic structures to chords, parity, Hamming decoding, rhythmic grids, and sonification.
• English/Japanese UI text with persistent language selection.

Design Intent

CHROMALUM keeps one compact data model at the center: every source pixel stores one of eight tone levels, while color mapping and optional glaze overrides select chromatic variants for those levels. This lets the app treat drawing, gallery generation, analysis, mathematical diagrams, and sonification as different views of the same discrete color structure instead of separate feature islands.

The algebraic layer and palette layer are related but distinct. XOR, Fano, Hamming, and K8 operate on the eight binary level labels. Chromatic variants are representatives from the RGB cube's maximum-saturation hue loop (the pure-hue loop, defined by maximum channel 1 and minimum channel 0) that project to those labels by equal GRB tone; their continuous coordinates are not themselves GF(2)^3 vectors.

The implementation favors browser-native primitives and explicit data structures over heavy runtime dependencies. Canvas buffers use typed arrays, large pixel operations can run in Web Workers with synchronous fallbacks, undo/redo stores compact diffs, and autosave uses IndexedDB.

Technical Highlights

• Canvas rendering: direct pixel-buffer rendering with dirty-rect updates.
• Image input: a documented lossy sRGB code-value estimator, kept separate from the canonical-coordinate output adapter.
• Performance: typed arrays, reusable buffers, scanline flood fill, and worker-backed flood fill and pixel analysis.
• Undo/redo: compressed diffs with optional glaze override deltas.
• Persistence: debounced IndexedDB autosave with pagehide/visibility flush.
• Offline support: production builds include a service worker that pre-caches the app shell, icons, workers, and lazy-loaded Music tab chunk for offline reopening.
• Testing: Vitest unit tests plus Playwright end-to-end, accessibility, and PWA checks covering canvas pixels, save flows, gallery previews, glaze clearing, Theory rendering, offline behavior, mobile touch input, and stable layouts.
• Documentation screenshots: the README keeps representative Theory and Music images in docs/assets/ for visitors browsing the repository.
• Quality gates: TypeScript strict mode, ESLint, Prettier, Knip dead-code detection, coverage thresholds, CodeQL, Dependabot, pinned GitHub Actions, and GitHub Pages deployment.

Offline and Local Data

CHROMALUM can be reopened offline after the production app has loaded once and the service worker has cached the app shell. The current work state is autosaved in this browser on this device using IndexedDB; where supported, the app makes a best-effort request for persistent browser storage after a successful autosave.

Browser storage is not a backup: clearing site data, using private browsing, or switching devices can remove local work. Save PNG exports for images you need to keep outside the browser.

Architecture

For the detailed technical architecture, see docs/architecture.md.

src/
  components/  React panels, controls, diagrams, and visualizations
  components/music/
               Music-tab controls, diagrams, and sonification widgets
  components/theory/
               Theory-tab diagrams and interaction helpers
  hooks/       UI state, canvas interaction, workers, export, pan/zoom, audio
  music/       Audio graph helpers, playback runners, schedules, and sequences
  drawing/     Paint primitives, flood fill, dirty rects, render buffers
  state/       Canvas reducer, color reducer, contexts, undo diff logic
  workers/     Flood fill and pixel-analysis worker entry points
  utils/       IndexedDB persistence, pixel analysis, ring buffer, errors
  data/        Theory, hex, and music data sets
  i18n/        English/Japanese translations
  styles/      Shared CSS and design tokens
  assets/      Static app assets used by the React UI
e2e/           Playwright browser flows
docs/          Research docs, architecture notes, licenses, and screenshots

Development

This project uses Node.js and npm. The expected toolchain is pinned through Volta:

node 24.14.1
npm 11.9.0

Install dependencies:

npm install

Install or refresh the Playwright Chromium browser after first setup or after @playwright/test updates:

npm run playwright:install

Start the local development server:

npm run dev

Start the development server on the fixed local address used for manual checks:

npm run dev:local

For Theory research and editing, start the dedicated development entry:

npm run dev:theory

This displays all Theory sections without initializing the editor, drawing, Gallery, or PWA modules.

Create a production build:

npm run build

Create an itch.io-style relative-path build:

npm run build:itch

Run type checks:

npm run typecheck:app
npm run typecheck:tooling
npm run typecheck:all

Run unit tests:

npm test

Run the focused Theory copy guard test:

npm run test:theory-copy

Run coverage:

npm run test:coverage

Run dead-code detection:

npm run deadcode

Run local performance benchmarks:

npm run benchmark

Run end-to-end tests:

npm run test:e2e

Run linting and formatting checks:

npm run lint
npm run format:check

Run the focused type and test checks for Theory work:

npm run verify:theory

Run the standard local verification set before pushing:

npm run verify

Run the same verification command used by the pre-push hook:

npm run verify:prepush

Run broader browser/PWA or full coverage verification:

npm run verify:e2e
npm run verify:full

To inspect canvas performance locally, open the app with ?debugPerf appended to the URL. The console reports rolling avgMs, p95Ms, and maxMs for renderCanvasBuffers, analysis map rendering, flood fill requests, and pixel-analysis requests.

format:check covers source, tests, GitHub configuration, root Markdown, and technical Markdown in docs/, plus TypeScript and tooling config files. Long-form research notes keep their editorial line wrapping and are excluded in .prettierignore.

Documentation

For first-time app usage, see docs/user-guide.md. For the full documentation map and the recommended reading order for research notes, see docs/README.md. For contribution workflow and local verification expectations, see CONTRIBUTING.md.

The core corpus is the three-part Tractatus Chromaticus ("Chromatic Treatise"), a unified treatise on the discrete algebraic color model that underlies the application:

• Pars I - 離散代数的色彩モデル
• Pars II - 離散代数的色彩モデル — 先行研究
• Pars III - Theoryタブ — 先行研究と改善提案

Two Music Appendix notes extend the same model into LinkedVisualization and sonification:

• Appendix A - Music-Linked Visualization
• Appendix B - Music-Linked Visualization — 先行研究と設計ノート

The research documents are credited to the pseudonymous author Doctor Chromaticus.

Security

Please report security issues privately. See SECURITY.md for supported versions, report scope, and the vulnerability reporting process.

License

• Application source code, tests, build config, and non-scholarly app assets: MIT License
• Scholarly/explanatory content: Creative Commons Attribution 4.0 International (CC BY 4.0)

The CC BY 4.0 content includes the research and explanatory documents in docs/, including the Tractatus Chromaticus core corpus and the Music Appendix notes, plus the authored prose, labels, and rendered explanatory diagrams in the Theory tab. The code that implements those views remains MIT-licensed.

Technical project documentation, including docs/user-guide.md and docs/architecture.md, follows the MIT-licensed project documentation unless a document says otherwise.

When reusing material from the CC BY 4.0 content, see the citation templates for academic, blog, book, slide, translation, and short-form attribution formats.