pi-roundtable-drawing 0.7.0

package/src/cards/deck.ts

@@ -0,0 +1,204 @@
+import {
+	existsSync,
+	readdirSync,
+	readFileSync,
+	realpathSync,
+	statSync,
+} from "node:fs";
+import { extname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { Image } from "canvas";
+import { Type } from "typebox";
+import Value from "typebox/value";
+
+/** The image types node-canvas loads everywhere. */
+export const FACE_EXTENSIONS = [".png", ".jpg", ".jpeg", ".gif"] as const;
+
+/** A deck's id is its directory name; it is what the model passes as `deck`. */
+const DECK_ID = /^[a-z0-9][a-z0-9_-]*$/;
+
+/** The card heights, as a multiple of the width, that a spread can draw. */
+export const MIN_ASPECT = 0.25;
+export const MAX_ASPECT = 4;
+
+const CardEntry = Type.Object(
+	{
+		id: Type.String({ minLength: 1 }),
+		name: Type.String({ minLength: 1 }),
+		file: Type.Optional(Type.String({ minLength: 1 })),
+		group: Type.Optional(Type.String({ minLength: 1 })),
+	},
+	{ additionalProperties: false },
+);
+
+const Manifest = Type.Object(
+	{
+		name: Type.String({ minLength: 1 }),
+		reversals: Type.Optional(Type.Boolean()),
+		aspect: Type.Optional(
+			Type.Number({ minimum: MIN_ASPECT, maximum: MAX_ASPECT }),
+		),
+		cards: Type.Array(CardEntry, { minItems: 1 }),
+	},
+	{ additionalProperties: false },
+);
+
+export interface Card {
+	id: string;
+	name: string;
+	/** The face image, as an absolute path; undefined draws a plain tile with the name. */
+	face?: string;
+	group?: string;
+}
+
+export interface Deck {
+	/** The directory name, which the tool takes as `deck`. */
+	id: string;
+	/** The name the operator gave the deck in its manifest. */
+	name: string;
+	/** Whether a draw may turn cards upside down by default. */
+	reversals: boolean;
+	/** Card height divided by card width; undefined takes the ratio of the first face drawn. */
+	aspect?: number;
+	cards: readonly Card[];
+}
+
+/** A deck directory that cannot be used; the message names the deck and what to fix. */
+export class DeckError extends Error {
+	override name = "DeckError";
+}
+
+function fail(id: string, problem: string): never {
+	throw new DeckError(`deck ${id}: ${problem}`);
+}
+
+function readManifest(id: string, dir: string) {
+	const path = join(dir, "deck.json");
+	let json: unknown;
+	try {
+		json = JSON.parse(readFileSync(path, "utf8"));
+	} catch (error) {
+		return fail(
+			id,
+			`deck.json cannot be read as JSON (${error instanceof Error ? error.message : String(error)}).`,
+		);
+	}
+	if (!Value.Check(Manifest, json)) {
+		const first = Value.Errors(Manifest, json)[0];
+		return fail(
+			id,
+			`deck.json is not a valid manifest at ${first?.instancePath || "the top level"}: ${first?.message ?? "unknown problem"}.`,
+		);
+	}
+	return json;
+}
+
+/** Decodes the face once, so a file that is not an image stops the start rather than the first draw. */
+function checkImage(id: string, card: string, file: string, path: string) {
+	let problem: string | undefined;
+	const image = new Image();
+	image.onerror = (error) => {
+		problem = error.message;
+	};
+	image.src = readFileSync(path);
+	if (problem !== undefined || !image.complete || image.width === 0)
+		fail(
+			id,
+			`card ${card}: file ${file} cannot be read as an image${problem ? ` (${problem})` : ""}.`,
+		);
+	const aspect = image.height / image.width;
+	if (aspect < MIN_ASPECT || aspect > MAX_ASPECT)
+		fail(
+			id,
+			`card ${card}: file ${file} is ${image.width} by ${image.height} px, a height of ${aspect.toFixed(2)} times the width; cards must be between ${MIN_ASPECT} and ${MAX_ASPECT}.`,
+		);
+}
+
+/** Whether `path` is `dir` or below it. */
+function within(dir: string, path: string): boolean {
+	const inside = relative(dir, path);
+	return (
+		inside !== ".." && !inside.startsWith(`..${sep}`) && !isAbsolute(inside)
+	);
+}
+
+function faceFile(id: string, dir: string, card: string, file: string) {
+	const outside = () =>
+		fail(id, `card ${card}: file ${file} must stay inside the deck directory.`);
+	const path = resolve(dir, file);
+	if (isAbsolute(file) || !within(dir, path)) outside();
+	if (
+		!(FACE_EXTENSIONS as readonly string[]).includes(
+			extname(path).toLowerCase(),
+		)
+	)
+		fail(
+			id,
+			`card ${card}: file ${file} must be one of ${FACE_EXTENSIONS.join(", ")}.`,
+		);
+	if (!existsSync(path) || !statSync(path).isFile())
+		fail(
+			id,
+			`card ${card}: file ${file} does not exist in the deck directory.`,
+		);
+	// A link may not lead out of the deck directory either.
+	if (!within(realpathSync(dir), realpathSync(path))) outside();
+	checkImage(id, card, file, path);
+	return path;
+}
+
+/** Reads and checks one deck directory (`<id>/deck.json` and the faces it names). */
+export function loadDeck(id: string, dir: string): Deck {
+	if (!DECK_ID.test(id))
+		fail(
+			id,
+			"the directory name must be lowercase letters, digits, dashes, or underscores, starting with a letter or digit. Rename the directory.",
+		);
+	const manifest = readManifest(id, dir);
+	const seen = new Set<string>();
+	const cards = manifest.cards.map((entry): Card => {
+		if (seen.has(entry.id))
+			fail(id, `two cards share the id ${JSON.stringify(entry.id)}.`);
+		seen.add(entry.id);
+		return {
+			id: entry.id,
+			name: entry.name,
+			...(entry.file ? { face: faceFile(id, dir, entry.id, entry.file) } : {}),
+			...(entry.group ? { group: entry.group } : {}),
+		};
+	});
+	return {
+		id,
+		name: manifest.name,
+		reversals: manifest.reversals ?? true,
+		...(manifest.aspect ? { aspect: manifest.aspect } : {}),
+		cards,
+	};
+}
+
+/** Every deck under `deckDir`: each subdirectory that holds a `deck.json`. */
+export function loadDecks(deckDir: string): Deck[] {
+	if (!existsSync(deckDir) || !statSync(deckDir).isDirectory())
+		throw new DeckError(
+			`deckDir ${deckDir} is not a directory. Point it at the directory that holds one subdirectory for each deck.`,
+		);
+	const decks = readdirSync(deckDir, { withFileTypes: true })
+		.filter(
+			(entry) =>
+				entry.isDirectory() &&
+				existsSync(join(deckDir, entry.name, "deck.json")),
+		)
+		.map((entry) => loadDeck(entry.name, join(deckDir, entry.name)))
+		.sort((a, b) => a.id.localeCompare(b.id));
+	if (decks.length === 0)
+		throw new DeckError(
+			`deckDir ${deckDir} holds no deck: add a subdirectory with a deck.json for each deck.`,
+		);
+	return decks;
+}
+
+/** The groups a deck names for its cards, in order of first appearance. */
+export function groupsOf(deck: Deck): string[] {
+	return [
+		...new Set(deck.cards.flatMap((card) => (card.group ? [card.group] : []))),
+	];
+}

package/src/cards/draw.ts

@@ -0,0 +1,66 @@
+import { DrawingError } from "../errors.ts";
+import type { Random } from "../random.ts";
+import { type Card, type Deck, groupsOf } from "./deck.ts";
+
+export interface DrawnCard extends Card {
+	reversed: boolean;
+}
+
+export interface DrawParams {
+	deck: Deck;
+	count: number;
+	/** Draw only from the cards of this group. */
+	group?: string | undefined;
+	exclude?: readonly string[] | undefined;
+	/** Whether cards may come up reversed; the deck's own default when absent. */
+	allowReversed?: boolean | undefined;
+	random: Random;
+}
+
+/** Draws from the whole deck minus the exclusions; there is no persistent deck between draws. */
+export function drawCards(params: DrawParams): DrawnCard[] {
+	const { deck, count, group, exclude, allowReversed, random } = params;
+	if (!Number.isInteger(count) || count < 1)
+		throw new DrawingError(
+			`count must be a whole number of at least 1; got ${count}.`,
+		);
+	if (group !== undefined && !groupsOf(deck).includes(group))
+		throw new DrawingError(
+			`Deck ${deck.id} has no group ${JSON.stringify(group)}. ${
+				groupsOf(deck).length > 0
+					? `Its groups are ${groupsOf(deck).join(", ")}.`
+					: "It has no groups; omit group."
+			}`,
+		);
+	const known = new Set(deck.cards.map((card) => card.id));
+	const excluded = new Set(exclude ?? []);
+	for (const id of excluded)
+		if (!known.has(id))
+			throw new DrawingError(
+				`exclude names ${JSON.stringify(id)}, which is not a card of deck ${deck.id}. Use the card ids the deck lists.`,
+			);
+	const pool = deck.cards.filter(
+		(card) =>
+			!excluded.has(card.id) && (group === undefined || card.group === group),
+	);
+	if (count > pool.length)
+		throw new DrawingError(
+			`Cannot draw ${count} cards: only ${pool.length} are available in deck ${deck.id}${group ? ` group ${group}` : ""} with ${excluded.size} excluded.`,
+		);
+
+	// Fisher–Yates on the copy, then take the first `count`.
+	for (let i = pool.length - 1; i > 0; i--) {
+		const j = Math.floor(random() * (i + 1));
+		const a = pool[i];
+		const b = pool[j];
+		if (a && b) {
+			pool[i] = b;
+			pool[j] = a;
+		}
+	}
+	const reversible = allowReversed ?? deck.reversals;
+	return pool.slice(0, count).map((card) => ({
+		...card,
+		reversed: reversible ? random() < 0.5 : false,
+	}));
+}

package/src/cards/spread.ts

@@ -0,0 +1,232 @@
+import { type CanvasRenderingContext2D, createCanvas, loadImage } from "canvas";
+import { DrawingError } from "../errors.ts";
+import { ensureFont, font, PALETTE } from "../style.ts";
+import { type Deck, MAX_ASPECT, MIN_ASPECT } from "./deck.ts";
+import type { DrawnCard } from "./draw.ts";
+
+export interface SpreadPosition {
+	row: number;
+	col: number;
+	label: string;
+}
+
+/** The most rows or columns a spread of your own may use; the schema holds the model to it. */
+export const MAX_GRID = 10;
+
+const PADDING = 32;
+const HEADING = 64;
+const GAP = 20;
+const LABEL = 26;
+const NAME = 30;
+const DEFAULT_ASPECT = 1.5;
+/** The picture stays within what canvas can allocate. */
+const MAX_SIDE = 16384;
+const MAX_PIXELS = 40_000_000;
+
+function cardWidth(count: number): number {
+	if (count <= 5) return 200;
+	if (count <= 21) return 150;
+	return 110;
+}
+
+/** Without a custom spread, cards fill rows left to right: one row up to five, then wider rows. */
+export function autoLayout(count: number): SpreadPosition[] {
+	const cols = count <= 5 ? count : count <= 10 ? 5 : 7;
+	return Array.from({ length: count }, (_, i) => ({
+		row: Math.floor(i / cols),
+		col: i % cols,
+		label: "",
+	}));
+}
+
+/** A spread needs one position for each card, none shared. */
+export function checkSpread(
+	positions: readonly SpreadPosition[],
+	count: number,
+): void {
+	if (positions.length !== count)
+		throw new DrawingError(
+			`The spread has ${positions.length} positions for ${count} cards. Give one position for each card.`,
+		);
+	const cells = new Set<string>();
+	for (const { row, col } of positions) {
+		if (![row, col].every((n) => Number.isInteger(n) && n >= 0))
+			throw new DrawingError(
+				`Spread positions need a row and a column that are whole numbers from 0; got row ${row}, column ${col}.`,
+			);
+		const cell = `${row}:${col}`;
+		if (cells.has(cell))
+			throw new DrawingError(
+				`Two cards share row ${row}, column ${col}. Give each card its own position.`,
+			);
+		cells.add(cell);
+	}
+}
+
+function fitText(
+	ctx: CanvasRenderingContext2D,
+	text: string,
+	maxWidth: number,
+): string {
+	if (ctx.measureText(text).width <= maxWidth) return text;
+	let cut = text;
+	while (cut.length > 1 && ctx.measureText(`${cut}…`).width > maxWidth)
+		cut = cut.slice(0, -1);
+	return `${cut}…`;
+}
+
+/** Breaks text into lines no wider than `maxWidth`, at spaces and, for a long word, anywhere. */
+function wrapText(
+	ctx: CanvasRenderingContext2D,
+	text: string,
+	maxWidth: number,
+): string[] {
+	const lines: string[] = [];
+	let line = "";
+	for (const word of text.split(/\s+/).filter(Boolean)) {
+		const next = line ? `${line} ${word}` : word;
+		if (ctx.measureText(next).width <= maxWidth) {
+			line = next;
+			continue;
+		}
+		if (line) lines.push(line);
+		line = "";
+		for (const char of word) {
+			if (line && ctx.measureText(line + char).width > maxWidth) {
+				lines.push(line);
+				line = "";
+			}
+			line += char;
+		}
+	}
+	if (line) lines.push(line);
+	return lines;
+}
+
+/**
+ * Draws the cards on a dark ground, every face visible. A card without a face image is a tile
+ * with its name. A reversed card is drawn upside down and marked "reversed" under its name.
+ */
+export async function renderSpread(
+	deck: Deck,
+	cards: readonly DrawnCard[],
+	positions: readonly SpreadPosition[],
+	heading: { title: string; subtitle: string },
+): Promise<Uint8Array> {
+	checkSpread(positions, cards.length);
+	ensureFont();
+	const faces = await Promise.all(
+		cards.map(async (card) => {
+			if (!card.face) return undefined;
+			try {
+				return await loadImage(card.face);
+			} catch (error) {
+				throw new DrawingError(
+					`The face of card ${card.id} in deck ${deck.id} cannot be read as an image (${error instanceof Error ? error.message : String(error)}). Fix ${card.face}.`,
+				);
+			}
+		}),
+	);
+	const firstFace = faces.find((face) => face !== undefined);
+	const aspect =
+		deck.aspect ??
+		(firstFace ? firstFace.height / firstFace.width : DEFAULT_ASPECT);
+	if (aspect < MIN_ASPECT || aspect > MAX_ASPECT)
+		throw new DrawingError(
+			`Deck ${deck.id} draws cards ${aspect.toFixed(2)} times as tall as wide; set aspect in its deck.json to a value from ${MIN_ASPECT} to ${MAX_ASPECT}.`,
+		);
+	const width = cardWidth(cards.length);
+	const height = Math.round(width * aspect);
+	const hasLabels = positions.some((p) => p.label);
+	const cellW = width + GAP;
+	const cellH = (hasLabels ? LABEL : 0) + height + NAME + GAP;
+	const cols = Math.max(...positions.map((p) => p.col)) + 1;
+	const rows = Math.max(...positions.map((p) => p.row)) + 1;
+	const gridW = cols * cellW - GAP;
+	const canvasW = Math.max(PADDING * 2 + gridW, 520);
+	// A narrow spread is centred on the minimum width the heading needs.
+	const left = (canvasW - gridW) / 2;
+	const canvasH = PADDING * 2 + HEADING + rows * cellH - GAP;
+	if (
+		canvasW > MAX_SIDE ||
+		canvasH > MAX_SIDE ||
+		canvasW * canvasH > MAX_PIXELS
+	)
+		throw new DrawingError(
+			`The spread would be ${canvasW} by ${canvasH} px, which is too large to draw. Draw fewer cards or use a smaller grid.`,
+		);
+
+	const canvas = createCanvas(canvasW, canvasH);
+	const ctx = canvas.getContext("2d");
+	ctx.fillStyle = PALETTE.background;
+	ctx.fillRect(0, 0, canvasW, canvasH);
+
+	ctx.textBaseline = "top";
+	ctx.textAlign = "left";
+	ctx.fillStyle = PALETTE.accentLight;
+	ctx.font = font(20);
+	ctx.fillText(
+		fitText(ctx, heading.title, canvasW - PADDING * 2),
+		PADDING,
+		PADDING,
+	);
+	ctx.fillStyle = PALETTE.text;
+	ctx.font = font(26);
+	ctx.fillText(
+		fitText(ctx, heading.subtitle, canvasW - PADDING * 2),
+		PADDING,
+		PADDING + 26,
+	);
+
+	const top = PADDING + HEADING;
+	for (const [i, card] of cards.entries()) {
+		const position = positions[i];
+		if (!position) continue;
+		const x = left + position.col * cellW;
+		let y = top + position.row * cellH;
+		ctx.textAlign = "center";
+		ctx.textBaseline = "top";
+		if (hasLabels) {
+			ctx.fillStyle = PALETTE.accentLight;
+			ctx.font = font(16);
+			ctx.fillText(fitText(ctx, position.label, width), x + width / 2, y);
+			y += LABEL;
+		}
+
+		const face = faces[i];
+		// A reversed card turns upside down whole, face or tile; its name stays upright below.
+		ctx.save();
+		if (card.reversed) {
+			ctx.translate(x + width, y + height);
+			ctx.rotate(Math.PI);
+		} else {
+			ctx.translate(x, y);
+		}
+		if (face) {
+			ctx.drawImage(face, 0, 0, width, height);
+		} else {
+			ctx.fillStyle = PALETTE.surface;
+			ctx.fillRect(0, 0, width, height);
+			ctx.strokeStyle = PALETTE.accent;
+			ctx.lineWidth = 2;
+			ctx.strokeRect(1, 1, width - 2, height - 2);
+			ctx.fillStyle = PALETTE.text;
+			ctx.font = font(width < 150 ? 14 : 18);
+			ctx.textBaseline = "middle";
+			const lines = wrapText(ctx, card.name, width - 16).slice(0, 6);
+			const lineHeight = width < 150 ? 18 : 24;
+			const first = height / 2 - ((lines.length - 1) * lineHeight) / 2;
+			lines.forEach((line, n) => {
+				ctx.fillText(line, width / 2, first + n * lineHeight);
+			});
+		}
+		ctx.restore();
+		ctx.textBaseline = "top";
+
+		ctx.fillStyle = card.reversed ? PALETTE.accentLight : PALETTE.text;
+		ctx.font = font(width < 150 ? 12 : 15);
+		const name = card.reversed ? `${card.name} (reversed)` : card.name;
+		ctx.fillText(fitText(ctx, name, width), x + width / 2, y + height + 8);
+	}
+	return new Uint8Array(canvas.toBuffer("image/png"));
+}

package/src/errors.ts

@@ -0,0 +1,4 @@
+/** A drawing request the renderer cannot honour; its message says what to change and is meant for the model to read. */
+export class DrawingError extends Error {
+	override name = "DrawingError";
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export type { Card, Deck } from "./cards/deck.ts";
+export type { DrawingOptions } from "./plugin.ts";
+export { drawing } from "./plugin.ts";
+export type { Random } from "./random.ts";
+export { seededRandom } from "./random.ts";