@altnovatrail/canvas 0.0.0-stage → 0.1.0

package/lib/core/fields.js

@@ -0,0 +1,78 @@
+/**
+ * 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 function record(value, path) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new TypeError(`${path}: an object, not ${shown(value)}`);
+    }
+    return value;
+}
+/**
+ * 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 function closed(value, path, names, what) {
+    const fields = {};
+    for (const [name, field] of Object.entries(record(value, path))) {
+        if (field === undefined)
+            continue;
+        if (!names.includes(name))
+            throw new TypeError(`${path}.${name}: no field of ${what}`);
+        fields[name] = field;
+    }
+    return fields;
+}
+/**
+ * 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 function listOf(value, path, least, what, each) {
+    if (!Array.isArray(value))
+        throw new TypeError(`${path}: a list of ${what}, not ${shown(value)}`);
+    if (value.length < least) {
+        const count = ["one", "two"][least - 1] ?? String(least);
+        throw new TypeError(`${path}: a list of ${what}, ${count} at least, not ${shown(value)}`);
+    }
+    return Array.from(value, (item, i) => each(item, `${path}[${i}]`));
+}
+/** A text for people to read: a string, not empty. */
+export function text(value, path, what) {
+    if (typeof value !== "string" || value === "") {
+        throw new TypeError(`${path}: ${what}, a string not empty, not ${shown(value)}`);
+    }
+    return value;
+}
+/**
+ * A whole number from `least` to `most`, or from `least` up, short of 2^53, where a number stops
+ * being exact.
+ */
+export function whole(value, path, least, most = Number.MAX_SAFE_INTEGER) {
+    if (typeof value !== "number" || !Number.isInteger(value) || value < least || value > most) {
+        const range = most === Number.MAX_SAFE_INTEGER ? `from ${least}` : `from ${least} to ${most}`;
+        throw new TypeError(`${path}: a whole number ${range}, not ${shown(value)}`);
+    }
+    return value;
+}
+/** A value as an error message shows it. */
+export function shown(value) {
+    if (typeof value === "number")
+        return String(value);
+    if (value === undefined)
+        return "undefined";
+    if (typeof value === "function")
+        return "a function";
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+/** Whether two lists are the same, item by item, by `same`: by identity unless given. */
+export function sameItems(a, b, same = Object.is) {
+    return a.length === b.length && a.every((item, n) => n in b && same(item, b[n]));
+}

package/lib/core/geometry.d.ts

@@ -0,0 +1,38 @@
+import type { Stroke } from "./ink.js";
+import type { Point } from "./screen.js";
+/**
+ * A rectangle on the sheet, as rbush takes one (R05): in units, or in tenths of a unit where the
+ * rules count in whole numbers. The contract's Box, spec's, is one in tenths: of a crop's numbers.
+ */
+export interface Box {
+    readonly minX: number;
+    readonly minY: number;
+    readonly maxX: number;
+    readonly maxY: number;
+}
+/**
+ * A length or a place in whole tenths of a unit, as a sample file keeps them (R09), rounded half
+ * up: 100.05 units, 1000.5 tenths, are 1001. The groups and the crop count in them (R24, R25).
+ */
+export declare function tenths(value: number): number;
+/** A stroke's box in whole tenths, with its ID: what the crop and the boxes' rule count by. */
+export interface Extent extends Box {
+    readonly id: number;
+}
+/**
+ * The box of a stroke's points in whole tenths (R25, R37): rounding keeps order, so its edges are
+ * the rounded least and most of the points. A stroke with no points is a TypeError, and one with a
+ * point off the sheet, or no number, a RangeError: the rules' whole numbers hold on the sheet alone.
+ */
+export declare function extentOf({ id, points }: Stroke): Extent;
+/** The box around a stroke's points, the raw points rather than the ink's outline. */
+export declare function boxOf(points: readonly Point[]): Box;
+/** The box around boxes. */
+export declare function around(boxes: readonly Box[]): Box;
+/** The box around a segment, wider by `margin` on every side. */
+export declare function segmentBox(a: Point, b: Point, margin: number): Box;
+/**
+ * How near two segments come, ab and cd: 0 if they cross or touch. A segment whose ends are one
+ * point is that point.
+ */
+export declare function segmentDistance(a: Point, b: Point, c: Point, d: Point): number;

package/lib/core/geometry.js

@@ -0,0 +1,107 @@
+import { SHEET } from "./sheet.js";
+/**
+ * A length or a place in whole tenths of a unit, as a sample file keeps them (R09), rounded half
+ * up: 100.05 units, 1000.5 tenths, are 1001. The groups and the crop count in them (R24, R25).
+ */
+export function tenths(value) {
+    return Math.round(value * 10);
+}
+/**
+ * The box of a stroke's points in whole tenths (R25, R37): rounding keeps order, so its edges are
+ * the rounded least and most of the points. A stroke with no points is a TypeError, and one with a
+ * point off the sheet, or no number, a RangeError: the rules' whole numbers hold on the sheet alone.
+ */
+export function extentOf({ id, points }) {
+    if (points.length === 0)
+        throw new TypeError(`the stroke ${id} has no points`);
+    let minX = Number.POSITIVE_INFINITY;
+    let minY = Number.POSITIVE_INFINITY;
+    let maxX = Number.NEGATIVE_INFINITY;
+    let maxY = Number.NEGATIVE_INFINITY;
+    for (const { x, y } of points) {
+        if (!onSheet(x, SHEET.width) || !onSheet(y, SHEET.height)) {
+            throw new RangeError(`the stroke ${id} has a point (${x}, ${y}) off the sheet`);
+        }
+        minX = Math.min(minX, tenths(x));
+        minY = Math.min(minY, tenths(y));
+        maxX = Math.max(maxX, tenths(x));
+        maxY = Math.max(maxY, tenths(y));
+    }
+    return { id, minX, minY, maxX, maxY };
+}
+function onSheet(value, size) {
+    return Number.isFinite(value) && value >= 0 && value <= size;
+}
+/** The box around a stroke's points, the raw points rather than the ink's outline. */
+export function boxOf(points) {
+    let minX = Number.POSITIVE_INFINITY;
+    let minY = Number.POSITIVE_INFINITY;
+    let maxX = Number.NEGATIVE_INFINITY;
+    let maxY = Number.NEGATIVE_INFINITY;
+    for (const { x, y } of points) {
+        minX = Math.min(minX, x);
+        minY = Math.min(minY, y);
+        maxX = Math.max(maxX, x);
+        maxY = Math.max(maxY, y);
+    }
+    return { minX, minY, maxX, maxY };
+}
+/** The box around boxes. */
+export function around(boxes) {
+    let minX = Number.POSITIVE_INFINITY;
+    let minY = Number.POSITIVE_INFINITY;
+    let maxX = Number.NEGATIVE_INFINITY;
+    let maxY = Number.NEGATIVE_INFINITY;
+    for (const box of boxes) {
+        minX = Math.min(minX, box.minX);
+        minY = Math.min(minY, box.minY);
+        maxX = Math.max(maxX, box.maxX);
+        maxY = Math.max(maxY, box.maxY);
+    }
+    return { minX, minY, maxX, maxY };
+}
+/** The box around a segment, wider by `margin` on every side. */
+export function segmentBox(a, b, margin) {
+    return {
+        minX: Math.min(a.x, b.x) - margin,
+        minY: Math.min(a.y, b.y) - margin,
+        maxX: Math.max(a.x, b.x) + margin,
+        maxY: Math.max(a.y, b.y) + margin,
+    };
+}
+/**
+ * How near two segments come, ab and cd: 0 if they cross or touch. A segment whose ends are one
+ * point is that point.
+ */
+export function segmentDistance(a, b, c, d) {
+    if (crosses(a, b, c, d))
+        return 0;
+    return Math.min(pointDistance(a, c, d), pointDistance(b, c, d), pointDistance(c, a, b), pointDistance(d, a, b));
+}
+/** How near a point comes to the segment ab. */
+function pointDistance(p, a, b) {
+    const dx = b.x - a.x;
+    const dy = b.y - a.y;
+    const length = dx * dx + dy * dy;
+    // The point of the segment nearest p, as a fraction of the way from a to b.
+    const along = length === 0 ? 0 : clamp(((p.x - a.x) * dx + (p.y - a.y) * dy) / length, 0, 1);
+    return Math.hypot(p.x - (a.x + along * dx), p.y - (a.y + along * dy));
+}
+/**
+ * Whether ab and cd cross: each segment's ends lie on either side of the other's line. Segments that
+ * only touch, or lie along one line, are left to the distances of their ends, which are 0 then.
+ */
+function crosses(a, b, c, d) {
+    const abc = turn(a, b, c);
+    const abd = turn(a, b, d);
+    const cda = turn(c, d, a);
+    const cdb = turn(c, d, b);
+    return abc * abd < 0 && cda * cdb < 0;
+}
+/** Which way a, b, c turn: above 0 one way, below the other, 0 on one line. */
+function turn(a, b, c) {
+    return (b.x - a.x) * (c.y - a.y) - (b.y - a.y) * (c.x - a.x);
+}
+function clamp(value, low, high) {
+    return Math.min(Math.max(value, low), high);
+}

package/lib/core/grid.d.ts

@@ -0,0 +1,30 @@
+/**
+ * How a task rules the sheet (concepts 8 spec): in squares, in lines or in dots, as concepts 16.1
+ * spec's illustration names them.
+ */
+export type GridKind = "squares" | "lines" | "dots";
+/** The grid of a sheet: its kind and its step, in sheet units. */
+export interface Grid {
+    readonly kind: GridKind;
+    readonly step: number;
+}
+export declare const GRID_KINDS: readonly GridKind[];
+/** The step of a grid whose task gives none, in units: canvas-api's square (R06). */
+export declare const GRID_STEP = 50;
+/**
+ * The steps a task may give, in units. A finer grid would be thousands of dots, and one wider than
+ * half the sheet rules nothing much.
+ */
+export declare const GRID_STEP_MIN = 20;
+export declare const GRID_STEP_MAX = 500;
+/**
+ * The grid of a sheet whose task gives none, or that has no task: squares of 50 units. concepts 8
+ * spec knows no sheet without a grid (R23).
+ */
+export declare const DEFAULT_GRID: Grid;
+/**
+ * A grid's path in SVG, in sheet units: a line along every ruling, strictly inside the sheet, or,
+ * for dots, a dot where two rulings cross — a subpath of no length, which a round cap draws as a
+ * dot.
+ */
+export declare function gridPath(grid: Grid): string;

package/lib/core/grid.js

@@ -0,0 +1,47 @@
+import { SHEET } from "./sheet.js";
+export const GRID_KINDS = ["squares", "lines", "dots"];
+/** The step of a grid whose task gives none, in units: canvas-api's square (R06). */
+export const GRID_STEP = 50;
+/**
+ * The steps a task may give, in units. A finer grid would be thousands of dots, and one wider than
+ * half the sheet rules nothing much.
+ */
+export const GRID_STEP_MIN = 20;
+export const GRID_STEP_MAX = 500;
+/**
+ * The grid of a sheet whose task gives none, or that has no task: squares of 50 units. concepts 8
+ * spec knows no sheet without a grid (R23).
+ */
+export const DEFAULT_GRID = Object.freeze({ kind: "squares", step: GRID_STEP });
+/**
+ * A grid's path in SVG, in sheet units: a line along every ruling, strictly inside the sheet, or,
+ * for dots, a dot where two rulings cross — a subpath of no length, which a round cap draws as a
+ * dot.
+ */
+export function gridPath(grid) {
+    const xs = rulings(grid.step, SHEET.width);
+    const ys = rulings(grid.step, SHEET.height);
+    const down = xs.map((x) => `M${x} 0V${SHEET.height}`);
+    const across = ys.map((y) => `M0 ${y}H${SHEET.width}`);
+    switch (grid.kind) {
+        case "squares":
+            return [...down, ...across].join("");
+        case "lines":
+            return across.join("");
+        case "dots":
+            return ys.flatMap((y) => xs.map((x) => `M${x} ${y}h0`)).join("");
+    }
+}
+/**
+ * Where the rulings of a step lie along a side of the sheet, inside it: each one i × step, worked
+ * out apart rather than summed, so that no error builds up, and rounded to a thousandth of a unit.
+ */
+function rulings(step, length) {
+    const places = [];
+    for (let i = 1;; i++) {
+        const place = Math.round(i * step * 1000) / 1000;
+        if (place >= length)
+            return places;
+        places.push(place);
+    }
+}

package/lib/core/groups.d.ts

@@ -0,0 +1,55 @@
+import type { Group } from "@altnovatrail/spec/canvas";
+import { type Box } from "./geometry.js";
+import type { Stroke } from "./ink.js";
+/**
+ * The rule of the groups of strokes (R24): two strokes are neighbours if no more than `pause`
+ * milliseconds lie between them and their boxes come within `across` sheet units of each other
+ * across the sheet and within `down` units down it. A group is the strokes a chain of neighbours
+ * joins. The rule counts in whole numbers — tenths of a unit and milliseconds, the precision of a
+ * sample file (R09), rounded half up as `Math.round` rounds: 1000.5 tenths are 1001 — and only
+ * subtracts and compares them, so that tutor's runner, which groups by the same rule, gets the same
+ * groups to the bit.
+ */
+export interface GroupRule {
+    /** The longest pause between two neighbours, in milliseconds. */
+    readonly pause: number;
+    /** How far apart across the sheet the boxes of two neighbours may be, in sheet units. */
+    readonly across: number;
+    /** How far apart down the sheet, in sheet units. */
+    readonly down: number;
+}
+/**
+ * The rule the sheet groups by (R24): 2 seconds, the threshold by which studies of writing tell a
+ * pause of writing from one of thinking, and a cell of the default grid, across and down.
+ */
+export declare const GROUP_RULE: GroupRule;
+/**
+ * A group of the strokes on a sheet: its label, by place, and the IDs of its strokes, in ascending
+ * order. The labels and the IDs are the table «label → stroke IDs» of one submission (R06). spec's
+ * type (R74 spec).
+ */
+export type { Group };
+/**
+ * The groups of the strokes on a sheet (R24): the strokes it shows, with the times of their points
+ * as they were written, in any order. Erased strokes are none of it: whoever groups a history
+ * replays it first, and the groups come from what the sheet shows. Labelled by place, from the top
+ * down (R09): A, B, … Z, then AA, AB, … — by the top of a group's rectangle, then its left edge.
+ */
+export declare function groupsOf(strokes: readonly Stroke[], rule?: GroupRule): Group[];
+/**
+ * The pairs of neighbours among the strokes on a sheet, by ID (R24): each pair once, the smaller
+ * ID first, in ascending order. Its groups join these pairs; the test vectors give them too, for a
+ * runner to see where its grouping parts from the sheet's.
+ */
+export declare function neighboursOf(strokes: readonly Stroke[], rule?: GroupRule): [number, number][];
+/**
+ * The rectangle of a group on the sheet: the box around the points of its strokes, in sheet units,
+ * of the geometry it is given — the raw strokes on the device, the recorded ones in a sample (R09).
+ * Its box in the fractions of a cut-out is the cut-out's (T13).
+ */
+export declare function rectOf(ids: readonly number[], strokes: readonly Stroke[]): Box;
+/**
+ * The label of the group in the place `n`, from 0: A to Z, then AA to AZ, BA to ZZ, AAA… — letters
+ * in base 26 without a zero, as the columns of a spreadsheet.
+ */
+export declare function labelOf(n: number): string;

package/lib/core/groups.js

@@ -0,0 +1,172 @@
+import RBush from "rbush";
+import { boxOf, tenths } from "./geometry.js";
+import { Sets } from "./sets.js";
+/**
+ * The rule the sheet groups by (R24): 2 seconds, the threshold by which studies of writing tell a
+ * pause of writing from one of thinking, and a cell of the default grid, across and down.
+ */
+export const GROUP_RULE = Object.freeze({ pause: 2000, across: 50, down: 50 });
+/**
+ * The groups of the strokes on a sheet (R24): the strokes it shows, with the times of their points
+ * as they were written, in any order. Erased strokes are none of it: whoever groups a history
+ * replays it first, and the groups come from what the sheet shows. Labelled by place, from the top
+ * down (R09): A, B, … Z, then AA, AB, … — by the top of a group's rectangle, then its left edge.
+ */
+export function groupsOf(strokes, rule = GROUP_RULE) {
+    const pieces = piecesOf(strokes);
+    const sets = new Sets(pieces.length);
+    for (const [a, b] of pairsOf(pieces, rule))
+        sets.join(a.at, b.at);
+    const members = new Map();
+    for (const piece of pieces) {
+        const root = sets.root(piece.at);
+        const group = members.get(root);
+        if (group === undefined)
+            members.set(root, [piece]);
+        else
+            group.push(piece);
+    }
+    return [...members.values()]
+        .map((group) => ({ place: placeOf(group), ids: group.map(({ id }) => id).sort(byNumber) }))
+        .sort((a, b) => byPlace(a.place, b.place) || (a.ids[0] ?? 0) - (b.ids[0] ?? 0))
+        .map(({ ids }, n) => ({ label: labelOf(n), ids }));
+}
+/**
+ * The pairs of neighbours among the strokes on a sheet, by ID (R24): each pair once, the smaller
+ * ID first, in ascending order. Its groups join these pairs; the test vectors give them too, for a
+ * runner to see where its grouping parts from the sheet's.
+ */
+export function neighboursOf(strokes, rule = GROUP_RULE) {
+    return pairsOf(piecesOf(strokes), rule)
+        .map(([a, b]) => (a.id < b.id ? [a.id, b.id] : [b.id, a.id]))
+        .sort(([a1, a2], [b1, b2]) => a1 - b1 || a2 - b2);
+}
+/**
+ * The rectangle of a group on the sheet: the box around the points of its strokes, in sheet units,
+ * of the geometry it is given — the raw strokes on the device, the recorded ones in a sample (R09).
+ * Its box in the fractions of a cut-out is the cut-out's (T13).
+ */
+export function rectOf(ids, strokes) {
+    const wanted = new Set(ids);
+    const points = strokes.filter(({ id }) => wanted.has(id)).flatMap(({ points }) => points);
+    if (points.length === 0)
+        throw new RangeError("no stroke of the group is on the sheet");
+    return boxOf(points);
+}
+/**
+ * The label of the group in the place `n`, from 0: A to Z, then AA to AZ, BA to ZZ, AAA… — letters
+ * in base 26 without a zero, as the columns of a spreadsheet.
+ */
+export function labelOf(n) {
+    let label = "";
+    for (let rest = n + 1; rest > 0; rest = Math.floor((rest - 1) / 26)) {
+        label = String.fromCharCode(65 + ((rest - 1) % 26)) + label;
+    }
+    return label;
+}
+/**
+ * The strokes as the rule sees them, each from one pass over its points. Rounding keeps the order
+ * of numbers, so the rounded least and greatest are the least and greatest rounded. A stroke
+ * without points, or an ID twice, is no sheet's.
+ */
+function piecesOf(strokes) {
+    const seen = new Set();
+    return strokes.map((stroke, at) => {
+        if (seen.has(stroke.id))
+            throw new TypeError(`the stroke ${stroke.id} is on the sheet twice`);
+        seen.add(stroke.id);
+        const [first] = stroke.points;
+        if (first === undefined)
+            throw new TypeError(`the stroke ${stroke.id} has no points`);
+        let { x: minX, y: minY, t: start } = first;
+        let { x: maxX, y: maxY, t: end } = first;
+        for (const { x, y, t } of stroke.points) {
+            minX = Math.min(minX, x);
+            minY = Math.min(minY, y);
+            maxX = Math.max(maxX, x);
+            maxY = Math.max(maxY, y);
+            start = Math.min(start, t);
+            end = Math.max(end, t);
+        }
+        return {
+            id: stroke.id,
+            at,
+            minX: tenths(minX),
+            minY: tenths(minY),
+            maxX: tenths(maxX),
+            maxY: tenths(maxY),
+            start: Math.round(start),
+            end: Math.round(end),
+        };
+    });
+}
+/**
+ * Every pair of neighbours, each once. The index finds the pieces whose boxes come near enough —
+ * in whole tenths that is the rule's own test — and the time decides.
+ */
+function pairsOf(pieces, rule) {
+    const { pause, across, down } = limitsOf(rule);
+    const index = new RBush().load(pieces);
+    const pairs = [];
+    for (const piece of pieces) {
+        const near = index.search({
+            minX: piece.minX - across,
+            minY: piece.minY - down,
+            maxX: piece.maxX + across,
+            maxY: piece.maxY + down,
+        });
+        for (const other of near) {
+            if (other.at <= piece.at)
+                continue;
+            if (gap(piece.minX, piece.maxX, other.minX, other.maxX) <= across &&
+                gap(piece.minY, piece.maxY, other.minY, other.maxY) <= down &&
+                gap(piece.start, piece.end, other.start, other.end) <= pause) {
+                pairs.push([piece, other]);
+            }
+        }
+    }
+    return pairs;
+}
+/**
+ * A rule's limits in the whole numbers the rule counts in. A limit that is not a finite number of
+ * 0 or more is no rule's: it would group nothing, or every pair, without a word.
+ */
+function limitsOf(rule) {
+    for (const name of ["pause", "across", "down"]) {
+        const value = rule[name];
+        if (!Number.isFinite(value) || value < 0) {
+            throw new RangeError(`the rule's ${name} is ${value}, not a finite number of 0 or more`);
+        }
+    }
+    return { pause: Math.round(rule.pause), across: tenths(rule.across), down: tenths(rule.down) };
+}
+/** How far apart two spans are: 0 if they overlap or touch. */
+function gap(low, high, otherLow, otherHigh) {
+    return Math.max(0, low - otherHigh, otherLow - high);
+}
+function placeOf(group) {
+    let minX = Number.POSITIVE_INFINITY;
+    let minY = Number.POSITIVE_INFINITY;
+    let maxX = Number.NEGATIVE_INFINITY;
+    let maxY = Number.NEGATIVE_INFINITY;
+    let start = Number.POSITIVE_INFINITY;
+    for (const piece of group) {
+        minX = Math.min(minX, piece.minX);
+        minY = Math.min(minY, piece.minY);
+        maxX = Math.max(maxX, piece.maxX);
+        maxY = Math.max(maxY, piece.maxY);
+        start = Math.min(start, piece.start);
+    }
+    return { minX, minY, maxX, maxY, start };
+}
+/**
+ * From the top down, then from the left; rectangles alike in both go by their bottom, their right
+ * and then by which was begun first. The IDs, which say the order of writing, settle nothing short
+ * of two groups alike in all of that.
+ */
+function byPlace(a, b) {
+    return (a.minY - b.minY || a.minX - b.minX || a.maxY - b.maxY || a.maxX - b.maxX || a.start - b.start);
+}
+function byNumber(a, b) {
+    return a - b;
+}

package/lib/core/hands.d.ts

@@ -0,0 +1,120 @@
+/**
+ * A pointer as the hands on the sheet see it (R29): where it is on the screen, how big its contact
+ * is, and when. The DOM-free part sees no DOM (R12), so the element hands it this much of each
+ * pointer event. The contact's size decides only what the pointer may do: it goes into no stroke,
+ * no history and no sample (R09).
+ */
+export interface Contact {
+    /** The event's `pointerId`. */
+    readonly pointerId: number;
+    /** The event's `pointerType`, as it came: "pen", "touch", "mouse" or another. */
+    readonly kind: string;
+    /** Where on the screen, in CSS pixels: the event's `clientX` and `clientY`. */
+    readonly x: number;
+    readonly y: number;
+    /**
+     * The contact's size on the screen, in CSS pixels: the event's `width` and `height`, 1 where the
+     * hardware does not measure it (Pointer Events Level 3).
+     */
+    readonly width: number;
+    readonly height: number;
+    /** When: the event's `timeStamp`, in milliseconds. */
+    readonly time: number;
+}
+/**
+ * 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 declare 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 declare 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 declare 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 declare class PenMode {
+    #private;
+    get on(): boolean;
+    /** Every watcher hears of a change. */
+    set on(on: boolean);
+    /** Whether a pointer writes or erases now on a sheet of the page. */
+    get writing(): boolean;
+    /**
+     * `watcher` hears of every change from now on, and of every stroke that ends, until the function
+     * this gives is called.
+     */
+    watch(watcher: () => void): () => void;
+    /** A sheet tells whether it is written on, until the function this gives is called. */
+    enlist(writes: () => boolean): () => void;
+    /** A pointer lifted off a sheet: once no sheet is written on, every watcher hears of it. */
+    settle(): void;
+}
+/** What the hands ask of the sheet they serve. */
+export interface HandsSheet {
+    /** The pointer that writes or erases now, if one does: the recorder's or the eraser's. */
+    writer(): number | undefined;
+    /** The stroke or the erasing of a pointer goes, as on `pointercancel`. */
+    drop(pointerId: number): void;
+    /**
+     * Two fingers moved down the screen by `dy` CSS pixels, or up for a negative one: the sheet goes
+     * with them. `fresh` marks a gesture's first step.
+     */
+    scroll(dy: number, fresh: boolean): void;
+}
+/**
+ * What a pointer down on the sheet does:
+ * - "writes": it may write or erase, and does while the sheet says it is the writer;
+ * - "waits": a finger in pen mode, waiting for a second to scroll with;
+ * - "scrolls": one of the two fingers of a gesture;
+ * - "palm": too big for a finger, it does nothing until it lifts;
+ * - "idle": it does nothing until it lifts.
+ */
+export type Role = "writes" | "waits" | "scrolls" | "palm" | "idle";
+/**
+ * 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 declare class Hands {
+    #private;
+    constructor(sheet: HandsSheet, mode: PenMode);
+    /** What each pointer down on the sheet does now. */
+    get roles(): ReadonlyMap<number, Role>;
+    /** Whether a pointer is down on the sheet: the hands saw it come down, and not yet lift. */
+    knows(pointerId: number): boolean;
+    /** Whether two fingers make a gesture now: they wait for their slop, or scroll. */
+    get scrolling(): boolean;
+    /** `pointerdown`: whether this pointer may write or erase. */
+    down(contact: Contact): boolean;
+    /** `pointermove`, once for each coalesced event: whether this pointer writes on. */
+    move(contact: Contact): boolean;
+    /** `pointerup`, `pointercancel` or a lost capture: the pointer has gone, and its gesture too. */
+    lift(pointerId: number): void;
+    /** The sheet has left the page, and no pointer is down on it now. */
+    reset(): void;
+}