@altnovatrail/canvas 0.0.0-stage → 0.1.0

package/lib/element/labels.d.ts

@@ -0,0 +1,41 @@
+/**
+ * What the element says: the row of buttons its own name — the canvas kind's, or a worked
+ * example's — the name of the group of tools and each button, a workbook's box its name, and the
+ * number of a part of a demo the element tells of.
+ */
+export interface Labels {
+    readonly sheet: string;
+    readonly workbook: string;
+    /** The row of a lesson's worked example, which has no tools of writing (R42). */
+    readonly example: string;
+    /** The buttons of a worked example's demo: the next part, and the whole demo, shown or hidden. */
+    readonly next: string;
+    readonly demo: string;
+    readonly tool: string;
+    readonly pen: string;
+    readonly eraser: string;
+    readonly undo: string;
+    readonly clear: string;
+    /** The buttons that scroll the sheet back up and on down, with a single pointer (R33). */
+    readonly up: string;
+    readonly down: string;
+    /** The button that lets a finger write again, in pen mode (R29). */
+    readonly finger: string;
+    /** A box of a workbook's line, numbered when the line has more than one (R36). */
+    readonly box: string;
+    /** What a filled box's name adds (R37). */
+    readonly filled: string;
+    /** The number of a part of a demo the element tells of, of so many: «Part 2 of 4» (R42). */
+    readonly part: string;
+    readonly of: string;
+}
+/**
+ * The labels for a language tag, and the language they are in. The tag is looked up as RFC 4647,
+ * section 3.4, does it: in lower case, cut subtag by subtag from its end until the table has what
+ * is left, a single-letter subtag going with the subtag after it. English stands for any other
+ * tag, and for none.
+ */
+export declare function labelsFor(tag: string | null): {
+    readonly lang: string;
+    readonly labels: Labels;
+};

package/lib/element/labels.js

@@ -0,0 +1,74 @@
+// The labels of the element's own buttons, of a workbook's boxes and of the parts of a worked
+// example's demo, in the languages of its interface (R28, R29, R33, R36, R37, R42): English and
+// Russian, as О-2 recommends, until app's T07 gives the shared scheme of translations of the packages
+// of the interface. The language is the element's own `lang`, looked up as RFC 4647 does it. This
+// module is no entry point of the package.
+/** The labels in English, the code's own language: those of any language the table has not. */
+const ENGLISH = Object.freeze({
+    sheet: "Sheet",
+    workbook: "Workbook",
+    example: "Worked example",
+    next: "Next",
+    demo: "Demo",
+    tool: "Tool",
+    pen: "Pen",
+    eraser: "Eraser",
+    undo: "Undo",
+    clear: "Clear",
+    up: "Up",
+    down: "Down",
+    finger: "Draw with finger",
+    box: "Box",
+    filled: "filled",
+    part: "Part",
+    of: "of",
+});
+/**
+ * The labels by language, each a language tag in lower case. A map, not an object: a tag such as
+ * "constructor" finds nothing of an object's prototype in it.
+ */
+const LABELS = new Map([
+    ["en", ENGLISH],
+    [
+        "ru",
+        Object.freeze({
+            sheet: "Лист",
+            workbook: "Тетрадь",
+            example: "Пример",
+            next: "Дальше",
+            demo: "Показ",
+            tool: "Инструмент",
+            pen: "Перо",
+            eraser: "Ластик",
+            undo: "Отменить",
+            clear: "Очистить",
+            up: "Выше",
+            down: "Ниже",
+            finger: "Рисовать пальцем",
+            box: "Окошко",
+            filled: "заполнено",
+            part: "Часть",
+            of: "из",
+        }),
+    ],
+]);
+/**
+ * The labels for a language tag, and the language they are in. The tag is looked up as RFC 4647,
+ * section 3.4, does it: in lower case, cut subtag by subtag from its end until the table has what
+ * is left, a single-letter subtag going with the subtag after it. English stands for any other
+ * tag, and for none.
+ */
+export function labelsFor(tag) {
+    let range = (tag ?? "").toLowerCase();
+    while (range !== "") {
+        const labels = LABELS.get(range);
+        if (labels !== undefined)
+            return { lang: range, labels };
+        let cut = range.lastIndexOf("-");
+        // "x" of "en-x-school", or the letter of an extension, means nothing without what follows it.
+        if (cut >= 2 && range[cut - 2] === "-")
+            cut -= 2;
+        range = cut > 0 ? range.slice(0, cut) : "";
+    }
+    return { lang: "en", labels: ENGLISH };
+}

package/lib/element/parts.d.ts

@@ -0,0 +1,63 @@
+import { type DemoState, type ExamplePart } from "../core/example.js";
+import type { Pictures } from "./pictures.js";
+/** The number of a part the region tells of, as the labels say it, and the labels' language. */
+export interface Told {
+    /** The number of the part, of so many, in the labels' language: «Часть 2 из 4.». */
+    readonly number: string;
+    /** The language of the labels the number is in. */
+    readonly lang: string;
+}
+/** The list of a demo's open parts and the region that tells of them, as the element shows them. */
+export declare class Parts {
+    #private;
+    /** The open parts, in the module's explanation language, or in the element's own without one. */
+    readonly list: HTMLOListElement;
+    /**
+     * The polite region that tells of the part just opened: empty from the start, and hidden from
+     * sight alone, for a region out of the tree of what a screen reader reads tells nothing.
+     */
+    readonly status: HTMLDivElement;
+    /**
+     * The pictures on areas of the sheet, for the layer of the author's demo: in sheet units, as the
+     * layer's view box counts, in the demo's order, so that a later part is drawn over an earlier.
+     */
+    readonly layer: SVGGElement;
+    /**
+     * Where the sheet scrolls to for a picture on an area just opened: a box of the area in the
+     * sheet's own flow, not on its sticky stage, whose pictures move only at the next frame. It is
+     * hidden, so it paints nothing and takes no pointer, but it has a box to scroll into sight.
+     */
+    readonly spot: HTMLDivElement;
+    /** The list and the region, by their IDs, whose pictures the element's pictures give files. */
+    constructor(ids: {
+        readonly status: string;
+        readonly parts: string;
+    }, pictures: Pictures);
+    /**
+     * The language the parts are in, a BCP 47 tag, or `undefined` for the element's own, which the
+     * list inherits. A new language changes the attribute alone.
+     */
+    set lang(lang: string | undefined);
+    /**
+     * The demo as a state has it: as many parts open as it says, from the first, items added or
+     * taken off at the list's end alone, and the list hidden or shown. Only what has changed is
+     * written: hidden, the parts keep their pictures.
+     */
+    show(demo: readonly ExamplePart[], { opened, hidden }: DemoState): void;
+    /** No part open, the list shown, and nothing told: a demo begins, or goes. */
+    clear(): void;
+    /**
+     * What the `n`th part, from 1, comes into sight by once it is open (R42): its item, or for a
+     * picture on an area of the sheet the spot, which it places on that area, in shares of the sheet,
+     * which keeps its proportions.
+     */
+    target(n: number): HTMLElement | undefined;
+    /**
+     * The region tells of a part just opened: its number, in the labels' language, and its words —
+     * a paragraph's text, a picture's description — in the parts' own. A picture that only decorates
+     * has its number alone.
+     */
+    tell(part: ExamplePart, told: Told): void;
+    /** The region is empty: what it told is no more, and the same words may be told again. */
+    quiet(): void;
+}

package/lib/element/parts.js

@@ -0,0 +1,191 @@
+// The parts of a worked example's demo the learner has opened (R42): a numbered list above the
+// sheet, under the statement, in the element's own scrolling, and a polite region that tells a
+// screen reader of the part just opened. A part opens at the list's end, and an item, once built,
+// stays as it is while the demo is the same: hidden, the list keeps its open parts out of sight. A
+// paragraph is its text; a picture beside the sheet is a frame of its size, as a statement's
+// picture is, which shows the picture once the element's pictures have its file and what it shows
+// in words till then. A picture on an area of the sheet is read by its words here, while the
+// picture itself stands on the layer of the author's demo, stretched over its area, the later part
+// over the earlier, and nothing stands there till its file is decoded (T61). This module is no
+// entry point of the package.
+import { onSheet } from "../core/example.js";
+import { SHEET } from "../core/sheet.js";
+import { placeOver, SVG, write } from "./attributes.js";
+import { framed } from "./statement.js";
+/** The list of a demo's open parts and the region that tells of them, as the element shows them. */
+export class Parts {
+    /** The open parts, in the module's explanation language, or in the element's own without one. */
+    list = document.createElement("ol");
+    /**
+     * The polite region that tells of the part just opened: empty from the start, and hidden from
+     * sight alone, for a region out of the tree of what a screen reader reads tells nothing.
+     */
+    status = document.createElement("div");
+    /**
+     * The pictures on areas of the sheet, for the layer of the author's demo: in sheet units, as the
+     * layer's view box counts, in the demo's order, so that a later part is drawn over an earlier.
+     */
+    layer = document.createElementNS(SVG, "g");
+    /**
+     * Where the sheet scrolls to for a picture on an area just opened: a box of the area in the
+     * sheet's own flow, not on its sticky stage, whose pictures move only at the next frame. It is
+     * hidden, so it paints nothing and takes no pointer, but it has a box to scroll into sight.
+     */
+    spot = document.createElement("div");
+    #pictures;
+    /** What takes the picture of an item off, once the item leaves the list. */
+    #off = new WeakMap();
+    /** The area of the sheet of an item whose picture stands there. */
+    #areas = new WeakMap();
+    /** The list and the region, by their IDs, whose pictures the element's pictures give files. */
+    constructor(ids, pictures) {
+        this.#pictures = pictures;
+        this.list.className = "parts";
+        this.list.id = ids.parts;
+        this.status.className = "status";
+        this.status.id = ids.status;
+        this.status.setAttribute("role", "status");
+        this.spot.className = "spot";
+    }
+    /**
+     * The language the parts are in, a BCP 47 tag, or `undefined` for the element's own, which the
+     * list inherits. A new language changes the attribute alone.
+     */
+    set lang(lang) {
+        write(this.list, "lang", lang ?? null);
+    }
+    /**
+     * The demo as a state has it: as many parts open as it says, from the first, items added or
+     * taken off at the list's end alone, and the list hidden or shown. Only what has changed is
+     * written: hidden, the parts keep their pictures.
+     */
+    show(demo, { opened, hidden }) {
+        let last = this.list.lastElementChild;
+        while (last !== null && this.list.childElementCount > opened) {
+            this.#takeOff(last);
+            last.remove();
+            last = this.list.lastElementChild;
+        }
+        for (let n = this.list.childElementCount; n < opened; n++) {
+            const part = demo[n];
+            if (part !== undefined)
+                this.list.append(this.#itemOf(part));
+        }
+        if (this.list.hidden !== hidden)
+            this.list.hidden = hidden;
+        // An SVG element has no hidden attribute: the presentation attribute hides it.
+        write(this.layer, "display", hidden ? "none" : null);
+    }
+    /** No part open, the list shown, and nothing told: a demo begins, or goes. */
+    clear() {
+        for (const item of [...this.list.children])
+            this.#takeOff(item);
+        this.list.replaceChildren();
+        this.list.hidden = false;
+        write(this.layer, "display", null);
+        this.spot.removeAttribute("style");
+        this.quiet();
+    }
+    /**
+     * What the `n`th part, from 1, comes into sight by once it is open (R42): its item, or for a
+     * picture on an area of the sheet the spot, which it places on that area, in shares of the sheet,
+     * which keeps its proportions.
+     */
+    target(n) {
+        const item = this.list.children[n - 1];
+        const area = item === undefined ? undefined : this.#areas.get(item);
+        if (area !== undefined) {
+            const { left, top, width, height } = area;
+            const share = (value, of) => `${(100 * value) / of}%`;
+            Object.assign(this.spot.style, {
+                left: share(left, SHEET.width),
+                top: share(top, SHEET.height),
+                width: share(width, SHEET.width),
+                height: share(height, SHEET.height),
+            });
+            return this.spot;
+        }
+        return item instanceof HTMLElement ? item : undefined;
+    }
+    /**
+     * The region tells of a part just opened: its number, in the labels' language, and its words —
+     * a paragraph's text, a picture's description — in the parts' own. A picture that only decorates
+     * has its number alone.
+     */
+    tell(part, told) {
+        const number = document.createElement("span");
+        number.lang = told.lang;
+        number.textContent = told.number;
+        const words = "text" in part ? part.text : part.alt;
+        if (words === "") {
+            this.status.replaceChildren(number);
+            return;
+        }
+        const said = document.createElement("span");
+        // The parts' language, which the list has, or none: then the element's own, as the list's.
+        const lang = this.list.getAttribute("lang");
+        if (lang !== null)
+            said.lang = lang;
+        said.textContent = words;
+        this.status.replaceChildren(number, " ", said);
+    }
+    /** The region is empty: what it told is no more, and the same words may be told again. */
+    quiet() {
+        this.status.replaceChildren();
+    }
+    /** An item leaving the list takes its picture off, once. */
+    #takeOff(item) {
+        this.#off.get(item)?.();
+        this.#off.delete(item);
+    }
+    /**
+     * The item of an open part: a paragraph's text, a picture beside the sheet in its frame, or the
+     * words of a picture on an area of the sheet, which a screen reader reads as the picture, while
+     * the item stays an item of the list, and the picture itself on the sheet. One that only
+     * decorates leaves its item empty, and on the sheet it stands all the same.
+     */
+    #itemOf(part) {
+        const item = document.createElement("li");
+        if ("text" in part) {
+            // Text, never markup: a module is data (R02 spec).
+            item.textContent = part.text;
+        }
+        else if (!onSheet(part)) {
+            const { frame, off } = framed(this.#pictures, part);
+            this.#off.set(item, off);
+            item.append(frame);
+        }
+        else {
+            this.#off.set(item, this.#onTheSheet(part));
+            this.#areas.set(item, part.area);
+            if (part.alt !== "") {
+                const words = document.createElement("div");
+                words.setAttribute("role", "img");
+                words.setAttribute("aria-label", part.alt);
+                words.textContent = part.alt;
+                item.append(words);
+            }
+        }
+        return item;
+    }
+    /**
+     * A picture on its area of the sheet, at the end of the layer, stretched over the area: its
+     * corners at the area's (README of the format, §21; SVG 2). It shows its file's address once the
+     * element's pictures have it decoded, and nothing till then: its words are in its item. What it
+     * gives back takes the picture off the sheet.
+     */
+    #onTheSheet(part) {
+        const image = document.createElementNS(SVG, "image");
+        placeOver(image, part.area);
+        image.setAttribute("preserveAspectRatio", "none");
+        this.layer.append(image);
+        const off = this.#pictures.place(part.picture, {
+            show: (url) => image.setAttribute("href", url),
+            hide: () => image.removeAttribute("href"),
+        });
+        return () => {
+            off();
+            image.remove();
+        };
+    }
+}

package/lib/element/pictures.d.ts

@@ -0,0 +1,45 @@
+/**
+ * What gives the file of a picture of a task or a worked example: the consumer's, for the canvas
+ * goes to no network (R07; repositories 2.1 spec). app takes the files from what api serves, the
+ * samples page from its own build.
+ */
+export type Media = (ref: string) => Promise<Blob>;
+/** A picture on show, as what shows it has it. */
+export interface PictureView {
+    /** Its file's address came, decoded: the picture shows it. */
+    show(url: string): void;
+    /** The address it showed went: the picture shows what it shows in words again. */
+    hide(): void;
+}
+/** The files of the pictures of an element, by their references, and their addresses. */
+export declare class Pictures {
+    #private;
+    get media(): Media | undefined;
+    /**
+     * A new function serves the references that have no file and no load under way: those waiting
+     * for one, and those whose load failed. It stops no load the last one began.
+     */
+    set media(media: Media | undefined);
+    /**
+     * The references of the pictures the element shows, or may show: a new task's statement's, or a
+     * new worked example's statement's and demo's. Those no longer named go: their addresses at once,
+     * so their pictures show their words, and their files; a load under way goes on, and its file
+     * goes to the reference only if it is named again by then. A reference named before keeps what it
+     * has. On the page, every reference without a file asks for it: one that did not come, or did
+     * not decode, is asked for again with each new task or example.
+     */
+    name(refs: Iterable<string>): void;
+    /**
+     * A picture of a reference on show: it shows the file's address at once if the address is
+     * decoded, and otherwise once it is. What it gives back takes the picture off, and lets no
+     * address go: an address lives while its reference is named and the element is on the page.
+     */
+    place(ref: string, view: PictureView): () => void;
+    /** The element came to the page: the files it has get their addresses, and the rest load. */
+    connect(): void;
+    /**
+     * The element left the page. The addresses of its files go, unless it comes back at once, as an
+     * element moved in the page does; the files stay with it, for it may come back later.
+     */
+    disconnect(): void;
+}

package/lib/element/pictures.js

@@ -0,0 +1,167 @@
+// The files of the pictures an element shows, by their references (R23, R42): a task's statement's,
+// and a worked example's — its statement's and its demo's, beside the sheet and on areas of it.
+// One reference is one file and one call of the consumer's media, however many pictures show it,
+// and a file stays while what the element shows names its reference. On the page a file has one
+// address, decoded once, before any picture shows it: a picture placed then shows it at once. What
+// a picture is — a frame of the statement or of the list of parts, or a picture on the sheet — is
+// its own: the pictures here are told when to show the address and when it has gone. This module is
+// no entry point of the package.
+/** The files of the pictures of an element, by their references, and their addresses. */
+export class Pictures {
+    /** The references named, in the order they were named, and what the element has of each. */
+    #held = new Map();
+    /** The pictures on show, by reference: placed apart from the naming. */
+    #views = new Map();
+    /** The loads under way, by reference: a reference named again waits for the load it began. */
+    #loading = new Map();
+    #media;
+    #connected = false;
+    get media() {
+        return this.#media;
+    }
+    /**
+     * A new function serves the references that have no file and no load under way: those waiting
+     * for one, and those whose load failed. It stops no load the last one began.
+     */
+    set media(media) {
+        this.#media = media;
+        if (this.#connected)
+            this.#load();
+    }
+    /**
+     * The references of the pictures the element shows, or may show: a new task's statement's, or a
+     * new worked example's statement's and demo's. Those no longer named go: their addresses at once,
+     * so their pictures show their words, and their files; a load under way goes on, and its file
+     * goes to the reference only if it is named again by then. A reference named before keeps what it
+     * has. On the page, every reference without a file asks for it: one that did not come, or did
+     * not decode, is asked for again with each new task or example.
+     */
+    name(refs) {
+        const named = new Set(refs);
+        for (const [ref, held] of this.#held) {
+            if (named.has(ref))
+                continue;
+            this.#release(ref, held);
+            this.#held.delete(ref);
+        }
+        for (const ref of named) {
+            if (this.#held.has(ref))
+                continue;
+            this.#held.set(ref, { file: undefined, url: undefined, image: undefined, decoded: false });
+        }
+        if (this.#connected)
+            this.#load();
+    }
+    /**
+     * A picture of a reference on show: it shows the file's address at once if the address is
+     * decoded, and otherwise once it is. What it gives back takes the picture off, and lets no
+     * address go: an address lives while its reference is named and the element is on the page.
+     */
+    place(ref, view) {
+        let views = this.#views.get(ref);
+        if (views === undefined) {
+            views = new Set();
+            this.#views.set(ref, views);
+        }
+        views.add(view);
+        const held = this.#held.get(ref);
+        if (held?.decoded === true && held.url !== undefined)
+            view.show(held.url);
+        return () => {
+            const placed = this.#views.get(ref);
+            placed?.delete(view);
+            if (placed?.size === 0)
+                this.#views.delete(ref);
+        };
+    }
+    /** The element came to the page: the files it has get their addresses, and the rest load. */
+    connect() {
+        this.#connected = true;
+        for (const [ref, held] of this.#held)
+            this.#attach(ref, held);
+        this.#load();
+    }
+    /**
+     * The element left the page. The addresses of its files go, unless it comes back at once, as an
+     * element moved in the page does; the files stay with it, for it may come back later.
+     */
+    disconnect() {
+        this.#connected = false;
+        queueMicrotask(() => {
+            if (this.#connected)
+                return;
+            for (const [ref, held] of this.#held)
+                this.#release(ref, held);
+        });
+    }
+    /** Each reference without its file and without a load under way asks the consumer for it. */
+    #load() {
+        const media = this.#media;
+        if (media === undefined)
+            return;
+        for (const [ref, held] of this.#held) {
+            if (held.file !== undefined || this.#loading.has(ref))
+                continue;
+            // A function that throws fails the load as one whose promise is rejected does.
+            const load = Promise.resolve()
+                .then(() => media(ref))
+                .then((file) => {
+                if (!(file instanceof Blob))
+                    throw new TypeError(`media gave ${typeof file}, not a Blob`);
+                // The file of a reference no longer named is not kept.
+                const named = this.#held.get(ref);
+                if (named === undefined)
+                    return;
+                named.file = file;
+                this.#attach(ref, named);
+            })
+                .catch((reason) => {
+                console.warn(`the picture "${ref}" did not come: ${String(reason)}`);
+            })
+                .finally(() => this.#loading.delete(ref));
+            this.#loading.set(ref, load);
+        }
+    }
+    /**
+     * A file gets its address, if the element is on the page and the file has none, and an image
+     * decodes it: then the pictures of its reference show it.
+     */
+    #attach(ref, held) {
+        if (held.file === undefined || held.url !== undefined || !this.#connected)
+            return;
+        const url = URL.createObjectURL(held.file);
+        const image = new Image();
+        held.url = url;
+        held.image = image;
+        image.src = url;
+        image.decode().then(() => {
+            // The address may have gone, or its reference, while the file was decoded.
+            if (held.image !== image)
+                return;
+            held.decoded = true;
+            for (const view of this.#views.get(ref) ?? [])
+                view.show(url);
+        }, () => {
+            if (held.image !== image)
+                return;
+            // A file that is no picture: it goes, and a new media function may give another.
+            this.#release(ref, held);
+            held.file = undefined;
+            console.warn(`the picture "${ref}" is no picture a browser shows`);
+        });
+    }
+    /** A file lets its address go, and the pictures that showed it show their words again. */
+    #release(ref, held) {
+        if (held.url === undefined)
+            return;
+        URL.revokeObjectURL(held.url);
+        const shown = held.decoded;
+        held.url = undefined;
+        held.image = undefined;
+        held.decoded = false;
+        if (!shown)
+            return;
+        for (const view of this.#views.get(ref) ?? [])
+            view.hide();
+    }
+}

package/lib/element/probe.d.ts

@@ -0,0 +1,33 @@
+import type { Box } from "../core/geometry.js";
+import type { Role } from "../core/hands.js";
+import type { Stroke } from "../core/ink.js";
+import type { View } from "../core/screen.js";
+/** An element's state, as its test reads it. */
+export interface Probe {
+    /** The strokes on the sheet, in the order they were written: the work's, after any undo. */
+    readonly strokes: readonly Stroke[];
+    /** The stroke being written, or nothing between strokes. */
+    readonly live: Stroke | undefined;
+    /** The IDs of the strokes the eraser under way has come near, or none between presses. */
+    readonly pending: readonly number[];
+    /** How many outlines of strokes the element has computed so far. */
+    readonly outlines: number;
+    /** Where the sheet is on the screen, or nothing while the element is not laid out. */
+    readonly view: View | undefined;
+    /**
+     * The tutor's marks the sheet shows, in their order: each one's name, the strokes it holds on to
+     * and its frame as last drawn, in sheet units — null while none of its strokes is on the screen.
+     * A mark without a place is not among them (R26).
+     */
+    readonly marks: readonly {
+        readonly name: string;
+        readonly ids: readonly number[];
+        readonly frame: Box | null;
+    }[];
+    /** What each pointer down on the sheet does, by its `pointerId` (R29). */
+    readonly roles: ReadonlyMap<number, Role>;
+}
+/** Called by each element as it is built, with what reads its state. */
+export declare function attachProbe(element: object, read: () => Probe): void;
+/** The state of an element of this package. */
+export declare function probe(element: object): Probe;

package/lib/element/probe.js

@@ -0,0 +1,18 @@
+// What a test sees of an element beyond its interface: its strokes, the stroke under way, what the
+// eraser is about to take, its view of the sheet, how many outlines it has drawn, the tutor's
+// marks it shows and what each pointer down on it does (R29). The history of writing is the
+// element's own property now (R27). This module is no entry point of the package, so the
+// element's interface stays what the tasks of the sheet make it (R07, R12, R19, R22, R27, R29;
+// RUN.md, T10, T14, T15, T33, T34, T35).
+const probes = new WeakMap();
+/** Called by each element as it is built, with what reads its state. */
+export function attachProbe(element, read) {
+    probes.set(element, read);
+}
+/** The state of an element of this package. */
+export function probe(element) {
+    const read = probes.get(element);
+    if (read === undefined)
+        throw new Error("not an element of this package");
+    return read();
+}

package/lib/element/session.d.ts

@@ -0,0 +1,3 @@
+import { PenMode } from "../core/hands.js";
+/** The pen mode of every sheet of this page. */
+export declare const PEN_MODE: PenMode;

package/lib/element/session.js

@@ -0,0 +1,7 @@
+// The page's pen mode (R29): one for every sheet of the page, from a pen's first touch on any of
+// them until the learner asks for the finger, or the page is loaded again. The next task is a new
+// element (R20), and the mode stays. It is a state of the interface in memory, not data: nothing is
+// stored or sent. This module is no entry point of the package.
+import { PenMode } from "../core/hands.js";
+/** The pen mode of every sheet of this page. */
+export const PEN_MODE = new PenMode();