@altnovatrail/canvas 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,60 @@
-# Temporary Holding Version
+# canvas
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![CI](https://github.com/altnovatrail/canvas/actions/workflows/ci.yml/badge.svg)](https://github.com/altnovatrail/canvas/actions/workflows/ci.yml)
+[![Release](https://github.com/altnovatrail/canvas/actions/workflows/release.yml/badge.svg)](https://github.com/altnovatrail/canvas/actions/workflows/release.yml)
+[![CodeQL](https://github.com/altnovatrail/canvas/actions/workflows/codeql.yml/badge.svg)](https://github.com/altnovatrail/canvas/actions/workflows/codeql.yml)
+[![Latest release](https://img.shields.io/github/v/release/altnovatrail/canvas)](https://github.com/altnovatrail/canvas/releases/latest)
+[![TypeScript version](https://img.shields.io/github/package-json/dependency-version/altnovatrail/canvas/dev/typescript)](package.json)
+[![Coverage](https://codecov.io/gh/altnovatrail/canvas/branch/main/graph/badge.svg)](https://codecov.io/gh/altnovatrail/canvas)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/altnovatrail/canvas/badge)](https://scorecard.dev/viewer/?uri=github.com/altnovatrail/canvas)
+[![License](https://img.shields.io/github/license/altnovatrail/canvas)](LICENSE)
+
+[![Code Smells](https://sonarcloud.io/api/project_badges/measure?project=altnovatrail_canvas&metric=code_smells)](https://sonarcloud.io/summary/new_code?id=altnovatrail_canvas)
+[![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=altnovatrail_canvas&metric=reliability_rating)](https://sonarcloud.io/summary/new_code?id=altnovatrail_canvas)
+[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=altnovatrail_canvas&metric=security_rating)](https://sonarcloud.io/summary/new_code?id=altnovatrail_canvas)
+[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=altnovatrail_canvas&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=altnovatrail_canvas)
+[![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=altnovatrail_canvas&metric=vulnerabilities)](https://sonarcloud.io/summary/new_code?id=altnovatrail_canvas)
+
+The NovaTrail canvases. A canvas is the workplace of a task, where the learner writes, draws and types; this UI package holds the canvas kinds — for now two, the handwriting sheet and the workbook — with their layers and tools, captures the learner's strokes with time and pressure, draws the picture of the work that goes to be checked and shows the tutor's marks tied to the learner's strokes, and the app builds it in at an exact version. A separate build of it is the samples page, where adult volunteers make samples for eval on the same canvas that learners use: a sample is saved as a file on the volunteer's device and reaches a module's eval set by pull request, and nothing goes to the platform's server.
+
+A component of [NovaTrail](https://github.com/altnovatrail/spec/tree/v0.6.2), a universal open platform for adaptive learning, interactive lessons and AI tutoring. It belongs to stage 2, First slice with learners, with tutor, api, app, skill-map and infra; with tutor it is the stage's first code: first the handwriting sheet, while the samples page waits until a measurement needs volunteers' or children's samples.
+
+## Status
+
+Code started. The detailing is done — epic E1, archived in [docs/plan/E1.md](docs/plan/E1.md). Epic E2, replanned for the MVP on 2026-10-22, built the handwriting sheet as the element `<novatrail-canvas>`, for tutor's check board to take in place of its own sheet; the board has decided to keep its own. Its last task was the author's try of the sheet by hand on the demo page, which found nothing to fix. E2 is done and archived in [docs/plan/E2.md](docs/plan/E2.md). The text canvas, epic E3, was dropped on 2026-10-25: canvas builds no text canvas. Epic E4, taken the same day, built the sheet for the product: the eraser and the history of writing, the layers and the grid, the groups of strokes and the crop for checking, the tutor's marks tied to the strokes, the package's full interface and the input on tablets. It was done on 2026-10-26 and is archived in [docs/plan/E4.md](docs/plan/E4.md). Epic E6, taken the same day, detailed and built the workbook, the first slice's second canvas kind, for school maths in grade 3, and was done on 2026-10-27; it is archived in [docs/plan/E6.md](docs/plan/E6.md). Epic E7, taken the same day, took what spec v0.2.42 brought: the task's new open fields, the exit condition that every answer slot holds something — `filled` on a sheet too — and the lesson's worked example, shown on a sheet the learner does not write on. On the way canvas moved to spec v0.4.1, whose npm package gives the types of the module format. E7 was done on 2026-11-01 and is archived in [docs/plan/E7.md](docs/plan/E7.md). Epic E8, taken the same day, is the first release of the package, which spec's cross-repository plan asks for before the app's code; the tests' coverage and the release's build come first. Then canvas moved to spec v0.6.2, of spec's 0.6 line, and its CI now checks the signature of each package of `@altnovatrail` in its lock file, as spec's rules ask; then the element took the module format 0.2 and the types of its contract with the app from spec's npm package, and the package came out in its first release, v0.1.0. The samples page is epic E5 for later; it waits until a measurement needs volunteers' or children's samples. So far there is the package, `@altnovatrail/canvas`, with its tools and the sheet's input: the element takes a pen, a finger or a mouse, one pointer at a time, and draws the strokes, and its methods `undo()` and `clear()` undo the last action and clear the sheet. Its eraser, E4's first task, takes strokes off whole along the path of a press: the element's `tool` switches to it, and a pen's eraser erases whatever the tool, if the task allows the eraser. The sheet keeps the history of writing — every stroke, erasing, clearing and undo, at the sheet's time — for the app to keep. The sheet is a stack of layers, in the order of spec's canvas layers: its task, the element's `task` property, rules it in squares, lines or dots, and the task's statement stands above the sheet, its pictures from the consumer's `media`. The task and the module's manifest come in the types of spec's npm package, `@altnovatrail/spec`; the element reads the module format 0.2, which spec v0.6.0 brought — a manifest of another version is a TypeError — and the task is checked as its schema checks it, a field it does not know a TypeError; what the statement gives and asks, the fields `givens` and `unknown`, the element takes and leaves for the app to show; a workbook's task the element shows too: its lines laid out on a page the size of the sheet — numbers, text fitted to the layout's own widths, and boxes, up to ten rows — which a screen reader reads as a list. On a workbook each stroke falls in one box or in none, by a rule in integers on the middle of its points' box; what falls in no box is draft, which stays on the page and goes to no check, and the property `filled` tells which boxes hold writing, and on a sheet whether its one answer anywhere on it, or the whole sheet, does. The module's manifest, the `manifest` property, gives the height of a digit on the crop, 24 px unless it gives another, as without a manifest, and the language of the statement. The sheet is at most 1000 CSS pixels wide, and the consumer themes it by custom properties. The DOM-free part parts the strokes into groups by place and time — two strokes no more than 2 seconds apart whose boxes come within a cell of each other are neighbours, and a chain of neighbours is a group — labels the groups A, B, C… by place and gives each one's rectangle on the sheet, for the crop, the tutor's marks and the samples to come; the rule's test vectors are a proposal for the eval protocol. It also draws the crop for checking, with its own raster and PNG encoder: the ink of the visible strokes, scaled so that the writing comes out at the digit height the module's manifest asks for, within the size every Claude model takes as it is, with the groups' frames in its fractions. Its test vectors go to the eval protocol too. The element takes the tutor's marks of a submission back by its property `marks`, with the context it is to give with the crop: a mark holds on to the learner's strokes — a group's, or those a model's box on the crop takes, two thirds of their points within a quarter of a digit of it — and a frame stands round those of them the sheet shows, over the work, read by its name and fading while the learner writes into it. The history goes out by the property `history` and the event `historychange`, which tells of every action with the events it adds, and comes back by the same property: the same history changes nothing, and another, one the sheet could have written, replaces the sheet, undo and all. `exportWork()` gives the work for checking: the PNG of the crop and the context of its submission, which the app keeps and gives back with the tutor's marks, its digest telling the sheet's own context from another sheet's. On a workbook it gives the crop of each filled box, with its item and slot, and the context of the table of boxes; a tutor's mark there stands on an answer cell by its place and frames the box with its ink. Above the statement and the sheet, outside their scrolling, stands the element's own row of buttons — the pen and the eraser the task allows, undo and clear — a toolbar worked by pointer and by keyboard, labelled in English or Russian by the element's own `lang`; a `toolchange` event tells of the learner's choice of tool. On a tablet a pen's touch puts the whole page in pen mode, where a finger writes nothing until the row's Draw with finger lets it write again; a touch wider or taller than 100 CSS pixels is a palm and writes nothing, and two fingers scroll the sheet. The row's Up and Down scroll it the same way with a single pointer, on any device, by four fifths of what is in sight. A lesson's worked example comes by the property `workedExample`, in place of a task: its statement stands above the sheet and its grid on it, but the learner does not write there — a finger or a pen scrolls the sheet as the browser scrolls the statement, and the row, named Worked example, has Next, Demo, Up and Down. Next opens the parts of the author's demo one at a time, into a numbered list above the sheet that a polite region tells a screen reader of, and Demo hides the whole demo and shows it again; the property `demoState` and the event `demochange` tell the app how far the learner has gone, and the app may give it back to a new element after the example — in React's JSX `workedExample` comes before `demoState`, and `ondemochange` listens. The pictures of the demo come from the consumer's `media` with the statement's, one file for each reference, all of them as the example comes, so that a part opened shows its picture at once; a picture on an area of the sheet stands on the sheet itself, stretched over its area, and the sheet scrolls to it as its part opens. The element now waits for the app and the samples page; a test plays the app's part, and `just demo` serves a page to try the element on by hand. A release comes out by itself after CI passes on `main`, when a path it is built from has changed: the package's archive, LICENSE and their sums, built, signed and checked by .github's shared release, and the same archive goes to npm: the first version by hand, while the release's own npm step, through trusted publishing, is being set up. A pull request from a branch of this repository tries the release and publishes nothing.
+
+## Install
+
+The app takes the package from npm at an exact version, and spec's npm package, whose types the element's contract is in, at the version the package has in its `dependencies`:
+
+```sh
+npm install --save-exact @altnovatrail/canvas@<version>
+npm install --save-exact --save-dev @altnovatrail/spec@<its version>
+```
+
+A pull request that changes the lock file has spec's recipe check it, as NovaTrail's rules ask of every package of `@altnovatrail`: `just -f spec/justfile release-verify-npm package-lock.json`, from a checkout of spec at a tag. It takes the archive from the registry only if it is the same bytes as the file of canvas's release, signed by .github's shared release at the call of canvas's `release.yml` on `main`.
+
+## Code
+
+- `src/core/` — the DOM-free part, `@altnovatrail/canvas/core`: it runs the same in a browser and in Node, and its entry point gives the sheet's size, the types of the data and the fold of a history into its strokes.
+- `src/element/` — the element `<novatrail-canvas>`, `@altnovatrail/canvas`: importing it registers the element. The types of its contract with the app — the element as `CanvasElement` has it, its events, the history of writing, the work for checking and its context — are spec's, from `@altnovatrail/spec/canvas`, and this entry point gives them under spec's names, the same types; the DOM-free part gives the data's among them, the history of writing and the context of a submission. The app takes them from spec's package, `import type { CanvasElement } from "@altnovatrail/spec/canvas"`, at the version canvas has in its `dependencies`; canvas's own are only what the contract does not name: the tutor's marks, the media and the task's temporary tools.
+- `scripts/` — the check of the package as a consumer takes it, and of the archive a release puts out.
+- `demo/` — a page to try the element on by hand, as the app is to have it: it gives the element a language and its task the tools allowed, keeps the history of writing as the element tells it and opens the sheet again from it, draws the groups of the strokes and the crop for checking under the sheet, gives the tutor's marks back over the crop Check sent, and shows a workbook's pages in the font and the language it gives, how many boxes are filled, the crop of each filled box Check sent and a mark given back on a box, and a lesson's worked example on a new element, on which nothing is written, whose demo opens part by part — a picture on an area of the sheet on the sheet itself — the page keeping how far it has gone and giving it back to the next element. `just demo` serves it on this machine.
+- `vectors/` — the test vectors of the rule of stroke groups, of the crop for checking, of the snapping of a model's box to the strokes, of the workbook's page layout and of the rule of boxes, which their tests write and keep current.
+- `licenses.json` — the packages the license check accepts by name, each with why.
+
+`just build` builds the package into `lib/`, and `just release-files v0.1.0` writes the files of that release into `dist/` — the package's archive, LICENSE and SHA256SUMS — and prints the sums, which a build of the same commit gives again. `just ci` runs the checks CI runs: format, lint and types; the tests in Node and in Chromium; advisories; licenses. They run in the devcontainer, whose toolchain stage holds the browser the tests run in. The license check is spec's recipe, run from the `spec/` submodule with the exceptions in `licenses.json`, so it needs `spec/` checked out: see [CLAUDE.md](CLAUDE.md), Environment.
+
+## Documents
+
+The documents are in Russian.
+
+- [docs/architecture.md](docs/architecture.md) — the component: what it does and does not do, its data and links, and what is still to decide.
+- [docs/decisions.md](docs/decisions.md) — the decision log: what was decided, why, and what was rejected.
+- [RUN.md](RUN.md) — the work plan, in epics.
+
+The working rules, for people and coding agents alike, are in [CLAUDE.md](CLAUDE.md) and [AGENTS.md](AGENTS.md). The platform's shared vocabulary, formats, contracts and decisions are in [spec](https://github.com/altnovatrail/spec/tree/v0.6.2), checked out here as a git submodule at `v0.6.2`: clone this repository with `git clone --recurse-submodules`.
+
+## License
+
+[Apache-2.0](LICENSE).

package/lib/core/boxes.d.ts

@@ -0,0 +1,54 @@
+import type { Filled, Filling } from "@altnovatrail/spec/canvas";
+import type { Stroke } from "./ink.js";
+import type { Page, PageBox } from "./page.js";
+/** A box of a page: its item and its slot in the item's line, each from 1, and where it stands. */
+export interface Cell {
+    readonly item: number;
+    readonly slot: number;
+    readonly box: PageBox;
+}
+/**
+ * The rule of boxes (R37), in thousandths of a box's width across and of its height down: how far
+ * the box is widened for the middle of a stroke's points, and how wide and how tall the box of its
+ * points may be.
+ */
+export interface BoxRule {
+    readonly margin: number;
+    readonly limit: number;
+}
+/** The rule the workbook has (R37): the sweep of T48 chose it. */
+export declare const BOX_RULE: BoxRule;
+/**
+ * Which answer slots the learner's strokes fill, per item, per slot, in the task's order: a
+ * workbook's boxes, each whether it holds a stroke (R34, R37), or a sheet's one answer anywhere on
+ * it or the whole sheet, whether the sheet holds one (R42). spec's type (R74 spec; R07).
+ */
+export type { Filled };
+/**
+ * What a sheet's one answer slot — anywhere on it, or the whole sheet — is filled with (R42): a
+ * stroke on the sheet, or none. The same array each time, as a workbook's filling stays the same
+ * until a box changes.
+ */
+export declare function sheetFilledOf(stroked: boolean): Filled;
+/** The boxes of a page in the task's order: by item, then by slot. */
+export declare function cellsOf(page: Page): readonly Cell[];
+/**
+ * The cell a stroke is in, by its place in `cells`, or −1 for the draft. Of the boxes it may be in,
+ * the one that holds the more of its points, within the widened box, and of those the earlier, in
+ * the order of `cells`: the task's order on a page. A stroke with no points is a TypeError, and
+ * one with a point off the sheet a RangeError, as the crop has them.
+ */
+export declare function cellOf(stroke: Stroke, cells: readonly Cell[], rule?: BoxRule): number;
+/** A filled box and the IDs of its strokes, in ascending order: spec's type (R74 spec; R07). */
+export type { Filling };
+/**
+ * The table of the boxes the strokes fill (R34): each box that holds a stroke, in the order of
+ * `cells`, with the IDs of its strokes. A stroke ID twice is a TypeError.
+ */
+export declare function tableOf(strokes: readonly Stroke[], cells: readonly Cell[], rule?: BoxRule): readonly Filling[];
+/**
+ * Which boxes of a page are filled, per item, per slot, in the task's order: the cells `taken`
+ * names by their place in `cells` — the page's, from `cellsOf` — each from `cellOf`; −1, the
+ * draft, fills none.
+ */
+export declare function filledOf(page: Page, cells: readonly Cell[], taken: Iterable<number>): Filled;

package/lib/core/boxes.js

@@ -0,0 +1,116 @@
+// The boxes of a workbook's page and the strokes in them (R34, R37). Each visible stroke is in one
+// box or in none: the rule takes it alone, in whole numbers, with no DOM and no time, and what is in
+// no box is the draft. A stroke is a box's if the middle of the box of its points lies in the box
+// widened by 120 thousandths of its size — 12 units of a box of 100, short of the 16 to halfway to
+// the next box — and it is no wider and no taller than the box and 30 units on each side: a
+// fraction's bar wider than the box is its own, and a line through the whole line is not. The
+// core's entry point does not give the rule, and vectors/boxes.json pins it: the eval protocol
+// takes it as it is (В47 in RUN.md).
+import { extentOf, tenths } from "./geometry.js";
+/** The rule the workbook has (R37): the sweep of T48 chose it. */
+export const BOX_RULE = Object.freeze({ margin: 120, limit: 1600 });
+/** A sheet's one answer slot, filled and not: the same frozen arrays for every sheet (R42). */
+const STROKED = Object.freeze([Object.freeze([true])]);
+const BLANK = Object.freeze([Object.freeze([false])]);
+/**
+ * What a sheet's one answer slot — anywhere on it, or the whole sheet — is filled with (R42): a
+ * stroke on the sheet, or none. The same array each time, as a workbook's filling stays the same
+ * until a box changes.
+ */
+export function sheetFilledOf(stroked) {
+    return stroked ? STROKED : BLANK;
+}
+/** The boxes of a page in the task's order: by item, then by slot. */
+export function cellsOf(page) {
+    return Object.freeze(page.items.flatMap((item, i) => item.boxes.map((box, j) => Object.freeze({ item: i + 1, slot: j + 1, box }))));
+}
+/**
+ * The cell a stroke is in, by its place in `cells`, or −1 for the draft. Of the boxes it may be in,
+ * the one that holds the more of its points, within the widened box, and of those the earlier, in
+ * the order of `cells`: the task's order on a page. A stroke with no points is a TypeError, and
+ * one with a point off the sheet a RangeError, as the crop has them.
+ */
+export function cellOf(stroke, cells, rule = BOX_RULE) {
+    if (rule !== BOX_RULE)
+        checkRule(rule);
+    const { margin, limit } = rule;
+    const { minX, minY, maxX, maxY } = extentOf(stroke);
+    const points = stroke.points.map(({ x, y }) => [tenths(x), tenths(y)]);
+    let chosen = -1;
+    let most = 0;
+    for (const [c, { box }] of cells.entries()) {
+        const left = 10 * box.left;
+        const top = 10 * box.top;
+        const width = 10 * box.width;
+        const height = 10 * box.height;
+        if (1000 * (maxX - minX) > limit * width || 1000 * (maxY - minY) > limit * height)
+            continue;
+        // The middle, doubled to stay whole: 2·left − 2·margin·width ≤ minX + maxX, and so on.
+        const middle = 1000 * (minX + maxX - 2 * left) >= -2 * margin * width &&
+            1000 * (minX + maxX - 2 * left - 2 * width) <= 2 * margin * width &&
+            1000 * (minY + maxY - 2 * top) >= -2 * margin * height &&
+            1000 * (minY + maxY - 2 * top - 2 * height) <= 2 * margin * height;
+        if (!middle)
+            continue;
+        let held = 0;
+        for (const [x, y] of points) {
+            if (1000 * (x - left) >= -margin * width &&
+                1000 * (x - left - width) <= margin * width &&
+                1000 * (y - top) >= -margin * height &&
+                1000 * (y - top - height) <= margin * height) {
+                held += 1;
+            }
+        }
+        if (chosen < 0 || held > most) {
+            chosen = c;
+            most = held;
+        }
+    }
+    return chosen;
+}
+/**
+ * The table of the boxes the strokes fill (R34): each box that holds a stroke, in the order of
+ * `cells`, with the IDs of its strokes. A stroke ID twice is a TypeError.
+ */
+export function tableOf(strokes, cells, rule = BOX_RULE) {
+    const ids = new Set();
+    const held = cells.map(() => []);
+    for (const stroke of strokes) {
+        if (ids.has(stroke.id))
+            throw new TypeError(`stroke ${stroke.id} is given twice`);
+        ids.add(stroke.id);
+        const c = cellOf(stroke, cells, rule);
+        if (c >= 0)
+            held[c]?.push(stroke.id);
+    }
+    return Object.freeze(cells.flatMap(({ item, slot }, c) => {
+        const own = held[c] ?? [];
+        return own.length === 0
+            ? []
+            : [Object.freeze({ item, slot, ids: Object.freeze(own.sort((a, b) => a - b)) })];
+    }));
+}
+/**
+ * Which boxes of a page are filled, per item, per slot, in the task's order: the cells `taken`
+ * names by their place in `cells` — the page's, from `cellsOf` — each from `cellOf`; −1, the
+ * draft, fills none.
+ */
+export function filledOf(page, cells, taken) {
+    const rows = page.items.map(({ boxes }) => boxes.map(() => false));
+    for (const c of taken) {
+        const cell = cells[c];
+        const row = cell === undefined ? undefined : rows[cell.item - 1];
+        if (cell !== undefined && row !== undefined)
+            row[cell.slot - 1] = true;
+    }
+    return Object.freeze(rows.map((row) => Object.freeze(row)));
+}
+/** A rule of whole thousandths, the margin up to the box itself and the limit at least nothing. */
+function checkRule({ margin, limit }) {
+    if (!Number.isInteger(margin) || margin < 0 || margin > 1000) {
+        throw new RangeError(`the margin of the rule of boxes is a whole 0 to 1000, not ${margin}`);
+    }
+    if (!Number.isInteger(limit) || limit < 0 || limit > 100_000) {
+        throw new RangeError(`the limit of the rule of boxes is a whole 0 to 100000, not ${limit}`);
+    }
+}

package/lib/core/clock.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The sheet's clock: milliseconds of the sheet, never going back (R09, R18). The page's time it is
+ * given — a pointer event's `timeStamp`, or `performance.now()` for a method the consumer calls —
+ * both count from the page's time origin (DOM Standard; High Resolution Time), so one clock serves
+ * the strokes, the eraser and the actions of the sheet alike (R22). A new sheet's time starts at
+ * its first event; a sheet given a history of writing goes on from where that history leaves off
+ * (R27): the sheet's time is its history's.
+ */
+export declare class Clock {
+    #private;
+    /**
+     * The sheet's time at a moment of the page's clock. The first moment asked about is the sheet's
+     * 0, or the time the clock resumed at, and a moment earlier than one asked about before takes
+     * that one's time.
+     */
+    at(time: number): number;
+    /** The latest time the clock has given, or the one it resumed at, or 0 before it is first asked. */
+    get latest(): number;
+    /**
+     * The clock goes on at `t`: the next moment asked about is the sheet's `t`, whatever the page's
+     * time, and the clock counts on from there (R27). It may go back, when the sheet takes a history
+     * shorter than the one it had; `resume(0)` makes it a new sheet's clock.
+     */
+    resume(t: number): void;
+}

package/lib/core/clock.js

@@ -0,0 +1,39 @@
+/**
+ * The sheet's clock: milliseconds of the sheet, never going back (R09, R18). The page's time it is
+ * given — a pointer event's `timeStamp`, or `performance.now()` for a method the consumer calls —
+ * both count from the page's time origin (DOM Standard; High Resolution Time), so one clock serves
+ * the strokes, the eraser and the actions of the sheet alike (R22). A new sheet's time starts at
+ * its first event; a sheet given a history of writing goes on from where that history leaves off
+ * (R27): the sheet's time is its history's.
+ */
+export class Clock {
+    #origin;
+    /** The sheet's time at the origin: 0, or where a history given to the sheet goes on. */
+    #base = 0;
+    #last = 0;
+    /**
+     * The sheet's time at a moment of the page's clock. The first moment asked about is the sheet's
+     * 0, or the time the clock resumed at, and a moment earlier than one asked about before takes
+     * that one's time.
+     */
+    at(time) {
+        this.#origin ??= time;
+        const t = Math.max(this.#base + (time - this.#origin), this.#last);
+        this.#last = t;
+        return t;
+    }
+    /** The latest time the clock has given, or the one it resumed at, or 0 before it is first asked. */
+    get latest() {
+        return this.#last;
+    }
+    /**
+     * The clock goes on at `t`: the next moment asked about is the sheet's `t`, whatever the page's
+     * time, and the clock counts on from there (R27). It may go back, when the sheet takes a history
+     * shorter than the one it had; `resume(0)` makes it a new sheet's clock.
+     */
+    resume(t) {
+        this.#origin = undefined;
+        this.#base = t;
+        this.#last = t;
+    }
+}

package/lib/core/crop.d.ts

@@ -0,0 +1,87 @@
+import type { CropNumbers, Frame } from "@altnovatrail/spec/canvas";
+import type { Group } from "./groups.js";
+import type { Stroke } from "./ink.js";
+/**
+ * The crop's rule in its numbers (R25): sizes on the crop in pixels, heights on the sheet in units.
+ * The rule counts in whole numbers — places in tenths of a unit, as the groups do (R24) — and each
+ * number it hands out that is not whole is one division of two whole numbers, so that tutor's
+ * runner, which crops by the same rule, gets the same numbers to the bit.
+ */
+export declare const CROP: Readonly<{
+    /** The margin around the work, px (R06). */
+    margin: 12;
+    /**
+     * A stroke lower than this, in units, is a line, not writing — a dot, a minus, a bar, an
+     * underline — and is in no bundle, nor joins any.
+     */
+    flat: 15;
+    /** The scale takes the median no higher than this, in units: a drawing alone stays a drawing. */
+    ceiling: 100;
+    /** The least width and height of a crop, px: Claude may err on images under 200 pixels. */
+    side: 200;
+    /**
+     * The longest side, px, and the most visual tokens, ⌈w / 28⌉ × ⌈h / 28⌉: what every model of
+     * Claude takes without scaling the image down, its standard tier.
+     */
+    edge: 1568;
+    tokens: 1568;
+    patch: 28;
+    /**
+     * The height of a digit a crop is drawn at unless the module's manifest says another, px: 24
+     * since the module format 0.2, with or without a manifest.
+     */
+    digit: 24;
+    /**
+     * The heights of digits a sample's crops are drawn at, px, until the eval protocol names its own
+     * (R09; R08 tutor).
+     */
+    heights: readonly [16, 24, 32, 48];
+    /** The tallest digit a crop takes, px: its ink then still stays within the margin. */
+    tallest: 256;
+}>;
+/**
+ * A group's frame on a crop: its label, and its ink in fractions 0–1000 of the crop, [ymin, xmin,
+ * ymax, xmax] — every pixel the ink of its strokes touches lies within it. spec's type (R74 spec).
+ */
+export type { Frame };
+/**
+ * The crop of a sheet for checking (R25), all but its pixels: what lies where, at what scale. Its
+ * numbers the marks are placed by — D′, the size, the margins, `sheet_box`, the frames and the
+ * whole numbers they come from — are spec's CropNumbers (R74 spec), and the rest the crop's own.
+ */
+export interface Crop extends CropNumbers {
+    /** D, the height of a digit asked for, px. */
+    readonly digit: number;
+    /** h_med, the median height of the bundles, in units: the floor if there are none. */
+    readonly median: number;
+    /** s, the crop's px to a sheet unit: D′ over h_med, or over the ceiling if h_med is above it. */
+    readonly scale: number;
+    /** The width of the line, px: D′ / 12, and 1 at least. */
+    readonly line: number;
+}
+/** A stroke as the crop sees it: the box of its points in tenths. */
+/**
+ * The bundles of the strokes on a sheet (R25): strokes no lower than `CROP.flat`, joined by a chain
+ * of boxes that touch or overlap, whenever each was written. Each bundle by its IDs ascending, the
+ * bundles by their smallest ID.
+ */
+export declare function bundlesOf(strokes: readonly Stroke[]): number[][];
+/** h_med (R25): the lower median of the heights of the bundles, in units; `CROP.flat` if none. */
+export declare function medianOf(strokes: readonly Stroke[]): number;
+/**
+ * The crop of the strokes on a sheet with its digits `digit` px high, and the frames of their
+ * groups (R25): the strokes the sheet shows, and their groups by the sheet's rule (R24). A sheet
+ * without strokes has no crop: it goes to no check (H3).
+ */
+export declare function cropOf(strokes: readonly Stroke[], groups: readonly Group[], digit?: number): Crop | null;
+/**
+ * Where a crop with its margins lies on the sheet, its `sheet_box` (R25): [ymin, xmin, ymax, xmax]
+ * in units, each one division of two whole numbers, from the whole numbers of the crop. A
+ * submission's `sheet_box` is checked by it when the tutor's marks come back with it (R26).
+ */
+export declare function sheetBoxOf(crop: Pick<Crop, "drawn" | "width" | "height" | "margins" | "exact">): readonly [number, number, number, number];
+/** What Claude counts an image as: ⌈w / 28⌉ × ⌈h / 28⌉ visual tokens, each a patch 28 px square. */
+export declare function tokensOf({ width, height }: {
+    width: number;
+    height: number;
+}): number;