@altnovatrail/canvas 0.0.0-stage → 0.1.1

package/lib/core/raster.js

@@ -0,0 +1,72 @@
+import { tenths } from "./geometry.js";
+import { encodePNG } from "./png.js";
+/**
+ * The pixels of a crop (R25): grey, a byte each, row by row from the top, white 255 and the ink 0,
+ * of the strokes the crop was made of. Every segment of a stroke is a line as wide all along, with
+ * round ends, and a stroke of one point a dot as wide as the line: a pixel takes the share of it
+ * that the line covers, along a ramp a pixel wide at the line's edge, and the darkest of what
+ * covers it. The places are the crop's own whole numbers, from the points in tenths of a unit, as
+ * a sample keeps them (R09). Only adding, subtracting, multiplying, dividing and Math.sqrt go into
+ * a pixel, which ECMAScript rounds alike in every engine, so the bytes are the same in each.
+ */
+export function rasterOf(strokes, crop) {
+    const { width, height, drawn } = crop;
+    const [top, left] = crop.margins;
+    const { box, median: unit } = crop.exact;
+    const gray = new Uint8Array(width * height).fill(255);
+    const reach = Math.max(drawn, 12) / 24;
+    // A whole number over the median: one division, as the crop's own numbers are.
+    const spot = ({ x, y }) => ({
+        x: ((tenths(x) - box.minX) * drawn + left * unit) / unit,
+        y: ((tenths(y) - box.minY) * drawn + top * unit) / unit,
+    });
+    for (const { points } of strokes) {
+        const spots = points.map(spot);
+        const [first] = spots;
+        if (spots.length === 1 && first !== undefined)
+            paint(gray, width, height, first, first, reach);
+        for (let k = 1; k < spots.length; k++) {
+            const [a, b] = [spots[k - 1], spots[k]];
+            if (a !== undefined && b !== undefined)
+                paint(gray, width, height, a, b, reach);
+        }
+    }
+    return gray;
+}
+/** The PNG of a crop: its pixels, encoded (R25). */
+export function pictureOf(strokes, crop) {
+    return encodePNG(rasterOf(strokes, crop), crop.width, crop.height);
+}
+/**
+ * One segment's ink on the pixels near it. Its ends go in one order whichever way it was written,
+ * so a stroke drawn back to front gives the same bytes.
+ */
+function paint(gray, width, height, from, to, reach) {
+    const forward = from.x < to.x || (from.x === to.x && from.y <= to.y);
+    const a = forward ? from : to;
+    const b = forward ? to : from;
+    const dx = b.x - a.x;
+    const dy = b.y - a.y;
+    const length = dx * dx + dy * dy;
+    const firstColumn = Math.max(0, Math.floor(Math.min(a.x, b.x) - reach - 1));
+    const lastColumn = Math.min(width - 1, Math.ceil(Math.max(a.x, b.x) + reach + 1));
+    const firstRow = Math.max(0, Math.floor(Math.min(a.y, b.y) - reach - 1));
+    const lastRow = Math.min(height - 1, Math.ceil(Math.max(a.y, b.y) + reach + 1));
+    for (let row = firstRow; row <= lastRow; row++) {
+        const cy = row + 0.5;
+        for (let column = firstColumn; column <= lastColumn; column++) {
+            const cx = column + 0.5;
+            // The point of the segment nearest the pixel's centre, as a share of the way from a to b.
+            const along = length === 0 ? 0 : Math.min(1, Math.max(0, ((cx - a.x) * dx + (cy - a.y) * dy) / length));
+            const ex = cx - (a.x + along * dx);
+            const ey = cy - (a.y + along * dy);
+            const cover = reach + 0.5 - Math.sqrt(ex * ex + ey * ey);
+            if (cover <= 0)
+                continue;
+            const value = Math.round(255 * (1 - Math.min(1, cover)));
+            const at = row * width + column;
+            if (value < (gray[at] ?? 255))
+                gray[at] = value;
+        }
+    }
+}

package/lib/core/recorder.d.ts

@@ -0,0 +1,73 @@
+import { Clock } from "./clock.js";
+import type { Stroke } from "./ink.js";
+/**
+ * What the recorder takes of a pointer event, and of each event coalesced into it. The DOM-free
+ * part sees no DOM (R12), so the element hands it this much, the place already in sheet units.
+ */
+export interface PointerSample {
+    /** The event's `pointerId`. */
+    readonly pointerId: number;
+    /** The event's `pointerType`, as it came. */
+    readonly kind: string;
+    /** The event's `button`, the button whose state changed: 0 is the primary, -1 none. */
+    readonly button: number;
+    /** The event's `buttons`, the buttons held: bit 1 is the primary. */
+    readonly buttons: number;
+    /** Where, in sheet units, clamped to the sheet. */
+    readonly x: number;
+    readonly y: number;
+    /** When: the event's `timeStamp`, in milliseconds. */
+    readonly time: number;
+    /** The event's `pressure`, 0 to 1. */
+    readonly pressure: number;
+}
+/**
+ * How close two recorded points of a stroke may come, in sheet units: 0.1, the precision of a
+ * sample file (R09). A point nearer than that to the last one recorded adds nothing the file would
+ * keep (R18).
+ */
+export declare const MIN_STEP = 0.1;
+/** `button` of the primary button: a pen's tip, a finger, a mouse's left button. */
+export declare const PRIMARY = 0;
+/** The primary button's bit in `buttons`. */
+export declare const PRIMARY_HELD = 1;
+/**
+ * The strokes of one sheet, from the pointer's samples (R18; architecture 3.1 in
+ * docs/architecture.md). One pointer writes at a time, with its primary button: a second pointer,
+ * and any other button, write nothing while a stroke is under way. A finished stroke goes to the
+ * handler the recorder is made with — onto the work on the sheet (R19). Its points take their time
+ * from the sheet's clock, which the sheet's other actions keep too (R22).
+ */
+export declare class Recorder {
+    #private;
+    constructor(finished: (stroke: Stroke) => void, clock?: Clock);
+    /** The stroke being written, or nothing between strokes. */
+    get live(): Stroke | undefined;
+    /** The `pointerId` of the pointer writing, or nothing between strokes. */
+    get pointer(): number | undefined;
+    /** `pointerdown`: a stroke begins here, if none is under way and the primary button went down. */
+    down(sample: PointerSample): boolean;
+    /**
+     * `pointermove`, once for each coalesced event: the stroke goes on here. A move without the
+     * primary button held ends the stroke where it was, its `pointerup` lost.
+     */
+    move(sample: PointerSample): boolean;
+    /**
+     * `pointerup`: the stroke ends where and when the pointer left, however near the last point,
+     * so that the stroke keeps a pause before it. Its pressure is the last move's: `pointerup`'s
+     * is 0 by definition, the buttons no longer pressed, rather than measured.
+     */
+    up(sample: PointerSample): boolean;
+    /** `pointercancel`: the device took the touch for an accident, and the stroke goes (R05). */
+    cancel(pointerId: number): boolean;
+    /**
+     * The stroke 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 stroke, unless one is named.
+     */
+    end(pointerId?: number): boolean;
+    /**
+     * The sheet has taken another history of writing (R27): the stroke under way goes, as on
+     * `pointercancel` — its ID and its times are the last sheet's — and the next stroke is `nextId`.
+     */
+    restart(nextId: number): void;
+}

package/lib/core/recorder.js

@@ -0,0 +1,127 @@
+import { Clock } from "./clock.js";
+/**
+ * How close two recorded points of a stroke may come, in sheet units: 0.1, the precision of a
+ * sample file (R09). A point nearer than that to the last one recorded adds nothing the file would
+ * keep (R18).
+ */
+export const MIN_STEP = 0.1;
+/** `button` of the primary button: a pen's tip, a finger, a mouse's left button. */
+export const PRIMARY = 0;
+/** The primary button's bit in `buttons`. */
+export const PRIMARY_HELD = 1;
+/**
+ * The strokes of one sheet, from the pointer's samples (R18; architecture 3.1 in
+ * docs/architecture.md). One pointer writes at a time, with its primary button: a second pointer,
+ * and any other button, write nothing while a stroke is under way. A finished stroke goes to the
+ * handler the recorder is made with — onto the work on the sheet (R19). Its points take their time
+ * from the sheet's clock, which the sheet's other actions keep too (R22).
+ */
+export class Recorder {
+    #finished;
+    #clock;
+    #live;
+    #nextId = 1;
+    constructor(finished, clock = new Clock()) {
+        this.#finished = finished;
+        this.#clock = clock;
+    }
+    /** The stroke being written, or nothing between strokes. */
+    get live() {
+        return this.#live;
+    }
+    /** The `pointerId` of the pointer writing, or nothing between strokes. */
+    get pointer() {
+        return this.#live?.pointerId;
+    }
+    /** `pointerdown`: a stroke begins here, if none is under way and the primary button went down. */
+    down(sample) {
+        if (this.#live !== undefined || sample.button !== PRIMARY)
+            return false;
+        const point = this.#point(sample, sample.pressure);
+        this.#live = {
+            id: this.#nextId++,
+            kind: sample.kind,
+            points: [point],
+            pointerId: sample.pointerId,
+            latest: point,
+        };
+        return true;
+    }
+    /**
+     * `pointermove`, once for each coalesced event: the stroke goes on here. A move without the
+     * primary button held ends the stroke where it was, its `pointerup` lost.
+     */
+    move(sample) {
+        const live = this.#live;
+        if (live === undefined || sample.pointerId !== live.pointerId)
+            return false;
+        if ((sample.buttons & PRIMARY_HELD) === 0)
+            return this.#finish();
+        const point = this.#point(sample, sample.pressure);
+        live.latest = point;
+        const last = live.points[live.points.length - 1];
+        if (last !== undefined && Math.hypot(point.x - last.x, point.y - last.y) < MIN_STEP) {
+            return false;
+        }
+        live.points.push(point);
+        return true;
+    }
+    /**
+     * `pointerup`: the stroke ends where and when the pointer left, however near the last point,
+     * so that the stroke keeps a pause before it. Its pressure is the last move's: `pointerup`'s
+     * is 0 by definition, the buttons no longer pressed, rather than measured.
+     */
+    up(sample) {
+        const live = this.#live;
+        if (live === undefined || sample.pointerId !== live.pointerId)
+            return false;
+        live.latest = this.#point(sample, live.latest.p);
+        return this.#finish();
+    }
+    /** `pointercancel`: the device took the touch for an accident, and the stroke goes (R05). */
+    cancel(pointerId) {
+        if (this.#live?.pointerId !== pointerId)
+            return false;
+        this.#live = undefined;
+        return true;
+    }
+    /**
+     * The stroke 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 stroke, unless one is named.
+     */
+    end(pointerId) {
+        if (this.#live === undefined)
+            return false;
+        if (pointerId !== undefined && this.#live.pointerId !== pointerId)
+            return false;
+        return this.#finish();
+    }
+    /**
+     * The sheet has taken another history of writing (R27): the stroke under way goes, as on
+     * `pointercancel` — its ID and its times are the last sheet's — and the next stroke is `nextId`.
+     */
+    restart(nextId) {
+        this.#live = undefined;
+        this.#nextId = nextId;
+    }
+    #finish() {
+        const live = this.#live;
+        if (live === undefined)
+            return false;
+        if (live.latest !== live.points[live.points.length - 1])
+            live.points.push(live.latest);
+        // The stroke is no longer under way by the time the handler has it.
+        this.#live = undefined;
+        this.#finished({ id: live.id, kind: live.kind, points: live.points });
+        return true;
+    }
+    /**
+     * A point of the sample, its time the sheet's and never going back. Its pressure is kept to 0–1,
+     * the range Pointer Events gives it: an event a script makes may say more, and the sheet would
+     * write a history it does not take back (R27).
+     */
+    #point(sample, pressure) {
+        const p = Math.min(Math.max(pressure, 0), 1);
+        return { x: sample.x, y: sample.y, t: this.#clock.at(sample.time), p };
+    }
+}

package/lib/core/screen.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Where the sheet is on the screen, one view for every layer (R06; architecture 3.2 in
+ * docs/architecture.md): `k` CSS pixels to a logical unit, for the sheet fits the width of its
+ * area, and `vy`, the top of the sheet's visible part, in units.
+ */
+export interface View {
+    readonly k: number;
+    readonly vy: number;
+}
+/** A point, on the sheet in logical units or on the screen in CSS pixels. */
+export interface Point {
+    readonly x: number;
+    readonly y: number;
+}
+/**
+ * The most CSS pixels to a unit: on a wide screen the sheet is at most 1000 CSS pixels wide, a
+ * pixel to a unit as on the picture of the work, and stands in the middle (R23).
+ */
+export declare const K_MAX = 1;
+/** `k` of a sheet `width` CSS pixels wide as it is on the screen: k = A / W. */
+export declare function scaleFor(width: number): number;
+/**
+ * `k` for a sheet laid out in an area `width` CSS pixels wide: it fits the width, up to `K_MAX`.
+ * This is the layout's `k`, before any transform the page puts on the element; input takes `k`
+ * from the sheet's rectangle on the screen, by `scaleFor`.
+ */
+export declare function fitScale(width: number): number;
+/**
+ * The point of the sheet under a point of the screen, given in CSS pixels from the top left corner
+ * of the sheet's visible part. A point beyond the sheet is clamped to its edge, as in spec 4.2 of
+ * canvas-api: a pointer captured by the sheet goes on writing on its edge.
+ */
+export declare function toSheet(view: View, x: number, y: number): Point;
+/** The point of the screen over a point of the sheet, from the top left corner of its visible part. */
+export declare function toScreen(view: View, x: number, y: number): Point;

package/lib/core/screen.js

@@ -0,0 +1,36 @@
+import { SHEET } from "./sheet.js";
+/**
+ * The most CSS pixels to a unit: on a wide screen the sheet is at most 1000 CSS pixels wide, a
+ * pixel to a unit as on the picture of the work, and stands in the middle (R23).
+ */
+export const K_MAX = 1;
+/** `k` of a sheet `width` CSS pixels wide as it is on the screen: k = A / W. */
+export function scaleFor(width) {
+    return width / SHEET.width;
+}
+/**
+ * `k` for a sheet laid out in an area `width` CSS pixels wide: it fits the width, up to `K_MAX`.
+ * This is the layout's `k`, before any transform the page puts on the element; input takes `k`
+ * from the sheet's rectangle on the screen, by `scaleFor`.
+ */
+export function fitScale(width) {
+    return Math.min(width / SHEET.width, K_MAX);
+}
+/**
+ * The point of the sheet under a point of the screen, given in CSS pixels from the top left corner
+ * of the sheet's visible part. A point beyond the sheet is clamped to its edge, as in spec 4.2 of
+ * canvas-api: a pointer captured by the sheet goes on writing on its edge.
+ */
+export function toSheet(view, x, y) {
+    return {
+        x: clamp(x / view.k, 0, SHEET.width),
+        y: clamp(y / view.k + view.vy, 0, SHEET.height),
+    };
+}
+/** The point of the screen over a point of the sheet, from the top left corner of its visible part. */
+export function toScreen(view, x, y) {
+    return { x: x * view.k, y: (y - view.vy) * view.k };
+}
+function clamp(value, low, high) {
+    return Math.min(Math.max(value, low), high);
+}

package/lib/core/sets.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The sets that strokes join into, pair by pair: union-find, each set known by its root, which is
+ * its smallest member. The groups grow in them (R24), and the crop's bundles (R25).
+ */
+export declare class Sets {
+    #private;
+    constructor(size: number);
+    root(at: number): number;
+    join(a: number, b: number): void;
+}

package/lib/core/sets.js

@@ -0,0 +1,31 @@
+/**
+ * The sets that strokes join into, pair by pair: union-find, each set known by its root, which is
+ * its smallest member. The groups grow in them (R24), and the crop's bundles (R25).
+ */
+export class Sets {
+    #parent;
+    constructor(size) {
+        this.#parent = Array.from({ length: size }, (_, at) => at);
+    }
+    root(at) {
+        let root = at;
+        while (this.#parent[root] !== root)
+            root = this.#parent[root] ?? root;
+        // Each piece on the way points at the root itself from now on.
+        for (let next = at; this.#parent[next] !== root;) {
+            const parent = this.#parent[next] ?? root;
+            this.#parent[next] = root;
+            next = parent;
+        }
+        return root;
+    }
+    join(a, b) {
+        const rootA = this.root(a);
+        const rootB = this.root(b);
+        // The smaller root stays: which pair comes first changes no root.
+        if (rootA < rootB)
+            this.#parent[rootB] = rootA;
+        else if (rootB < rootA)
+            this.#parent[rootA] = rootB;
+    }
+}

package/lib/core/sheet.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The handwriting sheet in logical units: 1000 wide and 1400 tall, the origin at its top left
+ * corner and y pointing down, one scale on both axes (R06). Every layer of the sheet counts in
+ * these units, whatever the device's screen.
+ */
+export declare const SHEET: Readonly<{
+    readonly width: 1000;
+    readonly height: 1400;
+}>;

package/lib/core/sheet.js

@@ -0,0 +1,6 @@
+/**
+ * The handwriting sheet in logical units: 1000 wide and 1400 tall, the origin at its top left
+ * corner and y pointing down, one scale on both axes (R06). Every layer of the sheet counts in
+ * these units, whatever the device's screen.
+ */
+export const SHEET = Object.freeze({ width: 1000, height: 1400 });

package/lib/core/submission.d.ts

@@ -0,0 +1,41 @@
+import { type Cell } from "./boxes.js";
+import type { Stroke } from "./ink.js";
+import { type SheetSubmission, type WorkbookSubmission } from "./marks.js";
+/** The work of a sheet for checking (R27): the PNG of its crop, and the context of the submission. */
+export interface WorkForCheck {
+    readonly png: Uint8Array<ArrayBuffer>;
+    readonly submission: SheetSubmission;
+}
+/** The crop of one filled box of a workbook (R38): its item and its slot, from 1, and its PNG. */
+export interface CellForCheck {
+    readonly item: number;
+    readonly slot: number;
+    readonly png: Uint8Array<ArrayBuffer>;
+}
+/**
+ * The work of a workbook for checking (R34, R38): the crop of each filled box, in the task's order,
+ * and the context of the submission.
+ */
+export interface CellsForCheck {
+    readonly cells: readonly CellForCheck[];
+    readonly submission: WorkbookSubmission;
+}
+/**
+ * The work of a sheet for checking, as `exportWork()` gives it (R07, R27): of the strokes the sheet
+ * shows, their groups by the sheet's rule (R24), their crop with its digits `digit` px high and its
+ * PNG (R25), and the context of the submission — the crop's numbers that place the tutor's marks,
+ * the groups, the table «label → stroke IDs», and their digest (R26, R27) — frozen through. A sheet
+ * without strokes has no work to check, and gives null (H3).
+ */
+export declare function workForCheck(strokes: readonly Stroke[], digit: number): WorkForCheck | null;
+/**
+ * The work of a workbook for checking, as `exportWork()` gives it (R34, R38): of the strokes the
+ * page shows, the table of the boxes they fill by the rule of boxes (R37), and the crop of each
+ * filled box by R25 — the box's strokes alone, one group of them, its digits `digit` px high —
+ * with its item and its slot, in the task's order, and the context of the submission: the table and
+ * its digest. The draft goes nowhere. A page with no box filled has no work to check, and gives
+ * null, though it holds draft. The crops are frozen, not their bytes, which no freezing holds; the
+ * context is frozen through. One crop of every box's strokes, which spec may choose (В45 in
+ * RUN.md), is `croppedOf` of the table's strokes with the table's rows for groups.
+ */
+export declare function cellsForCheck(strokes: readonly Stroke[], cells: readonly Cell[], digit: number): CellsForCheck | null;

package/lib/core/submission.js

@@ -0,0 +1,63 @@
+import { tableOf } from "./boxes.js";
+import { cropOf } from "./crop.js";
+import { groupsOf } from "./groups.js";
+import { digestOf, workbookDigestOf, } from "./marks.js";
+import { pictureOf } from "./raster.js";
+/**
+ * The work of a sheet for checking, as `exportWork()` gives it (R07, R27): of the strokes the sheet
+ * shows, their groups by the sheet's rule (R24), their crop with its digits `digit` px high and its
+ * PNG (R25), and the context of the submission — the crop's numbers that place the tutor's marks,
+ * the groups, the table «label → stroke IDs», and their digest (R26, R27) — frozen through. A sheet
+ * without strokes has no work to check, and gives null (H3).
+ */
+export function workForCheck(strokes, digit) {
+    const groups = groupsOf(strokes);
+    const cropped = croppedOf(strokes, groups, digit);
+    if (cropped === null)
+        return null;
+    const { drawn, width, height, margins, sheetBox, frames, exact } = cropped.crop;
+    const numbers = { drawn, width, height, margins, sheetBox, frames, exact };
+    const submission = { crop: numbers, groups, digest: digestOf(strokes, numbers, groups) };
+    return Object.freeze({ png: cropped.png, submission: frozen(submission) });
+}
+/**
+ * The work of a workbook for checking, as `exportWork()` gives it (R34, R38): of the strokes the
+ * page shows, the table of the boxes they fill by the rule of boxes (R37), and the crop of each
+ * filled box by R25 — the box's strokes alone, one group of them, its digits `digit` px high —
+ * with its item and its slot, in the task's order, and the context of the submission: the table and
+ * its digest. The draft goes nowhere. A page with no box filled has no work to check, and gives
+ * null, though it holds draft. The crops are frozen, not their bytes, which no freezing holds; the
+ * context is frozen through. One crop of every box's strokes, which spec may choose (В45 in
+ * RUN.md), is `croppedOf` of the table's strokes with the table's rows for groups.
+ */
+export function cellsForCheck(strokes, cells, digit) {
+    const boxes = tableOf(strokes, cells);
+    if (boxes.length === 0)
+        return null;
+    const byId = new Map(strokes.map((stroke) => [stroke.id, stroke]));
+    const own = (ids) => ids.flatMap((id) => byId.get(id) ?? []);
+    const crops = boxes.map(({ item, slot, ids }) => {
+        // A row of the table holds a stroke at least, and a crop of strokes is never null.
+        const cropped = croppedOf(own(ids), [{ label: "A", ids }], digit);
+        if (cropped === null)
+            throw new Error(`the box ${item}.${slot} has strokes and no crop`);
+        return Object.freeze({ item, slot, png: cropped.png });
+    });
+    const sent = own(boxes.flatMap(({ ids }) => ids));
+    const submission = { boxes, digest: workbookDigestOf(sent, boxes, cells) };
+    return Object.freeze({ cells: Object.freeze(crops), submission: frozen(submission) });
+}
+/** The crop of strokes in their groups, its digits `digit` px high, and its PNG (R25). */
+function croppedOf(strokes, groups, digit) {
+    const crop = cropOf(strokes, groups, digit);
+    return crop === null ? null : { crop, png: pictureOf(strokes, crop) };
+}
+/** A value of plain objects and arrays, frozen through. */
+function frozen(value) {
+    if (typeof value === "object" && value !== null && !Object.isFrozen(value)) {
+        for (const each of Object.values(value))
+            frozen(each);
+        Object.freeze(value);
+    }
+    return value;
+}