From 71d1da9ebf796f637756b9edbb73413687c2dcac Mon Sep 17 00:00:00 2001 From: Chizoba Jude Ojini Date: Thu, 29 Oct 2026 10:31:18 +0000 Subject: [PATCH 1/8] README: build and test status badge --- CONTRIBUTING.md | 1 + README.md | 2 ++ 2 files changed, 3 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8b68d10..0112afb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -30,6 +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. +- The badge at the top of the README is the last `check` run on `main` (typecheck, tests, notices, build and the Docker image test). If it is red, `main` is broken: fix that before releasing. - 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 diff --git a/README.md b/README.md index 68f6292..8fd0915 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ # Ream +[![Build and test](https://github.com/Deityhub/ream/actions/workflows/web.yml/badge.svg?branch=main)](https://github.com/Deityhub/ream/actions/workflows/web.yml) + **Ream is the file toolkit that runs on your computer.** Convert, edit, compress and secure PDFs, images and Office documents in your browser, with more kinds of file on the way. Your files are opened and processed on your own device and never reach a server. No account, no uploads, no trackers, and it works offline. **Use it at [ream.deityhub.com](https://ream.deityhub.com).** From 22f9227d38620f60dcda7de047196de333b1c70e Mon Sep 17 00:00:00 2001 From: Chizoba Jude Ojini Date: Thu, 29 Oct 2026 10:33:05 +0000 Subject: [PATCH 2/8] robots.txt: allow search, block AI training crawlers; noindex the pages.dev addresses --- AGENTS.md | 1 + apps/web/public/_headers | 7 +++ apps/web/public/robots.txt | 58 ++++++++++++++++++++++++ apps/web/src/crawlers.test.ts | 83 +++++++++++++++++++++++++++++++++++ docs/deploy.md | 8 ++++ scripts/nginx-conf.ts | 4 ++ 6 files changed, 161 insertions(+) create mode 100644 apps/web/public/robots.txt create mode 100644 apps/web/src/crawlers.test.ts diff --git a/AGENTS.md b/AGENTS.md index e472ce4..7ee21a2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -157,6 +157,7 @@ To add a tool: manifest, run, panel, three registry entries, and tests. Reuse th - 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). +- Crawlers: `apps/web/public/robots.txt` allows search engines and blocks AI training crawlers only (AI search and assistant fetchers and link-preview bots stay allowed, on purpose); `crawlers.test.ts` pins both lists, so adding a bot to one list means changing the test too. `_headers` ends with host rules (`https://:project.pages.dev/*`) that make the `pages.dev` addresses `noindex`; `scripts/nginx-conf.ts` skips rules for a whole address. - 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, ` +
+
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..64dd607 --- /dev/null +++ b/scripts/seo-check.ts @@ -0,0 +1,109 @@ +// 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 = /<meta name="description" content="([^"]*)"/.exec(html)?.[1] + const robots = /<meta data-seo name="robots" content="([^"]*)"/.exec(html)?.[1] + const canonical = /<link data-seo rel="canonical" href="([^"]*)"/.exec(html)?.[1] + const indexed = robots?.startsWith('index') ?? false + if (indexed) indexable++ + + if (!title) at('no <title>') + 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 = /<div id="root">([\s\S]*?)<\/div>\s*<\/body>/.exec(html)?.[1] ?? '' + if (!root) at('nothing inside #root for a crawler without scripts') + const h1s = root.match(/<h1[ >]/g)?.length ?? 0 + if (h1s !== 1) at(`${h1s} <h1> 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(/<script data-seo type="application\/ld\+json">([\s\S]*?)<\/script>/g)) { + try { + const j = JSON.parse(m[1]) + if (j['@context'] !== 'https://schema.org' || !j['@type']) at('structured data without @context or @type') + } catch { + at('structured data is not valid JSON') + } + } + // base is "/": a relative asset address breaks on every page below the first level + if (/(?:src|href)="\.\//.test(html)) at('a relative ./ address (the build base is /)') +} + +if (!pages.includes('index.html')) bad('dist', 'no index.html') +if (!pages.includes('404.html')) bad('dist', 'no 404.html: Cloudflare Pages would answer every unknown address with 200') + +// sitemap: every address is a page that exists, and every indexable page is in it +const sitemap = existsSync(join(dist, 'sitemap.xml')) ? readFileSync(join(dist, 'sitemap.xml'), 'utf8') : '' +const locs = [...sitemap.matchAll(/<loc>([^<]+)<\/loc>/g)].map((m) => m[1]) +if (!locs.length) bad('sitemap.xml', 'missing or empty') +for (const loc of locs) { + if (!loc.startsWith(`${SITE}/`)) bad('sitemap.xml', `${loc} is not on ${SITE}`) + else if (!exists(loc.slice(SITE.length))) bad('sitemap.xml', `${loc} has no file`) +} +if (locs.length !== indexable) bad('sitemap.xml', `${locs.length} addresses for ${indexable} indexable pages`) + +// social card: 1200 x 630 PNG +const og = join(dist, 'og.png') +if (!existsSync(og)) bad('og.png', 'missing') +else { + const b = readFileSync(og) + const [w, h] = [b.readUInt32BE(16), b.readUInt32BE(20)] + if (b.toString('latin1', 1, 4) !== 'PNG' || w !== 1200 || h !== 630) bad('og.png', `is ${w} x ${h}, expected a 1200 x 630 PNG`) +} + +// robots.txt itself is pinned by apps/web/src/crawlers.test.ts; here only that it points at the sitemap +if (existsSync(join(dist, 'robots.txt')) && !readFileSync(join(dist, 'robots.txt'), 'utf8').includes(`Sitemap: ${SITE}/sitemap.xml`)) bad('robots.txt', 'does not name the sitemap') + +// the service worker keeps pages under their folder's address, never as .../index.html (a redirect on Cloudflare Pages) or the 404 page +const sw = existsSync(join(dist, 'sw.js')) ? readFileSync(join(dist, 'sw.js'), 'utf8') : '' +const files = /const FILES = (\[[^\n]*\])/.exec(sw)?.[1] +if (!files) bad('sw.js', 'no file list') +else { + const kept: string[] = JSON.parse(files) + for (const f of kept) if (f.endsWith('index.html') || f === '404.html' || f === 'robots.txt' || f === 'sitemap.xml') bad('sw.js', `keeps ${f}`) + if (!kept.includes('./') || !kept.includes('tool/compress-pdf/')) bad('sw.js', 'does not keep the first page and the tool pages') +} + +if (problems.length) { + console.error(`${problems.length} problem${problems.length === 1 ? '' : 's'} in the built site:\n- ${problems.join('\n- ')}`) + process.exit(1) +} +console.log(`${pages.length} pages, ${locs.length} in the sitemap, all fine.`) From e23c24a8a946ad4f35b132405bf1a675de42875b Mon Sep 17 00:00:00 2001 From: Chizoba Jude Ojini <judoc96@gmail.com> Date: Thu, 29 Oct 2026 10:48:17 +0000 Subject: [PATCH 5/8] SEO: CI checks the pages, docs for routes, pages and search --- .github/workflows/web.yml | 9 +++++++++ AGENTS.md | 11 +++++++---- CONTRIBUTING.md | 3 +++ docs/deploy.md | 8 ++++++++ docs/design.md | 2 +- 5 files changed, 28 insertions(+), 5 deletions(-) diff --git a/.github/workflows/web.yml b/.github/workflows/web.yml index ed7c8bf..df4e5cc 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,14 @@ 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 /tool/compress-pdf/ | grep -q '^HTTP/1.1 200' || fail 'a tool page is not served' + page /tool/compress-pdf/ | grep -q '<title>Compress PDF' || fail 'the tool page has the wrong title' + page /tool/compress-pdf/ | grep -q 'rel="canonical" href="https://ream.deityhub.com/tool/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 '/tool/merge-pdf/' || fail 'the sitemap lacks a tool' + headers /tool/no-such-tool/ | grep -q '^HTTP/1.1 404' || fail 'an unknown tool is not a 404' + page /tool/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..f509595 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 <cmd> # dev CLI for pdf-core: info | merge | extract | remove | rotate | split | decrypt (-p <password>) 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/<tool-id>/`: 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/<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. +- 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`), `/tool/<id>/` a tool, `/licence/` and `/notices/` (`Legal.tsx`: the repo's `LICENSE` and `THIRD-PARTY-NOTICES.md`, imported `?raw` when the page opens); any other path shows `NotFound`. 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 `<Link to>` (a real `<a href>`; 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 `<title>`, 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). 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/<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 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). +- 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`, registered as `/sw.js` with scope `/`: the `serviceWorker` plugin in `vite.config.ts` writes it into `dist` after the build with every file's name (minus `.woff` fallbacks, the non-Latin Office fonts, which it keeps when first used, and what only crawlers or the 404 need) and a version hashed from their contents. Each page is kept under its folder's address (`./`, `tool/merge-pdf/`) because Pages redirects `.../index.html` to the folder. A navigation that fails offline gets its own kept page, else `./` (the app routes by address). Cache lookups use `ignoreVary` (a host sending `Vary: Origin` made every module script miss its kept copy). 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). ## Design system diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8b68d10..96c3e42 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -20,11 +20,14 @@ Use Yarn, not npm or pnpm. yarn typecheck yarn test yarn build +node scripts/seo-check.ts # the built site as a search engine sees it node scripts/notices.ts --check # after changing dependencies, run it without --check and commit the result ``` These are what the `check` job runs (plus building and testing the Docker image). Also run `node scripts/contrast.ts` after changing `packages/ui/src/theme.css`, and `node scripts/render-compare.ts` (macOS) after changing the PDF renderer. +A new tool needs its page text (title, description, intro, points and questions) in `packages/tools/src/seo/`: it is what search results and the page under the tool say, so write what the tool really does and where it stops. `yarn test` fails until it is there. + Add tests with your change: engines and tools are tested in plain Node, and a tool's tests call its `run()` directly. For anything with a screen, look at it in a browser at desktop and phone widths, in light and dark. ## Branches and releases diff --git a/docs/deploy.md b/docs/deploy.md index eec0ef4..c706f19 100644 --- a/docs/deploy.md +++ b/docs/deploy.md @@ -16,6 +16,14 @@ Ream is a progressive web app. `apps/web/public/manifest.webmanifest` and the ic - Limits: the first visit needs a connection; Firefox works offline but can't install sites as apps on the desktop; the browser can clear the saved app when the device is short of space (it is then downloaded again on the next visit). Checked in Chrome only. +## Addresses and search + +Every page has a real address: `/`, `/tools/`, `/tools/pdf/`, `/tools/image/`, `/tool/<id>/` (and `/licence/`, `/notices/`). The build writes a file for each (`tool/merge-pdf/index.html`), with its own title, description, canonical address, social card tags and structured data in the head and plain text inside the page, so search engines and link previews don't depend on running the app. `404.html` is also built, and **must stay**: without it Cloudflare Pages treats the site as a single-page app and answers every unknown address with 200 (a "soft 404" that search engines distrust). `sitemap.xml` lists every page worth finding. `node scripts/seo-check.ts` checks all of it on the built site, and `check` runs it. The Docker image gets the same files, with NGINX answering unknown addresses with `404.html`. + +Old links with a `#/` (`/#/tool/merge-pdf`) still work: the app turns them into the new addresses when the page opens. + +After a release, once: add `ream.deityhub.com` in [Google Search Console](https://search.google.com/search-console) (a DNS TXT record in Cloudflare proves you own it), submit `https://ream.deityhub.com/sitemap.xml`, and do the same in [Bing Webmaster Tools](https://www.bing.com/webmasters), which also feeds DuckDuckGo and others. Pages usually appear in search within days to weeks; Search Console shows which are indexed and why one isn't. The social card is `apps/web/public/og.png` (`node scripts/og.ts` redraws it). + ## Releases and versions The release version is the root `package.json` `version` (semantic versioning: `major.minor.patch`). diff --git a/docs/design.md b/docs/design.md index ab9e641..0036773 100644 --- a/docs/design.md +++ b/docs/design.md @@ -6,5 +6,5 @@ - **Fonts**: Barlow Condensed for headings and buttons over Barlow for text, bundled through `@fontsource/barlow-condensed` and `@fontsource/barlow` so they work offline (Industry's stylesheet loads them from Google Fonts; Ream doesn't). Numbers use tabular figures. Text watermarks on images (Watermark image) are drawn in Barlow. - **Icons**: Lucide's shapes at stroke 1.5, copied into `packages/ui/src/Icon.tsx` (ISC licence, no dependency). Whiteout, highlight and redact have no Lucide match and are drawn for Ream. - **Logo**: one sheet cut on a diagonal and slid apart (split and merge). `Logo` in `packages/ui` follows the theme; `apps/web/public/favicon.svg` (in the steel colours) is the static version; `apps/web/icons/icon.svg` (the mark on the steel accent, square) is the source of the app icons. -- **Pages**: `#/` is the landing page, `#/tools` the tools home. +- **Pages**: `/` is the landing page, `/tools/` the tools home, `/tools/pdf/` and `/tools/image/` the categories, `/tool/<id>/` a tool. Every page has its own address, title and description, so search engines and link previews can tell them apart. - Not done: page thumbnails strip in the tool page (waits for M3 tools whose output keeps one page per input page), command palette. The design's network monitor, recent-files list, save-to folder and "Show in folder" were left out: Ream has none of them. From f08b76b0c9ffb9143cb0fde05da90606f2087fe3 Mon Sep 17 00:00:00 2001 From: Chizoba Jude Ojini <judoc96@gmail.com> Date: Thu, 29 Oct 2026 11:35:16 +0000 Subject: [PATCH 6/8] Tool pages: the about text in four framed cells, hidden once a file is added --- AGENTS.md | 2 +- apps/web/src/ToolAbout.tsx | 73 +++++++++++++++++++------------------- apps/web/src/ToolPage.tsx | 9 +++-- 3 files changed, 44 insertions(+), 40 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index f509595..0cb5e61 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -156,7 +156,7 @@ To add a tool: manifest, run, panel, three registry entries, its page text in `p - **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 (`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`), `/tool/<id>/` a tool, `/licence/` and `/notices/` (`Legal.tsx`: the repo's `LICENSE` and `THIRD-PARTY-NOTICES.md`, imported `?raw` when the page opens); any other path shows `NotFound`. 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 `<Link to>` (a real `<a href>`; 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 `<title>`, 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). 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`. +- 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 `<title>`, 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/<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 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). diff --git a/apps/web/src/ToolAbout.tsx b/apps/web/src/ToolAbout.tsx index 06d51d1..0f8ee5e 100644 --- a/apps/web/src/ToolAbout.tsx +++ b/apps/web/src/ToolAbout.tsx @@ -5,46 +5,47 @@ import { focus } from './TopBar' import { toolPath } from './routes' import { relatedTools } from './seo' -/** the words of a tool's page, under the tool: what it does, what to know, and where to go next (the same text the page's file holds for crawlers) */ +const cell = 'blueprint flex flex-col gap-3 border border-line p-6' + +/** + * The words of a tool's page, under the empty tool: four framed cells (what it does, what you can do, questions, more + * tools). The same text the page's file holds for crawlers. Shown only until a file is added: it is no help while editing. + */ export function ToolAbout({ tool }: { tool: Tool }) { const s = seoOf(tool) if (!s.points.length && !s.faq.length) return null const more = relatedTools(tool) return ( - <section aria-labelledby="about-tool" className="mt-16 max-w-[70ch] border-t border-line pt-8"> - <h2 id="about-tool" className="text-3xl uppercase">About {tool.title}</h2> - <p className="mt-4 text-[15px] leading-relaxed text-muted">{s.intro}</p> - {s.points.length > 0 && ( - <> - <h3 className="mt-8 text-xl uppercase">What you can do</h3> - <ul className="mt-2 list-disc space-y-1 pl-5 text-[15px] leading-relaxed text-muted"> - {s.points.map((p) => <li key={p}>{p}</li>)} - </ul> - </> - )} - {s.faq.length > 0 && ( - <> - <h3 className="mt-8 text-xl uppercase">Questions</h3> - <dl className="mt-2 space-y-4 text-[15px] leading-relaxed"> - {s.faq.map(([q, a]) => ( - <div key={q}> - <dt className="font-semibold">{q}</dt> - <dd className="text-muted">{a}</dd> - </div> - ))} - </dl> - </> - )} - {more.length > 0 && ( - <> - <h3 className="mt-8 text-xl uppercase">More {tool.category === 'pdf' ? 'PDF' : 'image'} tools</h3> - <ul className="mt-2 flex flex-wrap gap-x-5 gap-y-1 text-[15px]"> - {more.map((t) => ( - <li key={t.id}><Link to={toolPath(t.id)} className={`text-accent-ink underline ${focus}`}>{t.title}</Link></li> - ))} - </ul> - </> - )} - </section> + <div className="mt-20 grid gap-6 md:grid-cols-2"> + <section aria-labelledby="about-tool" className={cell}> + <h2 id="about-tool" className="text-2xl uppercase">About {tool.title}</h2> + <p className="text-[15px] leading-relaxed text-muted">{s.intro}</p> + </section> + <section aria-labelledby="about-points" className={cell}> + <h2 id="about-points" className="text-2xl uppercase">What you can do</h2> + <ul className="list-disc space-y-1.5 pl-5 text-[15px] leading-relaxed text-muted"> + {s.points.map((p) => <li key={p}>{p}</li>)} + </ul> + </section> + <section aria-labelledby="about-faq" className={cell}> + <h2 id="about-faq" className="text-2xl uppercase">Questions</h2> + <dl className="space-y-4 text-[15px] leading-relaxed"> + {s.faq.map(([q, a]) => ( + <div key={q}> + <dt className="font-semibold">{q}</dt> + <dd className="text-muted">{a}</dd> + </div> + ))} + </dl> + </section> + <section aria-labelledby="about-more" className={cell}> + <h2 id="about-more" className="text-2xl uppercase">More {tool.category === 'pdf' ? 'PDF' : 'image'} tools</h2> + <ul className="flex flex-wrap gap-x-5 gap-y-2 text-[15px]"> + {more.map((t) => ( + <li key={t.id}><Link to={toolPath(t.id)} className={`text-accent-ink underline ${focus}`}>{t.title}</Link></li> + ))} + </ul> + </section> + </div> ) } diff --git a/apps/web/src/ToolPage.tsx b/apps/web/src/ToolPage.tsx index 54419c2..804686c 100644 --- a/apps/web/src/ToolPage.tsx +++ b/apps/web/src/ToolPage.tsx @@ -279,9 +279,12 @@ export function ToolPage({ tool }: { tool?: Tool }) { </aside> )} </div> - <Suspense fallback={null}> - <ToolAbout tool={tool} /> - </Suspense> + {/* about the tool: for a visitor who hasn't started; once there are files it is out of the way */} + {empty && ( + <Suspense fallback={null}> + <ToolAbout tool={tool} /> + </Suspense> + )} </main> {state.kind === 'done' && <ResultDialog tool={tool} outputs={state.outputs} onClose={() => setState({ kind: 'idle' })} onReset={() => changeFiles([])} />} {asking && ( From 2159a6f6a5556c046ae76971babeed21b1eedd43 Mon Sep 17 00:00:00 2001 From: Chizoba Jude Ojini <judoc96@gmail.com> Date: Thu, 29 Oct 2026 12:44:25 +0000 Subject: [PATCH 7/8] Tools live at /tools/<kind>/<id>/; a missing tool or the wrong kind is the not-found page --- .github/workflows/web.yml | 14 +++++++------ AGENTS.md | 2 +- apps/web/src/App.tsx | 3 +-- apps/web/src/Home.tsx | 4 ++-- apps/web/src/ToolAbout.tsx | 2 +- apps/web/src/ToolPage.tsx | 18 +++-------------- apps/web/src/TopBar.tsx | 2 +- apps/web/src/routes.test.ts | 36 +++++++++++++++++++++++++-------- apps/web/src/routes.ts | 31 ++++++++++++++++++++-------- apps/web/src/seo.test.ts | 20 ++++++++++-------- apps/web/src/seo.ts | 10 ++++----- docs/deploy.md | 4 ++-- docs/design.md | 2 +- packages/tools/src/seo/types.ts | 2 +- scripts/seo-check.ts | 8 +++++++- 15 files changed, 96 insertions(+), 62 deletions(-) diff --git a/.github/workflows/web.yml b/.github/workflows/web.yml index df4e5cc..7675f19 100644 --- a/.github/workflows/web.yml +++ b/.github/workflows/web.yml @@ -58,13 +58,15 @@ jobs: 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 /tool/compress-pdf/ | grep -q '^HTTP/1.1 200' || fail 'a tool page is not served' - page /tool/compress-pdf/ | grep -q '<title>Compress PDF' || fail 'the tool page has the wrong title' - page /tool/compress-pdf/ | grep -q 'rel="canonical" href="https://ream.deityhub.com/tool/compress-pdf/"' || fail 'the tool page has no canonical address' + 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 '<title>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 '/tool/merge-pdf/' || fail 'the sitemap lacks a tool' - headers /tool/no-such-tool/ | grep -q '^HTTP/1.1 404' || fail 'an unknown tool is not a 404' - page /tool/no-such-tool/ | grep -q 'noindex' || fail 'the 404 page can be indexed' + 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 0cb5e61..83a41fa 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -155,7 +155,7 @@ To add a tool: manifest, run, panel, three registry entries, its page text in `p - **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 (`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`), `/tool/<id>/` a tool, `/licence/` and `/notices/` (`Legal.tsx`: the repo's `LICENSE` and `THIRD-PARTY-NOTICES.md`, imported `?raw` when the page opens); any other path shows `NotFound`. 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 `<Link to>` (a real `<a href>`; 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. +- 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/<kind>/<id>/` 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 `<Link to>` (a real `<a href>`; 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 `<title>`, 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/<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. diff --git a/apps/web/src/App.tsx b/apps/web/src/App.tsx index 8e73b89..ab612c6 100644 --- a/apps/web/src/App.tsx +++ b/apps/web/src/App.tsx @@ -1,5 +1,4 @@ import { useEffect } from 'react' -import { findTool } from '@ream/tools' import { usePath } from './router' import { parseRoute } from './routes' import { Home } from './Home' @@ -24,7 +23,7 @@ export function App() { }, [path]) switch (route.page) { case 'tool': - return <ToolPage key={route.id} tool={findTool(route.id)} /> + return <ToolPage key={route.tool.id} tool={route.tool} /> case 'tools': return <Home key={route.cat} cat={route.cat} /> case 'licence': diff --git a/apps/web/src/Home.tsx b/apps/web/src/Home.tsx index 6fc7369..74fa661 100644 --- a/apps/web/src/Home.tsx +++ b/apps/web/src/Home.tsx @@ -33,7 +33,7 @@ export function Home({ cat }: { cat: Filter }) { const open = (t: Tool) => { setHandoff(dropped) - navigate(toolPath(t.id)) + navigate(toolPath(t)) } return ( @@ -115,5 +115,5 @@ export function ToolCard({ tool: t, suggested, dim, onOpen }: { tool: Tool; sugg const box = `blueprint flex h-full w-full flex-col gap-1.5 border p-4 text-left transition-colors duration-150 ${edge}` if (dim) return <div aria-disabled="true" className={`${box} opacity-50`}>{body}</div> if (onOpen) return <button onClick={onOpen} className={`${box} ${focus}`}>{body}</button> - return <Link to={toolPath(t.id)} className={`${box} ${focus}`}>{body}</Link> + return <Link to={toolPath(t)} className={`${box} ${focus}`}>{body}</Link> } diff --git a/apps/web/src/ToolAbout.tsx b/apps/web/src/ToolAbout.tsx index 0f8ee5e..e0ef499 100644 --- a/apps/web/src/ToolAbout.tsx +++ b/apps/web/src/ToolAbout.tsx @@ -42,7 +42,7 @@ export function ToolAbout({ tool }: { tool: Tool }) { <h2 id="about-more" className="text-2xl uppercase">More {tool.category === 'pdf' ? 'PDF' : 'image'} tools</h2> <ul className="flex flex-wrap gap-x-5 gap-y-2 text-[15px]"> {more.map((t) => ( - <li key={t.id}><Link to={toolPath(t.id)} className={`text-accent-ink underline ${focus}`}>{t.title}</Link></li> + <li key={t.id}><Link to={toolPath(t)} className={`text-accent-ink underline ${focus}`}>{t.title}</Link></li> ))} </ul> </section> diff --git a/apps/web/src/ToolPage.tsx b/apps/web/src/ToolPage.tsx index 804686c..4529dcb 100644 --- a/apps/web/src/ToolPage.tsx +++ b/apps/web/src/ToolPage.tsx @@ -15,7 +15,7 @@ import { SizeEstimate } from './SizeEstimate' import { LazyPdfPage, PdfPage } from './PdfPage' import { usePreview } from './usePreview' import { Breadcrumb, TopBar, focus } from './TopBar' -import { Link, navigate } from './router' +import { navigate } from './router' import { toolPath } from './routes' // the page's words (what it does, questions, more tools) load after the tool itself @@ -50,7 +50,7 @@ const pdfHost = { const GENERIC = 'Something went wrong while processing your files. Nothing was uploaded. Try again, or try a different file.' -export function ToolPage({ tool }: { tool?: Tool }) { +export function ToolPage({ tool }: { tool: Tool }) { const [files, setFiles] = useState<File[]>(() => (tool ? peekHandoff().filter((f) => acceptsFile(f, tool.accept)) : [])) const [state, setState] = useState<State>({ kind: 'idle' }) const [panel, setPanel] = useState<PanelModule | null>(null) @@ -95,18 +95,6 @@ export function ToolPage({ tool }: { tool?: Tool }) { } }, [tool]) - if (!tool) { - return ( - <> - <TopBar /> - <main className="mx-auto max-w-[1600px] px-4 py-6 sm:px-8"> - <Breadcrumb cat="all" /> - <p className="text-[15px]">That tool doesn't exist. <Link to="/tools/" className={`font-semibold text-accent-ink underline ${focus}`}>See all tools</Link>.</p> - </main> - </> - ) - } - const changeFiles = (next: File[]) => { setFiles(next) setActive((a) => Math.min(a, Math.max(0, next.length - 1))) @@ -391,7 +379,7 @@ function ResultDialog({ tool, outputs, onClose, onReset }: { tool: Tool; outputs key={t.id} onClick={() => { setHandoff(outputs.map(toFile)) - navigate(toolPath(t.id)) + navigate(toolPath(t)) }} className="border border-line px-2.5 py-1 hover:bg-ink/7 focus-visible:outline-2 focus-visible:outline-accent" > diff --git a/apps/web/src/TopBar.tsx b/apps/web/src/TopBar.tsx index d30befa..260a396 100644 --- a/apps/web/src/TopBar.tsx +++ b/apps/web/src/TopBar.tsx @@ -30,7 +30,7 @@ export function TopBar({ children }: { children?: ReactNode }) { export function Breadcrumb({ cat, tool, className = 'mb-6' }: { cat: Filter; tool?: Tool; className?: string }) { const levels = [{ href: filterHref('all'), label: filterName.all }] if (cat !== 'all') levels.push({ href: filterHref(cat), label: filterName[cat] }) - if (tool) levels.push({ href: toolPath(tool.id), label: tool.title }) + if (tool) levels.push({ href: toolPath(tool), label: tool.title }) return ( <nav aria-label="Breadcrumb" className={className}> <ol className="flex min-w-0 flex-wrap items-center gap-2.5 text-[13px] font-semibold tracking-widest text-muted uppercase"> diff --git a/apps/web/src/routes.test.ts b/apps/web/src/routes.test.ts index bce2e3a..47f46cb 100644 --- a/apps/web/src/routes.test.ts +++ b/apps/web/src/routes.test.ts @@ -1,36 +1,55 @@ import { describe, expect, test } from 'vitest' -import { tools } from '@ream/tools' +import { findTool, tools } from '@ream/tools' import { allRoutes, legacyPath, parseRoute, pathOf, toolPath, type Route } from './routes' +const tool = (id: string) => findTool(id)! + describe('routes', () => { test('every page round-trips through its path, which ends in a slash', () => { - const routes: Route[] = [{ page: 'landing' }, { page: 'tools', cat: 'all' }, { page: 'tools', cat: 'pdf' }, { page: 'tools', cat: 'image' }, { page: 'tool', id: 'merge-pdf' }, { page: 'licence' }, { page: 'notices' }] + const routes: Route[] = [{ page: 'landing' }, { page: 'tools', cat: 'all' }, { page: 'tools', cat: 'pdf' }, { page: 'tools', cat: 'image' }, { page: 'tool', tool: tool('merge-pdf') }, { page: 'licence' }, { page: 'notices' }] for (const r of routes) { const path = pathOf(r) expect(parseRoute(path)).toEqual(r) expect(path.endsWith('/')).toBe(true) } - expect(toolPath('compress-pdf')).toBe('/tool/compress-pdf/') + }) + + test('a tool lives under its own kind, never under /tool/', () => { + expect(toolPath(tool('sign-pdf'))).toBe('/tools/pdf/sign-pdf/') + expect(toolPath(tool('resize-image'))).toBe('/tools/image/resize-image/') + for (const t of tools) { + expect(toolPath(t)).toBe(`/tools/${t.category}/${t.id}/`) + expect(parseRoute(toolPath(t))).toEqual({ page: 'tool', tool: t }) + } }) test('a path with or without its closing slash, a query or a hash is the same page', () => { - for (const p of ['/tool/merge-pdf', '/tool/merge-pdf/', '/tool/merge-pdf?x=1', '/tool/merge-pdf/#top']) expect(parseRoute(p)).toEqual({ page: 'tool', id: 'merge-pdf' }) + for (const p of ['/tools/pdf/merge-pdf', '/tools/pdf/merge-pdf/', '/tools/pdf/merge-pdf?x=1', '/tools/pdf/merge-pdf/#top']) expect(parseRoute(p)).toEqual({ page: 'tool', tool: tool('merge-pdf') }) expect(parseRoute('')).toEqual({ page: 'landing' }) expect(parseRoute('//')).toEqual({ page: 'landing' }) }) - test('addresses that are not pages are not found', () => { - for (const p of ['/tools/video/', '/tool/', '/tool/a/b/', '/tool/not valid/', '/licence/x/', '/nothing/', '/index.html', '/404.html', '/sw.js']) { + test('addresses that are not pages are not found, a missing tool and a tool under the wrong kind included', () => { + for (const p of [ + '/tools/pdf/no-such-tool/', // no such tool + '/tools/image/sign-pdf/', // a PDF tool under images + '/tools/pdf/resize-image/', // an image tool under PDFs + '/tools/video/', '/tools/video/merge-pdf/', '/tools/pdf/merge-pdf/extra/', + '/tool/merge-pdf/', '/tool/', '/tool/no-such-tool/', // the old shape is gone + '/licence/x/', '/nothing/', '/index.html', '/404.html', '/sw.js', '/tools/toString/', + ]) { expect(parseRoute(p), p).toEqual({ page: 'notFound' }) } }) - test('old hash links become paths, other hashes are left alone', () => { - expect(legacyPath('#/tool/merge-pdf')).toBe('/tool/merge-pdf/') + test('old hash links become the new paths, other hashes are left alone', () => { + expect(legacyPath('#/tool/merge-pdf')).toBe('/tools/pdf/merge-pdf/') + expect(legacyPath('#/tool/resize-image')).toBe('/tools/image/resize-image/') expect(legacyPath('#/tools')).toBe('/tools/') expect(legacyPath('#/tools/image')).toBe('/tools/image/') expect(legacyPath('#/licence')).toBe('/licence/') expect(legacyPath('#/')).toBe('/') + expect(parseRoute(legacyPath('#/tool/no-such-tool')!).page).toBe('notFound') // an old link to a tool that doesn't exist expect(legacyPath('#/nothing')).toBeNull() expect(legacyPath('#section')).toBeNull() expect(legacyPath('')).toBeNull() @@ -43,5 +62,6 @@ describe('routes', () => { expect(new Set(all.map(pathOf)).size).toBe(all.length) expect(all.some((r) => r.page === 'notFound')).toBe(false) expect(all.length).toBe(ready.length + 6) + for (const r of all) expect(parseRoute(pathOf(r)).page, pathOf(r)).toBe(r.page) // every file the build writes is a page the app knows }) }) diff --git a/apps/web/src/routes.ts b/apps/web/src/routes.ts index 2281683..c290792 100644 --- a/apps/web/src/routes.ts +++ b/apps/web/src/routes.ts @@ -1,12 +1,20 @@ // The app's pages and their URLs. Plain functions, no React or DOM: the router, the build (which writes a page for // each route) and the tests all use them. Paths end in a slash, which is how Cloudflare Pages and NGINX serve // `folder/index.html`, so a reload never goes through a redirect. +// +// / the landing page +// /tools/ all tools /tools/pdf/ /tools/image/ one kind of tool +// /tools/pdf/sign-pdf/ a tool, always under its own kind +// /licence/ /notices/ the legal texts +// +// An address that is none of these is `notFound`, and so is a tool that doesn't exist or is under the wrong kind. import type { Category, Tool } from '@ream/core' +import { findTool } from '@ream/tools' export type Route = | { page: 'landing' } | { page: 'tools'; cat: 'all' | Category } - | { page: 'tool'; id: string } + | { page: 'tool'; tool: Tool } | { page: 'licence' } | { page: 'notices' } | { page: 'notFound' } @@ -14,18 +22,20 @@ export type Route = // a Record, so adding a Category without its page stops compiling const CATEGORY: Record<Category, true> = { pdf: true, image: true } export const categories = Object.keys(CATEGORY) as Category[] +const isCategory = (s: string): s is Category => Object.hasOwn(CATEGORY, s) /** the page a URL path shows; anything unknown is `notFound` */ export function parseRoute(path: string): Route { - const parts = path.split(/[?#]/)[0].split('/').filter(Boolean) - const [a, b, ...more] = parts + const [a, b, c, ...more] = path.split(/[?#]/)[0].split('/').filter(Boolean) if (more.length) return { page: 'notFound' } if (!a) return { page: 'landing' } if (a === 'tools') { if (!b) return { page: 'tools', cat: 'all' } - return b in CATEGORY ? { page: 'tools', cat: b as Category } : { page: 'notFound' } + if (!isCategory(b)) return { page: 'notFound' } + if (!c) return { page: 'tools', cat: b } + const tool = findTool(c) + return tool && tool.category === b ? { page: 'tool', tool } : { page: 'notFound' } } - if (a === 'tool') return b && /^[\w-]+$/.test(b) ? { page: 'tool', id: b } : { page: 'notFound' } if (!b && (a === 'licence' || a === 'notices')) return { page: a } return { page: 'notFound' } } @@ -38,7 +48,7 @@ export function pathOf(route: Route): string { case 'tools': return route.cat === 'all' ? '/tools/' : `/tools/${route.cat}/` case 'tool': - return `/tool/${route.id}/` + return toolPath(route.tool) case 'licence': return '/licence/' case 'notices': @@ -48,7 +58,7 @@ export function pathOf(route: Route): string { } } -export const toolPath = (id: string) => pathOf({ page: 'tool', id }) +export const toolPath = (tool: Pick<Tool, 'id' | 'category'>) => `/tools/${tool.category}/${tool.id}/` export const categoryPath = (cat: 'all' | Category) => pathOf({ page: 'tools', cat }) /** every page that has its own file in the build: the ones a visitor can reach, a tool still marked soon excepted */ @@ -57,7 +67,7 @@ export function allRoutes(tools: Tool[]): Route[] { { page: 'landing' }, { page: 'tools', cat: 'all' }, ...categories.map((cat): Route => ({ page: 'tools', cat })), - ...tools.filter((t) => t.status === 'ready').map((t): Route => ({ page: 'tool', id: t.id })), + ...tools.filter((t) => t.status === 'ready').map((tool): Route => ({ page: 'tool', tool })), { page: 'licence' }, { page: 'notices' }, ] @@ -66,6 +76,11 @@ export function allRoutes(tools: Tool[]): Route[] { /** the path an old hash link (`#/tool/merge-pdf`, from before the app had real URLs) stands for, or null for any other hash */ export function legacyPath(hash: string): string | null { if (!hash.startsWith('#/')) return null + const old = /^#\/tool\/([\w-]+)\/?$/.exec(hash) + if (old) { + const tool = findTool(old[1]) + return tool ? toolPath(tool) : `/tool/${old[1]}/` // a tool that doesn't exist: an address that isn't a page, so the not-found page shows + } const route = parseRoute(hash.slice(1)) return route.page === 'notFound' ? null : pathOf(route) } diff --git a/apps/web/src/seo.test.ts b/apps/web/src/seo.test.ts index 9b2763d..cc55a8a 100644 --- a/apps/web/src/seo.test.ts +++ b/apps/web/src/seo.test.ts @@ -1,7 +1,7 @@ import { describe, expect, test } from 'vitest' -import { tools } from '@ream/tools' +import { findTool, tools } from '@ream/tools' import { seoOf, toolSeo } from '@ream/tools/seo' -import { allRoutes, pathOf } from './routes' +import { allRoutes, parseRoute, pathOf } from './routes' import { SITE, headTags, pageSeo, sitemapXml } from './seo' const ready = tools.filter((t) => t.status === 'ready') @@ -65,24 +65,28 @@ describe('pages', () => { expect(new Set(urls).size).toBe(urls.length) expect(urls).toHaveLength(ready.length + 4) // the landing page, all tools and the two categories expect(urls).toContain(`${SITE}/`) - expect(urls).toContain(`${SITE}/tool/compress-pdf/`) + expect(urls).toContain(`${SITE}/tools/pdf/compress-pdf/`) + expect(urls).toContain(`${SITE}/tools/image/resize-image/`) + expect(urls.some((u) => u.includes('/tool/'))).toBe(false) expect(urls.every((u) => u.startsWith(`${SITE}/`) && u.endsWith('/'))).toBe(true) expect(xml).not.toMatch(/licence|notices|404/) }) test('licence, notices and not-found pages are kept out of search; a missing tool is a not-found page', () => { - for (const r of [{ page: 'licence' }, { page: 'notices' }, { page: 'notFound' }, { page: 'tool', id: 'no-such-tool' }] as const) { + const missing = parseRoute('/tools/pdf/no-such-tool/') + const soon = { page: 'tool', tool: { ...findTool('merge-pdf')!, status: 'soon' } } as const + for (const r of [{ page: 'licence' }, { page: 'notices' }, { page: 'notFound' }, missing, soon] as const) { expect(pageSeo(r, '1').index, r.page).toBe(false) expect(headTags(pageSeo(r, '1'))).toContain('noindex') } - expect(pageSeo({ page: 'tool', id: 'no-such-tool' }, '1').path).toBe('/404.html') + expect(pageSeo(missing, '1').path).toBe('/404.html') expect(headTags(pageSeo({ page: 'notFound' }, '1'))).not.toMatch(/canonical|og:url/) // no address of its own to declare }) test('the head names the page, points at its canonical address and carries structured data that parses', () => { - const tool = pageSeo({ page: 'tool', id: 'merge-pdf' }, '1') + const tool = pageSeo(parseRoute('/tools/pdf/merge-pdf/'), '1') const head = headTags(tool) - expect(head).toContain(`<link data-seo rel="canonical" href="${SITE}/tool/merge-pdf/" />`) + expect(head).toContain(`<link data-seo rel="canonical" href="${SITE}/tools/pdf/merge-pdf/" />`) expect(head).toContain('og:title') expect(head).toContain('twitter:card') expect(head).toContain(`${SITE}/og.png`) @@ -102,7 +106,7 @@ describe('pages', () => { test('the text inside the page links to every tool of its kind and has one heading', () => { const landing = pageSeo({ page: 'landing' }, '1').html - for (const t of ready) expect(landing).toContain(`href="/tool/${t.id}/"`) + for (const t of ready) expect(landing).toContain(`href="/tools/${t.category}/${t.id}/"`) for (const p of pages) expect(p.html.match(/<h1>/g), p.path).toHaveLength(1) }) }) diff --git a/apps/web/src/seo.ts b/apps/web/src/seo.ts index 53e6bca..6887e68 100644 --- a/apps/web/src/seo.ts +++ b/apps/web/src/seo.ts @@ -2,7 +2,7 @@ // text inside #root. One source for the build (which writes a file per route, see ../seoPlugin.ts) and for the app (which // keeps the head in step when you move between pages). Plain functions, no React or DOM. import type { Category, Tool } from '@ream/core' -import { findTool, tools } from '@ream/tools' +import { tools } from '@ream/tools' import { seoOf } from '@ream/tools/seo' import { categoryPath, toolPath, type Route, pathOf } from './routes' @@ -40,7 +40,7 @@ export const relatedTools = (tool: Tool) => ready.filter((t) => t.category === t const link = (path: string, text: string) => `<a href="${path}">${esc(text)}</a>` const list = (items: string[]) => `<ul>${items.map((i) => `<li>${i}</li>`).join('')}</ul>` -const toolLinks = (ts: Tool[]) => list(ts.map((t) => `${link(toolPath(t.id), t.title)}: ${esc(t.description)}`)) +const toolLinks = (ts: Tool[]) => list(ts.map((t) => `${link(toolPath(t), t.title)}: ${esc(t.description)}`)) const breadcrumb = (items: [name: string, path: string][]) => ({ '@context': 'https://schema.org', @@ -99,13 +99,13 @@ export function pageSeo(route: Route, version: string): PageSeo { description, path, index: true, - jsonLd: [breadcrumb(crumbs), { '@context': 'https://schema.org', '@type': 'ItemList', itemListElement: group.map((t, i) => ({ '@type': 'ListItem', position: i + 1, url: SITE + toolPath(t.id), name: t.title })) }], + jsonLd: [breadcrumb(crumbs), { '@context': 'https://schema.org', '@type': 'ItemList', itemListElement: group.map((t, i) => ({ '@type': 'ListItem', position: i + 1, url: SITE + toolPath(t), name: t.title })) }], html: `<main class="seo"><h1>${esc(name)}</h1><p>${esc(description)}</p>${toolLinks(group)}<p>${link('/', 'Back to Ream')}</p></main>`, } } case 'tool': { - const tool = findTool(route.id) - if (!tool || tool.status !== 'ready') return notFound('This tool does not exist') + const tool = route.tool + if (tool.status !== 'ready') return notFound('This tool is not ready') const s = seoOf(tool) const cat = CATEGORY_NAME[tool.category] return { diff --git a/docs/deploy.md b/docs/deploy.md index c706f19..98e9894 100644 --- a/docs/deploy.md +++ b/docs/deploy.md @@ -18,9 +18,9 @@ Ream is a progressive web app. `apps/web/public/manifest.webmanifest` and the ic ## Addresses and search -Every page has a real address: `/`, `/tools/`, `/tools/pdf/`, `/tools/image/`, `/tool/<id>/` (and `/licence/`, `/notices/`). The build writes a file for each (`tool/merge-pdf/index.html`), with its own title, description, canonical address, social card tags and structured data in the head and plain text inside the page, so search engines and link previews don't depend on running the app. `404.html` is also built, and **must stay**: without it Cloudflare Pages treats the site as a single-page app and answers every unknown address with 200 (a "soft 404" that search engines distrust). `sitemap.xml` lists every page worth finding. `node scripts/seo-check.ts` checks all of it on the built site, and `check` runs it. The Docker image gets the same files, with NGINX answering unknown addresses with `404.html`. +Every page has a real address: `/`, `/tools/`, `/tools/pdf/`, `/tools/image/`, `/tools/<kind>/<id>/` such as `/tools/pdf/sign-pdf/` (and `/licence/`, `/notices/`). A tool exists only under its own kind; anything else, a tool that doesn't exist or the wrong kind included, gets the 404 page. The build writes a file for each (`tool/merge-pdf/index.html`), with its own title, description, canonical address, social card tags and structured data in the head and plain text inside the page, so search engines and link previews don't depend on running the app. `404.html` is also built, and **must stay**: without it Cloudflare Pages treats the site as a single-page app and answers every unknown address with 200 (a "soft 404" that search engines distrust). `sitemap.xml` lists every page worth finding. `node scripts/seo-check.ts` checks all of it on the built site, and `check` runs it. The Docker image gets the same files, with NGINX answering unknown addresses with `404.html`. -Old links with a `#/` (`/#/tool/merge-pdf`) still work: the app turns them into the new addresses when the page opens. +Old links with a `#/` (`/#/tool/merge-pdf` becomes `/tools/pdf/merge-pdf/`) still work: the app turns them into the new addresses when the page opens. After a release, once: add `ream.deityhub.com` in [Google Search Console](https://search.google.com/search-console) (a DNS TXT record in Cloudflare proves you own it), submit `https://ream.deityhub.com/sitemap.xml`, and do the same in [Bing Webmaster Tools](https://www.bing.com/webmasters), which also feeds DuckDuckGo and others. Pages usually appear in search within days to weeks; Search Console shows which are indexed and why one isn't. The social card is `apps/web/public/og.png` (`node scripts/og.ts` redraws it). diff --git a/docs/design.md b/docs/design.md index 0036773..f423cf0 100644 --- a/docs/design.md +++ b/docs/design.md @@ -6,5 +6,5 @@ - **Fonts**: Barlow Condensed for headings and buttons over Barlow for text, bundled through `@fontsource/barlow-condensed` and `@fontsource/barlow` so they work offline (Industry's stylesheet loads them from Google Fonts; Ream doesn't). Numbers use tabular figures. Text watermarks on images (Watermark image) are drawn in Barlow. - **Icons**: Lucide's shapes at stroke 1.5, copied into `packages/ui/src/Icon.tsx` (ISC licence, no dependency). Whiteout, highlight and redact have no Lucide match and are drawn for Ream. - **Logo**: one sheet cut on a diagonal and slid apart (split and merge). `Logo` in `packages/ui` follows the theme; `apps/web/public/favicon.svg` (in the steel colours) is the static version; `apps/web/icons/icon.svg` (the mark on the steel accent, square) is the source of the app icons. -- **Pages**: `/` is the landing page, `/tools/` the tools home, `/tools/pdf/` and `/tools/image/` the categories, `/tool/<id>/` a tool. Every page has its own address, title and description, so search engines and link previews can tell them apart. +- **Pages**: `/` is the landing page, `/tools/` the tools home, `/tools/pdf/` and `/tools/image/` the categories, `/tools/<kind>/<id>/` a tool (always under its own kind, for example `/tools/pdf/sign-pdf/`). Every page has its own address, title and description, so search engines and link previews can tell them apart. - Not done: page thumbnails strip in the tool page (waits for M3 tools whose output keeps one page per input page), command palette. The design's network monitor, recent-files list, save-to folder and "Show in folder" were left out: Ream has none of them. diff --git a/packages/tools/src/seo/types.ts b/packages/tools/src/seo/types.ts index 4f0bac4..afa1779 100644 --- a/packages/tools/src/seo/types.ts +++ b/packages/tools/src/seo/types.ts @@ -1,5 +1,5 @@ /** - * The words of a tool's own page (ream.deityhub.com/tool/<id>/): what search engines list and what a visitor reads under + * The words of a tool's own page (ream.deityhub.com/tools/<kind>/<id>/): what search engines list and what a visitor reads under * the tool. Plain, true claims only: say what the tool does and where it stops (no OCR, no certificate signatures...). * `seo.test.ts` checks the lengths and that every tool has an entry. */ diff --git a/scripts/seo-check.ts b/scripts/seo-check.ts index 64dd607..0cce616 100644 --- a/scripts/seo-check.ts +++ b/scripts/seo-check.ts @@ -68,6 +68,12 @@ for (const file of pages) { } if (!pages.includes('index.html')) bad('dist', 'no index.html') +// a tool lives at /tools/<kind>/<id>/ and nowhere else: the shape before that (/tool/<id>/) must not come back +if (pages.some((f) => f.startsWith('tool/'))) bad('dist', 'a page under /tool/: tools live under /tools/<kind>/') +for (const f of pages) { + const m = /^tools\/([^/]+)\/([^/]+)\/index\.html$/.exec(f) + if (m && !readFileSync(join(dist, f), 'utf8').includes(`<link data-seo rel="canonical" href="${SITE}/tools/${m[1]}/${m[2]}/"`)) bad(f, 'a tool page whose canonical is not its own address') +} if (!pages.includes('404.html')) bad('dist', 'no 404.html: Cloudflare Pages would answer every unknown address with 200') // sitemap: every address is a page that exists, and every indexable page is in it @@ -99,7 +105,7 @@ if (!files) bad('sw.js', 'no file list') else { const kept: string[] = JSON.parse(files) for (const f of kept) if (f.endsWith('index.html') || f === '404.html' || f === 'robots.txt' || f === 'sitemap.xml') bad('sw.js', `keeps ${f}`) - if (!kept.includes('./') || !kept.includes('tool/compress-pdf/')) bad('sw.js', 'does not keep the first page and the tool pages') + if (!kept.includes('./') || !kept.includes('tools/pdf/compress-pdf/')) bad('sw.js', 'does not keep the first page and the tool pages') } if (problems.length) { From 5689047f025739298fe17c249fc3bf14a2f013bd Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Thu, 29 Oct 2026 13:22:18 +0000 Subject: [PATCH 8/8] Release v0.3.0 --- CHANGELOG.md | 6 ++++++ package.json | 2 +- 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ed674e1..0a18935 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,12 @@ 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.3.0 (2026-10-29) + +- SEO: real URLs, a page per route, copy for all 37 tools ([#12](https://github.com/Deityhub/ream/pull/12)) +- robots.txt: block AI training crawlers; noindex the pages.dev addresses ([#11](https://github.com/Deityhub/ream/pull/11)) +- README: build and test status badge ([#10](https://github.com/Deityhub/ream/pull/10)) + ## 0.2.0 (2026-10-27) - Faster tool processing ([#7](https://github.com/Deityhub/ream/pull/7)) diff --git a/package.json b/package.json index c940d51..7db0512 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "ream", - "version": "0.2.0", + "version": "0.3.0", "private": true, "license": "MIT", "type": "module",