# Project pack: BentoPDF @ dafb6f8

Facts about **BentoPDF** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v2.md). This pack is pinned to one version and never changes after publication.

> BentoPDF is a collection of PDF tools (merge, split, edit, convert, sign, compress and more) that run completely inside your web browser using WebAssembly. There is no server processing your files, so it works offline once loaded and is easy to host as a static website.

## Version and source
- Repository: https://github.com/alam00000/bentopdf
- Pinned commit: `dafb6f8e188591bf5838728542d4cd234b8d4a75`. Use exactly this version.
- Fresh checkout: use the setup below in an empty folder. If you already have this exact source checked out, keep your branch and use the development command instead; do not clone again or reset local changes.
- Or download a zip: https://github.com/alam00000/bentopdf/archive/dafb6f8e188591bf5838728542d4cd234b8d4a75.zip
- Official docs: https://bentopdf.com/faq.html
- Live demo: https://bentopdf.com. The official site runs the tools in your browser. Files stay on your device.
- Licence: **AGPL-3.0-only**. Free to use and change. If other people use your changed version, including over a network (for example a website you host for them), you must offer them your source code under the same licence. Using it privately for yourself or your household has no extra obligations. BentoPDF is also sold under a separate commercial licence. The open version is AGPL.

## Running the pinned source
- Fresh pinned-source setup (skip clone and checkout in an existing worktree):

  ```sh
  git clone https://github.com/alam00000/bentopdf bespoke-bentopdf
  cd bespoke-bentopdf
  git checkout --detach dafb6f8e188591bf5838728542d4cd234b8d4a75
  # Prepare development requirements and local configuration first.
  npm install
  npm run dev
  ```

The commands below are a starting point from the reviewed source. Prepare the listed tools, local configuration and companion services before starting the app. These instructions have not yet been validated in participant sessions.

### Separate trial of the current release
This tries an upstream release, which may differ from the pinned source above. It does not run your source changes. Use only sample data and a separate data directory or volume. Check the upstream documentation before running it.

  ```sh
  docker run -d --name bentopdf -p 3000:8080 ghcr.io/alam00000/bentopdf-simple:latest
  # then open http://localhost:3000
  ```

- Needs: Docker for a trial, Node 22 for development
- Develop: `npm run dev`
- Test: `npm test`
- Check/lint: `npm run lint`
- Build: `npm run build`
- Stack: typescript, html, css (Vite, Tailwind, pdf-lib, PDF.js, WebAssembly). Difficulty for a non-developer with an AI: **easy**. A static front-end site built with Vite. Each tool is a page and a TypeScript module. No back end to run.

## Customisation points (settings → extend → code)
- **simple-mode** [settings]: A trimmed down version with fewer tools and no marketing pages. → `SIMPLE_MODE.md and the simple Docker image`
- **branding** [extend]: Your name, logo, colours and languages. → `public/ assets, index.html and the locale files`
- **new-tool-page** [code]: Add a new browser-based PDF tool. → `src/js/logic and the tool HTML pages`
- **static-hosting** [extend]: Host the built site on any static host. → `STATIC-HOSTING.md, chart/ for Kubernetes`

## Must keep working
- Client-side only processing. Never upload user files to a server.
- Content security headers generated at build time.
- Offline operation after first load.

## Staying updatable
Add tools as new modules and pages. Keep translations in the locale files so upgrades merge cleanly.

## Data, costs and safety
- Personal data: **no**. Stored in: Nothing is stored on a server. Files stay in your browser while you work. The site works offline after the first load, so private documents never leave your device.
- Verify the site address before opening confidential documents.
- Large files can use a lot of browser memory. Close other tabs.

---

# Customising BentoPDF

BentoPDF is a static site, so changes are quick: edit, refresh, build.

## How the code is laid out

| You want to change… | Look in |
|---|---|
| Tool pages | the HTML files at the root and in src/pages |
| Tool logic | src/js/ |
| Shared styles | src/css/ |
| Translations | public/locales/ |
| Build scripts | scripts/ |
| Docker and Kubernetes | Dockerfile, docker-compose.yml, chart/ |

## Use the gentlest change first

1. **Settings (no code):** the simple-mode image and Docker settings.
2. **Extend:** branding, translations and static hosting.
3. **Code:** new tools and logic modules.

## Recipes

- **New tool:** copy a small existing tool page and its logic module, rename them, then add the tool to the home page grid and the translation files.
- **New language:** copy `public/locales/en` and translate, then register the language.

## Running and checking your changes

- `npm run dev` and use each tool on a small PDF.
- `npm test` and `npm run lint`.
- Disconnect from the internet and confirm the tool still works.

## Pitfalls

- Don't add any network calls with file contents.
- Large WebAssembly bundles need correct headers when hosted.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/bentopdf/dafb6f8/r2/bespoke.yaml) · Hosting options: [hosting.md](https://handoff.bespokeai.software/p/bentopdf/dafb6f8/r2/hosting.md) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/bentopdf/dafb6f8/r2/SKILL.md)