# handsupmin/fast-pixelizer architecture

> Architecture diagram of the GitHub repository handsupmin/fast-pixelizer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/handsupmin/fast-pixelizer
- Repository: https://github.com/handsupmin/fast-pixelizer

## Overview

1. **Repository purpose**
   - `fast-pixelizer` is a small TypeScript image-processing library, published as a zero-dependency package for both browser and Node.js.
   - The architecture is centered on two exported operations: `pixelate()` for creating pixel art, and `snap()` for repairing noisy or misaligned pixel-art grids.

2. **Public API boundary**
   - `src/index.ts` is the package entrypoint and likely re-exports the public surface.
   - Consumers import from the package root only; the internal algorithm files are not meant to be used directly.

3. **Core processing subsystems**
   - `src/algorithms.ts` contains the shared low-level image math: grid sampling, resampling, color aggregation, and likely the performance-oriented bucket/count logic described in the README.
   - `src/snap.ts` contains the higher-level grid-recovery pipeline for existing pixel art, including color quantization, boundary detection, and resolution inference.

4. **Data model boundary**
   - The library operates on plain image buffers rather than DOM objects or file formats.
   - Input is a generic `{ data: Uint8ClampedArray, width, height }` shape compatible with browser `ImageData`, node-canvas, and raw buffers.
   - Output is the same raw RGBA buffer shape plus derived metadata for `snap()`.

5. **`pixelate()` flow**
   - The `pixelate` path is a deterministic transform from arbitrary source image data to a coarser pixel-grid representation.
   - It supports two modes, `clean` and `detail`, which imply different cell-aggregation strategies: dominant color versus average color.
   - It also supports two output modes: preserving original dimensions or emitting a resized `resolution × resolution` grid.

6. **`snap()` flow**
   - The `snap` path is an analysis-plus-reconstruction pipeline, not just a resize.
   - It first simplifies colors, then detects likely row/column cuts, infers grid periodicity, and reconstructs a uniform lattice.
   - Its result includes diagnostic metadata (`detectedResolution`, `colCuts`, `rowCuts`) used for overlays and verification.

7. **Performance architecture**
   - The implementation is intentionally allocation-light and optimized for CPU-bound image loops.
   - The README calls out preallocated typed-array buckets and row-major iteration, which indicates the main performance boundary is in tight in-memory processing rather than I/O or async orchestration.

8. **Runtime and platform support**
   - The package is designed to run identically in browser and Node.js environments.
   - Browser usage is synchronous and canvas-based; Node.js usage is typically paired with `sharp` to read/write PNGs and convert to/from raw RGBA buffers.
   - There are no runtime dependencies in the library itself.

9. **Build and packaging**
   - `tsup.config.ts` suggests the package is bundled from TypeScript into distributable JavaScript artifacts.
   - `tsconfig.json`, `eslint.config.js`, and `.prettierrc` indicate a conventional TypeScript library toolchain rather than an app framework.

10. **Validation and regression protection**
    - `tests/snap.test.mjs` focuses specifically on `snap()` behavior, which is consistent with the README’s emphasis on regression fixes for grid drift.
    - `scripts/evaluate-snap-regressions.mjs` appears to benchmark or compare snap behavior across known problematic samples.
    - `docs/2026-03-29-snap-autoresearch-report.md` suggests the snap algorithm has been iteratively researched and documented, likely to justify detection heuristics and stability fixes.

11. **Examples and reproducibility**
    - The `examples/` and `docs/` assets are part of the repo’s verification story: they provide before/after outputs and sample images to demonstrate the algorithms.
    - `scripts/generate-examples.mjs` likely regenerates these example artifacts from the current implementation, making visual regressions easy to spot.

12. **Main architectural boundary to diagram**
    - The key diagram should show a thin public API layer (`index.ts`) feeding into two internal pipelines:
      - direct pixel-grid generation via `algorithms.ts`
      - adaptive grid recovery via `snap.ts`
    - Both pipelines consume the same raw image buffer contract and emit raw RGBA outputs, with `snap()` additionally emitting grid metadata for overlays and diagnostics.

Main entry points: [`src/snap.ts`](https://github.com/handsupmin/fast-pixelizer/blob/main/src/snap.ts) (Snap Pipeline), [`src/index.ts`](https://github.com/handsupmin/fast-pixelizer/blob/main/src/index.ts) (Entrypoint), [`src/algorithms.ts`](https://github.com/handsupmin/fast-pixelizer/blob/main/src/algorithms.ts) (Algorithms), [`scripts/generate-examples.mjs`](https://github.com/handsupmin/fast-pixelizer/blob/main/scripts/generate-examples.mjs) (Examples)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public_api["Public API"]
  node_src_index["Entrypoint<br/>TS export surface<br/>[index.ts]"]
  node_pixelate_api["Pixelate<br/>public op"]
  node_snap_api["Snap<br/>public op"]
  node_image_contract[("RGBA Buffer<br/>data contract")]
end

subgraph group_core["Core Processing"]
  node_algorithms_ts["Algorithms<br/>image math<br/>[algorithms.ts]"]
  node_grid_sampling["Sampling<br/>grid math"]
  node_resampling["Resampling<br/>transform"]
  node_color_buckets["Buckets<br/>perf loop"]
  node_snap_ts["Snap Pipeline<br/>analysis pipeline<br/>[snap.ts]"]
  node_color_simplify["Simplify<br/>analysis step"]
  node_cut_detection["Cut Detect<br/>analysis step"]
  node_resolution_infer["Infer Grid<br/>analysis step"]
  node_lattice_rebuild["Rebuild Grid<br/>reconstruction step"]
  node_snap_metadata["Diagnostics<br/>metadata"]
end

subgraph group_verification["Verification"]
  node_snap_test["Snap Test<br/>regression test<br/>[snap.test.mjs]"]
  node_regression_eval["Regressions<br/>benchmark script"]
  node_example_gen["Examples<br/>regen script"]
  node_research_report["Research Report<br/>design note"]
end

subgraph group_tooling["Tooling"]
  node_build_tooling["Build Setup<br/>tooling<br/>[tsup.config.ts]"]
end

node_src_index -->|"exports"| node_pixelate_api
node_src_index -->|"exports"| node_snap_api
node_src_index -->|"defines"| node_image_contract
node_pixelate_api -->|"uses"| node_algorithms_ts
node_pixelate_api -->|"samples"| node_grid_sampling
node_pixelate_api -->|"writes"| node_resampling
node_pixelate_api -->|"aggregates"| node_color_buckets
node_snap_api -->|"delegates"| node_snap_ts
node_snap_ts -->|"prep"| node_color_simplify
node_snap_ts -->|"detects"| node_cut_detection
node_snap_ts -->|"infers"| node_resolution_infer
node_snap_ts -->|"reconstructs"| node_lattice_rebuild
node_snap_ts -->|"returns"| node_snap_metadata
node_snap_ts -->|"shares math"| node_algorithms_ts
node_snap_test -->|"validates"| node_snap_ts
node_regression_eval -->|"measures"| node_snap_ts
node_example_gen -->|"renders"| node_algorithms_ts
node_example_gen -->|"renders"| node_snap_ts
node_research_report -->|"documents"| node_snap_ts
node_build_tooling -->|"bundles"| node_src_index

click node_src_index "https://github.com/handsupmin/fast-pixelizer/blob/main/src/index.ts"
click node_algorithms_ts "https://github.com/handsupmin/fast-pixelizer/blob/main/src/algorithms.ts"
click node_snap_ts "https://github.com/handsupmin/fast-pixelizer/blob/main/src/snap.ts"
click node_snap_test "https://github.com/handsupmin/fast-pixelizer/blob/main/tests/snap.test.mjs"
click node_regression_eval "https://github.com/handsupmin/fast-pixelizer/blob/main/scripts/evaluate-snap-regressions.mjs"
click node_example_gen "https://github.com/handsupmin/fast-pixelizer/blob/main/scripts/generate-examples.mjs"
click node_research_report "https://github.com/handsupmin/fast-pixelizer/blob/main/docs/2026-03-29-snap-autoresearch-report.md"
click node_build_tooling "https://github.com/handsupmin/fast-pixelizer/blob/main/tsup.config.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_src_index,node_pixelate_api,node_snap_api,node_image_contract toneBlue
class node_algorithms_ts,node_grid_sampling,node_resampling,node_color_buckets,node_snap_ts,node_color_simplify,node_cut_detection,node_resolution_infer,node_lattice_rebuild,node_snap_metadata toneAmber
class node_snap_test,node_regression_eval,node_example_gen,node_research_report toneMint
class node_build_tooling toneRose
```

## Components

### Public API

Package entrypoint and exported surface

- [Entrypoint](https://github.com/handsupmin/fast-pixelizer/blob/main/src/index.ts): TS export surface · Package root that re-exports the public API · `src/index.ts`
- **Pixelate**: public op · Deterministic transform that turns source images into a coarser pixel grid
- **Snap**: public op · Analysis-plus-reconstruction API for repairing noisy or misaligned pixel art
- **RGBA Buffer**: data contract · Shared raw image shape: { data, width, height } compatible with browser and Node runtimes

### Core Processing

Shared pixel math and grid-recovery pipelines

- [Algorithms](https://github.com/handsupmin/fast-pixelizer/blob/main/src/algorithms.ts): image math · Shared low-level sampling, resampling, and aggregation logic · `src/algorithms.ts`
- **Sampling**: grid math · Row-major grid sampling over source pixels and cells
- **Resampling**: transform · Reconstructs a coarser or resized output grid from source data
- **Buckets**: perf loop · Preallocated typed-array bucket/count logic for dominant-color and average-color aggregation
- [Snap Pipeline](https://github.com/handsupmin/fast-pixelizer/blob/main/src/snap.ts): analysis pipeline · Higher-level grid recovery flow for existing pixel art · `src/snap.ts`
- **Simplify**: analysis step · Reduces color noise before boundary and lattice detection
- **Cut Detect**: analysis step · Finds likely row and column boundaries in pixel-art grids
- **Infer Grid**: analysis step · Estimates the underlying periodic resolution from detected cuts
- **Rebuild Grid**: reconstruction step · Reconstructs a uniform lattice from the inferred cuts and resolution
- **Diagnostics**: metadata · Detected resolution and cut arrays used for overlays and verification

### Verification

Tests, regression evaluation, and visual examples

- [Snap Test](https://github.com/handsupmin/fast-pixelizer/blob/main/tests/snap.test.mjs): regression test · Focused regression coverage for snap behavior · `tests/snap.test.mjs`
- [Regressions](https://github.com/handsupmin/fast-pixelizer/blob/main/scripts/evaluate-snap-regressions.mjs): benchmark script · Compares snap behavior across known problematic samples · `scripts/evaluate-snap-regressions.mjs`
- [Examples](https://github.com/handsupmin/fast-pixelizer/blob/main/scripts/generate-examples.mjs): regen script · Regenerates before/after example artifacts from the current implementation · `scripts/generate-examples.mjs`
- [Research Report](https://github.com/handsupmin/fast-pixelizer/blob/main/docs/2026-03-29-snap-autoresearch-report.md): design note · Documents the snap heuristic research and stability work · `docs/2026-03-29-snap-autoresearch-report.md`

### Tooling

Build and repository automation

- [Build Setup](https://github.com/handsupmin/fast-pixelizer/blob/main/tsup.config.ts): tooling · TypeScript bundling and library packaging configuration · `tsup.config.ts`

## Connections

- Entrypoint → Pixelate: exports · Public package entrypoint exposes pixelate()
- Entrypoint → Snap: exports · Public package entrypoint exposes snap()
- Entrypoint → RGBA Buffer: defines · Entrypoint publishes the shared raw image buffer contract
- Pixelate → Algorithms: uses · Pixelate delegates to shared image math
- Pixelate → Sampling: samples · Computes source cells from the input image
- Pixelate → Resampling: writes · Produces the coarser output grid or resized image
- Pixelate → Buckets: aggregates · Uses bucketed dominant-color or average-color accumulation
- Snap → Snap Pipeline: delegates · Snap API enters the adaptive recovery pipeline
- Snap Pipeline → Simplify: prep · Simplifies colors before structural analysis
- Snap Pipeline → Cut Detect: detects · Finds likely row and column cuts
- Snap Pipeline → Infer Grid: infers · Estimates the underlying grid periodicity
- Snap Pipeline → Rebuild Grid: reconstructs · Rebuilds a uniform lattice from the inferred grid
- Snap Pipeline → Diagnostics: returns · Emits detectedResolution, colCuts, and rowCuts metadata
- Snap Pipeline → Algorithms: shares math · Reuses low-level pixel processing utilities where appropriate
- Snap Test → Snap Pipeline: validates · Regression coverage targets the snap pipeline
- Regressions → Snap Pipeline: measures · Compares pipeline behavior on known difficult samples
- Examples → Algorithms: renders · Uses current algorithms to regenerate example outputs
- Examples → Snap Pipeline: renders · Uses current snap behavior to regenerate before/after examples
- Research Report → Snap Pipeline: documents · Explains the heuristic and stability rationale behind snap
- Build Setup → Entrypoint: bundles · Build configuration packages the TypeScript library entrypoint
