@rapidmx/meet-plugin 0.15.0 → 0.16.0

package/apps/shared/collab/protocol.ts

@@ -0,0 +1,321 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * The payloads of the call's chat and shared whiteboard, carried as ordinary `SignalMessage`s (`chat`, `whiteboard`,
+ * `collab-sync-request`, `collab-sync` - see `../webrtc/types.ts`) over the meeting's signaling socket, and the
+ * validators every received one goes through. Everything here arrives from another participant's browser, which
+ * this one has no reason to trust beyond the sender identity the server stamps on the envelope: a payload that is
+ * malformed, out of range or too big is dropped whole by `parseChat()`/`parseWhiteboardOp()`/`parseSync()` before
+ * anything renders it.
+ *
+ * ## The board
+ *
+ * The whiteboard is a fixed `BOARD_WIDTH` x `BOARD_HEIGHT` coordinate space (16:9), whatever size each participant's
+ * window shows it at, holding three kinds of `BoardElement`: a freehand `stroke` drawn with one of `PEN_TYPES`, a
+ * `shape` drawn with the stencil (`STENCIL_SHAPES`), and a `stamp` (one of `STAMPS`). Coordinates are whole board
+ * units, so a stroke's points travel as a flat `[x0, y0, x1, y1, ...]` integer array.
+ *
+ * An element's id starts with its author's peer id (`<peer>:<n>`), and only its author may add to it - a `points`
+ * op or a second `add` under someone else's id is ignored, so nobody can rewrite another participant's drawing. Anyone
+ * may remove any element, though: erasing is a shared-board action, as on a real whiteboard.
+ *
+ * Clearing the board raises its `epoch`. Every element records the epoch it was drawn in, and an element from an
+ * older epoch is dropped wherever it shows up - so a participant who missed the clear, or a late joiner's catch-up
+ * sent by someone who did, cannot bring cleared drawings back.
+ */
+
+export const BOARD_WIDTH = 1600;
+export const BOARD_HEIGHT = 900;
+
+/** The freehand pens, each with its own look - see `whiteboardRender.ts`. */
+export const PEN_TYPES = ["ballpoint", "sharpie", "marker", "crayon", "pencil"] as const;
+export type PenType = (typeof PEN_TYPES)[number];
+
+/** What the stencil draws: dragged out from one corner (or end) to the other. */
+export const STENCIL_SHAPES = ["line", "arrow", "rect", "ellipse", "triangle", "star"] as const;
+export type StencilShape = (typeof STENCIL_SHAPES)[number];
+
+/** The stamps a participant can place. A received stamp outside this list is ignored, so an arbitrary string from
+ * another participant is never drawn - the same rule as the call's reactions (`REACTION_EMOJIS`). */
+export const STAMPS = ["⭐", "❤️", "✅", "❌", "❓", "❗", "💡", "👍", "👎", "😀", "🎉", "🔥", "➡️", "⬅️", "⬆️", "⬇️"] as const;
+export type Stamp = (typeof STAMPS)[number];
+
+/** The pen/line sizes, smallest first - an element's `size` is one of these. */
+export const SIZES = [2, 4, 8, 14, 24] as const;
+export const STAMP_SIZES = [32, 56, 96, 160] as const;
+
+/** The longest chat message, in characters. */
+export const MAX_CHAT_LENGTH = 4000;
+/** The most points one stroke may hold - about a minute of continuous drawing. */
+export const MAX_STROKE_POINTS = 8000;
+/** The most points one `points` op (or the first batch of an `add`) may carry. */
+export const MAX_POINTS_PER_OP = 2000;
+/** The most elements a board holds; drawing past it is refused until something is erased. */
+export const MAX_BOARD_ELEMENTS = 5000;
+/** The most chat messages kept; older ones are dropped. */
+export const MAX_CHAT_HISTORY = 500;
+/** The most ids one `remove` op may name. */
+export const MAX_REMOVE_IDS = 500;
+/** The longest element or chat id. */
+export const MAX_ID_LENGTH = 200;
+/** The longest display name a catch-up may carry for a chat message. */
+export const MAX_NAME_LENGTH = 200;
+
+export interface StrokeElement {
+    kind: "stroke";
+    id: string;
+    epoch: number;
+    pen: PenType;
+    color: string;
+    size: number;
+    /** Flat `[x0, y0, x1, y1, ...]`, whole board units. */
+    points: number[];
+}
+
+export interface ShapeElement {
+    kind: "shape";
+    id: string;
+    epoch: number;
+    shape: StencilShape;
+    color: string;
+    size: number;
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+}
+
+export interface StampElement {
+    kind: "stamp";
+    id: string;
+    epoch: number;
+    stamp: Stamp;
+    size: number;
+    x: number;
+    y: number;
+}
+
+export type BoardElement = StrokeElement | ShapeElement | StampElement;
+
+export type WhiteboardOp =
+    /** A new element - for a stroke, its first points; the rest follow in `points` ops. */
+    | { op: "add"; element: BoardElement }
+    /** More points of the sender's own stroke `id`, written from point index `start` on (so a repeat is harmless). */
+    | { op: "points"; id: string; start: number; points: number[] }
+    | { op: "remove"; ids: string[] }
+    /** The board was cleared, now at `epoch`. */
+    | { op: "clear"; epoch: number };
+
+/** One chat message as its author sends it. */
+export interface ChatPayload {
+    id: string;
+    text: string;
+    /** The author's clock, ms since the epoch - only for display, never for ordering. */
+    sentAt: number;
+}
+
+/** One chat message as a catch-up carries it: who sent it travels inside, since the envelope names the catch-up's sender. */
+export interface ChatHistoryEntry extends ChatPayload {
+    peer: string;
+    name: string;
+}
+
+/** One part of the catch-up an existing participant sends a newcomer - see `CollabSession`. */
+export interface SyncPayload {
+    part: number;
+    of: number;
+    epoch: number;
+    chat: ChatHistoryEntry[];
+    ops: WhiteboardOp[];
+}
+
+const COLOR_PATTERN = /^#[0-9a-f]{6}$/;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function isId(value: unknown): value is string {
+    return typeof value === "string" && value.length > 0 && value.length <= MAX_ID_LENGTH;
+}
+
+function isCoordinate(value: unknown, max: number): value is number {
+    return Number.isInteger(value) && (value as number) >= -max && (value as number) <= 2 * max;
+}
+
+function isEpoch(value: unknown): value is number {
+    return Number.isInteger(value) && (value as number) >= 0;
+}
+
+function isPoints(value: unknown, max: number): value is number[] {
+    if (!Array.isArray(value) || value.length % 2 !== 0 || value.length / 2 > max) {
+        return false;
+    }
+    for (let i = 0; i < value.length; i += 2) {
+        if (!isCoordinate(value[i], BOARD_WIDTH) || !isCoordinate(value[i + 1], BOARD_HEIGHT)) {
+            return false;
+        }
+    }
+    return true;
+}
+
+/** `color` as a lowercase `#rrggbb`, or `undefined` when it is not one. */
+export function normalizeColor(color: unknown): string | undefined {
+    if (typeof color !== "string") {
+        return undefined;
+    }
+    const lower = color.toLowerCase();
+    return COLOR_PATTERN.test(lower) ? lower : undefined;
+}
+
+/** Whether `id` is one `peer` may author - see this module's doc comment. */
+export function isOwnId(id: string, peer: string): boolean {
+    return id.startsWith(`${peer}:`);
+}
+
+function parseElement(value: unknown): BoardElement | undefined {
+    if (!isRecord(value) || !isId(value.id) || !isEpoch(value.epoch)) {
+        return undefined;
+    }
+    const { id, epoch } = value;
+    switch (value.kind) {
+        case "stroke": {
+            const color = normalizeColor(value.color);
+            if (!PEN_TYPES.includes(value.pen as PenType) || !color || !SIZES.includes(value.size as never) || !isPoints(value.points, MAX_POINTS_PER_OP) || value.points.length === 0) {
+                return undefined;
+            }
+            return { kind: "stroke", id, epoch, pen: value.pen as PenType, color, size: value.size as number, points: [...value.points] };
+        }
+        case "shape": {
+            const color = normalizeColor(value.color);
+            if (
+                !STENCIL_SHAPES.includes(value.shape as StencilShape) ||
+                !color ||
+                !SIZES.includes(value.size as never) ||
+                !isCoordinate(value.x1, BOARD_WIDTH) ||
+                !isCoordinate(value.y1, BOARD_HEIGHT) ||
+                !isCoordinate(value.x2, BOARD_WIDTH) ||
+                !isCoordinate(value.y2, BOARD_HEIGHT)
+            ) {
+                return undefined;
+            }
+            const { x1, y1, x2, y2 } = value as unknown as ShapeElement;
+            return { kind: "shape", id, epoch, shape: value.shape as StencilShape, color, size: value.size as number, x1, y1, x2, y2 };
+        }
+        case "stamp": {
+            if (!STAMPS.includes(value.stamp as Stamp) || !STAMP_SIZES.includes(value.size as never) || !isCoordinate(value.x, BOARD_WIDTH) || !isCoordinate(value.y, BOARD_HEIGHT)) {
+                return undefined;
+            }
+            return { kind: "stamp", id, epoch, stamp: value.stamp as Stamp, size: value.size as number, x: value.x, y: value.y };
+        }
+        default:
+            return undefined;
+    }
+}
+
+/** A received whiteboard op, validated and copied, or `undefined` to drop it. */
+export function parseWhiteboardOp(value: unknown): WhiteboardOp | undefined {
+    if (!isRecord(value)) {
+        return undefined;
+    }
+    switch (value.op) {
+        case "add": {
+            const element = parseElement(value.element);
+            return element ? { op: "add", element } : undefined;
+        }
+        case "points":
+            if (!isId(value.id) || !Number.isInteger(value.start) || (value.start as number) < 0 || (value.start as number) >= MAX_STROKE_POINTS) {
+                return undefined;
+            }
+            if (!isPoints(value.points, MAX_POINTS_PER_OP) || value.points.length === 0) {
+                return undefined;
+            }
+            return { op: "points", id: value.id, start: value.start as number, points: [...value.points] };
+        case "remove":
+            if (!Array.isArray(value.ids) || value.ids.length === 0 || value.ids.length > MAX_REMOVE_IDS || !value.ids.every(isId)) {
+                return undefined;
+            }
+            return { op: "remove", ids: [...(value.ids)] };
+        case "clear":
+            return isEpoch(value.epoch) ? { op: "clear", epoch: value.epoch } : undefined;
+        default:
+            return undefined;
+    }
+}
+
+/** A received chat message, validated and copied, or `undefined` to drop it. Blank text is dropped too. */
+export function parseChat(value: unknown): ChatPayload | undefined {
+    if (!isRecord(value) || !isId(value.id) || typeof value.text !== "string" || typeof value.sentAt !== "number" || !Number.isFinite(value.sentAt)) {
+        return undefined;
+    }
+    if (value.text.length > MAX_CHAT_LENGTH || !value.text.trim()) {
+        return undefined;
+    }
+    return { id: value.id, text: value.text, sentAt: value.sentAt };
+}
+
+/** A received catch-up part, validated and copied; entries that fail validation are left out rather than dropping
+ * the whole part, and `undefined` only when the part itself is malformed. */
+export function parseSync(value: unknown): SyncPayload | undefined {
+    if (!isRecord(value) || !Number.isInteger(value.part) || !Number.isInteger(value.of) || !isEpoch(value.epoch)) {
+        return undefined;
+    }
+    const part = value.part as number;
+    const of = value.of as number;
+    if (of < 1 || part < 0 || part >= of || !Array.isArray(value.chat) || !Array.isArray(value.ops)) {
+        return undefined;
+    }
+    const chat: ChatHistoryEntry[] = [];
+    for (const entry of value.chat) {
+        const parsed = parseChat(entry);
+        if (parsed && isRecord(entry) && isId(entry.peer) && typeof entry.name === "string" && entry.name.length <= MAX_NAME_LENGTH) {
+            chat.push({ ...parsed, peer: entry.peer, name: entry.name });
+        }
+    }
+    const ops: WhiteboardOp[] = [];
+    for (const op of value.ops) {
+        const parsed = parseWhiteboardOp(op);
+        if (parsed) {
+            ops.push(parsed);
+        }
+    }
+    return { part, of, epoch: value.epoch, chat, ops };
+}
+
+/** What a participant's pointer on the board shows: the pen, or the stencil, stamp or eraser, they have picked. */
+export const CURSOR_TOOLS = [...PEN_TYPES, "stencil", "stamp", "eraser"] as const;
+export type CursorTool = (typeof CURSOR_TOOLS)[number];
+
+/** Where a participant's pointer is on the board, and as what - or that it has left the board. Never stored, never
+ * part of a catch-up: a pointer is only ever where it was a moment ago. */
+export type CursorPayload = { hidden: true } | { x: number; y: number; tool: CursorTool; color: string; stamp?: Stamp };
+
+/** A received pointer update, validated and copied, or `undefined` to drop it. */
+export function parseCursor(value: unknown): CursorPayload | undefined {
+    if (!isRecord(value)) {
+        return undefined;
+    }
+    if (value.hidden === true) {
+        return { hidden: true };
+    }
+    const color = normalizeColor(value.color);
+    if (!CURSOR_TOOLS.includes(value.tool as CursorTool) || !color || !isCoordinate(value.x, BOARD_WIDTH) || !isCoordinate(value.y, BOARD_HEIGHT)) {
+        return undefined;
+    }
+    if (value.stamp !== undefined && !STAMPS.includes(value.stamp as Stamp)) {
+        return undefined;
+    }
+    const cursor: CursorPayload = { x: value.x, y: value.y, tool: value.tool as CursorTool, color };
+    if (value.stamp !== undefined) {
+        cursor.stamp = value.stamp as Stamp;
+    }
+    return cursor;
+}
+
+/** `value` rounded and kept within `[0, max]` - every coordinate this participant sends is, so no receiver's
+ * validation (which allows some slack beyond the board) ever drops it. */
+export function clampCoordinate(value: number, max: number): number {
+    return Math.min(max, Math.max(0, Math.round(Number.isFinite(value) ? value : 0)));
+}

package/apps/shared/collab/whiteboardRender.ts

@@ -0,0 +1,311 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Draws the whiteboard's elements on a 2D canvas, in board units (`protocol.ts`'s `BOARD_WIDTH` x `BOARD_HEIGHT`)
+ * scaled to the canvas. Each pen has its own look:
+ *
+ * - **ballpoint** - a thin, even, opaque line.
+ * - **sharpie** - a bolder opaque line with round ends.
+ * - **marker** - a broad, square-tipped, translucent stroke laid down in `multiply`, so it highlights what is under
+ * it instead of covering it, and doesn't darken where it overlaps itself (the stroke is one path).
+ * - **crayon** - a waxy translucent base speckled with grain, like wax catching on paper.
+ * - **pencil** - a coloring pencil: several fine, slightly offset, faint passes that build up a grainy line.
+ *
+ * The grain of a crayon or pencil comes from a random generator seeded by the element's id, so every participant's
+ * board draws the very same texture for the same stroke - it is not re-randomized per screen or per redraw.
+ */
+import { BOARD_HEIGHT, BOARD_WIDTH, type BoardElement, type ShapeElement, type StampElement, type StrokeElement } from "./protocol.js";
+
+/** The subset of `CanvasRenderingContext2D` the renderer uses, so a test can record calls on a plain object. */
+export type BoardContext = Pick<
+    CanvasRenderingContext2D,
+    | "save"
+    | "restore"
+    | "setTransform"
+    | "clearRect"
+    | "fillRect"
+    | "beginPath"
+    | "closePath"
+    | "moveTo"
+    | "lineTo"
+    | "quadraticCurveTo"
+    | "ellipse"
+    | "stroke"
+    | "fill"
+    | "fillText"
+    | "lineWidth"
+    | "lineCap"
+    | "lineJoin"
+    | "strokeStyle"
+    | "fillStyle"
+    | "globalAlpha"
+    | "globalCompositeOperation"
+    | "font"
+    | "textAlign"
+    | "textBaseline"
+>;
+
+/** The board's paper color. */
+export const BOARD_BACKGROUND = "#ffffff";
+
+/** The font stack stamps are drawn in - each platform's color emoji font first. */
+export const STAMP_FONT_FAMILY = '"Apple Color Emoji", "Segoe UI Emoji", "Noto Color Emoji", sans-serif';
+
+/** A small, fast, seedable PRNG (mulberry32) - returns numbers in [0, 1). */
+export function seededRandom(seed: string): () => number {
+    let state = 2166136261;
+    for (let i = 0; i < seed.length; i++) {
+        state = Math.imul(state ^ seed.charCodeAt(i), 16777619);
+    }
+    return () => {
+        state = (state + 0x6d2b79f5) | 0;
+        let t = Math.imul(state ^ (state >>> 15), 1 | state);
+        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+
+/** Clears the canvas to paper and draws `elements` in order, `scale` canvas pixels per board unit. */
+export function renderBoard(ctx: BoardContext, elements: readonly BoardElement[], scale: number): void {
+    ctx.save();
+    ctx.setTransform(1, 0, 0, 1, 0, 0);
+    ctx.globalAlpha = 1;
+    ctx.globalCompositeOperation = "source-over";
+    ctx.fillStyle = BOARD_BACKGROUND;
+    ctx.fillRect(0, 0, BOARD_WIDTH * scale, BOARD_HEIGHT * scale);
+    ctx.setTransform(scale, 0, 0, scale, 0, 0);
+    for (const element of elements) {
+        drawElement(ctx, element);
+    }
+    ctx.restore();
+}
+
+export function drawElement(ctx: BoardContext, element: BoardElement): void {
+    ctx.save();
+    switch (element.kind) {
+        case "stroke":
+            drawStroke(ctx, element);
+            break;
+        case "shape":
+            drawShape(ctx, element);
+            break;
+        case "stamp":
+            drawStamp(ctx, element);
+            break;
+    }
+    ctx.restore();
+}
+
+/** Traces a smooth path through `points` (curves through the midpoints between them), offset by (`dx`, `dy`). */
+function tracePath(ctx: BoardContext, points: readonly number[], dx = 0, dy = 0): void {
+    ctx.beginPath();
+    ctx.moveTo(points[0] + dx, points[1] + dy);
+    if (points.length === 2) {
+        // A single tap still leaves a dot.
+        ctx.lineTo(points[0] + dx + 0.01, points[1] + dy);
+        return;
+    }
+    for (let i = 2; i < points.length - 2; i += 2) {
+        const midX = (points[i] + points[i + 2]) / 2;
+        const midY = (points[i + 1] + points[i + 3]) / 2;
+        ctx.quadraticCurveTo(points[i] + dx, points[i + 1] + dy, midX + dx, midY + dy);
+    }
+    ctx.lineTo(points[points.length - 2] + dx, points[points.length - 1] + dy);
+}
+
+function drawStroke(ctx: BoardContext, stroke: StrokeElement): void {
+    const { points, size, color } = stroke;
+    ctx.strokeStyle = color;
+    ctx.fillStyle = color;
+    ctx.lineJoin = "round";
+    ctx.lineCap = "round";
+    switch (stroke.pen) {
+        case "ballpoint":
+            ctx.lineWidth = Math.max(1.2, size * 0.6);
+            tracePath(ctx, points);
+            ctx.stroke();
+            return;
+        case "sharpie":
+            ctx.lineWidth = size * 1.4;
+            tracePath(ctx, points);
+            ctx.stroke();
+            return;
+        case "marker":
+            ctx.globalCompositeOperation = "multiply";
+            ctx.globalAlpha = 0.4;
+            ctx.lineCap = "square";
+            ctx.lineWidth = size * 3;
+            tracePath(ctx, points);
+            ctx.stroke();
+            return;
+        case "crayon":
+            drawCrayon(ctx, stroke);
+            return;
+        case "pencil":
+            drawPencil(ctx, stroke);
+            return;
+    }
+}
+
+function drawCrayon(ctx: BoardContext, stroke: StrokeElement): void {
+    const random = seededRandom(stroke.id);
+    const width = stroke.size * 1.8;
+    ctx.globalAlpha = 0.55;
+    ctx.lineWidth = width;
+    tracePath(ctx, stroke.points);
+    ctx.stroke();
+    // Grain: specks scattered across the stroke's width along every segment, more for a longer segment.
+    ctx.globalAlpha = 0.7;
+    const speck = Math.max(1, width / 6);
+    eachSegment(stroke.points, (x0, y0, x1, y1, length) => {
+        const count = Math.ceil((length * width) / 18);
+        for (let i = 0; i < count; i++) {
+            const t = random();
+            const spread = (random() - 0.5) * width;
+            const along = (random() - 0.5) * speck;
+            ctx.fillRect(x0 + (x1 - x0) * t + spread * 0.7 + along, y0 + (y1 - y0) * t + spread * 0.7 - along, speck, speck);
+        }
+    });
+}
+
+function drawPencil(ctx: BoardContext, stroke: StrokeElement): void {
+    const random = seededRandom(stroke.id);
+    ctx.lineWidth = Math.max(0.8, stroke.size * 0.45);
+    ctx.globalAlpha = 0.35;
+    const passes = 3;
+    const jitter = Math.max(0.6, stroke.size * 0.35);
+    for (let pass = 0; pass < passes; pass++) {
+        tracePath(ctx, stroke.points, (random() - 0.5) * jitter, (random() - 0.5) * jitter);
+        ctx.stroke();
+    }
+}
+
+/** Calls `visit` with each segment of `points` and its length; a single point is a zero-length segment. */
+function eachSegment(points: readonly number[], visit: (x0: number, y0: number, x1: number, y1: number, length: number) => void): void {
+    if (points.length === 2) {
+        visit(points[0], points[1], points[0], points[1], 1);
+        return;
+    }
+    for (let i = 0; i < points.length - 2; i += 2) {
+        const [x0, y0, x1, y1] = [points[i], points[i + 1], points[i + 2], points[i + 3]];
+        visit(x0, y0, x1, y1, Math.hypot(x1 - x0, y1 - y0));
+    }
+}
+
+function drawShape(ctx: BoardContext, shape: ShapeElement): void {
+    const { x1, y1, x2, y2 } = shape;
+    ctx.strokeStyle = shape.color;
+    ctx.lineWidth = shape.size;
+    ctx.lineJoin = "round";
+    ctx.lineCap = "round";
+    ctx.beginPath();
+    const left = Math.min(x1, x2);
+    const top = Math.min(y1, y2);
+    const width = Math.abs(x2 - x1);
+    const height = Math.abs(y2 - y1);
+    switch (shape.shape) {
+        case "line":
+            ctx.moveTo(x1, y1);
+            ctx.lineTo(x2, y2);
+            break;
+        case "arrow": {
+            ctx.moveTo(x1, y1);
+            ctx.lineTo(x2, y2);
+            const angle = Math.atan2(y2 - y1, x2 - x1);
+            const head = Math.max(12, shape.size * 4);
+            for (const side of [-1, 1]) {
+                ctx.moveTo(x2, y2);
+                ctx.lineTo(x2 - head * Math.cos(angle + side * (Math.PI / 7)), y2 - head * Math.sin(angle + side * (Math.PI / 7)));
+            }
+            break;
+        }
+        case "rect":
+            ctx.moveTo(left, top);
+            ctx.lineTo(left + width, top);
+            ctx.lineTo(left + width, top + height);
+            ctx.lineTo(left, top + height);
+            ctx.closePath();
+            break;
+        case "ellipse":
+            ctx.ellipse(left + width / 2, top + height / 2, width / 2, height / 2, 0, 0, Math.PI * 2);
+            break;
+        case "triangle":
+            ctx.moveTo(left + width / 2, top);
+            ctx.lineTo(left + width, top + height);
+            ctx.lineTo(left, top + height);
+            ctx.closePath();
+            break;
+        case "star":
+            for (const [i, [px, py]] of starPoints(left, top, width, height).entries()) {
+                if (i === 0) {
+                    ctx.moveTo(px, py);
+                } else {
+                    ctx.lineTo(px, py);
+                }
+            }
+            ctx.closePath();
+            break;
+    }
+    ctx.stroke();
+}
+
+/** The ten corners of a five-pointed star filling the given box, starting at its top point. */
+export function starPoints(left: number, top: number, width: number, height: number): [number, number][] {
+    const cx = left + width / 2;
+    const cy = top + height / 2;
+    const corners: [number, number][] = [];
+    for (let i = 0; i < 10; i++) {
+        const radius = i % 2 === 0 ? 1 : 0.4;
+        const angle = -Math.PI / 2 + (i * Math.PI) / 5;
+        corners.push([cx + (Math.cos(angle) * radius * width) / 2, cy + (Math.sin(angle) * radius * height) / 2]);
+    }
+    return corners;
+}
+
+function drawStamp(ctx: BoardContext, stamp: StampElement): void {
+    ctx.font = `${stamp.size}px ${STAMP_FONT_FAMILY}`;
+    ctx.textAlign = "center";
+    ctx.textBaseline = "middle";
+    ctx.fillStyle = "#000000";
+    ctx.fillText(stamp.stamp, stamp.x, stamp.y);
+}
+
+function distanceToSegment(px: number, py: number, x0: number, y0: number, x1: number, y1: number): number {
+    const dx = x1 - x0;
+    const dy = y1 - y0;
+    const lengthSquared = dx * dx + dy * dy;
+    const t = lengthSquared === 0 ? 0 : Math.max(0, Math.min(1, ((px - x0) * dx + (py - y0) * dy) / lengthSquared));
+    return Math.hypot(px - (x0 + t * dx), py - (y0 + t * dy));
+}
+
+/** Whether the eraser at (`x`, `y`) with `radius`, in board units, touches `element`. A stroke or line counts its own
+ * width; a closed shape is touched on its outline's bounding box, a stamp anywhere on its square. */
+export function hitTest(element: BoardElement, x: number, y: number, radius: number): boolean {
+    switch (element.kind) {
+        case "stroke": {
+            const reach = radius + element.size;
+            let hit = false;
+            eachSegment(element.points, (x0, y0, x1, y1) => {
+                hit = hit || distanceToSegment(x, y, x0, y0, x1, y1) <= reach;
+            });
+            return hit;
+        }
+        case "shape": {
+            const reach = radius + element.size;
+            if (element.shape === "line" || element.shape === "arrow") {
+                return distanceToSegment(x, y, element.x1, element.y1, element.x2, element.y2) <= reach;
+            }
+            const left = Math.min(element.x1, element.x2) - reach;
+            const right = Math.max(element.x1, element.x2) + reach;
+            const top = Math.min(element.y1, element.y2) - reach;
+            const bottom = Math.max(element.y1, element.y2) + reach;
+            return x >= left && x <= right && y >= top && y <= bottom;
+        }
+        case "stamp": {
+            const half = element.size / 2 + radius;
+            return Math.abs(x - element.x) <= half && Math.abs(y - element.y) <= half;
+        }
+    }
+}