diff --git a/.github/workflows/web.yml b/.github/workflows/web.yml
index ed7c8bf..7675f19 100644
--- a/.github/workflows/web.yml
+++ b/.github/workflows/web.yml
@@ -42,6 +42,7 @@ jobs:
- run: yarn test
- run: node scripts/notices.ts --check
- run: yarn build
+ - run: node scripts/seo-check.ts
- name: The Docker image builds, serves the app and sends the security headers
run: |
docker build -t ream:check .
@@ -56,6 +57,16 @@ jobs:
asset=$(docker exec ream sh -c 'ls /usr/share/nginx/html/assets | head -1')
headers "/assets/$asset" | grep -qi '^cache-control: public, max-age=31536000, immutable' || fail 'assets are not cached for good'
headers /no-such-file | grep -q '^HTTP/1.1 404' || fail 'a missing file is not a 404'
+ page() { curl -sS "http://localhost:8080$1"; }
+ headers /tools/pdf/compress-pdf/ | grep -q '^HTTP/1.1 200' || fail 'a tool page is not served'
+ page /tools/pdf/compress-pdf/ | grep -q '
Compress PDF' || fail 'the tool page has the wrong title'
+ page /tools/pdf/compress-pdf/ | grep -q 'rel="canonical" href="https://ream.deityhub.com/tools/pdf/compress-pdf/"' || fail 'the tool page has no canonical address'
+ headers /sitemap.xml | grep -q '^HTTP/1.1 200' || fail 'no sitemap'
+ page /sitemap.xml | grep -q '/tools/pdf/merge-pdf/' || fail 'the sitemap lacks a tool'
+ for gone in /tools/pdf/no-such-tool/ /tools/image/sign-pdf/ /tools/video/ /tool/compress-pdf/; do
+ headers "$gone" | grep -q '^HTTP/1.1 404' || fail "$gone is not a 404"
+ done
+ page /tools/pdf/no-such-tool/ | grep -q 'noindex' || fail 'the 404 page can be indexed'
[ "$(docker exec ream id -u)" != 0 ] || fail 'NGINX runs as root'
echo "image: $(docker image inspect ream:check --format '{{.Size}}') bytes"
- uses: actions/upload-artifact@v7
diff --git a/AGENTS.md b/AGENTS.md
index e472ce4..83a41fa 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -34,10 +34,12 @@ yarn typecheck # tsc -p tsconfig.json (covers packages/*/src, pack
node scripts/pdf.ts # dev CLI for pdf-core: info | merge | extract | remove | rotate | split | decrypt (-p )
node scripts/contrast.ts # WCAG contrast check of every colour token in both modes
node scripts/notices.ts # rewrite THIRD-PARTY-NOTICES.md (--check: fail if out of date); fails on GPL/AGPL/unknown licences
+node scripts/seo-check.ts # the built site as a crawler sees it (run `yarn build` first): every page's title, description, canonical, social card, JSON-LD, links and the sitemap; `check` runs it
+node scripts/og.ts # redraw apps/web/public/og.png (the social card) with headless Chrome
node scripts/render-compare.ts # renderer vs macOS CoreGraphics (sips), fails above recorded limits (embedded fonts: real system fonts read at run time, never committed)
```
-**Before reporting work as done, run `yarn typecheck`, `yarn test` and `yarn build`, all clean.** Run `node scripts/contrast.ts` after touching `packages/ui/src/theme.css`. Run `node scripts/render-compare.ts` after touching `packages/pdf-render`.
+**Before reporting work as done, run `yarn typecheck`, `yarn test` and `yarn build`, all clean** (and `node scripts/seo-check.ts` after touching routes, pages or tool text). Run `node scripts/contrast.ts` after touching `packages/ui/src/theme.css`. Run `node scripts/render-compare.ts` after touching `packages/pdf-render`.
## Repository layout
@@ -69,7 +71,7 @@ Each tool is a folder in `packages/tools/src//`:
Current tools: merge-pdf, split-pdf, images-to-pdf, watermark, page-numbers, crop-pdf, metadata, extract-images, compress-pdf, protect-pdf, unlock-pdf, sign-pdf, resize-image, convert-image, rotate-image, crop-image, merge-images, compress-image, animated-gif, image-metadata, watermark-image, blur-image, filters-image, meme, organize-pdf, bookmarks-pdf, repair-pdf, pdf-to-text, redact-pdf, fill-pdf-form, edit-pdf, pdf-to-image, pdf-to-word, pdf-to-excel, pdf-to-powerpoint, excel-to-pdf, powerpoint-to-pdf.
-To add a tool: manifest, run, panel, three registry entries, and tests. Reuse the helpers above.
+To add a tool: manifest, run, panel, three registry entries, its page text in `packages/tools/src/seo/` (`seo.test.ts` fails without it, and checks the lengths), and tests. Reuse the helpers above.
## PDF engine notes (`pdf-core`)
@@ -153,12 +155,13 @@ To add a tool: manifest, run, panel, three registry entries, and tests. Reuse th
- **Edit content mode:** the `content` host call gives the page's lines and pictures; picking one makes a `LineEditItem` or `PictureEditItem` (deleting marks it `deleted`, so it can be put back), and the Erase tool makes `EraseItem`s. `contentEdits` (`content.ts`) turns them into `editContent`'s input plus what is drawn over the page instead (a line its own font can't show, as a `TextItem` on its old baseline; a replacement picture). The run goes `editForm`, `editContent`, `decorate`.
- **What the editor shows:** the page is drawn *without* what was changed (`PdfPage hide`, the renderer's `hide`: letters and pictures whose middle is in a changed item's old box, the same test the saved file uses; erased areas as an even-odd clip), so there are no cover boxes. Everything is stacked in the saved file's order (`layerOf` in `geometry.ts`: the page's own content and changes, then added items in list order, then comments, then fields) with a z-index per item; page lines and pictures can be picked with Select in Add to pages too, under whatever was added over them. `stepOrder` / `canStep` move an item past the next one it overlaps in its layer.
- **Fonts:** the `fonts` host call (`documentFonts` in pdf-render) lists the PDF's families for `FontsPanel`, whose choices go in `o.fonts`. A changed line its own subset can't show is drawn in its family (`fallbackFont`), so the font book uses a font added for it or the look-alike; `viewFonts.loadFont` mirrors that in the editor.
-- Routes (`App.tsx`, hash based): `#/tool/` 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.
+- Routes (`routes.ts`, `router.tsx`, `App.tsx`): real paths with the History API, no router dependency. `/` the landing page, `/tools/` the tools home, `/tools/pdf/` and `/tools/image/` a category (`Home.tsx`, `filterHref` in `TopBar.tsx`), `/tools///` a tool (for example `/tools/pdf/sign-pdf/`; there is no `/tool/` route), `/licence/` and `/notices/` (`Legal.tsx`: the repo's `LICENSE` and `THIRD-PARTY-NOTICES.md`, imported `?raw` when the page opens); `parseRoute` checks the registry, so a tool that doesn't exist, or sits under the wrong kind, is `notFound` like any other unknown path and shows `NotFound` (the host answers 404 with `404.html` for the same addresses). The `tool` route carries the `Tool` itself; build links with `toolPath(tool)`. Paths end in a slash (what Pages and NGINX serve for `folder/index.html`); `parseRoute` accepts both. `parseRoute`/`pathOf`/`allRoutes` are pure and shared with the build. Links are `` (a real ``; a plain click uses `navigate`, so new tabs and crawlers work), never `location.hash`. Old `#/...` links are turned into paths before the first render (`upgradeLegacyUrl`). 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.
+- SEO (`seo.ts`, `seoHead.ts`, `seoPlugin.ts`, `ToolAbout.tsx`, `packages/tools/src/seo/`): the build (`seoPlugin`, after the bundle) writes one HTML file per route from the built `index.html` (`tool/merge-pdf/index.html`...): its own ``, description, canonical address, Open Graph and Twitter tags, JSON-LD (landing: `WebSite` + `WebApplication`; tools: `WebApplication` + `BreadcrumbList`; marked `data-seo`) and plain text inside `#root` (`main.seo`, styled in `index.css`) that the app replaces when it starts. It also writes `404.html` (needed: without it Cloudflare Pages treats the site as an SPA and answers every unknown address with 200) and `sitemap.xml` (indexable routes only: not the licence, notices or 404 pages). `pageSeo(route)` is the one source for all of it; `seoHead.applyHead` (lazy) keeps the head in step while moving around the app. A tool's words (`title` at most 60 characters ending in "| Ream", `description` 70 to 155, `intro`, three `points`, two or more `faq`) live in `packages/tools/src/seo/{pdf,convert,image}.ts` and also show under the tool (`ToolAbout`, lazy: four framed cells, shown only while no file is added). Write only what the tool really does and where it stops (no OCR, no certificate signatures, Office conversions are approximate). `SITE` (`https://ream.deityhub.com`) in `seo.ts` is every canonical address, also from a self-hosted copy. The social card is `apps/web/public/og.png`, made by `node scripts/og.ts`.
- 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//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 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` 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" 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, `
+
+.toString('base64')})
Ream
+The file toolkit that runs on your computer.
+PDFs, images and Office files. Nothing is uploaded.
`
+
+const chrome = await openChrome()
+try {
+ const page = await chrome.page()
+ // not page.view: below 768 px it would emulate a phone; this is a plain 1200 x 630 canvas
+ await page.send('Emulation.setDeviceMetricsOverride', { width: 1200, height: 630, deviceScaleFactor: 1, mobile: false })
+ await page.goto(`data:text/html;base64,${Buffer.from(html).toString('base64')}`, 500)
+ await page.screenshot(join(root, 'apps/web/public/og.png'))
+ console.log('wrote apps/web/public/og.png')
+} finally {
+ await chrome.close()
+}
diff --git a/scripts/seo-check.ts b/scripts/seo-check.ts
new file mode 100644
index 0000000..0cce616
--- /dev/null
+++ b/scripts/seo-check.ts
@@ -0,0 +1,115 @@
+// Checks the built site the way a crawler sees it: reads apps/web/dist (run `yarn build` first) and fails on anything that
+// would cost the site its place in search or its link previews. Shares no code with the build on purpose, so a mistake
+// in it can't pass its own check.
+// node scripts/seo-check.ts
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
+import { join, relative } from 'node:path'
+
+const dist = join(import.meta.dirname, '../apps/web/dist')
+const SITE = 'https://ream.deityhub.com'
+const problems: string[] = []
+const bad = (where: string, what: string) => problems.push(`${where}: ${what}`)
+
+const walk = (dir: string): string[] => readdirSync(dir).flatMap((n) => (statSync(join(dir, n)).isDirectory() ? walk(join(dir, n)) : [join(dir, n)]))
+const pages = walk(dist).filter((f) => f.endsWith('.html')).map((f) => relative(dist, f).split('\\').join('/'))
+/** the address a page is served at */
+const addressOf = (file: string) => (file === 'index.html' ? '/' : file === '404.html' ? '/404.html' : `/${file.slice(0, -'index.html'.length)}`)
+/** whether a path inside the site leads to a file (a folder with an index counts) */
+const exists = (path: string) => {
+ const p = path.split(/[?#]/)[0].replace(/^\//, '')
+ return existsSync(join(dist, p)) && statSync(join(dist, p)).isFile() ? true : existsSync(join(dist, p, 'index.html'))
+}
+
+const titles = new Map()
+let indexable = 0
+for (const file of pages) {
+ const html = readFileSync(join(dist, file), 'utf8')
+ const address = addressOf(file)
+ const at = (what: string) => bad(file, what)
+ const title = /([^<]*)<\/title>/.exec(html)?.[1]
+ const description = /')
+ else {
+ if (title.length > 65) at(`title is ${title.length} characters: ${title}`)
+ if (indexed) {
+ if (titles.has(title)) at(`same title as ${titles.get(title)}`)
+ titles.set(title, file)
+ }
+ }
+ if (!description) at('no meta description')
+ else if (indexed && (description.length < 70 || description.length > 160)) at(`description is ${description.length} characters`)
+ if (!robots) at('no robots meta')
+ if (file === '404.html' ? canonical !== undefined : canonical !== SITE + address) at(`canonical is ${canonical}, expected ${file === '404.html' ? 'none' : SITE + address}`)
+ if (!indexed && !robots?.startsWith('noindex')) at(`robots says "${robots}"`)
+ if (indexed && !/property="og:image" content="https:\/\/ream\.deityhub\.com\/og\.png"/.test(html)) at('no social card image')
+ if (!/name="twitter:card" content="summary_large_image"/.test(html)) at('no twitter card')
+
+ const root = /([\s\S]*?)<\/div>\s*<\/body>/.exec(html)?.[1] ?? ''
+ if (!root) at('nothing inside #root for a crawler without scripts')
+ const h1s = root.match(/
]/g)?.length ?? 0
+ if (h1s !== 1) at(`${h1s} in the page text`)
+ for (const m of root.matchAll(/href="([^"]+)"/g)) if (m[1].startsWith('/') && !exists(m[1])) at(`link to ${m[1]} leads nowhere`)
+
+ for (const m of html.matchAll(/