@prosopo/puzzle-assets 0.1.3 → 0.2.0

package/dist/cjs/contrast.cjs

@@ -0,0 +1,142 @@
+//#region src/contrast.ts
+var VISION_TYPES = [
+	"normal",
+	"protanopia",
+	"deuteranopia",
+	"tritanopia"
+];
+/** sRGB 8-bit channel to linear light in [0, 1]. */
+var toLinear = (channel) => {
+	const c = channel / 255;
+	return c <= .04045 ? c / 12.92 : ((c + .055) / 1.055) ** 2.4;
+};
+var fromLinear = (value) => {
+	const c = value <= .0031308 ? value * 12.92 : 1.055 * value ** (1 / 2.4) - .055;
+	return Math.min(255, Math.max(0, Math.round(c * 255)));
+};
+/**
+* WCAG relative luminance, in [0, 1].
+*
+* Linearised first: averaging raw sRGB bytes is the usual mistake and it
+* overstates how light a saturated colour is, which would let this pass a pair
+* that a dichromat sees as flat.
+*/
+var relativeLuminance = (colour) => .2126 * toLinear(colour.r) + .7152 * toLinear(colour.g) + .0722 * toLinear(colour.b);
+/**
+* WCAG contrast ratio, in [1, 21].
+*
+* 1 means two colours are the same brightness — indistinguishable without hue —
+* and 21 is black against white.
+*/
+var contrastRatio = (a, b) => {
+	const la = relativeLuminance(a);
+	const lb = relativeLuminance(b);
+	const lighter = Math.max(la, lb);
+	const darker = Math.min(la, lb);
+	return (lighter + .05) / (darker + .05);
+};
+/**
+* Brettel/Viénot-style dichromacy simulation, in linear RGB.
+*
+* These are the Viénot–Brettel–Mollon single-plane projections, which is the
+* standard approximation and is more than accurate enough for the question being
+* asked here: not "what exactly does this look like" but "has the difference
+* between these two colours disappeared". The matrices are applied to linear
+* light, not to sRGB bytes — applying them to gamma-encoded values is a common
+* error that makes the result look more distinguishable than it is.
+*/
+var DICHROMACY_MATRICES = {
+	protanopia: [
+		.15286,
+		1.17579,
+		-.32865,
+		.11475,
+		.85426,
+		.03099,
+		-.00386,
+		-.00534,
+		1.0092
+	],
+	deuteranopia: [
+		.3677,
+		.86122,
+		-.22892,
+		.28039,
+		.67201,
+		.0476,
+		-.0118,
+		.04164,
+		.97016
+	],
+	tritanopia: [
+		1.25528,
+		-.07657,
+		-.17871,
+		-.07833,
+		.93087,
+		.14746,
+		.00491,
+		.2214,
+		.77309
+	]
+};
+/**
+* What `colour` looks like to someone with `vision`.
+*
+* `normal` is the identity, so callers can loop over [`VISION_TYPES`] without a
+* special case.
+*/
+var simulateVision = (colour, vision) => {
+	if (vision === "normal") return colour;
+	const m = DICHROMACY_MATRICES[vision];
+	const r = toLinear(colour.r);
+	const g = toLinear(colour.g);
+	const b = toLinear(colour.b);
+	return {
+		r: fromLinear(m[0] * r + m[1] * g + m[2] * b),
+		g: fromLinear(m[3] * r + m[4] * g + m[5] * b),
+		b: fromLinear(m[6] * r + m[7] * g + m[8] * b)
+	};
+};
+/**
+* The lowest contrast ratio between `a` and `b` across normal vision and all
+* three dichromacies.
+*
+* The minimum, not the average: a palette that reads well for most people and
+* collapses for deuteranopes has failed, and averaging would hide exactly that.
+*/
+var worstCaseContrast = (a, b) => {
+	let worst = Number.POSITIVE_INFINITY;
+	for (const vision of VISION_TYPES) {
+		const ratio = contrastRatio(simulateVision(a, vision), simulateVision(b, vision));
+		if (ratio < worst) worst = ratio;
+	}
+	return worst;
+};
+/**
+* The widest separation any pair in `colours` achieves in the worst case.
+*
+* This is the question a mesh background has to answer: not "is every pair
+* distinguishable" — a gradient needs near-neighbours — but "does the field
+* contain a visible light-to-dark range at all, for everyone". A palette whose
+* best pair is flat is a flat picture, and a piece resting on it has nothing but
+* its own edge treatment to separate it.
+*/
+var bestPairContrast = (colours) => {
+	let best = 1;
+	for (let i = 0; i < colours.length; i++) for (let j = i + 1; j < colours.length; j++) {
+		const a = colours[i];
+		const b = colours[j];
+		if (a === void 0 || b === void 0) continue;
+		const ratio = worstCaseContrast(a, b);
+		if (ratio > best) best = ratio;
+	}
+	return best;
+};
+//#endregion
+exports.VISION_TYPES = VISION_TYPES;
+exports.bestPairContrast = bestPairContrast;
+exports.contrastRatio = contrastRatio;
+exports.relativeLuminance = relativeLuminance;
+exports.simulateVision = simulateVision;
+exports.worstCaseContrast = worstCaseContrast;

package/dist/cjs/index.cjs

@@ -1,4 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_contrast = require("./contrast.cjs");
+const require_palette = require("./palette.cjs");
 const require_background = require("./background.cjs");
 const require_notch = require("./notch.cjs");
 const require_compose = require("./compose.cjs");
@@ -35,14 +37,14 @@ var DEFAULT_RENDER_SETTINGS = {
 * attacker diff the two composites and read both targets straight off. The
 * caller's buffer is responsible for enforcing consume-once.
 */
-var createBackground = (geometry = DEFAULT_GEOMETRY) => require_background.generateBackground(require_prng.createPrng(require_prng.createSeed()), geometry.width, geometry.height);
+var createBackground = (geometry = DEFAULT_GEOMETRY, seed = require_prng.createSeed()) => require_background.generateBackground(require_prng.createPrng(seed), geometry.width, geometry.height);
 /**
 * Cut a notch at `placement` and encode both halves.
 *
 * The background is consumed (mutated) by this call.
 */
-var renderPuzzle = async (background, placement, geometry = DEFAULT_GEOMETRY, settings = DEFAULT_RENDER_SETTINGS) => {
-	const prng = require_prng.createPrng(require_prng.createSeed());
+var renderPuzzle = async (background, placement, geometry = DEFAULT_GEOMETRY, settings = DEFAULT_RENDER_SETTINGS, seed = require_prng.createSeed()) => {
+	const prng = require_prng.createPrng(seed);
 	const pieceSize = geometry.pieceSize ?? geometry.notchSize;
 	require_decoys.paintDecoys(background, prng, settings.decoyCount, pieceSize, placement, settings.decoyEdgeDarkness, settings.decoyBodyBrightness, settings.decoyHoleDarken);
 	const shape = require_notch.createNotchShape(prng, pieceSize);
@@ -51,24 +53,40 @@ var renderPuzzle = async (background, placement, geometry = DEFAULT_GEOMETRY, se
 	return {
 		background: backgroundWebp,
 		piece: pieceWebp,
-		pieceSize
+		pieceSize,
+		seed
 	};
 };
-/** Convenience: generate, cut and encode in one call. */
-var createPuzzle = async (placement, geometry = DEFAULT_GEOMETRY, settings = DEFAULT_RENDER_SETTINGS) => renderPuzzle(createBackground(geometry), placement, geometry, settings);
+/**
+* Convenience: generate, cut and encode in one call.
+*
+* Takes both seeds so a caller holding a persisted pair can reproduce a served
+* challenge byte for byte — the background seed and the render seed are
+* independent and both are required.
+*/
+var createPuzzle = async (placement, geometry = DEFAULT_GEOMETRY, settings = DEFAULT_RENDER_SETTINGS, backgroundSeed = require_prng.createSeed(), renderSeed = require_prng.createSeed()) => renderPuzzle(createBackground(geometry, backgroundSeed), placement, geometry, settings, renderSeed);
 //#endregion
 exports.DEFAULT_GEOMETRY = DEFAULT_GEOMETRY;
 exports.DEFAULT_RENDER_SETTINGS = DEFAULT_RENDER_SETTINGS;
+exports.MIN_PALETTE_CONTRAST = require_palette.MIN_PALETTE_CONTRAST;
 exports.SEED_BYTES = require_prng.SEED_BYTES;
+exports.VISION_TYPES = require_contrast.VISION_TYPES;
+exports.bestPairContrast = require_contrast.bestPairContrast;
+exports.contrastRatio = require_contrast.contrastRatio;
 exports.createBackground = createBackground;
 exports.createPrng = require_prng.createPrng;
 exports.createPuzzle = createPuzzle;
 exports.createSeed = require_prng.createSeed;
+exports.drawPalette = require_palette.drawPalette;
 exports.encodeBackground = require_encode.encodeBackground;
 exports.encodePiece = require_encode.encodePiece;
 exports.encodePng = require_encode.encodePng;
 exports.generateBackground = require_background.generateBackground;
+exports.hslToRgb = require_palette.hslToRgb;
 exports.paintDecoyPiece = require_decoys.paintDecoyPiece;
 exports.paintDecoys = require_decoys.paintDecoys;
+exports.relativeLuminance = require_contrast.relativeLuminance;
 exports.renderPuzzle = renderPuzzle;
+exports.simulateVision = require_contrast.simulateVision;
 exports.toDataUri = require_encode.toDataUri;
+exports.worstCaseContrast = require_contrast.worstCaseContrast;

package/dist/cjs/notch.cjs

@@ -1,10 +1,23 @@
 //#region src/notch.ts
-var sideOffset = (side, half, distance) => {
+/** Unit outward normal and unit along-edge direction for a side. */
+var sideAxes = (side) => {
 	switch (side) {
-		case 0: return [0, -half - distance];
-		case 1: return [half + distance, 0];
-		case 2: return [0, half + distance];
-		default: return [-half - distance, 0];
+		case 0: return {
+			normal: [0, -1],
+			along: [1, 0]
+		};
+		case 1: return {
+			normal: [1, 0],
+			along: [0, 1]
+		};
+		case 2: return {
+			normal: [0, 1],
+			along: [-1, 0]
+		};
+		default: return {
+			normal: [-1, 0],
+			along: [0, -1]
+		};
 	}
 };
 var roundedBoxDistance = (px, py, half, radius) => {
@@ -12,100 +25,109 @@ var roundedBoxDistance = (px, py, half, radius) => {
 	const qy = Math.abs(py) - half + radius;
 	return Math.hypot(Math.max(qx, 0), Math.max(qy, 0)) + Math.min(Math.max(qx, qy), 0) - radius;
 };
-var createJigsawShape = (prng, size) => {
-	const knobRadius = size * prng.range(.15, .19);
-	const bodyHalf = size / 2 - knobRadius * .9;
-	const cornerRadius = bodyHalf * prng.range(.28, .42);
-	const knobSide = prng.int(0, 3);
-	const [knobX, knobY] = sideOffset(knobSide, bodyHalf, -knobRadius * .45);
-	const hasBite = prng.next() < .55;
-	const biteSide = (knobSide + prng.int(1, 3)) % 4;
-	const biteRadius = size * prng.range(.13, .17);
-	const [biteX, biteY] = sideOffset(biteSide, bodyHalf, -biteRadius * .55);
-	return { distance(lx, ly) {
-		const px = lx - size / 2;
-		const py = ly - size / 2;
-		const body = roundedBoxDistance(px, py, bodyHalf, cornerRadius);
-		const knob = Math.hypot(px - knobX, py - knobY) - knobRadius;
-		let d = Math.min(body, knob);
-		if (hasBite) {
-			const bite = Math.hypot(px - biteX, py - biteY) - biteRadius;
-			d = Math.max(d, -bite);
-		}
-		return d;
-	} };
-};
-var createCircleShape = (prng, size) => {
-	const radius = size / 2 * prng.range(.85, .98);
-	const cx = size / 2;
-	const cy = size / 2;
-	return { distance(lx, ly) {
-		return Math.hypot(lx - cx, ly - cy) - radius;
-	} };
-};
-var createRoundedRectShape = (prng, size) => {
-	const aspect = prng.range(.5, 1);
-	const halfMax = size / 2 * prng.range(.82, .98);
-	const [halfW, halfH] = prng.next() < .5 ? [halfMax, halfMax * aspect] : [halfMax * aspect, halfMax];
-	const cornerRadius = Math.min(halfW, halfH) * prng.range(.08, .5);
-	const cx = size / 2;
-	const cy = size / 2;
-	return { distance(lx, ly) {
-		const px = lx - cx;
-		const py = ly - cy;
-		const qx = Math.abs(px) - halfW + cornerRadius;
-		const qy = Math.abs(py) - halfH + cornerRadius;
-		return Math.hypot(Math.max(qx, 0), Math.max(qy, 0)) + Math.min(Math.max(qx, qy), 0) - cornerRadius;
-	} };
-};
-var createPolygonShape = (prng, size) => {
-	const n = prng.int(3, 8);
-	const inradius = size / 2 * prng.range(.85, .98) * Math.cos(Math.PI / n);
-	const rotation = prng.next() * Math.PI * 2;
-	const normals = [];
-	for (let i = 0; i < n; i++) {
-		const angle = 2 * Math.PI * i / n - Math.PI / 2 + rotation;
-		normals.push([Math.cos(angle), Math.sin(angle)]);
+/**
+* How many of the four edges carry a knob, and which.
+*
+* At least two, so the outline cannot come out as a plain rounded square and
+* fail to read as a jigsaw piece at all. At most three: four knobs on a small
+* square starts to read as a cross or a flower, which is the problem being
+* fixed rather than a jigsaw piece.
+*
+* At least one of them is a tab. A piece with only blanks is a square with bites
+* taken out of it — recognisable as damaged, not as interlocking.
+*/
+var chooseEdges = (prng) => {
+	const count = prng.int(2, 3);
+	const sides = [
+		0,
+		1,
+		2,
+		3
+	];
+	for (let i = sides.length - 1; i > 0; i--) {
+		const j = prng.int(0, i);
+		const a = sides[i];
+		const b = sides[j];
+		if (a === void 0 || b === void 0) continue;
+		sides[i] = b;
+		sides[j] = a;
 	}
-	const cx = size / 2;
-	const cy = size / 2;
-	return { distance(lx, ly) {
-		const px = lx - cx;
-		const py = ly - cy;
-		let maxD = Number.NEGATIVE_INFINITY;
-		for (const [nx, ny] of normals) {
-			const d = px * nx + py * ny - inradius;
-			if (d > maxD) maxD = d;
-		}
-		return maxD;
-	} };
-};
-var createFlowerShape = (prng, size) => {
-	const petals = prng.int(4, 8);
-	const rAvg = size / 2 * prng.range(.72, .88);
-	const rAmp = rAvg * prng.range(.1, .22);
-	const phase = prng.next() * Math.PI * 2;
-	const cx = size / 2;
-	const cy = size / 2;
-	return { distance(lx, ly) {
-		const px = lx - cx;
-		const py = ly - cy;
-		return Math.hypot(px, py) - (rAvg + rAmp * Math.cos(petals * Math.atan2(py, px) + phase));
-	} };
+	const edges = [
+		"flat",
+		"flat",
+		"flat",
+		"flat"
+	];
+	const chosen = sides.slice(0, count);
+	for (const side of chosen) edges[side] = prng.next() < .55 ? "tab" : "blank";
+	if (!chosen.some((side) => edges[side] === "tab")) {
+		const first = chosen[0];
+		if (first !== void 0) edges[first] = "tab";
+	}
+	return edges;
 };
 /**
-* Pick a random shape family per call. The real piece and its hole are cut
-* from the same call so they match; decoys each call independently so they
-* form a mixed field of silhouettes on the frame.
+* Margin left between the silhouette and the edge of its bounding box, in px.
+*
+* One pixel for the anti-aliasing band plus a little slack. The box is the
+* piece's own image and the caller's placement maths assumes the shape is inside
+* it: a tab reaching the border comes out clipped flat, which looks like a
+* manufacturing defect rather than a jigsaw tab.
+*/
+var BOX_MARGIN = 1.5;
+/**
+* Build one jigsaw piece.
+*
+* The body is a rounded square; each chosen edge gets a tab or a blank, and the
+* whole silhouette is scaled down at the end if a tab would otherwise reach past
+* the bounding box the caller places.
 */
 var createNotchShape = (prng, size) => {
-	switch (prng.int(0, 4)) {
-		case 0: return createJigsawShape(prng, size);
-		case 1: return createCircleShape(prng, size);
-		case 2: return createRoundedRectShape(prng, size);
-		case 3: return createPolygonShape(prng, size);
-		default: return createFlowerShape(prng, size);
+	const knobRadius = size * prng.range(.13, .17);
+	const nominalHalf = size / 2 - knobRadius * 1.05;
+	const edges = chooseEdges(prng);
+	const knobs = [];
+	let cornerRadius = nominalHalf * prng.range(.14, .3);
+	let bodyHalf = nominalHalf;
+	for (let side = 0; side < 4; side = side + 1) {
+		const kind = edges[side];
+		if (kind === void 0 || kind === "flat") continue;
+		const { normal, along } = sideAxes(side);
+		const radius = knobRadius * prng.range(.88, 1.12);
+		const offset = kind === "tab" ? radius * .52 : -radius * .42;
+		const slideLimit = Math.max(0, bodyHalf - radius - cornerRadius * .6);
+		const slide = prng.range(-slideLimit, slideLimit) * .6;
+		knobs.push({
+			kind,
+			cx: normal[0] * (bodyHalf + offset) + along[0] * slide,
+			cy: normal[1] * (bodyHalf + offset) + along[1] * slide,
+			radius
+		});
 	}
+	let maxExtent = bodyHalf;
+	for (const knob of knobs) {
+		if (knob.kind !== "tab") continue;
+		maxExtent = Math.max(maxExtent, Math.abs(knob.cx) + knob.radius, Math.abs(knob.cy) + knob.radius);
+	}
+	const limit = size / 2 - BOX_MARGIN;
+	if (maxExtent > limit) {
+		const scale = limit / maxExtent;
+		bodyHalf *= scale;
+		cornerRadius *= scale;
+		for (const knob of knobs) {
+			knob.cx *= scale;
+			knob.cy *= scale;
+			knob.radius *= scale;
+		}
+	}
+	return { distance(lx, ly) {
+		const px = lx - size / 2;
+		const py = ly - size / 2;
+		let d = roundedBoxDistance(px, py, bodyHalf, cornerRadius);
+		for (const knob of knobs) if (knob.kind === "tab") d = Math.min(d, Math.hypot(px - knob.cx, py - knob.cy) - knob.radius);
+		for (const knob of knobs) if (knob.kind === "blank") d = Math.max(d, -(Math.hypot(px - knob.cx, py - knob.cy) - knob.radius));
+		return d;
+	} };
 };
 /**
 * Anti-aliased coverage in [0, 1] for a signed distance, using a one-pixel

package/dist/cjs/palette.cjs

@@ -1,3 +1,4 @@
+const require_contrast = require("./contrast.cjs");
 //#region src/palette.ts
 var PALETTES = [
 	{
@@ -75,20 +76,52 @@ var hslToRgb = (h, s, l) => {
 * colour and the mesh reads as one flat field with a slight gradient, which is
 * the difference between "designed" and "beige".
 */
-var drawPalette = (prng, count) => {
-	const spec = prng.pick(PALETTES);
+/**
+* The worst-case contrast ratio the palette's widest pair must reach, across
+* normal vision and all three dichromacies.
+*
+* This is a floor on the *range* a background spans, not on every pair — a mesh
+* gradient needs near-neighbours, and demanding contrast between them would
+* produce stripes. What it rules out is a field that is uniformly one brightness,
+* where hue is the only thing separating anything and a dichromat sees a flat
+* rectangle.
+*
+* 1.6 is chosen to be achievable rather than aspirational: the palettes are
+* analogous-hue families on purpose, and pushing this towards WCAG's 3:1 would
+* reject most of them and force the generator into the widened-lightness
+* fallback on nearly every draw, which would make every background look the
+* same. Separation of the piece from what it rests on is guaranteed by its
+* luminance-stepped rim in `compose.ts`, not by this; this stops the background
+* itself from having no structure at all.
+*/
+var MIN_PALETTE_CONTRAST = 1.6;
+/** How many times to redraw before widening the lightness band instead. */
+var MAX_PALETTE_ATTEMPTS = 6;
+var drawOnce = (prng, count, spec, lightnessBoost) => {
 	const baseHue = spec.hue + prng.range(-20, 20);
 	const direction = prng.next() < .5 ? -1 : 1;
+	const low = Math.max(.08, spec.lightness[0] - lightnessBoost);
+	const high = Math.min(.92, spec.lightness[1] + lightnessBoost);
 	const colours = [];
 	for (let i = 0; i < count; i++) {
 		const hue = baseHue + direction * ((count === 1 ? .5 : i / (count - 1)) - .5) * 2 * spec.spread + prng.range(-6, 6);
 		const saturation = prng.range(spec.saturation[0], spec.saturation[1]);
 		const pole = i % 2 === 0 ? 0 : 1;
-		const lightness = spec.lightness[pole] + prng.range(-.04, .04) * (pole === 0 ? 1 : -1);
+		const lightness = (pole === 0 ? low : high) + prng.range(-.04, .04) * (pole === 0 ? 1 : -1);
 		colours.push(hslToRgb(hue, saturation, lightness));
 	}
 	return colours;
 };
+var drawPalette = (prng, count) => {
+	const spec = prng.pick(PALETTES);
+	let last = drawOnce(prng, count, spec, 0);
+	for (let attempt = 1; attempt <= MAX_PALETTE_ATTEMPTS; attempt++) {
+		if (require_contrast.bestPairContrast(last) >= 1.6) return last;
+		last = drawOnce(prng, count, spec, attempt * .07);
+	}
+	return last;
+};
 //#endregion
+exports.MIN_PALETTE_CONTRAST = MIN_PALETTE_CONTRAST;
 exports.drawPalette = drawPalette;
 exports.hslToRgb = hslToRgb;

package/dist/compose.d.ts

@@ -1,6 +1,10 @@
 import { type NotchShape } from "./notch.js";
 import type { Prng } from "./prng.js";
 import type { NotchPlacement, RgbaImage } from "./types.js";
+export declare const pieceRimGeometry: (size: number) => {
+    plateau: number;
+    width: number;
+};
 export interface CutResult {
     background: RgbaImage;
     piece: RgbaImage;

package/dist/compose.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compose.d.ts","sourceRoot":"","sources":["../src/compose.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,KAAK,UAAU,EAAwB,MAAM,YAAY,CAAC;AACnE,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAiE5D,MAAM,WAAW,SAAS;IAEzB,UAAU,EAAE,SAAS,CAAC;IAEtB,KAAK,EAAE,SAAS,CAAC;CACjB;AAQD,eAAO,MAAM,QAAQ,SACd,IAAI,cACE,SAAS,SACd,UAAU,QACX,MAAM,aACD,cAAc,cACb,MAAM,KAChB,SA4GF,CAAC"}
+{"version":3,"file":"compose.d.ts","sourceRoot":"","sources":["../src/compose.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,KAAK,UAAU,EAAwB,MAAM,YAAY,CAAC;AACnE,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAsE5D,eAAO,MAAM,gBAAgB,SACtB,MAAM,KACV;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAalC,CAAC;AAmIF,MAAM,WAAW,SAAS;IAEzB,UAAU,EAAE,SAAS,CAAC;IAEtB,KAAK,EAAE,SAAS,CAAC;CACjB;AAQD,eAAO,MAAM,QAAQ,SACd,IAAI,cACE,SAAS,SACd,UAAU,QACX,MAAM,aACD,cAAc,cACb,MAAM,KAChB,SAyHF,CAAC"}

package/dist/compose.js

@@ -1,3 +1,4 @@
+import { relativeLuminance } from "./contrast.js";
 import { coverageFromDistance } from "./notch.js";
 //#region src/compose.ts
 /**
@@ -39,6 +40,74 @@ var HOLE_INNER_SHADOW = .45;
 * against the darkened cutout it drops into.
 */
 var PIECE_EDGE_LIGHT = 8;
+/**
+* The piece's outline, measured inwards from the silhouette, as a fraction of
+* the piece's size.
+*
+* Full strength out to `PLATEAU`, then tapering to nothing by `WIDTH`. A rim that
+* tapers from the very first pixel has its strongest values exactly where
+* anti-aliasing makes the pixels partly transparent, so the part of it that is
+* fully opaque is only ever half strength — the cue measures far weaker than the
+* number configuring it suggests. The plateau puts the full step on pixels that
+* are actually opaque, and the taper then stops it ending in a hard line.
+*
+* PROPORTIONAL, NOT A FIXED PIXEL COUNT. A 4px band is a tidy outline on a
+* 120px piece and most of the surface area of a 44px one — the default
+* `notchSize` — which made the whole piece read as a pale blob rather than as a
+* piece with a lit edge. Caught by rendering it and looking; no measurement of
+* rim-versus-core contrast can see it, because by that measure a piece that is
+* entirely rim scores perfectly.
+*/
+var PIECE_RIM_PLATEAU_RATIO = .03;
+var PIECE_RIM_WIDTH_RATIO = .065;
+/** Floors, so the rim does not vanish on a very small piece. */
+var PIECE_RIM_MIN_PLATEAU = 1;
+var PIECE_RIM_MIN_WIDTH = 2.2;
+/** Rim geometry for a piece of `size` px. Exported so tests measure the band the renderer actually drew. */
+var pieceRimGeometry = (size) => {
+	const plateau = Math.max(PIECE_RIM_MIN_PLATEAU, size * PIECE_RIM_PLATEAU_RATIO);
+	return {
+		plateau,
+		width: Math.max(PIECE_RIM_MIN_WIDTH, size * PIECE_RIM_WIDTH_RATIO, plateau + 1)
+	};
+};
+/**
+* The WCAG contrast ratio the rim aims to reach against the piece's own body.
+*
+* This is the separation cue, and it is deliberately not a hue. The piece is cut
+* from the same mesh the background is drawn from, so on an unlucky palette it
+* was the same colour as whatever it was resting on and the only thing dividing
+* them was a CSS drop-shadow. A luminance step survives what hue does not:
+* greyscale, a monochrome display, every dichromacy, and a phone screen in
+* sunlight.
+*
+* Expressed as a ratio rather than as a fixed byte offset because a fixed offset
+* is not a fixed cue: 40 units out of 255 is obvious on a mid grey and almost
+* invisible near white, where the same step is a much smaller fraction of the
+* luminance. The required offset is solved for per piece from the luminance it
+* actually has.
+*
+* 1.5 is comfortably visible without reading as a drawn border. The tests assert
+* a lower bound than this, because the taper and the per-pixel noise cost a
+* little of it.
+*/
+var PIECE_RIM_TARGET_CONTRAST = 1.5;
+/**
+* Cap on the rim offset, in 0-255 units. Past roughly this the rim stops reading
+* as a lit or shaded edge and starts reading as a stroke drawn around a sticker,
+* which is the look this is trying to avoid.
+*/
+var PIECE_RIM_MAX_STEP = 72;
+/**
+* Above this relative luminance the piece is treated as light, and gets a dark
+* rim rather than a light one.
+*
+* Picking the direction from the piece's own mean rather than fixing it is the
+* whole point: a fixed light rim vanishes on a pale background and a fixed dark
+* one vanishes on a dark background, which is how a cue that is present in the
+* code ends up absent on screen.
+*/
+var PIECE_RIM_DIRECTION_THRESHOLD = .4;
 var clamp255 = (v) => v < 0 ? 0 : v > 255 ? 255 : v;
 /**
 * Sample the background at `(x, y)`. Returns `null` when the coordinate
@@ -56,6 +125,49 @@ var sampleBackground = (image, x, y) => {
 	];
 };
 /**
+* Rim strength in [0, 1] for a signed distance: 1 on the plateau, tapering to 0
+* at the full width inside the silhouette, 0 beyond it.
+*/
+var rimProfile = (d, plateau, width) => {
+	if (d <= -width) return 0;
+	if (d >= -plateau) return 1;
+	return (d + width) / (width - plateau);
+};
+/** Approximate sRGB byte for a relative luminance. */
+var byteForLuminance = (luminance) => 255 * Math.max(0, Math.min(1, luminance)) ** (1 / 2.2);
+/**
+* The signed offset, in 0-255 units, to apply at the piece's rim.
+*
+* Averages the luminance of the pixels the piece will be cut from, picks the
+* direction that steps *away* from it, then solves for the offset that reaches
+* [`PIECE_RIM_TARGET_CONTRAST`] against it. A dark piece gets a light rim and a
+* light piece a dark one, so the cue is present whatever the palette produced —
+* which neither a fixed direction nor a fixed magnitude can promise.
+*/
+var pieceRimDelta = (background, shape, size, left, top) => {
+	let total = 0;
+	let counted = 0;
+	for (let ly = 0; ly < size; ly += 4) for (let lx = 0; lx < size; lx += 4) {
+		if (coverageFromDistance(shape.distance(lx, ly)) <= 0) continue;
+		const sample = sampleBackground(background, left + lx, top + ly);
+		if (sample === null) continue;
+		total += relativeLuminance({
+			r: sample[0],
+			g: sample[1],
+			b: sample[2]
+		});
+		counted++;
+	}
+	if (counted === 0) return PIECE_RIM_MAX_STEP;
+	const pieceLuminance = total / counted;
+	const lighten = pieceLuminance <= PIECE_RIM_DIRECTION_THRESHOLD;
+	const delta = byteForLuminance(lighten ? PIECE_RIM_TARGET_CONTRAST * (pieceLuminance + .05) - .05 : (pieceLuminance + .05) / PIECE_RIM_TARGET_CONTRAST - .05) - byteForLuminance(pieceLuminance);
+	const capped = Math.max(-PIECE_RIM_MAX_STEP, Math.min(PIECE_RIM_MAX_STEP, delta));
+	const floor = 24;
+	if (Math.abs(capped) < floor) return lighten ? floor : -24;
+	return capped;
+};
+/**
 * Cut the notch out of `background` and produce the matching piece.
 *
 * `background` is mutated in place — it is a freshly generated, single-use
@@ -67,6 +179,8 @@ var cutNotch = (prng, background, shape, size, placement, holeDarken) => {
 	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]);
+	const rimStep = pieceRimDelta(background, shape, size, left, top);
+	const rim = pieceRimGeometry(size);
 	for (let ly = 0; ly < size; ly++) for (let lx = 0; lx < size; lx++) {
 		const d = shape.distance(lx, ly);
 		const coverage = coverageFromDistance(d);
@@ -82,8 +196,9 @@ var cutNotch = (prng, background, shape, size, placement, holeDarken) => {
 		}
 		const [r, g, b] = sample;
 		const edgeLight = d > -2 ? PIECE_EDGE_LIGHT * (1 + d / 2) : 0;
+		const rimDelta = rimStep * rimProfile(d, rim.plateau, rim.width);
 		const noise = (prng.next() - .5) * 2 * PIECE_NOISE;
-		const delta = brightness + edgeLight + noise;
+		const delta = brightness + edgeLight + rimDelta + noise;
 		pieceData[pi] = clamp255(Math.round(r + delta));
 		pieceData[pi + 1] = clamp255(Math.round(g + delta));
 		pieceData[pi + 2] = clamp255(Math.round(b + delta));
@@ -123,4 +238,4 @@ var cutNotch = (prng, background, shape, size, placement, holeDarken) => {
 	};
 };
 //#endregion
-export { cutNotch };
+export { cutNotch, pieceRimGeometry };