@pixxl-tools/compare

Text and image comparison utilities for Pixxl apps.

@pixxl-tools/compare is a pre-1.0 public package. It exposes pure browser-safe helpers for text diffs, image pixel comparison, and browser image loading. It does not expose a server endpoint and does not persist user input.

Quick Start

import { compareText } from "@pixxl-tools/compare/text";

const result = compareText({
  firstText: "Pixxl tools\nCompare text",
  secondText: "Pixxl tools\nCompare documents",
  granularity: "word",
});

console.log(result.stats.similarity);

Image comparison works on decoded RGBA buffers:

import { compareImageData } from "@pixxl-tools/compare/image";

const black = new Uint8ClampedArray([0, 0, 0, 255]);
const white = new Uint8ClampedArray([255, 255, 255, 255]);

const result = compareImageData({
  firstImage: { data: black, width: 1, height: 1 },
  secondImage: { data: white, width: 1, height: 1 },
  calculateClusters: true,
});

Install/CSS

Install the package:

pnpm add @pixxl-tools/compare

No CSS import is required. The helpers run without React.

Public API

• @pixxl-tools/compare: root export for text and image utilities.
• @pixxl-tools/compare/text: compareText, side-by-side rows, inline spans, scroll indicators, and text diff types.
• @pixxl-tools/compare/image: compareImageData, difference points, difference clusters, and pixel buffer types.
• @pixxl-tools/compare/browser: browser image decoding helpers for file and URL based workflows.

Model/Persistence

Inputs are transient values supplied by the caller.

• Text APIs accept strings and return diff rows plus similarity stats.
• Image APIs accept RGBA Uint8Array or Uint8ClampedArray data with width and height.
• JSON cannot carry typed arrays directly; encode buffers at transport boundaries and recreate typed arrays before comparison.
• The package does not store files, text, pixels, or comparison history.

Examples

Runnable examples:

• examples/compare/text-hello.ts
• examples/compare/image-hello.ts

Website examples:

• website/src/components/tools/TextComparePlayground.tsx
• website/src/components/tools/ImageComparePlayground.tsx

Testing

Relevant checks:

pnpm test
node scripts/check-docs.mjs
node scripts/check-public-api.mjs

Limits

• Text diff cost grows with input size and selected granularity.
• Image comparison samples the shared visible area when dimensions differ.
• Difference clusters are emitted only when calculateClusters is true.
• Browser decoding helpers require browser image APIs; core text/image utilities do not.

Troubleshooting

• If image comparison throws, verify data.length >= width * height * 4.
• If JSON transport loses image data, rebuild a typed array before calling compareImageData.
• If text diffs look too noisy, try ignoreWhitespace, ignoreCase, or a coarser granularity.

Migration/Versioning

Keep result shapes additive until a publish migration plan exists. Runtime normalization options should default conservatively so existing callers keep the same comparison behavior.