Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 62 additions & 0 deletions .github/workflows/prepare-release.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
# Start a release from GitHub (Actions → Prepare release → Run workflow): raises the version on a copy of dev, writes
# its CHANGELOG.md section (yarn release), and opens the pull request "Release v<version>" into dev. Review and edit the
# changelog there, merge it, then open dev → main as usual.
# RELEASE_TOKEN (a fine-grained token: this repo, Contents and Pull requests read and write) opens the pull request as
# you, so `check` and the preview run on it; GitHub doesn't start workflows for pull requests its own token opens.
name: Prepare release

on:
workflow_dispatch:
inputs:
kind:
description: 'patch (fixes), minor (new tools or features) or major (breaks how people use Ream)'
type: choice
options: [patch, minor, major]
default: minor

permissions:
contents: write
pull-requests: write

concurrency: prepare-release

jobs:
prepare:
runs-on: ubuntu-latest
timeout-minutes: 5
steps:
- uses: actions/checkout@v7
with:
ref: dev
fetch-depth: 0 # the tags and history the changelog is made from
token: ${{ secrets.RELEASE_TOKEN || github.token }}
- uses: actions/setup-node@v7
with:
node-version: 22 # scripts/release.ts is TypeScript, run directly; it needs only git
- name: Raise the version and write the changelog
id: release
run: |
node scripts/release.ts prepare "${{ inputs.kind }}"
echo "version=$(node scripts/release.ts version)" >> "$GITHUB_OUTPUT"
- name: Open the pull request into dev
env:
GH_TOKEN: ${{ secrets.RELEASE_TOKEN || github.token }}
VERSION: ${{ steps.release.outputs.version }}
run: |
branch="release/v$VERSION"
if git ls-remote --exit-code --heads origin "$branch" >/dev/null; then
echo "::error::$branch already exists: merge or delete its pull request first."
exit 1
fi
git config user.name 'github-actions[bot]'
git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
git switch -c "$branch"
git add package.json CHANGELOG.md
git commit -m "Release v$VERSION"
git push origin "$branch"
{
echo "Raises the version to $VERSION and adds its changelog section. Edit \`CHANGELOG.md\` here if the wording needs it; after merging, open the pull request from \`dev\` into \`main\` to release."
echo
node scripts/release.ts notes
} > body.md
gh pr create --base dev --head "$branch" --title "Release v$VERSION" --body-file body.md
6 changes: 4 additions & 2 deletions .github/workflows/web.yml
Original file line number Diff line number Diff line change
Expand Up @@ -127,10 +127,12 @@ jobs:
apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
command: pages deploy dist --project-name ream --branch main --commit-hash "${{ github.sha }}" --commit-message "v${{ steps.version.outputs.version }}"
- name: Tag the release and write its notes (the pull requests merged since the last one)
- name: Tag the release, with its CHANGELOG.md section as the notes
env:
GH_TOKEN: ${{ github.token }}
run: gh release create "v${{ steps.version.outputs.version }}" --repo "${{ github.repository }}" --target "${{ github.sha }}" --title "v${{ steps.version.outputs.version }}" --generate-notes
run: |
node repo/scripts/release.ts notes > notes.md
gh release create "v${{ steps.version.outputs.version }}" --repo "${{ github.repository }}" --target "${{ github.sha }}" --title "v${{ steps.version.outputs.version }}" --notes-file notes.md
# the image for self-hosting: Intel/AMD and ARM, tagged with the version and latest. The site is built once, on
# the runner's own platform; each platform's image only copies the files, so no emulation is needed.
- uses: docker/setup-buildx-action@v4
Expand Down
7 changes: 4 additions & 3 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -125,7 +125,7 @@ To add a tool: manifest, run, panel, three registry entries, and tests. Reuse th

## Platform seams

- Image codec: `codec()` / `setCodec()` in `image-core`. The app's worker sets `appCodec` (`image-core/browser`): our own decoders and encoders for PNG, JPEG, GIF and BMP, and the browser (OffscreenCanvas) only for WebP and for files ours refuse with `UnsupportedImage`. Tests call `setCodec(ownCodec)`; WebP can't be tested in Node. Decoders and encoders are pure and synchronous (`decodeJpeg`, `encodeJpeg`, `decodeGif`, `encodeGif`, `decodeBmp`, `encodeBmp`, `decodePng`, `encodePng`) and are used directly by tools that need more than one picture out (GIF frames, JPEG metadata segments).
- Image codec: `codec()` / `setCodec()` in `image-core`. The app's worker sets `appCodec` (`image-core/browser`): the browser's native codec (OffscreenCanvas) where ours is many times slower (JPEG read and written, opaque PNG written, WebP), ours for PNG reading, see-through PNG writing (a canvas premultiplies alpha, so lossless would stop being lossless), GIF and BMP, and ours again whenever the browser fails. Native JPEG reading keeps samples as stored (`colorSpaceConversion: 'none'`) like ours; the browser's JPEG adds an sRGB profile, so Compress image keeps only its JFIF header and puts the file's own segments back. Tests call `setCodec(ownCodec)`; the native paths can't be tested in Node and are checked in Chrome. Decoders and encoders are pure and synchronous (`decodeJpeg`, `encodeJpeg`, `decodeGif`, `encodeGif`, `decodeBmp`, `encodeBmp`, `decodePng`, `encodePng`) and are used directly where the codec can't do the job (GIF frames, palette PNGs (PDF to image keeps ours for its pages: small files for text), grey JPEGs). Compress PDF reads colour JPEGs through `Platform.decodeJpeg` (the browser's, as the renderer draws them) and the rest with ours.
- Text on pictures: the engine has no font code. Panels draw text to a PNG with the browser canvas (`bitmaps.ts`: `textMark`, `pictureMark`, `trimmedPng`; `meme/caption.ts`) and put it in the options; `run.ts` only decodes and places it with `overlay`. Keep it that way; a Node test passes a ready-made PNG. `blur-image` is the one panel that imports engine functions (`apply.ts`): it shows the same operations on a 1400 px copy so the preview matches the saved file.
- Flate: `deflate` / `inflate` in `core` use `CompressionStream` (async); `inflate` keeps its output when bytes follow the end of the data (a stream Length that counts a line break), which the platform stream rejects.
- Renderer `Platform`: `imageFromRGBA` and `decodeJpeg`. Tests pass fakes.
Expand All @@ -137,7 +137,7 @@ To add a tool: manifest, run, panel, three registry entries, and tests. Reuse th
- `ToolPage.tsx`: files | preview | options at `xl`; at `lg` the options stay on the right with the files above the preview; stacked below that, options before the preview. Options are always the right-hand region. Tools with their own surface (crop, sign) set `placesActions` and render the `actions` prop (run button, progress, errors) beside their controls. A finished run opens a modal `<dialog>` (download, keep editing, start over, use in another tool), not a card under the options. Locked PDFs open a password dialog and are replaced by a decrypted in-memory copy; the password is never stored.
- `previewController.ts` (pure, fake-timer tested) runs the same engine as the Run button: **600 ms debounce**, cancels stale runs, keeps the last result on screen. `ready` states have `stale` (outdated; Run never reuses a stale result) and `computing` (dim and "Updating..."). Do not make the UI react per keystroke.
- `previewWorker.ts` / `previewClient.ts`: one worker for inspect, render, unlock and metadata. The main thread never parses a PDF. Page canvases keep the old picture until the new one is ready (no flashing).
- Tool runs go through `runtime.ts` and `worker.ts` (progress, cancel, ZIP for several outputs). Limits: 50 files, 200 MB per file, 500 MB total.
- Tool runs go through `runtime.ts` and `worker.ts` (progress, cancel, ZIP for several outputs). Limits: 50 files, 200 MB per file, 500 MB total. One tool worker is kept warm between runs (`warmTool` loads the engine when a tool page opens; a run that starts while it's busy gets its own worker; cancelling terminates it). Each input carries a `key` (the same `File`, the same key), and `decodeFile` keeps decoded pictures under it (up to 512 MB, only for the current inputs), so a preview after an option change doesn't decode again. Run functions get a copy: they may change their pixels.
- Office files preview as PDFs: `previewClient` sends the kind with the bytes (`officeKind` in `usePdfInfo.ts`, kept free of engine code), `previewWorker` converts once with `officeToPdf` from `@ream/tools/office-preview` and then inspects and draws it like a PDF, adding an "approximate" warning. `isPreviewable` (PDF or Office) decides what `Preview` and `Thumb` show.
- Zoom: `ZoomBar`, `useZoom`, `zoomedWidth`, `renderWidthFor` and `useWidth` live in `@ream/ui` (`Zoom.tsx`). The Original/Result pane starts at fit width, with its `ZoomBar` (Fit width and Fit page) on the tabs row: `Preview` owns the zoom and `PdfView` reads it from `ZoomContext` and reports the size shown (no bar for pictures or text); panels that work on one page (Crop PDF, Sign PDF, Redact PDF, Fill PDF form) use `usePageZoom` (`tools/src/PageZoom.tsx`), which starts with the whole page in view and also offers Fit width. A zoom is a share of the actual size (a point is 4/3 CSS pixels), the page box is sized in CSS pixels inside a scrolling area, and everything drawn over it is positioned in fractions, so overlays scale with it. Pages are re-rendered at the shown size (in 200 px steps, at most 4000).
- Edit PDF (`tools/src/edit-pdf`):
Expand All @@ -156,7 +156,7 @@ To add a tool: manifest, run, panel, three registry entries, and tests. Reuse th
- Routes (`App.tsx`, hash based): `#/tool/<id>` the tool page, `#/tools`, `#/tools/pdf` and `#/tools/image` the tools home for a category (`Home.tsx`, `filterHref` in `TopBar.tsx`), `#/licence` and `#/notices` (`Legal.tsx`: the repo's `LICENSE` and `THIRD-PARTY-NOTICES.md`, imported `?raw` when the page opens) and `#/` (`Landing.tsx`); any other hash shows the landing page. The web-only pages share `Marketing.tsx` (nav, footer, `primary`/`secondary` link styles); app pages render `TopBar` (logo on the left; search and theme on the right; 1600 px like the pages) and `Breadcrumb` under it (All tools, the category, the tool; every level a link). The breadcrumb replaces visible headings on the tools home and tool pages (the `h1` is `sr-only`); on All tools the PDF tools and Image tools section titles link to their category. `focus` in `TopBar.tsx` is the shared focus ring.
- Tools home (`Home.tsx`, at most 1600 px wide) is drop-first: the `Dropzone` `bar` layout, and dropped files handed to a tool through `handoff.ts`, the same mechanism as "Use in another tool".
- Docker: `Dockerfile` builds the site with Node (on the build machine's platform) and serves it with `nginxinc/nginx-unprivileged` (non-root, port 8080). Its NGINX site is generated from `apps/web/public/_headers` by `scripts/nginx-conf.ts`, so change headers there only. The image build skips the typecheck (tests are left out by `.dockerignore`; CI typechecks anyway). `check` builds and runs it and checks the page, the headers, `sw.js` not being cached, the manifest's type, a 404 and a non-root user; the release pushes amd64 and arm64 images to `ghcr.io/deityhub/ream` and, with `DOCKERHUB_USERNAME`/`DOCKERHUB_TOKEN` set, `docker.io/<user>/ream`, tagged with the version and `latest`. Containers can't start in this Mac's Docker; test a server inside a throwaway `docker build` (start it in a `RUN`, query it with curl) or rely on CI.
- Versions: the root `package.json` `version` (semver, starting at 0.1.0) is the release version. A pull request into `main` must raise it (`yarn version patch|minor|major`; `node scripts/release.ts check` fails on a version already tagged or older); the merge deploys production, tags `v<version>` and creates a GitHub Release with generated notes. The version is in the footer (`__APP_VERSION__`, defined in `vite.config.ts`, declared in `version.d.ts`) and in the offline cache's name. `.github/workflows/deploy-version.yml` builds a released tag again and deploys it to production (rollback when the Cloudflare dashboard's can't).
- Versions: the root `package.json` `version` (semver, starting at 0.1.0) is the release version. A pull request into `main` must raise it and have its `CHANGELOG.md` section: `yarn release patch|minor|major` (`scripts/release.ts prepare`) writes both, the section from the pull requests merged since the last tag (first-parent merges of `dev`, their titles and links; earlier releases skipped), and `node scripts/release.ts check` fails on a version already tagged or older or one without a section. The merge deploys production, tags `v<version>` and creates a GitHub Release whose notes are that section (`release.ts notes`). `.github/workflows/prepare-release.yml` (Actions → Prepare release) runs `prepare` on `dev` and opens the "Release v<version>" pull request into `dev`, as the `RELEASE_TOKEN` secret so `check` and the preview run on it. The version is in the footer (`__APP_VERSION__`, defined in `vite.config.ts`, declared in `version.d.ts`) and in the offline cache's name. `.github/workflows/deploy-version.yml` builds a released tag again and deploys it to production (rollback when the Cloudflare dashboard's can't).
- Hosting: Cloudflare Pages, deployed by `.github/workflows/web.yml`: a pull request into `dev` runs `check` and gets a preview (its link is commented on the PR), a pull request into `main` runs `check`, a merge into `main` runs `check` and deploys production. Plain pushes run nothing. `check` is the status `.github/rulesets/protect-dev-main.json` requires (import it under Settings → Rules once the repo is public: rulesets aren't free on private repos). `apps/web/public/_headers` holds the security headers: the CSP allows only the site's own files, plus `api.fontsource.org` and `cdn.jsdelivr.net` in `connect-src` for Download free fonts, and no inline scripts or styles (`style-src 'self'`: React's `style` props are fine, `<style>` elements and `style="..."` strings are not). A new network host or inline style needs the policy changed, and the user asked first (the network rule above). Check with `wrangler pages dev` and a `securitypolicyviolation` listener.
- PWA: `manifest.webmanifest` and `icons/` in `apps/web/public` (PNGs from `apps/web/icons/icon.svg` by `node scripts/icons.ts`; square, full bleed, the mark inside the maskable safe zone). `apps/web/sw.js` is plain JS, outside `src`: the `serviceWorker` plugin in `vite.config.ts` writes it into `dist` after the build with every file's name (minus `.woff` fallbacks and the non-Latin Office fonts, which it keeps when first used) and a version hashed from their contents. The page is kept as `./` because Pages redirects `index.html` to `/`. Navigations are network first, everything else cache first. A new version waits until the user clicks Reload in `UpdateBar.tsx` (`pwa.ts` posts `switch`; the page reloads on `controllerchange` only after that, since the first worker's `clients.claim` changes the controller too). `pwa.ts` also keeps the `beforeinstallprompt` event for the landing page's Install Ream button. The worker is registered in production builds only: `yarn dev` has none. To test offline for real, serve the build with `wrangler pages dev`, let the worker fill its cache, then stop the server (CDP's offline emulation doesn't reach the worker's own requests).

Expand Down Expand Up @@ -195,6 +195,7 @@ To add a tool: manifest, run, panel, three registry entries, and tests. Reuse th
- Match the surrounding code: comment density, naming and idiom. Comments explain *why* (limits, gotchas, reasons), not what.
- Mark deliberate shortcuts that have a known ceiling with a `ponytail:` comment naming the ceiling and the upgrade path.
- Small files, one folder per tool, no abstractions without a second user, no config for values that never change.
- Pixel loops are hot (a phone photo is 12 to 50 million pixels): no allocation per pixel (`data.set(src.subarray(i, i + 4))`, array literals, destructuring), write the four bytes; walk memory in row order (a column at a time misses the cache); compare against the old code's output when speeding something up. Measure with a 12 MP photo and a few hundred pages before and after.
- Prefer the platform (CSS, native elements) over code, and the standard library over dependencies. Do not add runtime dependencies to engine packages. UI-only asset packages (fonts) are fine. Ream is MIT: anything shipped must be MIT-compatible (no GPL, AGPL or LGPL), and adding, removing or updating a runtime dependency means running `node scripts/notices.ts`. Code copied in by hand (like Lucide's shapes) keeps its notice in the file and gets an entry in `scripts/notices.ts`.
- Do not put personal data in URLs, logs or tests.

Expand Down
13 changes: 13 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
# Changelog

What changed in each release of Ream. `yarn release patch|minor|major` writes a section from the pull requests merged since the last release; edit it in the release pull request.

## 0.2.0 (2026-10-27)

- Faster tool processing ([#7](https://github.com/Deityhub/ream/pull/7))
- A changelog for each release, written by `yarn release` or the Prepare release workflow, and used as the release notes

## 0.1.0 (2026-10-27)

- The first release: Ream as a web app at ream.deityhub.com that installs as a PWA and works offline, with 37 tools for PDFs, images and Office files that run on your device.
- Docker image on GitHub Container Registry and Docker Hub, MIT licence and third-party notices.
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ Add tests with your change: engines and tools are tested in plain Node, and a to
## Branches and releases

- Branch from `dev` and open your pull request into `dev`. It runs `check` and gets a preview deploy, linked in a comment.
- A release is a pull request from `dev` into `main` that raises the version with `yarn version patch|minor|major`. Merging it deploys ream.deityhub.com, tags the version and publishes the release notes and Docker image. See [docs/deploy.md](docs/deploy.md).
- A release is a pull request from `dev` into `main` that raises the version and adds its `CHANGELOG.md` section, both written by `yarn release patch|minor|major`. Merging it deploys ream.deityhub.com, tags the version and publishes the release notes and Docker image. See [docs/deploy.md](docs/deploy.md).

## Ground rules

Expand Down
3 changes: 2 additions & 1 deletion apps/web/src/ToolPage.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ import { Button, Card, Dropzone, Icon } from '@ream/ui'
import { UserError, acceptsFile, formatBytes, type FileData, type Tool } from '@ream/core'
import { tools } from '@ream/tools'
import { panels, type PanelModule } from '@ream/tools/panels'
import { runTool, type Running } from './runtime'
import { runTool, warmTool, type Running } from './runtime'
import { download, toFile } from './download'
import { clearHandoff, peekHandoff, setHandoff } from './handoff'
import { FileMeta, Thumb } from './Thumb'
Expand Down Expand Up @@ -77,6 +77,7 @@ export function ToolPage({ tool }: { tool?: Tool }) {
useEffect(() => {
clearHandoff()
if (!tool || tool.status === 'soon' || !panels[tool.id]) return
warmTool(tool.id)
let live = true
panels[tool.id]().then((m) => {
if (!live) return
Expand Down
Loading
Loading