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

# vector-conformance — vector graphics

Vectors for `wai.graphics.vector`
([`extensions/graphics-vector.md`](../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; and what a package reads of a payload (§6): the document
digest, the window slice, the text floor and the caption intervals. SPEC §5 registers
the capability (§1.8) on this corpus. §6 in a whole package, with its planted faults, is
[`pack-conformance/multi/`](../pack-conformance/README.md) (`multi-captions-01`).

**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;
  - in the group `packages`, what a package reads of the payload (§6): `document`, its
    document digest (§6.2); `transcript`, the SHA-256 of its transcript (§5.4); `floor`
    and `floor_len`, the SHA-256 and the length of its text floor payload (§6.3); and
    `captions`, its caption intervals (§6.4) as `[lang, text, [[on, off], …]]`, in
    milliseconds;
  - 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).
- `packages` — one document as a package cuts it (§6): `whole`, of eight seconds, with a
  title, a caption string that two blocks draw at two times, a subtitle in another
  language, a forced narrative, a caption whose tag is written in upper case and whose
  window of 60 ticks crosses a millisecond, a caption whose window lies inside one
  millisecond and so has no caption interval, and a decorative line; its three window
  slices, the first cut inside the caption's and the subtitle's window, each with whole's
  document digest and `text_hash`, and its own transcript, floor and caption intervals;
  and `other`, whole with one string changed, whose document digest is another. The
  frames of this group are not rendered.
- `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

```sh
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.

```sh
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
```

```sh
cargo run --release --features std --bin wai-vector -- document ../vector-conformance/vectors/packages/piece-1.wvg1 --sets ../vector-conformance/sets
cargo run --release --features std --bin wai-vector -- captions ../vector-conformance/vectors/packages/whole.wvg1 --sets ../vector-conformance/sets
```

`document` prints a payload's document digest, `slice` writes a window slice, `floor`
writes a text floor payload and `captions` prints the caption intervals (§6).

`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.

```sh
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
```