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
merge-pdf/index.html  one tool, one self-contained file
split-pdf/index.html
compress-pdf/index.html
pdf-to-jpg/index.html
certificate/index.html
shared/kagaz.css      every page shares this stylesheet
shared/kagaz.js       browser helpers: drop zones, downloads, canvas, messages
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

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 the four.
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

Roughly in order of how useful they would be, with the easiest first.

Good first issues

• JPG to PDF — the obvious missing counterpart to PDF to JPG. pdf-lib's embedJpg does the hard part. Needs page-size options and ordering.
• Rotate and reorder pages — a thumbnail grid with rotate and drag. The PDF side is two lines; the interface is the work.
• Add page numbers — position, starting number, font size, skip-first-page.
• Add a watermark — text or image, opacity, angle, every page or a range.
• Dark mode — the palette is all CSS custom properties at the top of shared/kagaz.css, so this is mostly a prefers-color-scheme block.
• Hindi, Odia, Tamil, Bengali interface strings — the labels are plain text in the HTML. A translation is a genuinely valuable contribution and needs no JavaScript at all.

Harder, and more interesting

• More image formats in the compressor. It currently skips CMYK, JPEG 2000, JBIG2, CCITT fax and indexed-colour images rather than risk corrupting them. Each one you can decode safely is a real improvement to a real tool. Start with CCITT fax — it is what most document scanners produce.
• Downsample soft masks. Transparency masks are separate greyscale images and are often large. They can be re-deflated with CompressionStream, which browsers now have.
• True redaction. Draw a box, and actually remove the text and image data underneath rather than covering it. Most free tools draw a black rectangle over selectable text, which is a genuine safety bug people have been burned by.
• Offline install. A service worker to make Kagaz a proper installable PWA that survives having no network at all.
• Use the content stream to size images. The compressor currently caps images against the page size. Reading the actual transformation matrix would let it downsample far more precisely.

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 PDF to Word. It cannot be done well in a browser, and shipping a bad version would undermine the one thing this site is for.
• Add a feature that silently degrades a file. If a document cannot be processed safely, Kagaz says so.

Running the tests

node tests/stress.mjs

This throws deliberately awful PDFs at shared/ops.js — zero-byte files, truncated files, a JPEG renamed to .pdf, encrypted documents, a two-thousand-page monster, pages of impossible sizes — and checks that each one fails cleanly with a message a human could act on, rather than crashing or producing a broken file.

There is also an in-browser test page that runs the same battery against the real browser code, including the image compression that Node cannot exercise. Open it after any change.