{"id":"f24694f8-121d-4c25-880b-abf7b1918925","slug":"visual-primitives","kind":"skill","name":"visual-primitives","summary":"A CLI that attempts to suppress visual hallucinations in VLMs.","owner":"mapleluvr","repoUrl":"https://github.com/mapleluvr/visual-primitives","license":"MIT","licenseTier":"permissive","trust":"community","stars":3,"match":null,"fewStars":true,"format":"skill","createdAt":"2026-06-08T17:11:44.000Z","addedAt":"2026-10-22T01:16:57.802Z","logoUrl":"https://avatars.githubusercontent.com/u/277216670?u=e956d4e7ed8703dad0ba41747f4b2ad367c68f26&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["writing"],"tags":[],"runtime":"node","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-26T02:44:18.982Z","sample":false,"url":"https://conduits.dev/tools/visual-primitives","language":"TypeScript","transports":["stdio"],"install":{"npm":"@mapleluvr/visual-primitives"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"![visual-primitives](assets/visual-primitives-title.png)\n\n
\n\n*Explicit coordinates, inspectable image evidence, and one repeatable replication workflow.*\n\n\"Version:\n\"platform:\n\"License:\n\n
\n
\n\nQuick Start ｜\nCore Idea ｜\nFeatures ｜\nCLI ｜\nExamples ｜\nStructure ｜\nDocs\n\n中文\n\n
\n\n---\n\n`@mapleluvr/visual-primitives` ships one unified package containing:\n\n- the workflow-agnostic `vp` (and `visual-primitives`) CLI for turning explicit boxes and points into inspectable image evidence; and\n- six Agent Skills for generic visual evidence and frontend replication workflows.\n\nNode.js 22.18 or newer is required. There is no background daemon or hidden continuation session. Every command executes locally\nand deterministically against provided image files, performs one bounded image processing\noperation, prints a structured JSON receipt to `stdout`, and exits immediately.\n\n> [!IMPORTANT]\n> `visual-primitives` turns explicit coordinates into local visual evidence artifacts (`.png`\n> crops, labeled preview overlays, exact color samples). It does **not** perform object\n> detection, OCR, segmentation, automatic box generation, or blind UI inference. Coordinates are\n> provided by human users or reasoning agents, and direct visual inspection remains the authoritative\n> interpreter of all generated artifacts.\n\n## Core Idea\n\n\n\n`visual-primitives` treats spatial evidence as a verifiable contract:\n\n1. **Normalized vs. Pixel Coordinates**: Normalized coordinates (`0..999`) provide resolution-independent references across varied device viewports. Pixel coordinates provide exact 1:1 hardware buffer mapping.\n2. **Deterministic Resolution**: Bounding boxes undergo scaling, origin conversion, optional padding, and clamping in a single deterministic pipeline.\n3. **Clamping Transparency**: Every receipt exposes both `resolvedPixelBox` (the actual crop rectangle) and `unclampedPixelBox`, with a boolean `clamped` flag indicating whether any boundary was clipped.\n4. **Fail-Fast Batching**: In `crop-multi`, if any box fails validation or exceeds bounds under `--no-clamp`, zero files are written and the process exits with code `2` or `1`.\n5. **No Blind State**: Commands do not create background locks, temporary database records, or hidden sessions. Output paths are deterministic or explicitly specified.\n\n## Key Features\n\n- **Evidence-bound inspection**: generate concrete, pixel-accurate crops and previews from explicit\n coordinates to anchor visual reasoning in verifiable facts rather than hallucination.\n- **Pure local & zero daemon**: standalone CLI powered by `sharp` and native `libvips`; executes\n in-process with zero background services, zero network calls, and instant startup.\n- **Dual coordinate spaces**: supports paper-style normalized `0..999` thousandths (following\n *Thinking with Visual Primitives*) as well as direct pixel coordinates.\n- **Flexible coordinate geometry**: supports standard top-left origin or Cartesian bottom-left\n (y growing upward), with `left-top-right-bottom` (`ltrb`) or `left-bottom-right-top` (`lbrt`) tuples.\n- **Atomic fail-fast batching**: `vp crop-multi` crops multiple labeled regions in one call; if\n any coordinate or box is invalid, the operation aborts cleanly without partial files.\n- **CSS-level color precision**: `vp colors` samples points or odd $N \\times N$ pixel patches,\n returning RGB, Hex, OKLab color space coordinates, and patch mean statistics for design matching.\n- **Discoverable Agent Skill Set**: six portable agent skills (compatible across agent\n harnesses including Pi, Claude Code, Cursor, and others) covering standalone visual evidence,\n oracle intake, parent-agent loops, subagent orchestration, verdict synthesis, and delivery review.\n- **Masked Oracle Diff engine**: dedicated workflow helper comparing oracle reference designs\n against rendered implementations, strictly isolating code-drawable UI from approved image exclusions.\n- **Dual input modes**: ergonomic CLI flags for interactive shell use, plus `--json `\n for machine pipelines and programmatic invocation.\n- **Predictable machine contracts**: versioned JSON receipts on `stdout`, human summaries on\n `stderr` (suppressible with `--quiet`), and fixed exit codes (`0` success, `1` runtime/IO, `2` usage).\n\n## Quick Start\n\n### Requirements\n\n- Node.js 22.18 or newer\n- Linux, macOS, or Windows\n- Interactive terminal or headless automation environment\n- Optional: Any coding agent harness supporting Agent Skills (e.g. [Pi](https://github.com/earendil-works/pi), Claude Code, Cursor) for agent-driven replication\n\n### Installation\n\n#### CLI Installation (npm)\n\nInstall both binary aliases (`vp` and `visual-primitives`) globally from npm:\n\n```bash\nnpm install -g @mapleluvr/visual-primitives\nvp --help\nvisual-primitives --version\n```\n\nThe two aliases are completely equivalent.\n\n#### Install The Skill Set In Pi\n\nSkills follow the open Agent Skills standard and are portable across agent harnesses.\nIn Pi, install the package directly to load the six visual replication and evidence skills:\n\n```bash\n# Pinned npm version\npi install npm:@mapleluvr/visual-primitives@0.2.0\n\n# Or pinned Git release tag\npi install git:github.com/mapleluvr/visual-primitives@v0.2.0\n```\n\n> [!NOTE]\n> The Pi package manifest exposes **Skills only**. It intentionally does not register legacy\n> extension tools. Because Pi package installation does not guarantee npm binaries are on the\n> system `PATH`, agent skills automatically invoke the bundled CLI through `skills/_shared/run-vp.mjs`.\n> Humans may use the globally installed `vp` binary.\n\n### Getting Started\n\nCreate a working directory and copy a screenshot at least `1440 × 900` into it as `screenshot.png` before running these coordinate examples. For other dimensions or layouts, adjust the boxes and points first; these are supplied coordinates, not detected elements.\n\n```bash\nmkdir vp-demo\ncd vp-demo\n```\n\n#### 1. Annotate Assumptions on a Preview\n\nDraw labeled bounding boxes over the source image to verify coordinate assumptions before drawing conclusions:\n\n```bash\nvp annotate screenshot.png \\\n --box \"header:0,0,1440,80:#00aaff\" \\\n --box \"sidebar:0,80,260,900:#ff0055\" \\\n --box \"content:260,80,1440,900\" \\\n --out preview.png\n```\n\n#### 2. Crop a Focused Region\n\nCrop an exact rectangular bounding box for detailed visual inspection:\n\n```bash\nvp crop screenshot.png --box \"40,30,240,180\" --out header-card.png\n```\n\nFor normalized paper-style coordinates (0..999 thousandths):\n\n```bash\nvp crop screenshot.png --box \"28,33,167,200\" --space normalized-999 --out header-card.png\n```\n\n#### 3. Batch-Crop Multiple Regions\n\nCrop multiple labeled areas in a single atomic call. Files are named deterministically using the provided labels:\n\n```bash\nvp crop-multi screenshot.png \\\n --out-dir ./crops \\\n --box \"logo:20,20,120,60\" \\\n --box \"search-bar:160,20,600,60\" \\\n --box \"user-avatar:1380,20,1420,60\"\n```\n\n#### 4. Crop Around a Point of Interest\n\nExtract a square or rectangular neighborhood centered on an explicit coordinate:\n\n```bash\n# Using radius (crops a 160x160 square centered at 500, 300)\nvp point screenshot.png --point \"500,300\" --radius 80 --out target-center.png\n\n# Using explicit width x height\nvp point screenshot.png --point \"500,300\" --size 120x80 --out target-rect.png\n```\n\n#### 5. Sample CSS and OKLab Colors\n\nSample exact pixel colors or mean patch colors to achieve precise CSS styling:\n\n```bash\nvp colors screenshot.png \\\n --patch 3 \\\n --point \"bg:10,10\" \\\n --point \"brand-red:420,280\" \\\n --point \"text-primary:100,50\"\n```\n\n#### 6. Pipeline with JSON Input\n\nUse `--json` to pass complete structured payloads from files or `stdin`:\n\n```bash\nvp crop --json crop-spec.json\ncat crop-spec.json | vp crop --json -\n```\n\n```json\n{\n \"imagePath\": \"screenshot.png\",\n \"box\": [40, 30, 240, 180],\n \"coordinateSpace\": \"pixel\",\n \"outputPath\": \"header.png\"\n}\n```\n\n### Read the Receipt\n\n```bash\nvp annotate screenshot.png --box \"header:40,30,240,180\" --out annotated.png\nvp crop screenshot.png --box \"40,30,240,180\" --out header.png\nvp colors screenshot.png --point \"header-bg:80,50\" --patch 3\n```\n\nEvery successful command writes one structured JSON receipt to `stdout` (with summaries on `stderr`):\n\n```json\n{\n \"imagePath\": \"/workspace/screenshot.png\",\n \"outputPath\": \"/workspace/header.png\",\n \"source\": {\n \"width\": 1440,\n \"height\": 900,\n \"format\": \"png\"\n },\n \"input\": {\n \"box\": [40, 30, 240, 180],\n \"coordinateSpace\": \"pixel\",\n \"origin\": \"top-left\",\n \"boxOrder\": \"left-top-right-bottom\",\n \"padding\": 0,\n \"clamp\": true\n },\n \"resolvedPixelBox\": {\n \"left\": 40,\n \"top\": 30,\n \"right\": 240,\n \"bottom\": 180,\n \"width\": 200,\n \"height\": 150\n },\n \"unclampedPixelBox\": {\n \"left\": 40,\n \"top\": 30,\n \"right\": 240,\n \"bottom\": 180,\n \"width\": 200,\n \"height\": 150\n },\n \"clamped\": false\n}\n```\n\nFor automated agent or headless workflows, `--json ` accepts full JSON inputs via file\nor `stdin`, preserving legacy tool payload schemas and default normalized coordinates.\n\n## Command Line\n\n| Command | Purpose |\n| --- | --- |\n| `vp crop --box [options]` | Crop one rectangular region from a source image. |\n| `vp crop-multi --box <[label:]l,t,r,b> ...` | Crop multiple labeled regions atomically in one fail-fast call. |\n| `vp annotate --box <[label:]l,t,r,b[:color]> ...` | Draw labeled boxes and outlines on a same-size preview image. |\n| `vp point --point (--radius \\| --size )` | Crop a rectangular region centered on an explicit coordinate. |\n| `vp colors --point <[label:]x,y> ...` | Sample exact pixel or patch colors (RGB, Hex, OKLab, patch mean). |\n\n### Common Options\n\n| Option | Values | Default | Description |\n| --- | --- | --- | --- |\n| `-i, --image ` | File path | Positional 1 | Source image path (supports PNG, JPEG, WebP, AVIF, TIFF, GIF, SVG). |\n| `-s, --space ` | `pixel` \\| `normalized-999` | `pixel` | Coordinate interpretation (`px`, `999` aliases accepted). |\n| `--origin ` | `top-left` \\| `bottom-left` | `top-left` | Coordinate origin (`bottom-left` means y grows upward). |\n| `--box-order ` | `ltrb` \\| `lbrt` | `ltrb` | Coordinate order (`left-top-right-bottom` or `left-bottom-right-top`). |\n| `--padding ` | Non-negative integer | `0` | Additional pixel margin expanded around resolved boxes. |\n| `--no-clamp` | Flag | Clamping on | Fail on out-of-bounds boxes instead of clipping to image dimensions. |\n| `--json ` | File path or `-` | None | Read full input payload as JSON; ignores other input flags. |\n| `--compact` | Flag | Pretty | Output compact single-line JSON instead of indented JSON. |\n| `-q, --quiet` | Flag | Verbose | Suppress the human-readable summary line on `stderr`. |\n| `-h, --help` | Flag | None | Display global or command-specific usage help. |\n| `-v, --version` | Flag | None | Display the installed package version. |\n\n### Exit Codes\n\n| Exit Code | Meaning | Standard Output | Standard Error |\n| :---: | --- | --- | --- |\n| `0` | Success | Structured JSON receipt | One-line summary (unless `--quiet`) |\n| `1` | Runtime / Image / IO failure | Empty | Descriptive error message |\n| `2` | Usage / Validation error | Empty | Help hint or schema error message |\n\n## Visual Evidence & Replication Workflows\n\nFrontend UI is meant to be looked at, so these examples are shown, not merely scored.\nThe following real-world examples were produced in a single pass by a mid-tier frontend model\ndriven through `frontend-replication` $\\rightarrow$ `inline-replication`.\n\nThe quality comes from strictly running the replication loop rather than raw model capability.\nA standard prompt that reliably drives the loop:\n\n```text\nReplicate the frontend screenshot at (viewport x). Follow the\nfrontend-replication workflow strictly.\n\n- Match the oracle's exact pixel dimensions in the rendered screenshot.\n- Render every code-drawable region in code (CSS/SVG): text, table columns,\n icons, badges, status pills, progress bars, and brand colors.\n- Approved exclusions may be represented by placeholders or delegated image assets:\n avatars, album / cover art, organic illustrations, and dense logo marks.\n- Keep code-drawable content inside the scoring domain; use exclusions only for\n tightly bounded regions that cannot be described as boxes and paths.\n```\n\n### Worked Example 1: Fast and Accurate Dashboard Mockup\n\nThe oracle is an analytics dashboard mockup featuring a regular grid layout: a navigation sidebar,\na top KPI row, two visual chart cards, and a recent transactions table.\n\n

\n \"Dashboard\n

\n\n

Left: Oracle mockup (1487x1058). Right: Single-pass render (1487x1058).

\n\nOn a clean, regular layout like this, the workflow achieves high fidelity immediately:\n- The sidebar hierarchy, KPI metric cards, revenue area chart, traffic donut chart, and transaction table land accurately.\n- Semantic indicators (green up-deltas, red down-deltas, amber pending status pills) reproduce exact hex colors sampled via `vp colors`.\n- Both views match pixel-for-pixel on dimensions and major component alignment in a single pass.\n\n### Worked Example 2: Dense Real-World Application (NetEase Cloud Music)\n\nThe oracle is an authentic desktop client screenshot (`1448x940`) of NetEase Cloud Music — a dense,\nthree-region interface featuring multi-size Chinese typography, badge systems (`超清母带`, `VIP`),\na signature brand red, complex column alignment, and a floating playback progress bar.\n\n

\n \"NetEase\n

\n\n

Left: Real desktop screenshot oracle (1448x940). Right: Single-pass render (1448x940). Full-resolution images in docs/visual-primitives/examples/.

\n\n#### Exclusion Boundaries vs. Code-Drawable Scoring Domain\n\nThe core design principle of `visual-primitives` replication is drawing a strict line between\n**what a text model can describe in code** and **organic imagery that requires image assets**:\n\n- **Delegated Exclusions**: Six regions were excluded from code-scoring and delegated to asset placeholders — the playlist cover art, two user avatars, two song thumbnails, and the rotating vinyl record.\n- **Code-Drawable Domain**: Everything else stayed strictly in the scoring domain — layout grid, table alignment, badge typography, icon glyphs, search bars, and audio controls.\n\n#### Direct Inspection Findings\n\nEven with this extreme density, the single-pass render holds together with remarkable fidelity. Direct inspection reveals only subtle, small-area details:\n1. **NetEase Logo Mark**: The render approximates the brand mark with inline SVG rather than the exact proprietary vector curve.\n2. **Progress Bar Knob**: The circular scrubber sits 2 pixels above the red/gray track boundary instead of perfectly centered.\n3. **Icon Weights**: Several navigation icons differ by one font-weight step.\n\nThe visual evidence tools (`vp annotate`, `vp crop`, `masked-oracle-diff`) identify these exact discrepancies, enabling targeted feedback in the next refinement loop.\n\n## Skill Set\n\nThe package includes six discoverable skills for agent-assisted visual engineering.\nBuilt on the open Agent Skills standard, they are portable across coding agent harnesses\n(such as Pi, Claude Code, Cursor, and custom agent harnesses):\n\n| Skill | Role | Primary Use Case |\n| --- | --- | --- |\n| `using-visual-primitives` | General Primitive Guidance | Core tool selection, coordinate systems, preview annotations, and direct visual inspection. |\n| `frontend-replication` | Replication Gateway | Oracle intake, run workspace creation, manifest initialization, and routing. |\n| `inline-replication` | Parent-Agent Loop | Single-agent end-to-end replication for simple to medium pages. |\n| `subagent-driven-replication` | Multi-Agent Orchestration | High-precision replication dividing work among worker and reviewer subagents. |\n| `refining-with-feedback` | Iterative Refinement | Synthesizing previous draft history, failed inspections, and diff verdicts into targeted fixes. |\n| `finalizing-replication` | Final Quality Gate | Conducting final direct human inspection and user-facing delivery review. |\n\n### Package Launcher\n\nIn agent environments, skills invoke the CLI via the cross-platform packaged launcher:\n\n```bash\nnode /_shared/run-vp.mjs [options]\n```\n\nThis guarantees execution regardless of whether global npm binaries are present on the host `PATH`.\n\n## Frontend Workflow Helper: `masked-oracle-diff`\n\n`masked-oracle-diff` remains owned by the frontend replication workflow. It is not a `vp` command,\nnpm binary, generic core export, or responsibility of `using-visual-primitives`.\n\nWhen a replication skill is loaded, resolve `scripts/run-masked-oracle-diff.mjs` relative to the\nloaded `frontend-replication` skill directory and invoke that package-local runner:\n\n```bash\nnode /scripts/run-masked-oracle-diff.mjs \\\n --manifest docs/visual-primitives/runs//scripts/diff-manifest.json\n```\n\n*(Repository maintainers working in this repository checkout may also run `npm run oracle:diff -- --manifest `.)*\n\n### Artifact Output\n\nThe helper generates a complete diagnostic suite in the run workspace:\n- `diff.gray.png`: Visual difference heatmap highlighting discrepancies.\n- `mask.png`: Binary mask confirming evaluated vs. excluded regions.\n- `matrix.json`: $25 \\times 25$ spatial error distribution grid.\n- `components/` & `stripes/`: Decomposed component-level diff analysis.\n- `summary.json`: Aggregate diff metrics and pass/fail thresholds.\n- `VERDICT.md`: Human- and agent-readable markdown verdict.\n\n> [!NOTE]\n> A clean diff score opens the door to final direct inspection; it does not certify delivery\n> by itself. Direct visual inspection remains mandatory.\n\n## Project Structure\n\n```text\nvisual-primitives/\n├── src/ # CLI, schemas, crops and color processing\n├── skills/ # Six Agent Skills\n│ ├── _shared/ # Bundled CLI launcher\n│ └── frontend-replication/scripts/ # Masked Oracle Diff\n├── scripts/ # Build, package smoke and release checks\n├── tests/ # Synthetic image and CLI contract tests\n├── docs/ # Designs, worked examples and workflow records\n└── assets/ # README title artwork\n```\n\n## Replication Run Workspace\n\nReplication workflows organize durable artifacts in a standardized run directory structure:\n\n```text\ndocs/visual-primitives/runs//\n oracles/ # Source screenshots, reference assets, and oracle-manifest.json\n annots/ # Annotated preview overlays from vp annotate\n cropped/ # Isolated region crops from vp crop and vp crop-multi\n rendered/ # Rendered webpage screenshots from browser captures\n diffs/ # Masked oracle diff images, matrices, and summaries\n drafts/ # Progressive code implementations and draft manifests\n verdict/ # Process feedback verdicts from automated verification runs\n scripts/ # Run-local capture scripts and manifest configurations\n final/ # Final direct-inspection notes and delivery review artifacts\n```\n\n## Support and Boundaries\n\n| Capability | Current boundary |\n| --- | --- |\n| Local image processing | Node.js ≥22.18; Linux / macOS / Windows |\n| Coordinate source | Explicit human or agent input; no detection, OCR or automatic segmentation |\n| Pi integration | Skills only; no legacy native extension-tool registration |\n| Masked Oracle Diff | Owned by the frontend replication workflow, not a `vp` subcommand |\n| Scores and acceptance | Diagnostic signals only; final direct visual inspection is still required |\n| Runtime state | No daemon or hidden continuation session; artifacts use declared output paths |\n\n## Versioning\n\nThe CLI and Skill Set use one package version and one Git tag. Package version `X.Y.Z` corresponds to tag `vX.Y.Z`. Command names, JSON input semantics, exit codes, documented Skill resources, and helper ownership are protected compatibility contracts.\n\n## Migration from `pi-visual-primitives`\n\nVersion `0.2.0` represents a complete architectural evolution from the legacy `pi-visual-primitives` package:\n\n1. **Standalone CLI**: Legacy TypeScript extension tools (`crop_bounding_box`, `sample_colors`) are replaced by the high-performance `vp` CLI binary.\n2. **Skills-Only Pi Package**: Pi package manifests load skills without registering native runtime extension tools.\n3. **Command Mapping**:\n - `crop_bounding_box` $\\rightarrow$ `vp crop`\n - `crop_multiple_bounding_boxes` $\\rightarrow$ `vp crop-multi`\n - `annotate_bounding_boxes` $\\rightarrow$ `vp annotate`\n - `crop_around_point` $\\rightarrow$ `vp point`\n - `sample_colors` $\\rightarrow$ `vp colors`\n4. **Path Independence**: Agents execute via `skills/_shared/run-vp.mjs` without requiring manual system environment configuration.\n5. **Workflow Scoping**: `masked-oracle-diff` is properly scoped inside `frontend-replication` rather than cluttering generic primitive tools.\n\n## Documentation\n\n- [Release & Architecture Intent](docs/superpowers/work/vp-cli-skill-set-release/intent.md)\n- [Single-Package Architecture Decision](docs/superpowers/work/vp-cli-skill-set-release/decisions/0001-single-package-architecture.md)\n- [Package and CLI Contract](docs/superpowers/work/vp-cli-skill-set-release/contracts/package-and-cli-contract.md)\n- [Skill Set & Loop Hardening Review](docs/skill-set-loop-review.md)\n- [Visual Reproduction Specification](docs/superpowers/specs/2026-07-01-aigc-oracle-web-reproduction-devskillpack-design.md)\n- [Conformance Review](docs/conformance-review.md)\n- [Release Management Guide](RELEASE.md)\n- [Changelog](CHANGELOG.md)\n\n## Development\n\n```bash\n# Install dependencies\nnpm ci --ignore-scripts\n\n# Verify types, builds, and scripts\nnpm run check\n\n# Execute test suite\nnpm test\n\n# Run package smoke test (builds tarball, validates CLI, all 6 skills, and launcher)\nnpm run package:smoke\n\n# Security audit\nnpm audit --audit-level=high\n```\n\nAll test suites generate deterministic synthetic image fixtures in memory with `sharp.create()`,\nkeeping the repository lightweight and free of binary test artifacts.\n\nCI runs continuously across Ubuntu, macOS, and Windows with Node 22.18.0 and Node 24.x.\nPublishing is strictly tag-gated using npm Trusted Publishing with cryptographic provenance.\n\n## Safety Model & Evidence Boundaries\n\n- **Strict Schema Admission**: The CLI rejects unknown JSON properties, non-finite coordinates, out-of-range enums, and conflicting parameters.\n- **Fail-Closed Processing**: Invalid image headers, unreadable files, or malformed coordinates terminate execution immediately with descriptive diagnostics.\n- **Local Image Processing**: Image operations use native libraries without shell expansion or arbitrary script evaluation; this is not a general-purpose security sandbox.\n\n## License\n\nLicensed under the [MIT License](LICENSE).\n\n---\n\n
\n\n**State the coordinates. Keep the evidence. Inspect the result.**\n\n
\n"}