If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/visioncortex/vtracer shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Single-maintainer risk — review before adopting

• Last commit 6w ago
• 9 active contributors
• MIT licensed
• CI configured
• ⚠ Single-maintainer risk — top contributor 90% of recent commits
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live visioncortex/vtracer repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/visioncortex/vtracer.

What it runs against: a local clone of visioncortex/vtracer — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in visioncortex/vtracer | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | Last commit ≤ 75 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of visioncortex/vtracer. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/visioncortex/vtracer.git
#   cd vtracer
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of visioncortex/vtracer and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "visioncortex/vtracer(\\.git)?\\b" \\
  && ok "origin remote is visioncortex/vtracer" \\
  || miss "origin remote is not visioncortex/vtracer (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 75 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~45d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/visioncortex/vtracer"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

VTracer is a Rust-based raster-to-vector graphics converter that transforms bitmap images (JPG, PNG) into compact SVG files using an O(n) curve-fitting algorithm. Unlike Potrace (which requires binary input) or Adobe Illustrator's Image Trace, VTracer handles colored high-resolution scans and was originally designed for gigapixel blueprint digitization, also supporting pixel art through hierarchical clustering. Monorepo with workspace (Cargo.toml lists cmdapp and webapp members). Core vectorization logic lives in cmdapp/src/ (main.rs, converter.rs, config.rs). Python bindings (cmdapp/vtracer/) wrap Rust via PyO3. webapp/ (implied, likely WebAssembly via docs/589cb57662b50620abca.module.wasm) exposes the algorithm to browsers. Docs in docs/ include web UI, samples in docs/assets/samples/.

Digital archivists, engineering firms scanning historic blueprints, pixel artists, and developers building image vectorization tools who need lightweight, high-performance conversion without external dependencies or expensive software licenses.

Actively maintained and production-ready. At v0.6.0 with CI/CD pipelines (GitHub Actions for Rust, Python, and releases), published as both CLI tool and Python/JavaScript bindings via cmdapp/. Has been in development long enough to accumulate CHANGELOG entries and multi-platform releases, with demonstrated real-world use on large archival projects.

Low risk for core algorithm stability—Rust's type system prevents memory issues endemic to C-based alternatives like Potrace. Risk factors: single organization (Vision Cortex Research Group) maintains it, unclear open issue count from provided data, monorepo structure means breaking API changes could affect both cmdapp and webapp simultaneously. Python bindings (vtracer/) require prebuilt wheels or compilation.

Cannot determine from provided file structure alone—no CHANGELOG dates or commit history visible. Presence of docs/ with versioned WASM suggests recent web deployment. Python bindings with pyproject.toml indicate active Python ecosystem integration. GitHub Actions workflows (python.yml, release.yml, rust.yml) imply ongoing CI/CD maintenance.

git clone https://github.com/visioncortex/vtracer.git
cd vtracer
cargo build --release  # For CLI tool in cmdapp/
cd cmdapp && cargo run --release -- --input sample.png --output output.svg

For Python: pip install vtracer (if published) or build from cmdapp/ with maturin develop.

Daily commands: Rust CLI: cargo run -p cmdapp --release -- --input image.png --output result.svg --color_precision 6 --corner_threshold 45. Python: python -c 'import vtracer; vtracer.convert_image(...)' (after installing/building). Web: Open docs/index.html in a browser (bootstrap.js loads WASM module at docs/589cb57662b50620abca.module.wasm).

• cmdapp/src/converter.rs: Contains the core O(n) vectorization and curve-fitting algorithm—the intellectual heart of the project.
• cmdapp/src/config.rs: Defines all CLI parameters (color_precision, corner_threshold, gradient_step, filter_speckle, hierarchical) that control algorithm behavior.
• cmdapp/src/main.rs: CLI entry point; shows how to invoke the converter and validate inputs.
• cmdapp/src/svg.rs: Generates final SVG output from vectorized paths—critical for understanding output format.
• cmdapp/src/python.rs: PyO3 bindings exposing Rust functions to Python; essential for maintainers adding Python features.
• cmdapp/vtracer/init.py: Python package entry point; shows the public API exposed to Python users.
• Cargo.toml: Workspace definition; lists dependencies and member crates (cmdapp, webapp).
• docs/index.html: Web UI entry point; documents the interactive web app interface.

Algorithm changes: Edit cmdapp/src/converter.rs (core conversion logic) or cmdapp/src/config.rs (parameters). Output format: cmdapp/src/svg.rs. CLI options: cmdapp/src/main.rs + cmdapp/src/config.rs. Python API: cmdapp/src/python.rs (PyO3 bindings) or cmdapp/vtracer/init.py. Web UI: docs/index.html, docs/*.js, docs/uikit/. Tests: Look for #[test] blocks in .rs files (not visible in provided list—likely inline in src/).

Build requirements: Rust toolchain must be installed; cmdapp builds a native binary. Python wheels: PyO3-compiled wheels may not exist for all platforms—building from source requires Rust compiler. WASM size: docs/589cb57662b50620abca.module.wasm is ~600KB+, affecting web performance. No visible test directory: Tests may be inline with #[cfg(test)] in .rs files, making them easy to miss. Workspace resolver: Cargo.toml specifies resolver = "2"; incompatible with Rust < 1.51. Python type hints: cmdapp/vtracer/vtracer.pyi exists but may diverge from implementation if not regenerated after API changes.

• Curve fitting (polynomial approximation) — VTracer's O(n) fitting algorithm is the core innovation that makes it faster than Potrace; understanding how it fits bezier curves to raster traces is essential to contributing to converter.rs.
• Hierarchical clustering — Referenced in config.rs (--hierarchical stacked) and README; the 'stacking strategy' that avoids shapes with holes is a key differentiator from Adobe Illustrator's Image Trace.
• Image trace/vectorization pipeline — VTracer's main strength—combines color segmentation, edge detection, and curve fitting; understanding the pipeline order (see converter.rs) explains why it handles scans better than binary-only tools.
• Bezier curves (SVG path data) — Output format for all vectorized shapes; cmdapp/src/svg.rs generates SVG paths using cubic/quadratic Bezier commands—understanding curve representation is critical for output debugging.
• PyO3 (Rust-Python interop) — cmdapp/src/python.rs uses PyO3 for Python bindings; contributors adding features must understand how Rust types marshall to/from Python (ownership, error handling, GIL).
• WebAssembly (WASM) target — docs/ and webapp/ imply Rust compilation to WASM; understanding wasm-bindgen and JavaScript-WASM interop is essential for debugging the web UI or optimizing payload size.
• Color quantization / clustering — config.rs parameters like --color_precision and --gradient_step control how colors are grouped before vectorization; this preprocessing is why VTracer handles color images (unlike Potrace).

• potrace/potrace — Direct predecessor and competitor—uses O(n²) fitting on binary images; VTracer improves on its algorithm and handles color.
• visioncortex/visioncortex — Core library providing image processing pipelines and clustering algorithms that VTracer depends on; likely contains shared vision utilities.
• visioncortex/impression — Companion project by same org; implements the hierarchical clustering mentioned in VTracer's README and referenced in docs.
• RazrFalcon/svgcleaner — Post-processing tool for SVG optimization; natural companion for users wanting to reduce VTracer output file sizes further.
• ImageMagick/ImageMagick — Often used upstream for image preprocessing before vectorization; many VTracer users combine it with ImageMagick pipelines.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add Python type hints and tests for cmdapp/vtracer module

The cmdapp/vtracer package has a .pyi stub file (cmdapp/vtracer/vtracer.pyi) but no corresponding unit tests. Python bindings to Rust code are critical integration points that should have dedicated test coverage. This would catch regressions in the Python-Rust FFI layer and validate the type hints match actual behavior.

• [ ] Create cmdapp/tests/test_vtracer.py with unit tests for Python API methods defined in cmdapp/vtracer/vtracer.pyi
• [ ] Add parametrized tests for different image formats (jpg, png) referenced in README
• [ ] Test error handling for invalid inputs and edge cases
• [ ] Add tests to cmdapp/.github/workflows/python.yml CI to run pytest on the cmdapp package

Add integration tests for cmdapp/src/config.rs and cmdapp/src/converter.rs

The cmdapp workspace has core modules (config.rs, converter.rs, svg.rs) but the .github/workflows/rust.yml likely only runs cargo test at workspace level. These modules deserve specific integration tests that validate the config parsing pipeline and end-to-end conversion flow with sample images from docs/assets/samples/.

• [ ] Create cmdapp/tests/integration_test.rs with tests for config loading and validation from cmdapp/src/config.rs
• [ ] Add integration tests that invoke the converter pipeline on sample images (e.g., docs/assets/samples/tank-unit-preview.png) and validate SVG output structure
• [ ] Test the config->converter->svg module chain with realistic parameters
• [ ] Ensure tests run in .github/workflows/rust.yml

Add WebAssembly build and regression tests for webapp output

The webapp/Cargo.toml references a wasm target (evident from docs/589cb57662b50620abca.module.wasm), but there's no explicit CI workflow validating wasm-pack builds or testing the JavaScript bindings. The .github/workflows/rust.yml should include wasm-specific build steps to catch compilation regressions early.

• [ ] Add wasm-pack build target to .github/workflows/rust.yml with 'wasm-pack build webapp'
• [ ] Create webapp/tests/wasm_test.js to validate JavaScript API exported from Rust (conversion functions, error handling)
• [ ] Add npm test step in webapp CI that runs wasm integration tests against compiled .wasm module
• [ ] Document wasm build requirements in webapp/Readme.md if missing

• Add unit tests for cmdapp/src/svg.rs—visible file with no test markers in provided data. Write tests verifying SVG path generation for simple shapes (rectangles, circles) to catch regressions.: Critical output module with no visible test coverage; errors here silently produce malformed SVG.
• Document the hierarchical clustering algorithm referenced in README and config (--hierarchical stacked vs non-stacked modes). Add code comments to converter.rs explaining the stacking strategy.: README mentions 'stacking strategy' and links to impression-docs, but the actual algorithm in converter.rs is undocumented; new contributors cannot understand why it's faster than competitors.
• Add Python type hints to cmdapp/vtracer/init.py—vtracer.pyi exists but runtime imports lack annotations. Use @overload or Protocol to document the public API.: IDE autocomplete and mypy checking fail for Python users; improving DX for the Python binding will increase adoption.

VTracer is a Rust-based image conversion tool with moderate security posture. The codebase is relatively simple with low injection risk due to Rust's memory safety. Primary concerns are: (1) web application security headers and asset serving for the WASM-based docs/webapp, (2) dependency management and version pinning for third-party libraries like UIKit, (3) input validation for the image processing pipeline, and (4) metadata leakage from sample assets. No hardcoded secrets or obvious SQL injection risks detected. The project would benefit from explicit security documentation for input handling and formal security headers configuration for web serving.

• Medium · Web Application Exposes WASM Module Without Security Headers — docs/589cb57662b50620abca.module.wasm, webapp/app/bootstrap.js, docs/bootstrap.js. The docs and webapp directories contain compiled WebAssembly modules (*.wasm files) and JavaScript bundles that are served directly. Without proper security headers (Content-Security-Policy, X-Content-Type-Options), these assets could be vulnerable to MIME-type sniffing attacks or cross-site execution risks. Fix: Ensure the web server serving these assets includes proper security headers: X-Content-Type-Options: nosniff, Content-Security-Policy with appropriate directives, and Content-Type: application/wasm for WASM files.
• Medium · Third-Party UI Framework Without Version Pinning — docs/uikit/. The codebase includes UIKit framework files (docs/uikit/) without visible version pinning or lock file content. UIKit CSS/JS dependencies could have unpatched vulnerabilities. Fix: Pin UIKit to a specific version, maintain a package-lock.json or similar, and regularly audit dependencies for security vulnerabilities using tools like npm audit or cargo audit.
• Low · Sample Images and Assets May Contain Metadata — docs/assets/samples/. The docs/assets/samples/ directory contains multiple image files (JPG, PNG) that may contain EXIF metadata or other embedded information that could expose sensitive data or system information. Fix: Strip EXIF and other metadata from sample images before committing to the repository. Use tools like exiftool or ImageMagick to remove metadata: exiftool -all= file.jpg
• Low · Missing Input Validation Documentation — cmdapp/src/converter.rs, webapp/src/conversion/. The image conversion pipeline (cmdapp/src/converter.rs) lacks visible input validation for various image formats. While the tool accepts colored images, there's no clear documentation about maximum file sizes, supported formats, or handling of malformed inputs. Fix: Implement explicit input validation: validate file sizes, image dimensions, and format headers. Add error handling for malformed or oversized inputs. Document supported image formats and limitations.
• Low · Webpack Configuration May Allow Unsafe Operations — webapp/app/webpack.config.js. The webapp includes webpack.config.js but content is not visible. Webpack configurations can expose security risks if not properly configured (e.g., source maps in production, eval mode enabled). Fix: Review webpack configuration to ensure: source maps are disabled in production, eval mode is disabled, minimize is enabled, and no dangerous loaders are used. Use webpack-bundle-analyzer to audit bundled dependencies.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.