open-standards/wai/vector-conformance/README.md

vector-conformance — vector graphics

Vectors for wai.graphics.vector (extensions/graphics-vector.md): the WOS1 outline set and the WVG1 payload with the order in which a sink refuses them (§2), the arithmetic a sink loads with: the clock, track evaluation, the load-time interval check and the per-frame cost (§3.1–§3.4); and the raster stage family RS1–RS9 and the frame procedure (§3.5–§3.10), as the SHA-256 of every frame's RGBA8P; text runs drawn from the in-house outline sets (§4): the default stroke set and the test repertoire; and the text layer (§5): the transcript and every frame's projection, as each payload's text record. The capability is a Draft and is not registered; this corpus precedes its registration.

Provenance. Generated here by wai-vector vectors gen from formulas and from centre lines drawn in this repository: every payload, outline set, stroke source and arithmetic input is integers and text written here, with no media and no third-party font. The synthetic outline sets are drawn from formulas in wai-vector/src/vectors/sets.rs and raster.rs. The two in-house sets are drawn here as integer centre lines, the ASCII stroke set in wai-vector/src/vectors/stroke.rs and the Arabic, Hebrew and Devanagari test repertoire in wai-vector/src/vectors/repertoire.rs; the generator writes them as WSF1 sources under sources/ and expands each by Annex A into sets/stroke-ascii.wos1 and sets/test-repertoire.wos1. No outline is traced from any font. Every set's notes state where it comes from and that it is licensed Apache-2.0, and the two in-house sets' notes carry the licence text. All text in the blocks is written here; the a11y payloads' blocks, windows and strings are written in wai-vector/src/vectors/a11y.rs, the words of the title card and credit roll in wai-vector/src/vectors/text.rs, and each text record is computed from its payload by wai-vector/src/text.rs.

Equivalence. A sink conforms on this corpus when, for every payload, it reports the expected file's code: the first refusal §2.7 gives, or accepted; and for every accepted payload it computes the same SIZE costs (§3.4(b)), the same text_hash and block identities (§2.11), the same ticks per frame and frame range for each rate (§3.1, §2.7), and, where the expected file lists frames, the same RGBA8P bytes for every frame at every listed size and rate (overlay-equivalence, §1.3); and, in the group a11y, the same text record, byte for byte (text-equivalence, §1.3). An outline-set parser conforms when it reports §2.1's first code for every .wos1 vector.

Layout

• sets/<name>.wos1 — the outline sets the payloads hold as held sets. A held SET record finds its set here by SHA-256; a digest none of these files has is not held. Among them: stroke-ascii.wos1, the default stroke set, whose SHA-256 is Annex B's; and test-repertoire.wos1, the test repertoire (§4.5).
• sources/<name>.wsf1 — the WSF1 stroke sources of those two sets (Annex A). Expanding a source by Annex A gives its set byte for byte.
• vectors/<group>/<name>.wvg1 — a payload, with its JSON authoring form (§2.12) beside it as <name>.json. The form has one member per field, zero fields included, and converts back to the same bytes (wai-vector pack).
• vectors/<group>/<name>.wos1 — an outline set checked on its own (§2.1).
• vectors/arith/<name>.json and vectors/flatten/<name>.json — an arithmetic input: an operation and its cases.
• vectors/<group>/index.json — what each vector pins.
• expected/<group>/<name>.json — the result recomputed from the vector and sets/ alone, keys in ascending order, no whitespace:
  • a refusal: {"code": …};
  • an accepted payload: instr (its SHA-256), text_hash, blocks (each block's identity, in reading order), sizes ([w, h, cost]) and rates ([num, den, P, first frame, last frame]; the range is empty when the first exceeds the last);
  • in the groups that render (fills, runs, composite, motion, clock, slicing and text), frames: for each listed size and rate, every frame's [g, SHA-256 of RGBA8P] and the clip digest, the SHA-256 of the frames' digests concatenated in order of g (SPEC §7, Digests); in composite, also each frame's RGBA8S digest (rgba8s);
  • in the group a11y, text_record: the SHA-256 of the payload's text record (§5.4), which is the file beside it;
  • an arithmetic input: its results, or the SHA-256 of a whole table.
• expected/a11y/<name>.a11y.jsonl — an accepted a11y payload's text record (§5.4), exactly as §5.4 writes it: the transcript on the first line, then one line for each frame of the document at each listed rate, rates in RATE order and frames ascending, each line ended by U+000A.
• sha256.json — the digest sidecar SPEC §7, Digests, asks of a corpus: each entry names its buffer and states its SHA-256: the div255 table, and for each rendering vector at each listed size and rate, every frame's digest and the clip digest.

Groups

• arith — div255 over every input; both coverage quantisers over every v in [−2^18, 2^18]; the straight-alpha channel over every c ≤ A; R_rat and R_half_up at ties of both signs and at the driver's widths; track evaluation at spans of 2^31 − 1 ticks, value steps of 2^23 and tables that are not monotone.

• canonical — accepted payloads of every structure, each of which writes back to its own bytes, and one refusal per canonical rule (§2.5): first-reference order, duplicates and unreferenced entries in each pool; text blocks: group numbering, an ungrouped block between groups (accepted), a group that resumes or is split (refused), ruby links to the block itself and to a later block, and ruby ranges that start or end inside a character, run past the string, or end where it ends (accepted); clusters; and a decorative path alternative.

• refusals — a payload or outline set per code and per check of §2.7 and §2.1, and pairs of faults whose code pins the order: steps in order, fields in offset order within a record, tables in file order (PATHS before TEXTS before ITEMS), the record pass before any cross-table check, typing before strings, the text-block rules and the decorative path alternative before any set, each set's checks before the next set's. Held sets come from sets/, through a resolver that refuses a digest it does not hold and reads at most length + 1 bytes.

• geometry — the interval check (§3.4(a)) accepted with an end at 2^22 − 1 and refused at 2^22 on each axis, at a second listed size, for an item never active, for a clip, for enclosing groups' translations and for a glyph with no points; and a document whose true range fits and whose interval does not, refused.

• cost — a document whose cost is exactly 2^32 − 1 (accepted), one at 2^32 (too_large), stated costs off by one (payload_malformed), a reused path counted per use, windows that touch counted once, a group's cost, and three shapes that exceed the ceiling by reusing a full-canvas path, a path of 16,381 points and a full-canvas glyph.

• flatten — quadratics and cubics at the corners of the device range (levels 9 and 10), at each level boundary, degenerate, and at negative coordinates: each curve's level and vertices (§3.5).

• fills — fills and the same fills with every contour reversed, whose frames are equal (P1); random polygons; a self-intersecting star under both rules; slivers; edges on pixel and subpixel boundaries; the left fold; squares at each canvas edge; negative coordinates; A-F5's triangle; a comb of 16,382 points that attains D_r = 256·p; a path of 16,383 points; the non-zero seam and the even-odd fringe of §3.13.

• runs — glyphs that abut mid-pixel (no seam within a run, a seam across runs), overlap, carry marks; a run of 4,096 glyphs; one glyph at all 256 subpixel phases. The run set is drawn here (vectors/raster.rs) and carried inline. And an Arabic joining sequence from the test repertoire, in one run (its joins over-cover, the knot of §3.13) and split across two (the runs composite by source-over).

• composite — opacity, isolated groups four deep, clips under both rules, the group pop, and pixels on which the two candidate fill orders differ (§3.9).

• motion — a credit roll at an integer speed (frame k is frame 0 moved, P2) and at a fractional one, a lower third that slides, holds and fades as a group, and each easing mode; a lower third and a short credit roll set in the stroke set; and a title card and a credit roll in the stroke set at 1280 × 720 and 25 fps, seven seconds: a lower third that slides in, holds and fades out as a group, then a heading and five credits, each a role and what filled it, that rise three design pixels a frame and fade out, each line's window cut to the frames at which it meets the canvas.

• clock — one document at 1280 × 720, 1920 × 1080 and 3840 × 2160, and at 25, 30000/1001 and 60 fps.

• slicing — a document and three pieces cut from it; each piece's frames equal the whole's at the same g (P7).

• text — text runs from the held stroke set and test repertoire, each at two listed sizes: printable ASCII; Arabic right to left, with contextual forms, the lam-alef ligature and two marks; Hebrew, with a final form; Devanagari, with the vowel sign i drawn before its consonant, a mark above and a conjunct; an Arabic block holding a Latin word and digits, its runs from both sets; one block over three runs and lines, with a cluster of no glyphs and an inserted hyphen; a ruby annotation; a vertical-rl block; and U+1F600 drawn by one monochrome glyph. These vectors pin runs, clusters, blocks and frames; a11y pins the projection and the transcript.

• a11y — the text layer (§5.4), as each payload's text record: §5.4's worked example; frames before, between and after windows, and a title that stays projected at opacity 0 until its window ends; a decorative block, left out; the text alternatives of paths; reading groups; ruby links over part of a base, one of which outlasts its base; every registered purpose and three unregistered ones, written as the byte carried; windows that touch, overlap, nest, stay one tick apart and come out of order; windows cut by the document's own; windows cut by enclosing groups, one of which never opens; the three writing modes, whose block identities differ; one document at four rates, with a frame on a window's first tick and one on its end; strings that take each of the three escapes, and markup characters, a soft hyphen, Hebrew, Devanagari and U+1F600, which take none; and a payload with no text. The frames of this group are not rendered.

Regenerating and verifying

cd wai/wai-vector
cargo run --release --features std --bin wai-vector -- vectors gen ..
cargo run --release --features std --bin wai-vector -- vectors verify ..

vectors verify regenerates every file and requires the committed bytes, then recomputes every expected file and every text record from its vector and sets/ alone, and converts every payload's authoring form back to its bytes. wai-vector/wasm/verify.mjs recomputes the expected files under a browser's WebAssembly engine with Node, each a11y payload's text_record among them.

cargo run --release --features std --bin wai-vector -- a11y ../vector-conformance/vectors/a11y/worked-example.wvg1 --sets ../vector-conformance/sets
cargo run --release --features std --bin wai-vector -- text ../vector-conformance/vectors/a11y/worked-example.wvg1 --sets ../vector-conformance/sets

a11y prints a payload's text record (or, with transcript, or a rate and a frame, one value of it), and text its text_hash and each block's identity, fields, string and active set.

wai-vector/browser/run.mjs runs the corpus in three browser engines. It puts every payload through the sink's package, the module wai-vector/wasm/build-pkg.sh builds: the payload's code, each listed size's cost, and its frames, each hashed in the page by the module and by the platform, the sampled ones again in Node from the bytes the page sent; and, for each a11y payload, the sink's transcript and its projection at every frame of every listed rate, which written out as lines must be the committed <name>.a11y.jsonl byte for byte. It then runs the recomputation of wai-vector/wasm/verify.mjs in each engine. A run passes only when all three engines ran.

bash wai/wai-vector/wasm/build-pkg.sh
(cd wai/wai-vector/wasm && cargo build --release --target wasm32-unknown-unknown)
cd wai/wai-vector/browser
npm ci
npx playwright install chromium webkit firefox
node run.mjs --engines chromium,webkit,firefox ../../vector-conformance