Paradimg

Browser-side image processing controlled through URL fragments.

Paradimg v0.1.1

Installation
Usage
URL modifiers
API
Custom pipelines
Behaviour
Development
Licence

Installation

HTML (CDN)

Process marked image URLs automatically from a CDN:

<script src="https://unpkg.com/paradimg"></script>

Mirrors:

Use a pinned version in production:

<script src="https://unpkg.com/paradimg@0.1.1"></script>

npm

Install the package first:

npm install paradimg

Then process matching images automatically:

import 'paradimg/auto'

Or call the explicit API when the page is ready:

import { processImages } from 'paradimg'

await processImages()

Direct download

Download the package tarball or individual files from npm/CDN:

The browser-ready auto-registration file is dist/paradimg-auto.min.js.

Distribution files:

dist/paradimg.mjs: ES module library API.
dist/paradimg.cjs: CommonJS library API.
dist/paradimg-auto.mjs: ES module automatic entry.
dist/paradimg-auto.cjs: CommonJS automatic entry.
dist/paradimg-auto.min.js: minified classic browser automatic entry.

Usage

Add modifiers after #? in an image URL. They run from left to right.

<img src="portrait.jpg#?half&dither=4x4,8c" alt="A pixelated portrait" />

Paradimg selects img[src*="#?"], decodes the source image, renders each requested effect to a Canvas, then replaces the image with a PNG object URL. The original URL remains available in data-image-processor-original-src.

URL modifiers

Modifier	Description
`brightness=1.15`	Multiplies each RGB channel. Defaults to `1.15`.
`contrast=1.2`	Adjusts contrast around a midpoint of 128. Defaults to `1.2`.
`bw`	Converts to grayscale. Use `bw=invert` or `bw=threshold` for variants.
`half`	Resizes the image to 50% with smoothing.
`double`	Resizes to 200% with pixelated nearest-neighbour scaling.
`dither`	Applies an 8×8, 8-colour ordered dither.
`dither=4x4,4c`	Chooses a Bayer matrix (`2x2`, `4x4`, `8x8`, `16x16`, `none`) and colour levels (`2c`, `4c`, `8c`).
`dither=8x8,bw`	Uses two-level monochrome ordered dithering.

Layout fragments can coexist with modifiers. Paradimg ignores unknown flags, so an application can keep flags such as large or full for its own CSS:

<img src="photo.jpg#?large&dither=4x4,4c" alt="Dithered photo" />

API

The package exports the processor and every built-in plugin:

import {
    ImageProcessor,
    brightness,
    bw,
    contrast,
    createImageProcessor,
    dither,
    double,
    half,
    parseHashFlags,
    processImages,
} from 'paradimg'

processImages(options?) builds a default processor and resolves after every matching image has been processed. createImageProcessor(options?) returns that processor without running it. parseHashFlags(src) exposes the fragment parser.

Custom pipelines

Use only the effects and selector your page needs:

import { ImageProcessor, dither, half } from 'paradimg'

const processor = new ImageProcessor([half, dither], 'img[data-pixel-art]')
await processor.processImages()

Plugins have a keyword and an async process(img, context) method. Register your own plugin to introduce an application-specific URL modifier.

Behaviour

Dithered images are clickable after processing: clicking swaps between the processed PNG and the original source. This is useful for inspecting an effect without a separate before/after UI.

Paradimg is browser-only because it uses <canvas> and HTMLImageElement. For a no-JavaScript baseline, generate static derivatives at build time and use Paradimg as an optional enhancement.

Development

npm install
npm run build
npm test

Use the Node version configured by Mise. npm run build produces the npm library and the Astro documentation site. npm run release:dry-run previews the shared release-it workflow.

Licence

ISC. See LICENSE.md.