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`; and text runs
drawn from the in-house outline sets (§4): the default stroke set and the test
repertoire. 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.

**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). 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`);
  - an arithmetic input: its results, or the SHA-256 of a whole table.
- `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, group numbering and contiguity,
  ruby links, 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, the record pass before any cross-table check, 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; and a lower third and a short credit roll set in the stroke set.
- `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. The blocks' projection lands with
  §5; these vectors pin runs, clusters, blocks and frames.

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