@altnovatrail/canvas 0.0.0-stage → 0.1.0

package/lib/core/hands.js

@@ -0,0 +1,273 @@
+/**
+ * A touch wider or taller than this, in CSS pixels, is a palm (R29). WebKit on iPadOS gives a touch
+ * twice its contact's radius, a fingertip's 40–60 px by one report, so canvas-api's 30 px would
+ * take most fingers there for palms. T22 measures it on the devices.
+ */
+export const PALM_PX = 100;
+/**
+ * Two touches that come down at most this many milliseconds apart are two fingers of one gesture
+ * (R29): Android's tap timeout, 100 ms, with a margin for children's fingers.
+ */
+export const PAIR_MS = 150;
+/**
+ * How far a touch may wander, in CSS pixels, before it is going somewhere (R29): Android's touch
+ * slop, 8 dp. A finger that has gone further is writing, and two fingers scroll once their middle
+ * has gone further.
+ */
+export const SLOP_PX = 8;
+/**
+ * The pen mode (R29): on from a pen's touch on a sheet, off when the learner asks for the finger.
+ * While it is on, a finger neither writes nor erases. One is shared by every sheet of a page, and
+ * it lives in memory alone: nothing is stored or sent, and a new page starts without it.
+ *
+ * It knows, too, whether any sheet of the page is written on: a row of buttons changes between the
+ * strokes of the whole page alone, for a row that wraps moves the sheets below it as well.
+ */
+export class PenMode {
+    #on = false;
+    #watchers = new Set();
+    #sheets = new Set();
+    get on() {
+        return this.#on;
+    }
+    /** Every watcher hears of a change. */
+    set on(on) {
+        if (on === this.#on)
+            return;
+        this.#on = on;
+        this.#tell();
+    }
+    /** Whether a pointer writes or erases now on a sheet of the page. */
+    get writing() {
+        for (const writes of this.#sheets)
+            if (writes())
+                return true;
+        return false;
+    }
+    /**
+     * `watcher` hears of every change from now on, and of every stroke that ends, until the function
+     * this gives is called.
+     */
+    watch(watcher) {
+        this.#watchers.add(watcher);
+        return () => {
+            this.#watchers.delete(watcher);
+        };
+    }
+    /** A sheet tells whether it is written on, until the function this gives is called. */
+    enlist(writes) {
+        this.#sheets.add(writes);
+        return () => {
+            this.#sheets.delete(writes);
+        };
+    }
+    /** A pointer lifted off a sheet: once no sheet is written on, every watcher hears of it. */
+    settle() {
+        if (!this.writing)
+            this.#tell();
+    }
+    #tell() {
+        for (const watcher of [...this.#watchers])
+            watcher();
+    }
+}
+/**
+ * The hands on a sheet (R29): which pointer may write, which is a palm, and which two fingers
+ * scroll, for a pen, fingers and a mouse on one screen.
+ * - One pointer writes at a time, as before (R18), and the sheet's recorder and eraser say which.
+ * - A pen's touch puts the page in pen mode and takes away the stroke of a touch under way: it was
+ *   a palm. While a pen or a mouse writes, a touch does nothing until it lifts.
+ * - A touch wider or taller than `PALM_PX`, at its `pointerdown` or at any move, is a palm: it does
+ *   nothing until it lifts, and what it was writing goes.
+ * - Without pen mode the first finger writes. A second that comes down within `PAIR_MS`, before the
+ *   first has gone `SLOP_PX`, takes the first one's stroke away, and the two scroll. A second that
+ *   comes later does nothing.
+ * - In pen mode a finger writes nothing, and two that come down within `PAIR_MS` scroll.
+ * - A third finger does nothing. When one of the two lifts, the other does nothing until it lifts.
+ * - Two fingers scroll by the travel of their middle down the screen, past the first `SLOP_PX`.
+ * - Any other pointer, a mouse or one of no type, writes when nothing does, whatever the mode.
+ */
+export class Hands {
+    #sheet;
+    #mode;
+    #hands = new Map();
+    #gesture;
+    constructor(sheet, mode) {
+        this.#sheet = sheet;
+        this.#mode = mode;
+    }
+    /** What each pointer down on the sheet does now. */
+    get roles() {
+        return new Map([...this.#hands].map(([id, hand]) => [id, hand.role]));
+    }
+    /** Whether a pointer is down on the sheet: the hands saw it come down, and not yet lift. */
+    knows(pointerId) {
+        return this.#hands.has(pointerId);
+    }
+    /** Whether two fingers make a gesture now: they wait for their slop, or scroll. */
+    get scrolling() {
+        return this.#gesture !== undefined;
+    }
+    /** `pointerdown`: whether this pointer may write or erase. */
+    down(contact) {
+        // A pointer that comes down again was lost on its way up.
+        this.lift(contact.pointerId);
+        if (contact.kind === "pen")
+            return this.#pen(contact);
+        if (contact.kind === "touch")
+            return this.#touch(contact);
+        return this.#add(contact, this.#sheet.writer() === undefined ? "writes" : "idle");
+    }
+    /** `pointermove`, once for each coalesced event: whether this pointer writes on. */
+    move(contact) {
+        const hand = this.#hands.get(contact.pointerId);
+        if (hand === undefined)
+            return false;
+        if (hand.kind === "touch" && hand.role !== "palm" && isPalm(contact)) {
+            // A palm that has grown: what it was doing goes.
+            if (this.#sheet.writer() === contact.pointerId)
+                this.#sheet.drop(contact.pointerId);
+            if (hand.role === "scrolls")
+                this.#end();
+            hand.role = "palm";
+            return false;
+        }
+        hand.y = contact.y;
+        hand.travel = Math.max(hand.travel, Math.hypot(contact.x - hand.x0, contact.y - hand.y0));
+        if (hand.role === "scrolls")
+            this.#step();
+        return hand.role === "writes" && this.#sheet.writer() === contact.pointerId;
+    }
+    /** `pointerup`, `pointercancel` or a lost capture: the pointer has gone, and its gesture too. */
+    lift(pointerId) {
+        const hand = this.#hands.get(pointerId);
+        if (hand === undefined)
+            return;
+        if (hand.role === "scrolls")
+            this.#end();
+        this.#hands.delete(pointerId);
+    }
+    /** The sheet has left the page, and no pointer is down on it now. */
+    reset() {
+        this.#hands.clear();
+        this.#gesture = undefined;
+    }
+    #pen(contact) {
+        this.#mode.on = true;
+        // A touch writing when a pen comes was a palm, and its stroke goes. A gesture under way ends,
+        // and every touch down now does nothing until it lifts.
+        const writer = this.#sheet.writer();
+        if (writer !== undefined && this.#hands.get(writer)?.kind === "touch")
+            this.#sheet.drop(writer);
+        this.#gesture = undefined;
+        for (const hand of this.#hands.values()) {
+            if (hand.kind === "touch" && hand.role !== "palm")
+                hand.role = "idle";
+        }
+        return this.#add(contact, this.#sheet.writer() === undefined ? "writes" : "idle");
+    }
+    #touch(contact) {
+        if (isPalm(contact))
+            return this.#add(contact, "palm");
+        const writer = this.#sheet.writer();
+        // While a pen or a mouse writes, or two fingers scroll, a touch does nothing.
+        const writing = writer === undefined ? undefined : this.#hands.get(writer);
+        if ((writer !== undefined && writing?.kind !== "touch") || this.#gesture !== undefined) {
+            return this.#add(contact, "idle");
+        }
+        if (this.#mode.on) {
+            // In pen mode a finger writes nothing: it waits for a second one to scroll with.
+            const partner = this.#latest("waits", contact);
+            this.#add(contact, partner === undefined ? "waits" : "scrolls");
+            if (partner !== undefined)
+                this.#pair(partner, contact.pointerId);
+            return false;
+        }
+        // Without it the first finger writes, and a second soon after makes the two a scroll.
+        const first = this.#latest("writes", contact);
+        if (first !== undefined && (this.#hands.get(first)?.travel ?? 0) <= SLOP_PX) {
+            if (writer === first)
+                this.#sheet.drop(first);
+            this.#add(contact, "scrolls");
+            this.#pair(first, contact.pointerId);
+            return false;
+        }
+        return this.#add(contact, writer === undefined ? "writes" : "idle");
+    }
+    #add(contact, role) {
+        this.#hands.set(contact.pointerId, {
+            kind: contact.kind,
+            role,
+            x0: contact.x,
+            y0: contact.y,
+            t0: contact.time,
+            y: contact.y,
+            travel: 0,
+        });
+        return role === "writes";
+    }
+    /** The touch in `role` that came down last, at most `PAIR_MS` before this one, if any. */
+    #latest(role, contact) {
+        let found;
+        let at = -Infinity;
+        for (const [id, hand] of this.#hands) {
+            if (hand.kind !== "touch" || hand.role !== role || id === contact.pointerId)
+                continue;
+            if (contact.time - hand.t0 > PAIR_MS || hand.t0 < at)
+                continue;
+            found = id;
+            at = hand.t0;
+        }
+        return found;
+    }
+    #pair(first, second) {
+        const one = this.#hands.get(first);
+        const two = this.#hands.get(second);
+        if (one === undefined || two === undefined)
+            return;
+        one.role = "scrolls";
+        two.role = "scrolls";
+        this.#gesture = { fingers: [first, second], from: (one.y + two.y) / 2, last: undefined };
+    }
+    /** The gesture ends: its fingers do nothing until they lift. */
+    #end() {
+        const gesture = this.#gesture;
+        if (gesture === undefined)
+            return;
+        this.#gesture = undefined;
+        for (const id of gesture.fingers) {
+            const hand = this.#hands.get(id);
+            if (hand?.role === "scrolls")
+                hand.role = "idle";
+        }
+    }
+    /** The two fingers' middle has moved: past the slop, the sheet goes with it. */
+    #step() {
+        const gesture = this.#gesture;
+        if (gesture === undefined)
+            return;
+        const one = this.#hands.get(gesture.fingers[0]);
+        const two = this.#hands.get(gesture.fingers[1]);
+        if (one === undefined || two === undefined)
+            return;
+        const middle = (one.y + two.y) / 2;
+        if (gesture.last === undefined) {
+            const gone = middle - gesture.from;
+            if (Math.abs(gone) <= SLOP_PX)
+                return;
+            // The slop is where the gesture starts: the sheet moves from there, without a jump.
+            gesture.last = middle;
+            this.#sheet.scroll(gone - Math.sign(gone) * SLOP_PX, true);
+            return;
+        }
+        if (middle === gesture.last)
+            return;
+        const dy = middle - gesture.last;
+        gesture.last = middle;
+        this.#sheet.scroll(dy, false);
+    }
+}
+/** Whether a touch is too big for a finger: a palm, or the side of a hand. */
+function isPalm(contact) {
+    return contact.width > PALM_PX || contact.height > PALM_PX;
+}

package/lib/core/history.d.ts

@@ -0,0 +1,42 @@
+import type { HistoryEvent } from "@altnovatrail/spec/canvas";
+import type { Stroke } from "./ink.js";
+/**
+ * An event of the history of writing (R09, R22): spec's type, of the contract of canvas and app
+ * (R74 spec; R07). What an action on the sheet did, at the sheet's time `t` when it landed, in the
+ * order the actions landed; each event says which strokes it put on the sheet or took off, so
+ * whoever reads the history replays it without the rules of the stack of undo (R19). Those the
+ * sheet hands out are frozen through (R27).
+ */
+export type { HistoryEvent };
+/**
+ * The strokes a history leaves on the sheet, in the order they were written: what the sheet shows
+ * after it (R09).
+ */
+export declare function replay(history: readonly HistoryEvent[]): Stroke[];
+/**
+ * The events of a history given to the sheet (R27), each checked field by field and copied into
+ * frozen objects of the sheet's own, with only the fields the sheet keeps: others are passed over.
+ * A value that is not such a history is a TypeError that names the field. Each event must be one of
+ * the four, at a time from 0 that never goes back along the history; a stroke must have a new ID, a
+ * whole number from 1, and one point at least, each on the sheet, with a pressure from 0 to 1, its
+ * times never going back and none after the time it landed. Times are checked for their order
+ * alone: with several pointers at once (T35) strokes may overlap in time. Whether the actions keep
+ * the rules of the stack, the work on the sheet checks as it replays them (`Work.restore`).
+ */
+export declare function historyOf(value: unknown): HistoryEvent[];
+/**
+ * An event, frozen through: its stroke with its points, or its lists of IDs (R27). Whoever holds
+ * an event the sheet handed out cannot change the sheet by it.
+ */
+export declare function frozen(event: HistoryEvent): HistoryEvent;
+/**
+ * Whether a value given as a history is the history the sheet has (R27): the very array, or a list
+ * whose every event says what the sheet's says, by the fields the sheet keeps — others are passed
+ * over. `undefined` is the empty history. It never throws: a value that is no history is simply not
+ * the same one.
+ */
+export declare function sameHistory(value: unknown, history: readonly HistoryEvent[]): boolean;
+/** Whether a history is the beginning of another: shorter, and the same event for event. */
+export declare function begins(history: readonly HistoryEvent[], of: readonly HistoryEvent[]): boolean;
+/** Whether a value says what an event of the sheet's history says, by the fields it keeps. */
+export declare function sameEvent(value: unknown, event: HistoryEvent): boolean;

package/lib/core/history.js

@@ -0,0 +1,228 @@
+import { record, shown } from "./fields.js";
+import { SHEET } from "./sheet.js";
+/**
+ * The strokes a history leaves on the sheet, in the order they were written: what the sheet shows
+ * after it (R09).
+ */
+export function replay(history) {
+    const written = [];
+    const visible = new Set();
+    for (const event of history) {
+        switch (event.kind) {
+            case "write":
+                written.push(event.stroke);
+                visible.add(event.stroke.id);
+                break;
+            case "erase":
+            case "clear":
+                for (const id of event.ids)
+                    visible.delete(id);
+                break;
+            case "undo":
+                for (const id of event.removed)
+                    visible.delete(id);
+                for (const id of event.restored)
+                    visible.add(id);
+                break;
+        }
+    }
+    return written.filter((stroke) => visible.has(stroke.id));
+}
+/**
+ * The events of a history given to the sheet (R27), each checked field by field and copied into
+ * frozen objects of the sheet's own, with only the fields the sheet keeps: others are passed over.
+ * A value that is not such a history is a TypeError that names the field. Each event must be one of
+ * the four, at a time from 0 that never goes back along the history; a stroke must have a new ID, a
+ * whole number from 1, and one point at least, each on the sheet, with a pressure from 0 to 1, its
+ * times never going back and none after the time it landed. Times are checked for their order
+ * alone: with several pointers at once (T35) strokes may overlap in time. Whether the actions keep
+ * the rules of the stack, the work on the sheet checks as it replays them (`Work.restore`).
+ */
+export function historyOf(value) {
+    if (!Array.isArray(value))
+        throw new TypeError(`history: a list of events, not ${shown(value)}`);
+    const ids = new Set();
+    let latest = 0;
+    // Array.from visits every index, a hole too, which map would pass over unchecked.
+    return Array.from(value, (item, n) => {
+        const path = `history[${n}]`;
+        const fields = record(item, path);
+        const t = timeOf(fields.t, `${path}.t`);
+        if (t < latest) {
+            throw new TypeError(`${path}.t: ${t}, earlier than the event before it, at ${latest}`);
+        }
+        latest = t;
+        switch (fields.kind) {
+            case "write": {
+                const stroke = strokeOf(fields.stroke, `${path}.stroke`);
+                if (ids.has(stroke.id)) {
+                    throw new TypeError(`${path}.stroke.id: ${stroke.id}, the ID of a stroke written before`);
+                }
+                ids.add(stroke.id);
+                const end = stroke.points.at(-1)?.t ?? 0;
+                if (t < end) {
+                    throw new TypeError(`${path}.t: ${t}, earlier than the stroke's last point, at ${end}`);
+                }
+                return frozen({ kind: "write", t, stroke });
+            }
+            case "erase":
+                return frozen({ kind: "erase", t, ids: idsOf(fields.ids, `${path}.ids`) });
+            case "clear":
+                return frozen({ kind: "clear", t, ids: idsOf(fields.ids, `${path}.ids`) });
+            case "undo":
+                return frozen({
+                    kind: "undo",
+                    t,
+                    removed: idsOf(fields.removed, `${path}.removed`),
+                    restored: idsOf(fields.restored, `${path}.restored`),
+                });
+            default:
+                throw new TypeError(`${path}.kind: "write", "erase", "clear" or "undo", not ${shown(fields.kind)}`);
+        }
+    });
+}
+/**
+ * An event, frozen through: its stroke with its points, or its lists of IDs (R27). Whoever holds
+ * an event the sheet handed out cannot change the sheet by it.
+ */
+export function frozen(event) {
+    if (event.kind === "write") {
+        for (const point of event.stroke.points)
+            Object.freeze(point);
+        Object.freeze(event.stroke.points);
+        Object.freeze(event.stroke);
+    }
+    else if (event.kind === "undo") {
+        Object.freeze(event.removed);
+        Object.freeze(event.restored);
+    }
+    else {
+        Object.freeze(event.ids);
+    }
+    return Object.freeze(event);
+}
+/**
+ * Whether a value given as a history is the history the sheet has (R27): the very array, or a list
+ * whose every event says what the sheet's says, by the fields the sheet keeps — others are passed
+ * over. `undefined` is the empty history. It never throws: a value that is no history is simply not
+ * the same one.
+ */
+export function sameHistory(value, history) {
+    if (value === history)
+        return true;
+    if (value === undefined)
+        return history.length === 0;
+    if (!Array.isArray(value) || value.length !== history.length)
+        return false;
+    try {
+        return history.every((event, n) => sameEvent(value[n], event));
+    }
+    catch {
+        // A getter of the consumer's that throws: no history the sheet keeps.
+        return false;
+    }
+}
+/** Whether a history is the beginning of another: shorter, and the same event for event. */
+export function begins(history, of) {
+    return history.length < of.length && history.every((event, n) => sameEvent(of[n], event));
+}
+/** Whether a value says what an event of the sheet's history says, by the fields it keeps. */
+export function sameEvent(value, event) {
+    if (value === event)
+        return true;
+    if (typeof value !== "object" || value === null)
+        return false;
+    const given = value;
+    if (given.kind !== event.kind || given.t !== event.t)
+        return false;
+    switch (event.kind) {
+        case "write":
+            return sameStroke(given.stroke, event.stroke);
+        case "erase":
+        case "clear":
+            return sameIds(given.ids, event.ids);
+        case "undo":
+            return sameIds(given.removed, event.removed) && sameIds(given.restored, event.restored);
+    }
+}
+function sameStroke(value, stroke) {
+    if (value === stroke)
+        return true;
+    if (typeof value !== "object" || value === null)
+        return false;
+    const given = value;
+    const points = given.points;
+    return (given.id === stroke.id &&
+        given.kind === stroke.kind &&
+        Array.isArray(points) &&
+        points.length === stroke.points.length &&
+        stroke.points.every((point, n) => samePoint(points[n], point)));
+}
+function samePoint(value, point) {
+    if (value === point)
+        return true;
+    if (typeof value !== "object" || value === null)
+        return false;
+    const given = value;
+    return given.x === point.x && given.y === point.y && given.t === point.t && given.p === point.p;
+}
+function sameIds(value, ids) {
+    return (value === ids ||
+        (Array.isArray(value) && value.length === ids.length && ids.every((id, n) => value[n] === id)));
+}
+function strokeOf(value, path) {
+    const fields = record(value, path);
+    const id = idOf(fields.id, `${path}.id`);
+    if (typeof fields.kind !== "string") {
+        throw new TypeError(`${path}.kind: the pointer's type, a string, not ${shown(fields.kind)}`);
+    }
+    if (!Array.isArray(fields.points)) {
+        throw new TypeError(`${path}.points: a list of points, not ${shown(fields.points)}`);
+    }
+    if (fields.points.length === 0) {
+        throw new TypeError(`${path}.points: a list of points, one at least, not an empty one`);
+    }
+    let latest = 0;
+    const points = Array.from(fields.points, (item, n) => {
+        const at = `${path}.points[${n}]`;
+        const point = record(item, at);
+        const x = within(point.x, `${at}.x`, 0, SHEET.width);
+        const y = within(point.y, `${at}.y`, 0, SHEET.height);
+        const t = timeOf(point.t, `${at}.t`);
+        if (t < latest) {
+            throw new TypeError(`${at}.t: ${t}, earlier than the point before it, at ${latest}`);
+        }
+        latest = t;
+        const p = within(point.p, `${at}.p`, 0, 1);
+        return { x, y, t, p };
+    });
+    return { id, kind: fields.kind, points };
+}
+function idsOf(value, path) {
+    if (!Array.isArray(value)) {
+        throw new TypeError(`${path}: a list of stroke IDs, not ${shown(value)}`);
+    }
+    return Array.from(value, (id, n) => idOf(id, `${path}[${n}]`));
+}
+/**
+ * A stroke's ID: a whole number from 1, and below the largest safe integer, so that the ID the
+ * sheet gives the next stroke is a whole number too.
+ */
+function idOf(value, path) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value + 1) || value < 1) {
+        throw new TypeError(`${path}: a stroke's ID, a whole number from 1 below 2^53 − 1, not ${shown(value)}`);
+    }
+    return value;
+}
+function timeOf(value, path) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+        throw new TypeError(`${path}: the sheet's time in milliseconds, from 0, not ${shown(value)}`);
+    }
+    return value;
+}
+function within(value, path, least, most) {
+    if (typeof value !== "number" || !(value >= least && value <= most)) {
+        throw new TypeError(`${path}: a number from ${least} to ${most}, not ${shown(value)}`);
+    }
+    return value;
+}

package/lib/core/index.d.ts

@@ -0,0 +1,12 @@
+export type { Box } from "@altnovatrail/spec/canvas";
+export type { Filling } from "./boxes.js";
+export type { Crop, Frame } from "./crop.js";
+export type { DemoState, WorkedExample } from "./example.js";
+export type { GridKind } from "./grid.js";
+export type { Group } from "./groups.js";
+export { type HistoryEvent, replay } from "./history.js";
+export type { InkPoint, Stroke } from "./ink.js";
+export type { Manifest } from "./manifest.js";
+export type { Anchor, CellPlace, CropNumbers, Mark, Marks, SheetSubmission, Submission, WorkbookSubmission, } from "./marks.js";
+export { SHEET } from "./sheet.js";
+export type { Canvas, Task } from "./task.js";

package/lib/core/index.js

@@ -0,0 +1,15 @@
+// The DOM-free part of the canvas, the package's entry point @altnovatrail/canvas/core: plain
+// TypeScript that runs the same in a browser and in Node, for the tests and the synthetic samples
+// too (R05, R07). Importing it registers no element: the element is the other entry point. It
+// gives the sheet's size, the types of the data the element takes and gives — the strokes and the
+// history of writing, the task, the worked example and the manifest, how far the learner has gone
+// through the example's demo (R42) and the context of a submission, of a sheet or of a workbook,
+// all of spec's types (R73 spec, R74 spec), and the tutor's marks, the element's own until spec's
+// contract has them — and the fold of a history into the strokes it leaves, so that a consumer
+// reads a history it keeps without the DOM (R27). The code runs without the DOM, but spec's
+// declarations of the element's contract, which its types come from, name the DOM's types too: a
+// consumer without the DOM's types skips them with skipLibCheck (T69). The rules of the groups, the
+// crop and the snapping stay inside until the eval protocol, which takes them as they are, comes
+// out (epic E3 in spec's RUN.md; R31).
+export { replay } from "./history.js";
+export { SHEET } from "./sheet.js";

package/lib/core/ink.d.ts

@@ -0,0 +1 @@
+export type { InkPoint, Stroke } from "@altnovatrail/spec/canvas";

package/lib/core/ink.js

@@ -0,0 +1,5 @@
+// A point of a stroke and a stroke (R06, R09, R18, R27): spec's types, of the contract of canvas
+// and app (R74 spec; R07) — where a point lies on the sheet, in logical units, when it was written
+// and how hard the pointer pressed, and a stroke's ID on its sheet, its pointer's type and its
+// points. Only a pen's pressure changes the width of the line (R05, R18).
+export {};

package/lib/core/manifest.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The version of the module format the element reads: while the format is v0, the platform reads
+ * its current version alone, and a module of another is refused with the reason (R44 spec).
+ */
+export declare const FORMAT = "0.2";
+/** The open view of a module's manifest, whole: spec's type (R73 spec). */
+export type { Manifest } from "@altnovatrail/spec/formatv0/open";
+/**
+ * What the element makes of a manifest: the height of a digit its crop for checking is drawn at,
+ * and the language of the statement — the element's own `lang`, inherited, for `undefined`.
+ */
+export interface Settings {
+    readonly digit: number;
+    readonly lang: string | undefined;
+}
+/** The settings without a manifest: digits of 24 px, and the element's own language. */
+export declare const NO_MANIFEST: Settings;
+/**
+ * The settings of a manifest, or of none for `undefined`. A field the element reads that the
+ * schema refuses is a TypeError that names it; `null` is no manifest, and a wrong value.
+ */
+export declare function settingsOf(manifest: unknown): Settings;

package/lib/core/manifest.js

@@ -0,0 +1,50 @@
+// The module's manifest as the element reads it (R32): the open view of manifest.yaml, of which it
+// takes three fields — the version of the module format, the height of a digit on the crop for
+// checking and the explanation language, which the task's statement is in (R51 spec). The rest of
+// the manifest it passes over: what a manifest may hold, module-kit checks. Its canvas settings are
+// the canvas's own, though: a setting the element does not know is a TypeError, as a field of a
+// task is, for the element would draw the module's canvas without it. The type is spec's, from
+// its npm package at the version of the spec/ submodule (R73 spec; R41), and app gets the
+// manifest's open view once for a module's package and gives it to the element as it is (R36 spec).
+import { CROP } from "./crop.js";
+import { closed, record, shown, whole } from "./fields.js";
+/**
+ * The version of the module format the element reads: while the format is v0, the platform reads
+ * its current version alone, and a module of another is refused with the reason (R44 spec).
+ */
+export const FORMAT = "0.2";
+/** The settings without a manifest: digits of 24 px, and the element's own language. */
+export const NO_MANIFEST = Object.freeze({ digit: CROP.digit, lang: undefined });
+/**
+ * A language tag of the format: a language, an optional script and an optional region, each in the
+ * letter case of the registry — en, zh-Hans, pt-BR, es-419 (language_tag).
+ */
+const LANGUAGE = /^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|[0-9]{3}))?$/;
+/**
+ * The settings of a manifest, or of none for `undefined`. A field the element reads that the
+ * schema refuses is a TypeError that names it; `null` is no manifest, and a wrong value.
+ */
+export function settingsOf(manifest) {
+    if (manifest === undefined)
+        return NO_MANIFEST;
+    const fields = record(manifest, "manifest");
+    if (fields.module_format_version !== FORMAT) {
+        throw new TypeError(`manifest.module_format_version: "${FORMAT}", the version of the module format the element reads, not ${shown(fields.module_format_version)}`);
+    }
+    const languages = record(fields.languages, "manifest.languages");
+    const lang = languages.explanation;
+    if (typeof lang !== "string" || !LANGUAGE.test(lang)) {
+        throw new TypeError(`manifest.languages.explanation: a language tag, as en, zh-Hans or pt-BR, in the letter case of the registry, not ${shown(lang)}`);
+    }
+    return { digit: digitOf(fields.canvas), lang };
+}
+/** The height of a digit a manifest's canvas settings give: 24 unless given. */
+function digitOf(value) {
+    if (value === undefined)
+        return CROP.digit;
+    const canvas = closed(value, "manifest.canvas", ["digit_height"], "a module's canvas settings");
+    if (canvas.digit_height === undefined) {
+        throw new TypeError(`manifest.canvas: the settings of the module's canvas, at least one, not ${shown(value)}`);
+    }
+    return whole(canvas.digit_height, "manifest.canvas.digit_height", 1, CROP.tallest);
+}