Initial scaffold
ober
be2cdcdc2c0c2b24f1057a968f15666081460ee7
new file mode 100644 --- /dev/null +++ b/.gitignore @@ -0,0 +1,3 @@ +dist/ +build/ +*.log new file mode 100644 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. new file mode 100644 --- /dev/null +++ b/README.md @@ -0,0 +1,60 @@ +# jerboa-pdf + +`jerboa-pdf` is the PDF layer for Jerboa applications that must run on small +systems without Python, MuPDF, Poppler, Qt, or OpenCV. + +The first target is the SFB SSD reviewer. The design deliberately avoids +server-side PDF rasterization on Android. Instead: + +1. Jerboa serves PDF bytes from an allowlisted local source directory. +2. The browser renders pages with vendored `pdf.js`. +3. The browser passes page pixels to the Rust/WASM detector from + `jerboa-vision`. +4. Jerboa persists reviewed JSON and exports coordinate drafts. + +This keeps the eventual Android artifact close to a single static Jerboa binary +plus static web assets and one WASM detector. + +## Non-Goals + +- No MuPDF dependency. +- No Poppler dependency. +- No Python bridge. +- No server-side OCR in the first version. + +## API Shape + +Planned Jerboa routes: + +- `GET /api/pdf/books`: list allowlisted PDFs. +- `GET /api/pdf/:id`: serve a source PDF with path traversal protection. +- `GET /api/pdf/:id/info`: return page count and metadata when available. + +The browser-side renderer should return the same logical page image contract as +the old Python server: + +```json +{ + "kind": "pdf", + "path": "/safe/source.pdf", + "name": "source.pdf", + "page": 54, + "dpi": 144, + "width": 1224, + "height": 1584, + "pixels": "browser ImageData RGBA" +} +``` + +`pixels` is not sent to Jerboa unless explicitly debugging. The normal path is +browser PDF render -> browser WASM detection -> session JSON -> Jerboa save. + +## Static Build Strategy + +- Vendor `pdf.js` release assets into the SSD web app. +- Serve those assets from the Jerboa binary or adjacent static asset directory. +- Avoid npm at runtime. +- Keep native Rust PDF metadata parsing optional and small. + +If server-side PDF rendering is ever required, it should be a separate optional +feature and must not be part of the Android default. new file mode 100644 --- /dev/null +++ b/docs/android-static-plan.md @@ -0,0 +1,34 @@ +# Android Static PDF Plan + +Termux cannot be the place where PDF rasterization drags in MuPDF, Poppler, +Qt, OpenCV, or Python. The correct split is: + +- Browser: PDF rasterization via `pdf.js`. +- Browser WASM: SSD box detection via `jerboa-vision`. +- Jerboa server: routing, file access policy, session persistence, export. + +## Required Assets + +- `pdf.min.js` +- `pdf.worker.min.js` +- `jerboa_vision.wasm` +- SSD review `index.html`, `style.css`, and `app.js` + +These assets can be embedded or copied next to the Jerboa binary. + +## Runtime Requirements + +- Android browser with Canvas and WebAssembly. +- Termux only needs to run the Jerboa static web server. +- No Python packages. +- No native PDF renderer. + +## Risks + +- Very large PDFs can pressure browser memory. +- `pdf.js` page rendering must be throttled to one page at a time. +- Browser-rendered dimensions must stay stable so reviewed coordinates remain + reproducible. + +The app should persist the PDF fingerprint, page number, render scale, canvas +width, and canvas height with every reviewed session.