@altnovatrail/canvas 0.0.0-stage → 0.1.1

package/lib/core/crop.js

@@ -0,0 +1,227 @@
+import RBush from "rbush";
+import { around, extentOf } from "./geometry.js";
+import { Sets } from "./sets.js";
+/**
+ * The crop's rule in its numbers (R25): sizes on the crop in pixels, heights on the sheet in units.
+ * The rule counts in whole numbers — places in tenths of a unit, as the groups do (R24) — and each
+ * number it hands out that is not whole is one division of two whole numbers, so that tutor's
+ * runner, which crops by the same rule, gets the same numbers to the bit.
+ */
+export const CROP = Object.freeze({
+    /** The margin around the work, px (R06). */
+    margin: 12,
+    /**
+     * A stroke lower than this, in units, is a line, not writing — a dot, a minus, a bar, an
+     * underline — and is in no bundle, nor joins any.
+     */
+    flat: 15,
+    /** The scale takes the median no higher than this, in units: a drawing alone stays a drawing. */
+    ceiling: 100,
+    /** The least width and height of a crop, px: Claude may err on images under 200 pixels. */
+    side: 200,
+    /**
+     * The longest side, px, and the most visual tokens, ⌈w / 28⌉ × ⌈h / 28⌉: what every model of
+     * Claude takes without scaling the image down, its standard tier.
+     */
+    edge: 1568,
+    tokens: 1568,
+    patch: 28,
+    /**
+     * The height of a digit a crop is drawn at unless the module's manifest says another, px: 24
+     * since the module format 0.2, with or without a manifest.
+     */
+    digit: 24,
+    /**
+     * The heights of digits a sample's crops are drawn at, px, until the eval protocol names its own
+     * (R09; R08 tutor).
+     */
+    heights: Object.freeze([16, 24, 32, 48]),
+    /** The tallest digit a crop takes, px: its ink then still stays within the margin. */
+    tallest: 256,
+});
+/** A stroke as the crop sees it: the box of its points in tenths. */
+/**
+ * The bundles of the strokes on a sheet (R25): strokes no lower than `CROP.flat`, joined by a chain
+ * of boxes that touch or overlap, whenever each was written. Each bundle by its IDs ascending, the
+ * bundles by their smallest ID.
+ */
+export function bundlesOf(strokes) {
+    return bundled(extentsOf(strokes))
+        .map((bundle) => bundle.map(({ id }) => id).sort(byNumber))
+        .sort((a, b) => (a[0] ?? 0) - (b[0] ?? 0));
+}
+/** h_med (R25): the lower median of the heights of the bundles, in units; `CROP.flat` if none. */
+export function medianOf(strokes) {
+    return medianTenths(extentsOf(strokes)) / 10;
+}
+/**
+ * The crop of the strokes on a sheet with its digits `digit` px high, and the frames of their
+ * groups (R25): the strokes the sheet shows, and their groups by the sheet's rule (R24). A sheet
+ * without strokes has no crop: it goes to no check (H3).
+ */
+export function cropOf(strokes, groups, digit = CROP.digit) {
+    if (!Number.isInteger(digit) || digit < 1 || digit > CROP.tallest) {
+        throw new RangeError(`a digit ${digit} px high: a crop takes whole px from 1 to ${CROP.tallest}`);
+    }
+    const extents = extentsOf(strokes);
+    const members = membersOf(groups, extents);
+    if (extents.length === 0)
+        return null;
+    const box = around(extents);
+    const median = medianTenths(extents);
+    const unit = Math.min(median, CROP.ceiling * 10);
+    let size = sizeOf(box, unit, digit);
+    // At a digit of 1 px every sheet fits: its sides are 200 px, for (14000 / 150 + 24) px is less.
+    while (!fits(size) && size.drawn > 1)
+        size = sizeOf(box, unit, size.drawn - 1);
+    const { drawn, width, height, top, left } = size;
+    // The line's width in twelfths of a px, 12 at least.
+    const line = Math.max(drawn, 12);
+    // Places on the crop as whole numbers, X × 24 × unit. A frame reaches past the points by half the
+    // line and by the pixel at its edge, which the raster still shades: (line / 24 + 1) px.
+    const across = (x) => 24 * ((x - box.minX) * drawn + left * unit);
+    const down = (y) => 24 * ((y - box.minY) * drawn + top * unit);
+    const reach = (line + 24) * unit;
+    const frames = groups.map(({ label }, n) => {
+        const frame = around(members[n] ?? []);
+        return {
+            label,
+            box: [
+                floorDiv(1000 * (down(frame.minY) - reach), 24 * unit * height),
+                floorDiv(1000 * (across(frame.minX) - reach), 24 * unit * width),
+                ceilDiv(1000 * (down(frame.maxY) + reach), 24 * unit * height),
+                ceilDiv(1000 * (across(frame.maxX) + reach), 24 * unit * width),
+            ],
+        };
+    });
+    const margins = [top, left];
+    const exact = { box, median: unit };
+    return {
+        digit,
+        drawn,
+        median: median / 10,
+        scale: (10 * drawn) / unit,
+        line: line / 12,
+        width,
+        height,
+        margins,
+        sheetBox: sheetBoxOf({ drawn, width, height, margins, exact }),
+        frames,
+        exact,
+    };
+}
+/**
+ * Where a crop with its margins lies on the sheet, its `sheet_box` (R25): [ymin, xmin, ymax, xmax]
+ * in units, each one division of two whole numbers, from the whole numbers of the crop. A
+ * submission's `sheet_box` is checked by it when the tutor's marks come back with it (R26).
+ */
+export function sheetBoxOf(crop) {
+    const { drawn, width, height, margins: [top, left], exact: { box, median: unit }, } = crop;
+    return [
+        (box.minY * drawn - top * unit) / (10 * drawn),
+        (box.minX * drawn - left * unit) / (10 * drawn),
+        (box.minY * drawn - top * unit + height * unit) / (10 * drawn),
+        (box.minX * drawn - left * unit + width * unit) / (10 * drawn),
+    ];
+}
+/**
+ * The strokes as the crop sees them. A stroke without points, or an ID twice, is no sheet's, and a
+ * point that is no finite place on the sheet is no point of it.
+ */
+function extentsOf(strokes) {
+    const seen = new Set();
+    return strokes.map((stroke) => {
+        if (seen.has(stroke.id))
+            throw new TypeError(`the stroke ${stroke.id} is on the sheet twice`);
+        seen.add(stroke.id);
+        return extentOf(stroke);
+    });
+}
+/**
+ * Each group's strokes. The groups are those of the strokes given: each stroke in one of them, and
+ * no stroke of a group missing from the sheet.
+ */
+function membersOf(groups, extents) {
+    const byId = new Map(extents.map((extent) => [extent.id, extent]));
+    const grouped = new Set();
+    const members = groups.map(({ label, ids }) => {
+        if (ids.length === 0)
+            throw new TypeError(`the group ${label} has no strokes`);
+        return ids.map((id) => {
+            const extent = byId.get(id);
+            if (extent === undefined)
+                throw new TypeError(`the group ${label} has a stroke ${id} not on the sheet`);
+            if (grouped.has(id))
+                throw new TypeError(`the stroke ${id} is in two groups`);
+            grouped.add(id);
+            return extent;
+        });
+    });
+    for (const { id } of extents) {
+        if (!grouped.has(id))
+            throw new TypeError(`the stroke ${id} is in no group`);
+    }
+    return members;
+}
+/** The bundles, each the extents of its strokes: the index finds the boxes that touch. */
+function bundled(extents) {
+    const tall = extents.filter(({ minY, maxY }) => maxY - minY >= CROP.flat * 10);
+    const index = new RBush().load(tall.map((extent, at) => ({ ...extent, at })));
+    const sets = new Sets(tall.length);
+    for (const [at, extent] of tall.entries()) {
+        for (const other of index.search(extent))
+            sets.join(at, other.at);
+    }
+    const bundles = new Map();
+    for (const [at, extent] of tall.entries()) {
+        const root = sets.root(at);
+        const bundle = bundles.get(root);
+        if (bundle === undefined)
+            bundles.set(root, [extent]);
+        else
+            bundle.push(extent);
+    }
+    return [...bundles.values()];
+}
+/** h_med in tenths: the height of the bundle in the lower middle, ⌊(n − 1) / 2⌋ from the lowest. */
+function medianTenths(extents) {
+    const heights = bundled(extents)
+        .map((bundle) => {
+        const { minY, maxY } = around(bundle);
+        return maxY - minY;
+    })
+        .sort(byNumber);
+    return heights[Math.floor((heights.length - 1) / 2)] ?? CROP.flat * 10;
+}
+function sizeOf(box, unit, drawn) {
+    const width = ceilDiv((box.maxX - box.minX) * drawn, unit) + 2 * CROP.margin;
+    const height = ceilDiv((box.maxY - box.minY) * drawn, unit) + 2 * CROP.margin;
+    return {
+        drawn,
+        width: Math.max(width, CROP.side),
+        height: Math.max(height, CROP.side),
+        top: CROP.margin + floorDiv(Math.max(CROP.side - height, 0), 2),
+        left: CROP.margin + floorDiv(Math.max(CROP.side - width, 0), 2),
+    };
+}
+/** Whether every model of Claude takes the crop as it is: no side too long, no tokens too many. */
+function fits(size) {
+    return Math.max(size.width, size.height) <= CROP.edge && tokensOf(size) <= CROP.tokens;
+}
+/** What Claude counts an image as: ⌈w / 28⌉ × ⌈h / 28⌉ visual tokens, each a patch 28 px square. */
+export function tokensOf({ width, height }) {
+    return ceilDiv(width, CROP.patch) * ceilDiv(height, CROP.patch);
+}
+/**
+ * ⌊a / b⌋ of two whole numbers, a ≥ 0 and b > 0: what is left over is taken away first, so the
+ * division is exact. The numbers of the rule stay below 2^53, where whole numbers are exact.
+ */
+function floorDiv(a, b) {
+    return (a - (a % b)) / b;
+}
+function ceilDiv(a, b) {
+    return floorDiv(a + b - 1, b);
+}
+function byNumber(a, b) {
+    return a - b;
+}

package/lib/core/eraser.d.ts

@@ -0,0 +1,42 @@
+import type { Stroke } from "./ink.js";
+import { type PointerSample } from "./recorder.js";
+import type { Point } from "./screen.js";
+/** `button` of a pen's eraser, its other end (Pointer Events Level 3). */
+export declare const ERASER_BUTTON = 5;
+/**
+ * The eraser (R22): one press of a pointer takes off the sheet, whole, every stroke its path comes
+ * near — a tap is a path of one point. The strokes it comes near are pending while it is down, and
+ * when it lifts they go to the handler the eraser is made with, in one action, with the page's
+ * time of the lift: one undo brings them all back. `pointercancel` drops the press and erases
+ * nothing. One pointer erases at a time, with the primary button or a pen's eraser.
+ */
+export declare class Eraser {
+    #private;
+    constructor(near: (from: Point, to: Point, reach: number) => readonly Stroke[], finished: (ids: readonly number[], time: number) => void);
+    /** The `pointerId` of the pointer erasing, or nothing between presses. */
+    get pointer(): number | undefined;
+    /** The IDs of the strokes the press under way has come near: they go when it lifts. */
+    get pending(): ReadonlySet<number>;
+    /**
+     * `pointerdown`: a press begins here, `reach` sheet units wide on either side, if none is under
+     * way and the primary button or a pen's eraser went down. It takes what lies under it at once.
+     */
+    down(sample: PointerSample, reach: number): boolean;
+    /**
+     * `pointermove`, once for each coalesced event: the eraser goes on to here, and says whether it
+     * came near a stroke it had not. A move without its button held ends the press where it was.
+     * A pointer out of sight of the sheet — beyond the part on the screen, where a captured pointer
+     * goes on — takes nothing, and the way goes on from the last place in sight when it comes back:
+     * the eraser takes only what the learner sees it pass.
+     */
+    move(sample: PointerSample, inSight?: boolean): boolean;
+    /** `pointerup`: the eraser goes on to where the pointer left, if in sight, and the press lands. */
+    up(sample: PointerSample, inSight?: boolean): boolean;
+    /** `pointercancel`: the device took the touch for an accident, and nothing is erased (R05). */
+    cancel(pointerId: number): boolean;
+    /**
+     * The press ends where the pointer last was, its `pointerup` never to come: the pointer's capture
+     * was lost, or the sheet left the page. Any pointer's press, unless one is named.
+     */
+    end(pointerId?: number): boolean;
+}

package/lib/core/eraser.js

@@ -0,0 +1,127 @@
+import { PRIMARY, PRIMARY_HELD } from "./recorder.js";
+/** `button` of a pen's eraser, its other end (Pointer Events Level 3). */
+export const ERASER_BUTTON = 5;
+/** The eraser's bit in `buttons`. */
+const ERASER_HELD = 32;
+const NONE = new Set();
+/**
+ * The eraser (R22): one press of a pointer takes off the sheet, whole, every stroke its path comes
+ * near — a tap is a path of one point. The strokes it comes near are pending while it is down, and
+ * when it lifts they go to the handler the eraser is made with, in one action, with the page's
+ * time of the lift: one undo brings them all back. `pointercancel` drops the press and erases
+ * nothing. One pointer erases at a time, with the primary button or a pen's eraser.
+ */
+export class Eraser {
+    #near;
+    #finished;
+    #press;
+    constructor(near, finished) {
+        this.#near = near;
+        this.#finished = finished;
+    }
+    /** The `pointerId` of the pointer erasing, or nothing between presses. */
+    get pointer() {
+        return this.#press?.pointerId;
+    }
+    /** The IDs of the strokes the press under way has come near: they go when it lifts. */
+    get pending() {
+        return this.#press?.hits ?? NONE;
+    }
+    /**
+     * `pointerdown`: a press begins here, `reach` sheet units wide on either side, if none is under
+     * way and the primary button or a pen's eraser went down. It takes what lies under it at once.
+     */
+    down(sample, reach) {
+        if (this.#press !== undefined)
+            return false;
+        let held;
+        if (sample.button === PRIMARY)
+            held = PRIMARY_HELD;
+        else if (sample.button === ERASER_BUTTON && sample.kind === "pen")
+            held = ERASER_HELD;
+        else
+            return false;
+        const point = { x: sample.x, y: sample.y };
+        const press = {
+            pointerId: sample.pointerId,
+            held,
+            reach,
+            last: point,
+            time: sample.time,
+            hits: new Set(),
+        };
+        this.#press = press;
+        this.#take(press, point);
+        return true;
+    }
+    /**
+     * `pointermove`, once for each coalesced event: the eraser goes on to here, and says whether it
+     * came near a stroke it had not. A move without its button held ends the press where it was.
+     * A pointer out of sight of the sheet — beyond the part on the screen, where a captured pointer
+     * goes on — takes nothing, and the way goes on from the last place in sight when it comes back:
+     * the eraser takes only what the learner sees it pass.
+     */
+    move(sample, inSight = true) {
+        const press = this.#press;
+        if (press === undefined || sample.pointerId !== press.pointerId)
+            return false;
+        if ((sample.buttons & press.held) === 0)
+            return this.#finish(press.time);
+        press.time = sample.time;
+        if (!inSight)
+            return false;
+        const point = { x: sample.x, y: sample.y };
+        const took = this.#take(press, point);
+        press.last = point;
+        return took;
+    }
+    /** `pointerup`: the eraser goes on to where the pointer left, if in sight, and the press lands. */
+    up(sample, inSight = true) {
+        const press = this.#press;
+        if (press === undefined || sample.pointerId !== press.pointerId)
+            return false;
+        if (inSight)
+            this.#take(press, { x: sample.x, y: sample.y });
+        return this.#finish(sample.time);
+    }
+    /** `pointercancel`: the device took the touch for an accident, and nothing is erased (R05). */
+    cancel(pointerId) {
+        if (this.#press?.pointerId !== pointerId)
+            return false;
+        this.#press = undefined;
+        return true;
+    }
+    /**
+     * The press ends where the pointer last was, its `pointerup` never to come: the pointer's capture
+     * was lost, or the sheet left the page. Any pointer's press, unless one is named.
+     */
+    end(pointerId) {
+        const press = this.#press;
+        if (press === undefined)
+            return false;
+        if (pointerId !== undefined && press.pointerId !== pointerId)
+            return false;
+        return this.#finish(press.time);
+    }
+    /** The strokes near the eraser's way from its last place to `to`: whether any was new. */
+    #take(press, to) {
+        let took = false;
+        for (const stroke of this.#near(press.last, to, press.reach)) {
+            if (press.hits.has(stroke.id))
+                continue;
+            press.hits.add(stroke.id);
+            took = true;
+        }
+        return took;
+    }
+    #finish(time) {
+        const press = this.#press;
+        if (press === undefined)
+            return false;
+        // The press is no longer under way by the time the handler has its strokes.
+        this.#press = undefined;
+        if (press.hits.size > 0)
+            this.#finished([...press.hits], time);
+        return true;
+    }
+}

package/lib/core/example.d.ts

@@ -0,0 +1,66 @@
+import type { DemoState } from "@altnovatrail/spec/canvas";
+import type * as open from "@altnovatrail/spec/formatv0/open";
+import type { GridKind } from "./grid.js";
+import { type PicturePart, SHEET_KIND, type SheetTemplate, type StatementPart, type TextPart, type Zone } from "./task.js";
+/** A lesson's worked example as a consumer gives it: spec's type (R73 spec). */
+export type WorkedExample = open.WorkedExample;
+/** The sheet of a worked example, as the element checked it: a handwriting sheet and its grid. */
+export interface ExampleCanvas {
+    readonly kind: typeof SHEET_KIND;
+    /** Squares unless given. */
+    readonly grid?: GridKind;
+    /** The grid's step in sheet units, a whole number from 20 to 500: 50 unless given. */
+    readonly grid_step?: number;
+}
+/** A picture of the demo on the sheet: shown on the layer of the author's demo, in its area. */
+export interface AreaPicture {
+    /** Its path from the module's media/, which the consumer's `media` takes to give its file. */
+    readonly picture: string;
+    /** What the picture shows, in words: "" for a picture that only decorates. */
+    readonly alt: string;
+    /** The area of the sheet it is shown in, at its size: on the sheet, by the rule lesson.areas. */
+    readonly area: Zone;
+}
+/** A part of the author's demo: a paragraph, a picture beside the sheet, or one on the sheet. */
+export type ExamplePart = TextPart | PicturePart | AreaPicture;
+/** A worked example as the element checked it: its statement, its sheet and its demo's parts. */
+export interface CheckedExample {
+    /** What the example asks, in the module's explanation language, as a task's statement. */
+    readonly statement: readonly StatementPart[];
+    readonly canvas: ExampleCanvas;
+    /** The parts of how the example is solved, in order: the learner opens them one at a time. */
+    readonly demo: readonly ExamplePart[];
+}
+/**
+ * How far the learner has gone through the author's demo (R42): how many of its parts are open,
+ * from the first, and whether the whole demo is hidden. app keeps it and may give it back. spec's
+ * type (R74 spec).
+ */
+export type { DemoState };
+/** Where every demo starts: no part open, and nothing hidden. One for every element. */
+export declare const DEMO_START: DemoState;
+/**
+ * A worked example's open view, checked as the format's schema and its rule lesson.areas check it,
+ * and a copy of it with the fields the schema names: the element reads each field once. What they
+ * refuse is a TypeError that names the field by its path. A field is left out by `undefined` alone:
+ * `null` is a value, and a wrong one.
+ */
+export declare function exampleOf(value: unknown): CheckedExample;
+/**
+ * What the sheet makes of a worked example, as of a task (R42): the grid on the sheet, the
+ * statement above it, and the pen alone, for the learner does not write on it.
+ */
+export declare function exampleTemplate(example: CheckedExample): SheetTemplate;
+/**
+ * The state of a demo of `parts` parts, checked (R42): an object of `opened`, a whole number from 0
+ * to `parts`, and `hidden`, true or false, both of them and nothing else. What it refuses is a
+ * TypeError that names the field by its path. It gives a frozen copy of its own.
+ */
+export declare function demoStateOf(value: unknown, parts: number): DemoState;
+/** Whether a part of the demo stands on the sheet, in an area of it. */
+export declare function onSheet(part: ExamplePart): part is AreaPicture;
+/**
+ * Whether two worked examples show the same (R42): the same statement, the same grid — its kind and
+ * step as drawn, the defaults filled in — and the same parts of the demo in the same order.
+ */
+export declare function sameExample(a: CheckedExample, b: CheckedExample): boolean;

package/lib/core/example.js

@@ -0,0 +1,116 @@
+// A lesson's worked example (R58 spec; R42): the open view of a segment `worked_example`, of spec's
+// type WorkedExample (R73 spec; R41) — its statement, the handwriting sheet the author's demo is
+// shown on, and the demo's parts in order: paragraphs, pictures beside the sheet and pictures on
+// areas of it. The element checks it as the schema does, every object closed (R32), and by the
+// format's rule lesson.areas too: an area lies on the sheet. What the check gives is the element's
+// own shape of the same example, the kinds of its parts apart, which the rest of the element reads,
+// and the sheet makes a template of it as of a task: its grid, its statement and the pen alone. How
+// far the learner has gone through the demo is a state of its own, which app keeps and gives back.
+import { closed, listOf, sameItems, shown, whole } from "./fields.js";
+import { SHEET } from "./sheet.js";
+import { altOf, gridFrom, gridOf, partOf, pictureOf, SHEET_KIND, samePart, textOrPictureOf, zoneOf, } from "./task.js";
+/** Where every demo starts: no part open, and nothing hidden. One for every element. */
+export const DEMO_START = Object.freeze({ opened: 0, hidden: false });
+/** The path the element names a worked example's fields by: its property's name. */
+const ROOT = "workedExample";
+/** The path the element names the state of a demo's fields by: its property's name. */
+const STATE = "demoState";
+/** A worked example's tools: the pen alone, which writes nothing on its sheet (R42). */
+const PEN_ALONE = Object.freeze(["pen"]);
+/**
+ * A worked example's open view, checked as the format's schema and its rule lesson.areas check it,
+ * and a copy of it with the fields the schema names: the element reads each field once. What they
+ * refuse is a TypeError that names the field by its path. A field is left out by `undefined` alone:
+ * `null` is a value, and a wrong one.
+ */
+export function exampleOf(value) {
+    const example = closed(value, ROOT, ["statement", "canvas", "demo"], "a worked example");
+    const statement = listOf(example.statement, `${ROOT}.statement`, 1, "parts", partOf);
+    const canvas = exampleCanvasOf(example.canvas, `${ROOT}.canvas`);
+    const demo = listOf(example.demo, `${ROOT}.demo`, 1, "parts of the demo", demoPartOf);
+    return { statement, canvas, demo };
+}
+/**
+ * What the sheet makes of a worked example, as of a task (R42): the grid on the sheet, the
+ * statement above it, and the pen alone, for the learner does not write on it.
+ */
+export function exampleTemplate(example) {
+    return { grid: gridFrom(example.canvas), statement: example.statement, tools: PEN_ALONE };
+}
+/**
+ * The state of a demo of `parts` parts, checked (R42): an object of `opened`, a whole number from 0
+ * to `parts`, and `hidden`, true or false, both of them and nothing else. What it refuses is a
+ * TypeError that names the field by its path. It gives a frozen copy of its own.
+ */
+export function demoStateOf(value, parts) {
+    const state = closed(value, STATE, ["opened", "hidden"], "the state of a demo");
+    const opened = whole(state.opened, `${STATE}.opened`, 0, parts);
+    if (typeof state.hidden !== "boolean") {
+        throw new TypeError(`${STATE}.hidden: true or false, not ${shown(state.hidden)}`);
+    }
+    return Object.freeze({ opened, hidden: state.hidden });
+}
+/** Whether a part of the demo stands on the sheet, in an area of it. */
+export function onSheet(part) {
+    return "area" in part;
+}
+/**
+ * Whether two worked examples show the same (R42): the same statement, the same grid — its kind and
+ * step as drawn, the defaults filled in — and the same parts of the demo in the same order.
+ */
+export function sameExample(a, b) {
+    const [one, other] = [gridFrom(a.canvas), gridFrom(b.canvas)];
+    return (sameItems(a.statement, b.statement, samePart) &&
+        one.kind === other.kind &&
+        one.step === other.step &&
+        sameItems(a.demo, b.demo, sameDemoPart));
+}
+/**
+ * The sheet of a worked example: a handwriting sheet and its grid, and no tools, for the learner
+ * does not write on it (README of the format, §21). A workbook is in no version of the format yet.
+ */
+function exampleCanvasOf(value, path) {
+    const canvas = closed(value, path, ["kind", "grid", "grid_step"], "a worked example's canvas");
+    if (canvas.kind !== SHEET_KIND) {
+        throw new TypeError(`${path}.kind: "${SHEET_KIND}", for a worked example is shown on a handwriting sheet, not ${shown(canvas.kind)}`);
+    }
+    return { kind: SHEET_KIND, ...gridOf(canvas, path) };
+}
+/**
+ * A part of the demo: a paragraph, a picture beside the sheet with its size, or a picture on the
+ * sheet with its area, which has no size of its own.
+ */
+function demoPartOf(value, path) {
+    const fields = ["text", "picture", "alt", "width", "height", "area"];
+    const part = closed(value, path, fields, "a part of the demo");
+    if (part.picture === undefined)
+        closed(part, path, ["text"], "a paragraph of the demo");
+    if (part.area === undefined)
+        return textOrPictureOf(part, path, "the demo");
+    closed(part, path, ["picture", "alt", "area"], "a picture on the sheet");
+    const picture = pictureOf(part.picture, `${path}.picture`);
+    const alt = altOf(part.alt, `${path}.alt`);
+    return { picture, alt, area: areaOf(part.area, `${path}.area`) };
+}
+/**
+ * An area of the sheet, as a zone is, that lies on the sheet: its right edge at most at the sheet's
+ * width and its bottom at most at its height, or the sheet could not show it (lesson.areas).
+ */
+function areaOf(value, path) {
+    const area = zoneOf(value, path);
+    if (area.left + area.width > SHEET.width || area.top + area.height > SHEET.height) {
+        throw new TypeError(`${path}: an area on the sheet, its right edge at most ${SHEET.width} and its bottom at most ${SHEET.height}, not ${shown(value)}`);
+    }
+    return area;
+}
+/** Whether two parts of the demo show the same: a paragraph, or a picture beside or on the sheet. */
+function sameDemoPart(a, b) {
+    if (!onSheet(a) || !onSheet(b))
+        return !onSheet(a) && !onSheet(b) && samePart(a, b);
+    return (a.picture === b.picture &&
+        a.alt === b.alt &&
+        a.area.left === b.area.left &&
+        a.area.top === b.area.top &&
+        a.area.width === b.area.width &&
+        a.area.height === b.area.height);
+}

package/lib/core/fields.d.ts

@@ -0,0 +1,29 @@
+/**
+ * What reads a value a consumer gives the element, such as a task or the tutor's marks: its fields,
+ * and the value itself as an error message shows it. A value the element cannot take is a
+ * TypeError that names the field by its path.
+ */
+/** The fields of an object; anything else is a TypeError at `path`. */
+export declare function record(value: unknown, path: string): Record<string, unknown>;
+/**
+ * The fields of an object closed as the module format closes its objects (R32), read once into a
+ * record of their own: a field it does not name is a TypeError at that field's path. A field left
+ * out by `undefined` is no field, and is not in the record.
+ */
+export declare function closed(value: unknown, path: string, names: readonly string[], what: string): Record<string, unknown>;
+/**
+ * A list of at least `least` items, each read by `each` at its own path. Array.from visits every
+ * index, a hole too, which map would pass over unchecked.
+ */
+export declare function listOf<T>(value: unknown, path: string, least: number, what: string, each: (item: unknown, path: string) => T): T[];
+/** A text for people to read: a string, not empty. */
+export declare function text(value: unknown, path: string, what: string): string;
+/**
+ * A whole number from `least` to `most`, or from `least` up, short of 2^53, where a number stops
+ * being exact.
+ */
+export declare function whole(value: unknown, path: string, least: number, most?: number): number;
+/** A value as an error message shows it. */
+export declare function shown(value: unknown): string;
+/** Whether two lists are the same, item by item, by `same`: by identity unless given. */
+export declare function sameItems<T>(a: readonly T[], b: readonly T[], same?: (x: T, y: T) => boolean): boolean;