Contribute

Getting set up

git clone https://github.com/namastevis/kagaz.git
cd kagaz
python3 -m http.server 8000
# open http://localhost:8000

The small web server is only needed because pdf.js loads its worker as a separate file, which browsers block on file://. Any static server will do.

How the code is laid out

index.html              the landing page
roadmap/index.html      what exists, what is coming, what never will
merge-pdf/index.html    one tool, one self-contained file
split-pdf/  compress-pdf/  pdf-to-jpg/  jpg-to-pdf/
organize-pdf/  rotate-pdf/  crop-pdf/  page-numbers/
watermark-pdf/  sign-pdf/  scan-to-pdf/  redact-pdf/
certificate/index.html  Certificate Press
shared/kagaz.css        every page shares this stylesheet
shared/kagaz.js         browser helpers: drop zones, downloads, canvas, thumbnails
shared/ops.js           the PDF logic — deliberately DOM-free
vendor/                 pdf-lib, pdf.js, JSZip, fontkit — vendored, never a CDN
tests/stress.mjs        throws deliberately broken PDFs at shared/ops.js
tests/verify.mjs        fails the build if any page loads an external asset

Three rules keep it that way, and they are the only ones:

1. One tool is one HTML file. Markup, styles specific to it, and its logic all live together. You should be able to understand a tool without opening anything else.
2. Nothing may be fetched from another origin. No CDN, no font service, no analytics. The entire premise of Kagaz is that opening it makes no network requests, and a contributor adding a Google Font would quietly break that.
3. PDF logic goes in shared/ops.js, not in the page. That file has no DOM references, so it runs in Node and can be tested. Anything needing a canvas is passed in as an argument.

Adding a new tool

1. Copy merge-pdf/index.html to your-tool/index.html. It is the simplest of them.
2. Change the title, description, canonical URL and the copy below the fold. The slug should be what a person would actually type into a search box — rotate-pdf, not rotator.
3. Put the actual PDF manipulation in shared/ops.js as a function that takes bytes and returns bytes.
4. Add a card to the grid on the landing page and a link in every tool's footer list.
5. Add a case to tests/stress.mjs.

Things worth building

The full list lives on the roadmap, which also records what will never be built here and why. Everything in its “being built” section is unclaimed.

Good places to start, roughly easiest first:

• Indian language interfaces — Hindi, Odia, Tamil, Bengali. The labels are plain text in the HTML, so this needs no JavaScript at all and is genuinely valuable.
• Dark mode — the palette is CSS custom properties at the top of shared/kagaz.css, so this is mostly one prefers-color-scheme block.
• Drag to reorder — the page grids use arrow buttons so they work on a phone. Adding drag as an enhancement on larger screens would be nice.
• Fill PDF forms — pdf-lib already exposes form fields; the work is the interface.
• Automatic scan cropping — edge detection and perspective correction for photographed pages.

Harder, and more interesting

• More image formats in the compressor. It skips CMYK, JPEG 2000, JBIG2, CCITT fax and indexed-colour images rather than risk corrupting them. Start with CCITT fax — it is what most document scanners produce.
• Downsample soft masks. Transparency masks are separate greyscale images and are often large. CompressionStream makes re-deflating them possible.
• Search and redact. Find every occurrence of a name across a document rather than marking each by hand.
• Encryption. Password protecting a PDF means implementing the spec's crypto by hand. Possible, delicate, and the sort of thing that needs careful review.
• Offline install. A service worker to make Kagaz a proper installable PWA.

Please don't

• Add a framework, a bundler, or a package manager step.
• Add analytics, error reporting, or anything that phones home. Yes, even the privacy-respecting kind.
• Add anything from the roadmap's “never” list. Each one needs a server, and a server means uploading someone's document.
• Add a feature that silently degrades a file. If it cannot be processed safely, say so.

Reporting something without opening an issue

Not everyone who finds a bug here writes code, and a GitHub account should not be the price of telling me something is broken. The report page offers three routes — email, a post on X, or a prefilled GitHub issue — and fills in the browser details for you, since that is the part people cannot be expected to know.

Nothing on that page sends anything by itself. It builds a link and waits for you to press it.

Running the checks

npm run check

Three suites, and none of them need a single dependency — clone the repository and they run:

• npm run lint — the project's own rules. No network APIs, no persistent storage, no assets from another origin, every inline script parses, every tool page links to the report page.
• npm run verify — the site: dead links, metadata, mobile viewport, tap targets.
• npm test — the PDF engine against deliberately awful files: zero-byte, truncated, a JPEG renamed to .pdf, encrypted, two thousand pages, impossible page sizes, seven-step chains.

The linter is the one worth understanding. It does not check style — it checks that the promises on the front page still match the code. Add a fetch, or reach for localStorage, and the build fails telling you which claim you just broke. That is deliberate: those two lines are the entire product, and they are far too easy to erode by accident.

ESLint is configured but optional, and CI treats it as advisory. Style should never be the reason a contribution is turned away.

There is also an in-browser test page covering what Node cannot — the canvas codec, createImageBitmap, and rendering. Open it after any change to the shared helpers.