@prosopo/puzzle-assets 0.1.4 → 0.2.1

package/package.json

@@ -1,61 +1,60 @@
 {
-	"name": "@prosopo/puzzle-assets",
-	"version": "0.1.4",
-	"description": "Procedural imagery for the slider puzzle captcha",
-	"main": "dist/index.js",
-	"types": "dist/index.d.ts",
-	"type": "module",
-	"engines": {
-		"node": "^24",
-		"npm": "^11"
-	},
-	"exports": {
-		".": {
-			"types": "./dist/index.d.ts",
-			"import": "./dist/index.js",
-			"require": "./dist/cjs/index.cjs"
-		},
-		"./browser": {
-			"types": "./dist/browser.d.ts",
-			"import": "./dist/browser.js",
-			"require": "./dist/cjs/browser.cjs"
-		}
-	},
-	"scripts": {
-		"clean": "del-cli --verbose dist tsconfig.tsbuildinfo",
-		"build": "npm run build:cross-env -- --mode ${NODE_ENV:-development}",
-		"build:cross-env": "vite build --config vite.esm.config.ts",
-		"build:tsc": "tsc --build --verbose",
-		"build:cjs": "NODE_ENV=${NODE_ENV:-development}; vite build --config vite.cjs.config.ts --mode $NODE_ENV",
-		"preview": "tsx scripts/preview.ts",
-		"test": "NODE_ENV=${NODE_ENV:-test}; npx vitest run --config ./vite.test.config.ts",
-		"typecheck": "tsc --project tsconfig.types.json"
-	},
-	"repository": {
-		"type": "git",
-		"url": "git+https://github.com/prosopo/captcha.git",
-		"directory": "packages/puzzle-assets"
-	},
-	"author": "Prosopo Limited",
-	"license": "Apache-2.0",
-	"bugs": {
-		"url": "https://github.com/prosopo/captcha/issues"
-	},
-	"homepage": "https://github.com/prosopo/captcha#readme",
-	"dependencies": {
-		"sharp": "0.35.4"
-	},
-	"devDependencies": {
-		"@prosopo/config": "3.3.14",
-		"@types/node": "22.10.2",
-		"@vitest/coverage-v8": "4.1.11",
-		"del-cli": "6.0.0",
-		"dotenv": "16.4.5",
-		"tslib": "2.7.0",
-		"tsx": "4.20.3",
-		"typescript": "5.6.2",
-		"vite": "8.1.5",
-		"vitest": "4.1.11"
-	},
-	"sideEffects": false
-}
+  "name": "@prosopo/puzzle-assets",
+  "version": "0.2.1",
+  "description": "Procedural imagery for the slider puzzle captcha",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "engines": {
+    "node": "^24"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/cjs/index.cjs"
+    },
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "import": "./dist/browser.js",
+      "require": "./dist/cjs/browser.cjs"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/prosopo/captcha.git",
+    "directory": "packages/puzzle-assets"
+  },
+  "author": "Prosopo Limited",
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/prosopo/captcha/issues"
+  },
+  "homepage": "https://github.com/prosopo/captcha#readme",
+  "dependencies": {
+    "sharp": "0.35.4"
+  },
+  "devDependencies": {
+    "@prosopo/config": "3.4.3",
+    "@types/node": "22.10.2",
+    "@vitest/coverage-v8": "4.1.11",
+    "del-cli": "6.0.0",
+    "dotenv": "16.4.5",
+    "tslib": "2.7.0",
+    "tsx": "4.20.3",
+    "typescript": "5.6.2",
+    "vite": "8.1.5",
+    "vitest": "4.1.11"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "clean": "del-cli --verbose dist tsconfig.tsbuildinfo",
+    "build": "pnpm run build:cross-env --mode ${NODE_ENV:-development}",
+    "build:cross-env": "vite build --config vite.esm.config.ts",
+    "build:tsc": "tsc --build --verbose",
+    "build:cjs": "NODE_ENV=${NODE_ENV:-development}; vite build --config vite.cjs.config.ts --mode $NODE_ENV",
+    "preview": "tsx scripts/preview.ts",
+    "test": "NODE_ENV=${NODE_ENV:-test}; pnpm exec vitest run --config ./vite.test.config.ts",
+    "typecheck": "tsc --project tsconfig.types.json"
+  }
+}

package/src/background.ts

@@ -1,189 +0,0 @@
-// Copyright 2021-2026 Prosopo (UK) Ltd.
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-import { type Rgb, drawPalette } from "./palette.js";
-import type { Prng } from "./prng.js";
-import type { RgbaImage } from "./types.js";
-
-interface MeshPoint {
-	x: number;
-	y: number;
-	colour: Rgb;
-	/** Falloff radius. Small values give tight colour fields, large ones wash. */
-	sigma: number;
-}
-
-interface Blob {
-	x: number;
-	y: number;
-	sigma: number;
-	colour: Rgb;
-	alpha: number;
-}
-
-/**
- * Grain amplitude, in 0-255 units, applied per channel.
- *
- * This is the one knob serving both goals at once. Visually it reads as film
- * grain and stops the mesh gradient banding on 8-bit displays. Structurally it
- * raises the noise floor an edge detector has to clear to find the notch
- * boundary — a perfectly smooth gradient would hand the target over to a Canny
- * filter. Too high and the image looks like TV static, so it stays subtle.
- */
-const GRAIN_AMPLITUDE = 5;
-
-const VIGNETTE_STRENGTH = 0.16;
-
-const clamp255 = (v: number): number => (v < 0 ? 0 : v > 255 ? 255 : v);
-
-/**
- * Smooth multi-colour blend: every pixel is a Gaussian-weighted mix of the
- * control points, giving the "mesh gradient" look — broad soft colour fields
- * with no hard edges anywhere.
- *
- * The falloff has to be local. Inverse-distance weighting (1/d^2) looks right
- * on paper but at 300x200 every control point is a comparable distance from
- * every pixel, so the weights come out near-equal and the whole frame collapses
- * to the palette's mean — a flat grey-ish wash. A Gaussian with sigma around a
- * third of the frame keeps each point dominant near itself and still blends
- * smoothly in between.
- */
-const meshColourAt = (
-	points: readonly MeshPoint[],
-	x: number,
-	y: number,
-): Rgb => {
-	let wSum = 0;
-	let r = 0;
-	let g = 0;
-	let b = 0;
-	for (const point of points) {
-		const dx = x - point.x;
-		const dy = y - point.y;
-		const w = Math.exp(-(dx * dx + dy * dy) / (2 * point.sigma * point.sigma));
-		wSum += w;
-		r += point.colour.r * w;
-		g += point.colour.g * w;
-		b += point.colour.b * w;
-	}
-	// Every point can be far away near a corner; fall back to the nearest.
-	if (wSum < 1e-6) {
-		let best = points[0];
-		if (!best) throw new Error("puzzle-assets: no mesh points");
-		let bestD = Number.POSITIVE_INFINITY;
-		for (const point of points) {
-			const d = (x - point.x) ** 2 + (y - point.y) ** 2;
-			if (d < bestD) {
-				bestD = d;
-				best = point;
-			}
-		}
-		return best.colour;
-	}
-	return { r: r / wSum, g: g / wSum, b: b / wSum };
-};
-
-/**
- * Synthesise a background. Deterministic in `prng`, so the same seed always
- * yields the same picture — see the seed-secrecy note in prng.ts for why that
- * determinism is safe only while the seed stays on the provider.
- */
-export const generateBackground = (
-	prng: Prng,
-	width: number,
-	height: number,
-): RgbaImage => {
-	const pointCount = prng.int(4, 6);
-	// Drawn to length: drawPalette spreads hues evenly across the band, so
-	// taking a prefix of a longer draw would cover only part of it and leave
-	// the mesh monotone.
-	const palette = drawPalette(prng, pointCount);
-	const blobPalette = drawPalette(prng, 3);
-
-	const minDimension = Math.min(width, height);
-	const points: MeshPoint[] = [];
-	for (let i = 0; i < pointCount; i++) {
-		const colour = palette[i];
-		if (!colour) throw new Error("puzzle-assets: palette underflow");
-		points.push({
-			// Allow control points slightly outside the frame so the gradient
-			// keeps moving at the edges instead of pooling into flat corners.
-			x: prng.range(-0.15, 1.15) * width,
-			y: prng.range(-0.15, 1.15) * height,
-			colour,
-			sigma: prng.range(0.26, 0.48) * minDimension,
-		});
-	}
-
-	const blobs: Blob[] = [];
-	const blobCount = prng.int(2, 4);
-	for (let i = 0; i < blobCount; i++) {
-		const colour = blobPalette[i % blobPalette.length];
-		if (!colour) throw new Error("puzzle-assets: palette underflow");
-		blobs.push({
-			x: prng.range(0.1, 0.9) * width,
-			y: prng.range(0.1, 0.9) * height,
-			sigma: prng.range(0.18, 0.38) * minDimension,
-			colour,
-			alpha: prng.range(0.16, 0.32),
-		});
-	}
-
-	const data = Buffer.alloc(width * height * 4);
-	const cx = width / 2;
-	const cy = height / 2;
-	const maxRadius = Math.sqrt(cx * cx + cy * cy);
-
-	for (let y = 0; y < height; y++) {
-		for (let x = 0; x < width; x++) {
-			const base = meshColourAt(points, x, y);
-			let r = base.r;
-			let g = base.g;
-			let b = base.b;
-
-			// Soft radial depth. Gaussian falloff means no visible boundary.
-			for (const blob of blobs) {
-				const dx = x - blob.x;
-				const dy = y - blob.y;
-				const a =
-					blob.alpha *
-					Math.exp(-(dx * dx + dy * dy) / (2 * blob.sigma * blob.sigma));
-				r += (blob.colour.r - r) * a;
-				g += (blob.colour.g - g) * a;
-				b += (blob.colour.b - b) * a;
-			}
-
-			// Vignette: darkens the corners a little, which reads as depth and
-			// keeps attention in the middle where the puzzle happens.
-			const dxc = x - cx;
-			const dyc = y - cy;
-			const vignette =
-				1 -
-				VIGNETTE_STRENGTH * ((dxc * dxc + dyc * dyc) / (maxRadius * maxRadius));
-			r *= vignette;
-			g *= vignette;
-			b *= vignette;
-
-			const grain = (prng.next() - 0.5) * 2 * GRAIN_AMPLITUDE;
-
-			const i = (y * width + x) * 4;
-			data[i] = clamp255(Math.round(r + grain));
-			data[i + 1] = clamp255(Math.round(g + grain));
-			data[i + 2] = clamp255(Math.round(b + grain));
-			data[i + 3] = 255;
-		}
-	}
-
-	return { data, width, height };
-};

package/src/browser.ts

@@ -1,100 +0,0 @@
-// Copyright 2021-2026 Prosopo (UK) Ltd.
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-// Browser-safe surface: same drawing pipeline as the provider, minus the
-// sharp-based WebP encoder. Consumers paint the returned RGBA buffers onto
-// a <canvas> directly.
-
-import { generateBackground } from "./background.js";
-import { cutNotch } from "./compose.js";
-import { paintDecoys } from "./decoys.js";
-import { createNotchShape } from "./notch.js";
-import { createPrng, createSeed } from "./prng.js";
-import type {
-	NotchPlacement,
-	PuzzleGeometry,
-	PuzzleRenderSettings,
-	RgbaImage,
-} from "./types.js";
-
-export { createPrng, createSeed, SEED_BYTES } from "./prng.js";
-export { generateBackground } from "./background.js";
-export { paintDecoys, paintDecoyPiece } from "./decoys.js";
-export type {
-	NotchPlacement,
-	PuzzleGeometry,
-	PuzzleRenderSettings,
-	RenderedPuzzle,
-	RgbaImage,
-} from "./types.js";
-
-export const DEFAULT_GEOMETRY: PuzzleGeometry = {
-	width: 300,
-	height: 200,
-	notchSize: 44,
-};
-
-export const DEFAULT_RENDER_SETTINGS: PuzzleRenderSettings = {
-	decoyCount: 5,
-	decoyEdgeDarkness: 20,
-	decoyBodyBrightness: 4,
-	holeDarken: 0.55,
-	decoyHoleDarken: 0.7,
-};
-
-export interface RenderedPuzzleRgba {
-	background: RgbaImage;
-	piece: RgbaImage;
-	pieceSize: number;
-}
-
-/**
- * Same pipeline as `renderPuzzle` in index.ts but returns raw RGBA rather
- * than WebP-encoded buffers, so browser consumers can `putImageData` onto
- * a canvas without needing sharp.
- */
-export const renderPuzzleToRgba = (
-	background: RgbaImage,
-	placement: NotchPlacement,
-	geometry: PuzzleGeometry = DEFAULT_GEOMETRY,
-	settings: PuzzleRenderSettings = DEFAULT_RENDER_SETTINGS,
-): RenderedPuzzleRgba => {
-	const prng = createPrng(createSeed());
-	const pieceSize = geometry.pieceSize ?? geometry.notchSize;
-	paintDecoys(
-		background,
-		prng,
-		settings.decoyCount,
-		pieceSize,
-		placement,
-		settings.decoyEdgeDarkness,
-		settings.decoyBodyBrightness,
-		settings.decoyHoleDarken,
-	);
-	const shape = createNotchShape(prng, pieceSize);
-	const { background: cut, piece } = cutNotch(
-		prng,
-		background,
-		shape,
-		pieceSize,
-		placement,
-		settings.holeDarken,
-	);
-	return { background: cut, piece, pieceSize };
-};
-
-export const createBackground = (
-	geometry: PuzzleGeometry = DEFAULT_GEOMETRY,
-): RgbaImage =>
-	generateBackground(createPrng(createSeed()), geometry.width, geometry.height);

package/src/compose.ts

@@ -1,210 +0,0 @@
-// Copyright 2021-2026 Prosopo (UK) Ltd.
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-import { type NotchShape, coverageFromDistance } from "./notch.js";
-import type { Prng } from "./prng.js";
-import type { NotchPlacement, RgbaImage } from "./types.js";
-
-/**
- * Per-pixel noise added to the piece, in 0-255 units.
- *
- * This is not decoration. The piece is cut from the background, so a
- * pixel-exact copy would let an attacker slide the piece over the background
- * with normalised cross-correlation and land on the target in one pass —
- * which would make the whole server-rendering exercise worthless. The piece is
- * therefore brightness-shifted and re-noised so it correlates well with a
- * region of the background but never perfectly, and the background gets fresh
- * noise around the cut so the seam is not a clean template either.
- */
-const PIECE_NOISE = 7;
-const PIECE_BRIGHTNESS_RANGE: [number, number] = [-8, 8];
-
-/**
- * Disturbance ring outside the cut, in px. The ring exists so an edge detector
- * cannot lock onto a clean gradient discontinuity along the seam. The noise
- * tapers linearly to zero at the outer edge so it fades into the ambient
- * background grain instead of terminating in a visible border.
- */
-const SEAM_NOISE_RADIUS = 3;
-/**
- * Peak amplitude at the seam itself, in 0-255 units. Kept close to the
- * background grain amplitude so the ring reads as continuation of the grain
- * rather than as a halo around the hole.
- */
-const SEAM_NOISE = 4;
-
-/**
- * Depth cue on the hole. HOLE_INNER_SHADOW is a fixed within-primitive
- * ratio, but HOLE_DARKEN is caller-provided so operators can tune how
- * obvious the target is versus the decoys.
- */
-const HOLE_INNER_SHADOW = 0.45;
-
-/**
- * Depth cue on the piece itself. A subtle brightness rise just inside the
- * silhouette edge, so the piece reads as raised rather than as a flat sticker.
- * Kept low deliberately — a stronger rim starts to look like a drawn border
- * against the darkened cutout it drops into.
- */
-const PIECE_EDGE_LIGHT = 8;
-
-const clamp255 = (v: number): number => (v < 0 ? 0 : v > 255 ? 255 : v);
-
-/**
- * Sample the background at `(x, y)`. Returns `null` when the coordinate
- * sits outside the frame — the piece is clipped at the boundary rather
- * than filled from a clamped edge pixel, so a piece whose placement
- * overhangs the frame simply loses those pixels.
- */
-const sampleBackground = (
-	image: RgbaImage,
-	x: number,
-	y: number,
-): [number, number, number] | null => {
-	if (x < 0 || y < 0 || x >= image.width || y >= image.height) {
-		return null;
-	}
-	const i = (y * image.width + x) * 4;
-	return [image.data[i] ?? 0, image.data[i + 1] ?? 0, image.data[i + 2] ?? 0];
-};
-
-export interface CutResult {
-	/** The background, mutated in place, with the hole cut into it. */
-	background: RgbaImage;
-	/** The draggable piece, on transparency. */
-	piece: RgbaImage;
-}
-
-/**
- * Cut the notch out of `background` and produce the matching piece.
- *
- * `background` is mutated in place — it is a freshly generated, single-use
- * image, so there is nothing to preserve.
- */
-export const cutNotch = (
-	prng: Prng,
-	background: RgbaImage,
-	shape: NotchShape,
-	size: number,
-	placement: NotchPlacement,
-	holeDarken: number,
-): CutResult => {
-	const half = size / 2;
-	const left = Math.round(placement.targetX - half);
-	const top = Math.round(placement.targetY - half);
-
-	const pieceData = Buffer.alloc(size * size * 4);
-	const brightness = prng.range(
-		PIECE_BRIGHTNESS_RANGE[0],
-		PIECE_BRIGHTNESS_RANGE[1],
-	);
-
-	// Pass 1: build the piece from the pixels about to be removed.
-	for (let ly = 0; ly < size; ly++) {
-		for (let lx = 0; lx < size; lx++) {
-			const d = shape.distance(lx, ly);
-			const coverage = coverageFromDistance(d);
-			const pi = (ly * size + lx) * 4;
-
-			if (coverage <= 0) {
-				pieceData[pi + 3] = 0;
-				continue;
-			}
-
-			const sample = sampleBackground(background, left + lx, top + ly);
-			if (sample === null) {
-				// Piece extends past the frame — leave this pixel transparent
-				// so the overhang doesn't smear the edge colour outward.
-				pieceData[pi + 3] = 0;
-				continue;
-			}
-			const [r, g, b] = sample;
-
-			// A bright rim just inside the edge makes the piece read as a
-			// raised object rather than a flat sticker.
-			const edgeLight = d > -2 ? PIECE_EDGE_LIGHT * (1 + d / 2) : 0;
-			const noise = (prng.next() - 0.5) * 2 * PIECE_NOISE;
-			const delta = brightness + edgeLight + noise;
-
-			pieceData[pi] = clamp255(Math.round(r + delta));
-			pieceData[pi + 1] = clamp255(Math.round(g + delta));
-			pieceData[pi + 2] = clamp255(Math.round(b + delta));
-			pieceData[pi + 3] = Math.round(coverage * 255);
-		}
-	}
-
-	// Pass 2: cut the hole, with an inner shadow for depth, and disturb a ring
-	// of pixels around the seam.
-	for (let ly = -SEAM_NOISE_RADIUS; ly < size + SEAM_NOISE_RADIUS; ly++) {
-		for (let lx = -SEAM_NOISE_RADIUS; lx < size + SEAM_NOISE_RADIUS; lx++) {
-			const x = left + lx;
-			const y = top + ly;
-			if (x < 0 || y < 0 || x >= background.width || y >= background.height) {
-				continue;
-			}
-			const bi = (y * background.width + x) * 4;
-			const d = shape.distance(lx, ly);
-			const coverage = coverageFromDistance(d);
-
-			if (coverage > 0) {
-				const r = background.data[bi] ?? 0;
-				const g = background.data[bi + 1] ?? 0;
-				const b = background.data[bi + 2] ?? 0;
-
-				// Darken towards the hole, deeper near the edges so the cut has
-				// an inner shadow rather than reading as a flat grey patch.
-				const edge = d > -3 ? HOLE_INNER_SHADOW * (1 + d / 3) : 0;
-				const factor = holeDarken * (1 - edge);
-				const mix = coverage;
-
-				background.data[bi] = clamp255(
-					Math.round(r * (1 - mix) + r * factor * mix),
-				);
-				background.data[bi + 1] = clamp255(
-					Math.round(g * (1 - mix) + g * factor * mix),
-				);
-				background.data[bi + 2] = clamp255(
-					Math.round(b * (1 - mix) + b * factor * mix),
-				);
-			} else if (d < SEAM_NOISE_RADIUS) {
-				// Just outside the cut: re-noise so the seam is not a clean
-				// gradient discontinuity for an edge detector to lock onto.
-				// Falloff: full amplitude at the seam, zero at the outer edge
-				// of the ring, so the disturbance blends into ambient grain
-				// instead of terminating in a visible halo.
-				const falloff = 1 - d / SEAM_NOISE_RADIUS;
-				const noise = (prng.next() - 0.5) * 2 * SEAM_NOISE * falloff;
-				background.data[bi] = clamp255(
-					Math.round((background.data[bi] ?? 0) + noise),
-				);
-				background.data[bi + 1] = clamp255(
-					Math.round((background.data[bi + 1] ?? 0) + noise),
-				);
-				background.data[bi + 2] = clamp255(
-					Math.round((background.data[bi + 2] ?? 0) + noise),
-				);
-			}
-		}
-	}
-
-	// Drop shadow is applied client-side via CSS `filter: drop-shadow` on the
-	// piece element — see PuzzleCanvas.tsx. Baking one into the piece pixels
-	// stacked with the CSS shadow read as a visible border once lossless WebP
-	// stopped smudging the baked version away.
-
-	return {
-		background,
-		piece: { data: pieceData, width: size, height: size },
-	};
-};