Cursor rule

1---
2description: E2E OCR assertions with Tesseract.js for canvas-only UI such as PDF pages in Cypress page objects
3globs: e2e_test/start/pageObjects/**/*.ts
4alwaysApply: false
5---
6# E2E OCR Rules
7 
8Use this rule when asserting text that is not in the DOM, such as PDF content drawn only to `<canvas>`. Keep OCR in test infrastructure, not product code.
9 
10## Tesseract Setup
11 
12- Use `tesseract.js`, a root devDependency, for canvas-only assertions via `cy.task`.
13- Register a Node task in `e2e_test/config/common.ts`.
14- The task should call `tesseract.js` `createWorker` and `recognize` on image bytes, such as base64 PNG without the `data:image/png;base64,` prefix.
15- Example task name: `ocrCanvasImage`.
16 
17## Language Data
18 
19- Commit `e2e_test/tesseract/eng.traineddata` uncompressed.
20- Pass `langPath` and `cachePath` to that directory when creating the worker.
21- This prevents Tesseract from writing `eng.traineddata` to the repo root. Root-level traineddata files are gitignored as a fallback.
22 
23## Page Object Pattern
24 
25- Wait until the canvas has real ink before OCR. Sampling `getImageData` for dark pixels is better than checking only non-zero alpha, because an empty white fill can still have alpha.
26- Export with `toDataURL("image/png")`.
27- Strip the data URL prefix.
28- Use `cy.task(..., { timeout: ... })` for slow OCR.
29- Assert the returned string contains the expected substring with a clear message.
30- Reference: `e2e_test/start/pageObjects/bookReadingPage.ts`, from `expectPdfBeginningVisible` through `expectCurrentPage(1).expectVisibleOCRContains`.
31