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..6c1f3fc 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,14 @@ 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`), `/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. - 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). +- 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, `<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/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/CONTRIBUTING.md b/CONTRIBUTING.md index 8b68d10..a367fe4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -20,16 +20,20 @@ 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 - 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).** diff --git a/apps/web/index.html b/apps/web/index.html index 4ccf142..60dfb40 100644 --- a/apps/web/index.html +++ b/apps/web/index.html @@ -3,9 +3,9 @@ <head> <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> - <link rel="icon" type="image/svg+xml" href="./favicon.svg" /> - <link rel="manifest" href="./manifest.webmanifest" /> - <link rel="apple-touch-icon" href="./icons/apple-touch-icon.png" /> + <link rel="icon" type="image/svg+xml" href="/favicon.svg" /> + <link rel="manifest" href="/manifest.webmanifest" /> + <link rel="apple-touch-icon" href="/icons/apple-touch-icon.png" /> <meta name="description" content="A private file toolkit that runs on your computer. Convert, edit and secure PDFs, images and documents without uploading them." /> <meta name="theme-color" content="#f2f2f3" media="(prefers-color-scheme: light)" /> <meta name="theme-color" content="#1d2d3d" media="(prefers-color-scheme: dark)" /> diff --git a/apps/web/public/_headers b/apps/web/public/_headers index 8876a56..cfb8e41 100644 --- a/apps/web/public/_headers +++ b/apps/web/public/_headers @@ -15,3 +15,10 @@ # the service worker and the page must always be checked for a newer version /sw.js Cache-Control: no-cache + +# Only ream.deityhub.com is for search engines: the same site on Cloudflare's own addresses (the project's, and every +# preview deployment's) would be an indexable duplicate +https://:project.pages.dev/* + X-Robots-Tag: noindex +https://:version.:project.pages.dev/* + X-Robots-Tag: noindex diff --git a/apps/web/public/manifest.webmanifest b/apps/web/public/manifest.webmanifest index b0e771d..b3c7e2f 100644 --- a/apps/web/public/manifest.webmanifest +++ b/apps/web/public/manifest.webmanifest @@ -2,9 +2,9 @@ "name": "Ream: file toolkit", "short_name": "Ream", "description": "A private file toolkit that runs on your computer. Convert, edit and secure PDFs, images and documents without uploading them.", - "id": "./", - "start_url": "./#/tools", - "scope": "./", + "id": "/", + "start_url": "/tools/", + "scope": "/", "display": "standalone", "background_color": "#f2f2f3", "theme_color": "#f2f2f3", diff --git a/apps/web/public/og.png b/apps/web/public/og.png new file mode 100644 index 0000000..f39d195 Binary files /dev/null and b/apps/web/public/og.png differ diff --git a/apps/web/public/robots.txt b/apps/web/public/robots.txt new file mode 100644 index 0000000..b249f97 --- /dev/null +++ b/apps/web/public/robots.txt @@ -0,0 +1,58 @@ +# Ream's robots.txt. Search engines are welcome; crawlers that gather pages to train AI models are not. +# +# This is a request, not a lock: well-behaved crawlers follow it, others may not. Cloudflare's "Block AI bots" setting +# (Security, Bots) is what enforces it. The bots below are the training crawlers; AI search and assistant fetchers +# (OAI-SearchBot, ChatGPT-User, PerplexityBot, Claude-SearchBot, Claude-User) and link-preview bots are not blocked. +# Applebot (Siri and Spotlight search) and Googlebot are allowed; only their AI-training opt-out tokens are blocked. +# The list follows https://github.com/ai-robots-txt/ai.robots.txt, kept to training crawlers. + +User-agent: * +Allow: / +# Cloudflare's content signals: found by search and quoted by assistants, but not used to train models +Content-Signal: search=yes, ai-input=yes, ai-train=no + +User-agent: GPTBot +User-agent: ClaudeBot +User-agent: anthropic-ai +User-agent: Claude-Web +User-agent: CCBot +User-agent: Google-Extended +User-agent: GoogleOther +User-agent: GoogleOther-Image +User-agent: GoogleOther-Video +User-agent: Applebot-Extended +User-agent: Meta-ExternalAgent +User-agent: FacebookBot +User-agent: Bytespider +User-agent: TikTokSpider +User-agent: Amazonbot +User-agent: cohere-ai +User-agent: cohere-training-data-crawler +User-agent: MistralAI-Training +User-agent: Diffbot +User-agent: ImagesiftBot +User-agent: omgili +User-agent: omgilibot +User-agent: Timpibot +User-agent: PanguBot +User-agent: Kangaroo Bot +User-agent: AI2Bot +User-agent: Ai2Bot-Dolma +User-agent: Webzio-Extended +User-agent: img2dataset +User-agent: LAIONDownloader +User-agent: ICC-Crawler +User-agent: VelenPublicWebCrawler +User-agent: SBIntuitionsBot +User-agent: DeepSeekBot +User-agent: QwenBot +User-agent: MoonshotBot +User-agent: DoubaoBot +User-agent: TongyiBot +User-agent: ChatGLM-Spider +User-agent: YiBot +User-agent: Cotoyogi +User-agent: Scrapy +Disallow: / + +Sitemap: https://ream.deityhub.com/sitemap.xml diff --git a/apps/web/seoPlugin.ts b/apps/web/seoPlugin.ts new file mode 100644 index 0000000..1c102dc --- /dev/null +++ b/apps/web/seoPlugin.ts @@ -0,0 +1,43 @@ +import type { OutputAsset } from 'rollup' +import type { Plugin } from 'vite' +import { tools } from '@ream/tools' +import { allRoutes, pathOf, type Route } from './src/routes' +import { headTags, pageSeo, sitemapXml, type PageSeo } from './src/seo' + +/** + * Writes a page for every route (tool/merge-pdf/index.html and so on), a 404 page and sitemap.xml, from the built index.html: + * each has its own title, description, canonical address, social card tags and structured data in the head, and plain + * text inside #root that the app replaces when it starts. Search engines and link previews read these files; the app + * works the same from any of them. + */ +export const seoPages = (version: string): Plugin => ({ + name: 'ream-seo', + apply: 'build', + generateBundle: { + order: 'post', + handler(_, bundle) { + const index = bundle['index.html'] as OutputAsset | undefined + if (!index) throw new Error('ream-seo: the build has no index.html to start from') + const template = String(index.source) + const page = (s: PageSeo) => { + const head = `<title>${escapeText(s.title)}` + let html = template.replace(/[^<]*<\/title>/, head).replace(/(<meta name="description" content=")[^"]*(")/, `$1${escapeAttr(s.description)}$2`) + html = html.replace('</head>', ` ${headTags(s)}\n </head>`).replace('<div id="root"></div>', `<div id="root">${s.html}</div>`) + if (html === template) throw new Error('ream-seo: the template has nothing to fill in') + return html + } + const emit = (fileName: string, source: string) => this.emitFile({ type: 'asset', fileName, source }) + const routes: Route[] = allRoutes(tools) + for (const route of routes) { + const file = pathOf(route) === '/' ? 'index.html' : `${pathOf(route).slice(1)}index.html` + if (file === 'index.html') index.source = page(pageSeo(route, version)) + else emit(file, page(pageSeo(route, version))) + } + emit('404.html', page(pageSeo({ page: 'notFound' }, version))) + emit('sitemap.xml', sitemapXml(routes, version)) + }, + }, +}) + +const escapeText = (s: string) => s.replace(/&/g, '&').replace(/</g, '<') +const escapeAttr = (s: string) => escapeText(s).replace(/"/g, '"') diff --git a/apps/web/src/App.tsx b/apps/web/src/App.tsx index 1f7621f..ab612c6 100644 --- a/apps/web/src/App.tsx +++ b/apps/web/src/App.tsx @@ -1,22 +1,37 @@ import { useEffect } from 'react' -import { findTool } from '@ream/tools' -import { useHash } from './useHash' +import { usePath } from './router' +import { parseRoute } from './routes' import { Home } from './Home' import { ToolPage } from './ToolPage' import { Landing } from './Landing' import { Legal } from './Legal' +import { NotFound } from './NotFound' export function App() { - const hash = useHash() + const path = usePath() useEffect(() => { scrollTo(0, 0) - }, [hash]) - const id = hash.match(/^#\/tool\/([\w-]+)$/)?.[1] - if (id) return <ToolPage key={id} tool={findTool(id)} /> - const cat = hash.match(/^#\/tools\/(pdf|image)$/)?.[1] as 'pdf' | 'image' | undefined - if (cat) return <Home key={cat} cat={cat} /> - if (hash === '#/tools') return <Home key="all" cat="all" /> - if (hash === '#/licence') return <Legal page="licence" /> - if (hash === '#/notices') return <Legal page="notices" /> - return <Landing /> + }, [path]) + const route = parseRoute(path) + // a page opened at its address already has its head from the build; moving between pages keeps it in step + useEffect(() => { + let live = true + void import('./seoHead').then((m) => live && m.applyHead(parseRoute(path))) + return () => { + live = false + } + }, [path]) + switch (route.page) { + case 'tool': + return <ToolPage key={route.tool.id} tool={route.tool} /> + case 'tools': + return <Home key={route.cat} cat={route.cat} /> + case 'licence': + case 'notices': + return <Legal page={route.page} /> + case 'notFound': + return <NotFound /> + case 'landing': + return <Landing /> + } } diff --git a/apps/web/src/Home.tsx b/apps/web/src/Home.tsx index cd3e98f..74fa661 100644 --- a/apps/web/src/Home.tsx +++ b/apps/web/src/Home.tsx @@ -4,6 +4,8 @@ import { tools } from '@ream/tools' import { acceptsFile, type Category, type Tool } from '@ream/core' import { setHandoff } from './handoff' import { Breadcrumb, TopBar, filterHref, focus, type Filter } from './TopBar' +import { Link, navigate } from './router' +import { toolPath } from './routes' const ready = tools.filter((t) => t.status === 'ready') const heads: Record<Filter, string> = { all: 'All tools', pdf: 'PDF tools', image: 'Image tools' } @@ -31,7 +33,7 @@ export function Home({ cat }: { cat: Filter }) { const open = (t: Tool) => { setHandoff(dropped) - location.hash = `#/tool/${t.id}` + navigate(toolPath(t)) } return ( @@ -79,7 +81,7 @@ export function Home({ cat }: { cat: Filter }) { <section key={s.title ?? i} aria-label={s.title ?? head} className="space-y-5"> {s.title && ( <h2 className="border-b border-line pb-2 text-2xl uppercase"> - {s.href ? <a href={s.href} className={`hover:text-accent-ink hover:underline ${focus}`}>{s.title}</a> : s.title} + {s.href ? <Link to={s.href} className={`hover:text-accent-ink hover:underline ${focus}`}>{s.title}</Link> : s.title} </h2> )} <div className="grid grid-cols-[repeat(auto-fill,minmax(min(250px,100%),1fr))] gap-5"> @@ -113,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 <a href={`#/tool/${t.id}`} className={`${box} ${focus}`}>{body}</a> + return <Link to={toolPath(t)} className={`${box} ${focus}`}>{body}</Link> } diff --git a/apps/web/src/Landing.tsx b/apps/web/src/Landing.tsx index 7989c64..2805e08 100644 --- a/apps/web/src/Landing.tsx +++ b/apps/web/src/Landing.tsx @@ -5,6 +5,7 @@ import { Marketing, kicker, primary, secondary, wrap } from './Marketing' import { install, installed, usePwa } from './pwa' import { ToolCard } from './Home' import { filterHref, focus } from './TopBar' +import { Link } from './router' const ready = tools.filter((t) => t.status === 'ready') const pick = (ids: string[]) => ids.map(findTool).filter((t): t is Tool => !!t) @@ -87,7 +88,7 @@ export function Landing() { Convert, edit, compress and secure your files: PDFs, images and Office documents today, with more kinds of file on the way. Every tool runs on your own machine, so your files never reach a server. </p> <div className="mt-8 flex flex-wrap gap-3"> - <a className={primary} href="#/tools">Open the tools</a> + <Link className={primary} to="/tools/">Open the tools</Link> <InstallButton /> </div> <InstallHint /> @@ -155,7 +156,7 @@ export function Landing() { <section className={`${wrap} flex flex-col items-start gap-6 pt-24`}> <h2 className="max-w-3xl text-[clamp(2.25rem,4.6vw,3.5rem)] leading-[1.04] uppercase">Pick a tool and start. Your files stay with you.</h2> - <a className={primary} href="#/tools">Open the tools</a> + <Link className={primary} to="/tools/">Open the tools</Link> </section> {groups.map((g, i) => ( @@ -166,9 +167,9 @@ export function Landing() { <h2 className="text-4xl uppercase">{g.title}</h2> <p className="mt-1 text-[17px] text-muted">{g.blurb}</p> </div> - <a href={filterHref(g.cat)} className={`font-heading text-lg font-semibold tracking-wide text-accent-ink uppercase hover:underline ${focus}`}> + <Link to={filterHref(g.cat)} className={`font-heading text-lg font-semibold tracking-wide text-accent-ink uppercase hover:underline ${focus}`}> All {ready.filter((t) => t.category === g.cat).length} {g.noun} tools → - </a> + </Link> </div> <div className="grid grid-cols-[repeat(auto-fill,minmax(min(16rem,100%),1fr))] gap-6"> {g.tools.map((t) => <ToolCard key={t.id} tool={t} />)} diff --git a/apps/web/src/Marketing.tsx b/apps/web/src/Marketing.tsx index 830594d..a5af840 100644 --- a/apps/web/src/Marketing.tsx +++ b/apps/web/src/Marketing.tsx @@ -2,6 +2,7 @@ import type { ReactNode } from 'react' import { Logo } from '@ream/ui' import { ThemeToggle } from './ThemeToggle' import { focus } from './TopBar' +import { Link } from './router' const action = `inline-flex min-h-11 items-center justify-center px-5 font-heading text-[17px] font-semibold tracking-wide transition-colors duration-150 ${focus}` /** the one solid object on a page: an accent fill wearing the corner marks */ @@ -18,9 +19,9 @@ export function Marketing({ children }: { children: ReactNode }) { <div className="flex min-h-screen flex-col"> <header> <div className={`${wrap} flex flex-wrap items-center justify-between gap-4 py-4`}> - <a href="#/" className={`flex items-center gap-2 font-heading text-[22px] font-semibold tracking-wide uppercase ${focus}`}> + <Link to="/" className={`flex items-center gap-2 font-heading text-[22px] font-semibold tracking-wide uppercase ${focus}`}> <Logo size={24} /> Ream - </a> + </Link> <nav className="flex flex-wrap items-center gap-x-6 gap-y-2 text-[15px] font-medium"> <ThemeToggle /> </nav> @@ -35,8 +36,8 @@ export function Marketing({ children }: { children: ReactNode }) { <span className="flex flex-wrap gap-x-4 gap-y-1 text-[13px] text-muted"> <span>© 2026 Chizoba Jude Ojini</span> <span className="tabular-nums">Version {__APP_VERSION__}</span> - <a className={`underline hover:text-ink ${focus}`} href="#/licence">MIT licence</a> - <a className={`underline hover:text-ink ${focus}`} href="#/notices">Third-party notices</a> + <Link className={`underline hover:text-ink ${focus}`} to="/licence/">MIT licence</Link> + <Link className={`underline hover:text-ink ${focus}`} to="/notices/">Third-party notices</Link> </span> </div> </footer> diff --git a/apps/web/src/NotFound.tsx b/apps/web/src/NotFound.tsx new file mode 100644 index 0000000..d936c9a --- /dev/null +++ b/apps/web/src/NotFound.tsx @@ -0,0 +1,17 @@ +import { Link } from './router' +import { Marketing, primary, secondary, wrap } from './Marketing' + +export function NotFound() { + return ( + <Marketing> + <section className={`${wrap} pb-20 pt-16 sm:pt-24`}> + <h1 className="text-[clamp(3rem,7vw,6rem)] leading-[1.04] uppercase">Page not found</h1> + <p className="mt-8 max-w-[60ch] text-lg leading-relaxed text-muted">There is nothing at this address. Check it for typing mistakes, or pick a tool from the list.</p> + <div className="mt-8 flex flex-wrap gap-3"> + <Link className={primary} to="/tools/">Open the tools</Link> + <Link className={secondary} to="/">Home</Link> + </div> + </section> + </Marketing> + ) +} diff --git a/apps/web/src/ToolAbout.tsx b/apps/web/src/ToolAbout.tsx new file mode 100644 index 0000000..e0ef499 --- /dev/null +++ b/apps/web/src/ToolAbout.tsx @@ -0,0 +1,51 @@ +import type { Tool } from '@ream/core' +import { seoOf } from '@ream/tools/seo' +import { Link } from './router' +import { focus } from './TopBar' +import { toolPath } from './routes' +import { relatedTools } from './seo' + +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 ( + <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)} 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 8006b0a..4529dcb 100644 --- a/apps/web/src/ToolPage.tsx +++ b/apps/web/src/ToolPage.tsx @@ -1,4 +1,4 @@ -import { useEffect, useId, useRef, useState } from 'react' +import { lazy, Suspense, useEffect, useId, useRef, useState } from 'react' import { Button, Card, Dropzone, Icon } from '@ream/ui' import { UserError, acceptsFile, formatBytes, type FileData, type Tool } from '@ream/core' import { tools } from '@ream/tools' @@ -15,6 +15,11 @@ import { SizeEstimate } from './SizeEstimate' import { LazyPdfPage, PdfPage } from './PdfPage' import { usePreview } from './usePreview' import { Breadcrumb, TopBar, focus } from './TopBar' +import { navigate } from './router' +import { toolPath } from './routes' + +// the page's words (what it does, questions, more tools) load after the tool itself +const ToolAbout = lazy(() => import('./ToolAbout').then((m) => ({ default: m.ToolAbout }))) type State = | { kind: 'idle' } @@ -45,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) @@ -90,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. <a href="#/tools" className={`font-semibold text-accent-ink underline ${focus}`}>See all tools</a>.</p> - </main> - </> - ) - } - const changeFiles = (next: File[]) => { setFiles(next) setActive((a) => Math.min(a, Math.max(0, next.length - 1))) @@ -274,6 +267,12 @@ export function ToolPage({ tool }: { tool?: Tool }) { </aside> )} </div> + {/* 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 && ( @@ -380,7 +379,7 @@ function ResultDialog({ tool, outputs, onClose, onReset }: { tool: Tool; outputs key={t.id} onClick={() => { setHandoff(outputs.map(toFile)) - location.hash = `#/tool/${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 a722099..260a396 100644 --- a/apps/web/src/TopBar.tsx +++ b/apps/web/src/TopBar.tsx @@ -2,11 +2,13 @@ import type { ReactNode } from 'react' import { Logo } from '@ream/ui' import type { Category, Tool } from '@ream/core' import { ThemeToggle } from './ThemeToggle' +import { Link } from './router' +import { categoryPath, toolPath } from './routes' export const focus = 'focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-accent' export type Filter = Category | 'all' -export const filterHref = (f: Filter) => (f === 'all' ? '#/tools' : `#/tools/${f}`) +export const filterHref = categoryPath const filterName: Record<Filter, string> = { all: 'All tools', pdf: 'PDF', image: 'Images' } /** The app's bar: logo on the left; what the page adds (search) and the theme on the right. */ @@ -14,9 +16,9 @@ export function TopBar({ children }: { children?: ReactNode }) { return ( <header> <div className="mx-auto flex max-w-[1600px] flex-wrap items-center gap-3 px-4 py-4 sm:px-8"> - <a href="#/" className={`mr-auto flex items-center gap-2 font-heading text-[22px] font-semibold tracking-wide uppercase ${focus}`}> + <Link to="/" className={`mr-auto flex items-center gap-2 font-heading text-[22px] font-semibold tracking-wide uppercase ${focus}`}> <Logo size={24} /> Ream - </a> + </Link> {children} <ThemeToggle /> </div> @@ -28,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: `#/tool/${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"> @@ -37,13 +39,13 @@ export function Breadcrumb({ cat, tool, className = 'mb-6' }: { cat: Filter; too return ( <li key={l.href} className="flex min-w-0 items-center gap-2.5"> {i > 0 && <span aria-hidden="true">/</span>} - <a - href={l.href} + <Link + to={l.href} aria-current={last ? 'page' : undefined} className={`truncate hover:text-accent-ink hover:underline ${focus} ${last ? 'text-ink' : ''}`} > {l.label} - </a> + </Link> </li> ) })} diff --git a/apps/web/src/crawlers.test.ts b/apps/web/src/crawlers.test.ts new file mode 100644 index 0000000..cdbaf8e --- /dev/null +++ b/apps/web/src/crawlers.test.ts @@ -0,0 +1,83 @@ +import { execFileSync } from 'node:child_process' +import { readFileSync } from 'node:fs' +import { describe, expect, test } from 'vitest' + +const root = new URL('../../../', import.meta.url) +const robots = readFileSync(new URL('apps/web/public/robots.txt', root), 'utf8') + +/** the groups of a robots.txt: the agents that share the rules, and the rules */ +function groups(text: string) { + const out: { agents: string[]; rules: [string, string][] }[] = [] + let current: (typeof out)[number] | null = null + let lastWasAgent = false + for (const raw of text.split('\n')) { + const line = raw.replace(/#.*/, '').trim() + const at = line.indexOf(':') + if (at < 0) continue + const key = line.slice(0, at).trim().toLowerCase() + const value = line.slice(at + 1).trim() + if (key === 'sitemap') continue + if (key === 'user-agent') { + if (!current || !lastWasAgent) out.push((current = { agents: [], rules: [] })) + current.agents.push(value.toLowerCase()) + lastWasAgent = true + } else if (current) { + current.rules.push([key, value]) + lastWasAgent = false + } + } + return out +} + +/** whether the whole site is closed to this crawler: its own group if it has one, else the `*` group (RFC 9309) */ +function blocked(agent: string) { + const all = groups(robots) + const own = all.find((g) => g.agents.includes(agent.toLowerCase())) ?? all.find((g) => g.agents.includes('*'))! + return own.rules.some(([k, v]) => k === 'disallow' && v === '/') +} + +describe('robots.txt', () => { + test('search engines and link-preview bots are welcome', () => { + for (const agent of ['Googlebot', 'Bingbot', 'Applebot', 'DuckDuckBot', 'Twitterbot', 'LinkedInBot', 'facebookexternalhit', 'Slackbot', 'WhatsApp']) { + expect(blocked(agent), agent).toBe(false) + } + }) + + test('AI training crawlers are blocked', () => { + for (const agent of ['GPTBot', 'ClaudeBot', 'anthropic-ai', 'CCBot', 'Google-Extended', 'Applebot-Extended', 'Bytespider', 'Meta-ExternalAgent', 'cohere-ai', 'Diffbot', 'Amazonbot']) { + expect(blocked(agent), agent).toBe(true) + } + }) + + test('AI search and assistant fetchers are not blocked, as chosen', () => { + for (const agent of ['OAI-SearchBot', 'ChatGPT-User', 'PerplexityBot', 'Claude-SearchBot', 'Claude-User']) { + expect(blocked(agent), agent).toBe(false) + } + }) + + test('says AI training is off in the content signals, names the sitemap and lists nobody twice', () => { + expect(robots).toMatch(/^Content-Signal: .*\bai-train=no\b/m) + expect(robots).toMatch(/^Sitemap: https:\/\/ream\.deityhub\.com\/sitemap\.xml$/m) + const agents = groups(robots).flatMap((g) => g.agents) + expect(agents.length).toBe(new Set(agents).size) + }) +}) + +describe('search engines and the other addresses of the site', () => { + // the rules, without their comments + const headers = readFileSync(new URL('apps/web/public/_headers', root), 'utf8').split('\n').filter((l) => !l.trimStart().startsWith('#')).join('\n') + + test("Cloudflare's own addresses (and previews) are noindex, the custom domain is not", () => { + for (const host of ['https://:project.pages.dev/*', 'https://:version.:project.pages.dev/*']) { + expect(headers).toMatch(new RegExp(`^${host.replace(/[.*]/g, '\\$&')}\\n\\s+X-Robots-Tag: noindex$`, 'm')) + } + expect(headers).not.toMatch(/ream\.deityhub\.com/) + expect(headers.match(/X-Robots-Tag/g)).toHaveLength(2) // nothing on the shared /* rule + }) + + test('the self-hosted NGINX site has no location for those addresses', () => { + const conf = execFileSync(process.execPath, ['scripts/nginx-conf.ts'], { cwd: root, encoding: 'utf8' }) + expect(conf).not.toMatch(/pages\.dev|X-Robots-Tag|location [^\n]*https?:/) + expect(conf).toMatch(/location = \/sw\.js/) // the other rules are still there + }) +}) diff --git a/apps/web/src/index.css b/apps/web/src/index.css index 7a9d484..2b1e27f 100644 --- a/apps/web/src/index.css +++ b/apps/web/src/index.css @@ -40,3 +40,11 @@ label:has(input:is([type='checkbox'], [type='radio']):not(:disabled)) { cursor: background-image: conic-gradient(var(--surface-2) 25%, transparent 0 50%, var(--surface-2) 0 75%, transparent 0); background-size: 16px 16px; } + +/* What a page holds before the app starts, and what a crawler that doesn't run scripts reads (see seoPlugin.ts). The app replaces it. */ +main.seo { max-width: 46rem; margin: 0 auto; padding: 4rem 1rem; line-height: 1.6; } +main.seo h1 { font-size: 2.5rem; line-height: 1.1; text-transform: uppercase; margin-bottom: 1rem; } +main.seo h2 { font-size: 1.5rem; text-transform: uppercase; margin: 2rem 0 0.5rem; } +main.seo ul { list-style: disc; padding-left: 1.25rem; } +main.seo dt { font-weight: 600; margin-top: 1rem; } +main.seo a { color: var(--accent-ink); text-decoration: underline; } diff --git a/apps/web/src/main.tsx b/apps/web/src/main.tsx index cabf8e1..4b6584f 100644 --- a/apps/web/src/main.tsx +++ b/apps/web/src/main.tsx @@ -4,7 +4,9 @@ import './index.css' import { App } from './App' import { startPwa } from './pwa' import { UpdateBar } from './UpdateBar' +import { upgradeLegacyUrl } from './router' +upgradeLegacyUrl() startPwa() createRoot(document.getElementById('root')!).render( diff --git a/apps/web/src/pwa.ts b/apps/web/src/pwa.ts index 1e028dd..649a252 100644 --- a/apps/web/src/pwa.ts +++ b/apps/web/src/pwa.ts @@ -48,7 +48,7 @@ export function startPwa() { addEventListener('appinstalled', () => set({ install: null })) if (!import.meta.env.PROD || !('serviceWorker' in navigator)) return addEventListener('load', async () => { - const reg = await navigator.serviceWorker.register('./sw.js', { scope: './' }).catch(() => null) + const reg = await navigator.serviceWorker.register('/sw.js', { scope: '/' }).catch(() => null) if (!reg) return // a worker that installs while an older one runs the page is a new version: offer it const watch = (w: ServiceWorker | null) => { diff --git a/apps/web/src/router.tsx b/apps/web/src/router.tsx new file mode 100644 index 0000000..69fb087 --- /dev/null +++ b/apps/web/src/router.tsx @@ -0,0 +1,40 @@ +import { useSyncExternalStore, type AnchorHTMLAttributes, type MouseEvent } from 'react' +import { legacyPath } from './routes' + +// path routing with the History API: no router dependency, and a real URL for every page (see routes.ts) +const CHANGED = 'ream:navigate' + +const subscribe = (on: () => void) => { + addEventListener('popstate', on) + addEventListener(CHANGED, on) + return () => { + removeEventListener('popstate', on) + removeEventListener(CHANGED, on) + } +} + +/** the current URL path; the page re-renders when it changes */ +export const usePath = () => useSyncExternalStore(subscribe, () => location.pathname, () => '/') + +export function navigate(to: string, { replace = false } = {}) { + if (to === location.pathname) return scrollTo(0, 0) + history[replace ? 'replaceState' : 'pushState'](null, '', to) + dispatchEvent(new Event(CHANGED)) +} + +/** a real link (crawlers, new tabs and copying the address all work); a plain click moves inside the app instead of loading the page again */ +export function Link({ to, onClick, ...rest }: { to: string } & AnchorHTMLAttributes<HTMLAnchorElement>) { + const go = (e: MouseEvent<HTMLAnchorElement>) => { + onClick?.(e) + if (e.defaultPrevented || e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey || (rest.target && rest.target !== '_self')) return + e.preventDefault() + navigate(to) + } + return <a href={to} onClick={go} {...rest} /> +} + +/** old links (`/#/tool/merge-pdf`, and installed apps that open `#/tools`) become real URLs before the first render */ +export function upgradeLegacyUrl() { + const path = legacyPath(location.hash) + if (path) history.replaceState(null, '', path) +} diff --git a/apps/web/src/routes.test.ts b/apps/web/src/routes.test.ts new file mode 100644 index 0000000..47f46cb --- /dev/null +++ b/apps/web/src/routes.test.ts @@ -0,0 +1,67 @@ +import { describe, expect, test } from 'vitest' +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', 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) + } + }) + + 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 ['/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, 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 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() + }) + + test('the build writes a page for the landing page, the tools home, each category, every ready tool, the licence and the notices', () => { + const ready = tools.filter((t) => t.status === 'ready') + const all = allRoutes(tools) + expect(all.filter((r) => r.page === 'tool')).toHaveLength(ready.length) + 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 new file mode 100644 index 0000000..c290792 --- /dev/null +++ b/apps/web/src/routes.ts @@ -0,0 +1,86 @@ +// 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'; tool: Tool } + | { page: 'licence' } + | { page: 'notices' } + | { page: 'notFound' } + +// 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 [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' } + 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 (!b && (a === 'licence' || a === 'notices')) return { page: a } + return { page: 'notFound' } +} + +/** the canonical path of a page, with its closing slash */ +export function pathOf(route: Route): string { + switch (route.page) { + case 'landing': + return '/' + case 'tools': + return route.cat === 'all' ? '/tools/' : `/tools/${route.cat}/` + case 'tool': + return toolPath(route.tool) + case 'licence': + return '/licence/' + case 'notices': + return '/notices/' + case 'notFound': + return '/404.html' + } +} + +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 */ +export function allRoutes(tools: Tool[]): Route[] { + return [ + { page: 'landing' }, + { page: 'tools', cat: 'all' }, + ...categories.map((cat): Route => ({ page: 'tools', cat })), + ...tools.filter((t) => t.status === 'ready').map((tool): Route => ({ page: 'tool', tool })), + { page: 'licence' }, + { page: 'notices' }, + ] +} + +/** 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 new file mode 100644 index 0000000..cc55a8a --- /dev/null +++ b/apps/web/src/seo.test.ts @@ -0,0 +1,112 @@ +import { describe, expect, test } from 'vitest' +import { findTool, tools } from '@ream/tools' +import { seoOf, toolSeo } from '@ream/tools/seo' +import { allRoutes, parseRoute, pathOf } from './routes' +import { SITE, headTags, pageSeo, sitemapXml } from './seo' + +const ready = tools.filter((t) => t.status === 'ready') + +describe("every tool's page text", () => { + test('every tool has an entry, and nothing is written for a tool that does not exist', () => { + expect(Object.keys(toolSeo).sort()).toEqual(ready.map((t) => t.id).sort()) + }) + + test('titles are unique, end with the name and fit a search result; descriptions fit a snippet', () => { + const titles = ready.map((t) => seoOf(t).title) + expect(new Set(titles).size).toBe(titles.length) + for (const t of ready) { + const s = seoOf(t) + expect(s.title.length, `${t.id} title: ${s.title.length}`).toBeLessThanOrEqual(60) + expect(s.title.endsWith(' | Ream'), t.id).toBe(true) + expect(s.description.length, `${t.id} description: ${s.description.length}`).toBeGreaterThanOrEqual(70) + expect(s.description.length, `${t.id} description: ${s.description.length}`).toBeLessThanOrEqual(155) + } + }) + + test('each page has a real intro, three points and at least two questions, in the house style', () => { + for (const t of ready) { + const s = seoOf(t) + expect(s.intro.length, t.id).toBeGreaterThan(120) + expect(s.points, t.id).toHaveLength(3) + expect(s.faq.length, t.id).toBeGreaterThanOrEqual(2) + const text = [s.title, s.description, s.intro, ...s.points, ...s.faq.flat()].join(' ') + expect(text, t.id).not.toMatch(/!|\bplease\b|\bAI\b/i) + for (const [q, a] of s.faq) { + expect(q.endsWith('?'), `${t.id}: ${q}`).toBe(true) + expect(a.length, `${t.id}: ${q}`).toBeGreaterThan(20) + } + } + }) + + test('a tool without written text still gets a usable page', () => { + const s = seoOf({ ...ready[0], id: 'a-new-tool', title: 'A new tool', description: 'Does something' }) + expect(s.title).toContain('A new tool') + expect(s.description).toContain('never uploaded') + }) +}) + +describe('pages', () => { + const routes = allRoutes(tools) + const pages = routes.map((r) => pageSeo(r, '1.2.3')) + + test('every page has its own title and description, and a canonical path that is its own file', () => { + expect(new Set(pages.map((p) => p.title)).size).toBe(pages.length) + expect(new Set(pages.map((p) => p.description)).size).toBe(pages.length) + routes.forEach((r, i) => expect(pages[i].path).toBe(pathOf(r))) + for (const p of pages) { + expect(p.title.length, p.title).toBeLessThanOrEqual(65) + expect(p.description.length, p.description).toBeLessThanOrEqual(160) + } + }) + + test('the sitemap lists the pages worth finding, once each, and not the licence texts', () => { + const xml = sitemapXml(routes, '1.2.3') + const urls = [...xml.matchAll(/<loc>([^<]+)<\/loc>/g)].map((m) => m[1]) + 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}/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', () => { + 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(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(parseRoute('/tools/pdf/merge-pdf/'), '1') + const head = headTags(tool) + 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`) + const kinds = [...head.matchAll(/<script data-seo type="application\/ld\+json">([^<]+)<\/script>/g)].map((m) => JSON.parse(m[1])['@type']) + expect(kinds).toEqual(['WebApplication', 'BreadcrumbList']) + const landing = pageSeo({ page: 'landing' }, '1.2.3') + expect(JSON.stringify(landing.jsonLd)).toContain('"softwareVersion":"1.2.3"') + }) + + test('text in a title or description cannot break out of its tag', () => { + const head = headTags({ title: 'A "quoted" <b>', description: 'x & "y" <script>', path: '/', index: true, jsonLd: [{ note: '</script><b>' }], html: '' }) + expect(head).not.toMatch(/<b>/) + expect(head.match(/<script/g)).toHaveLength(1) // only the structured data block, and its text can't close it early + expect(head).toContain('"quoted"') + expect(head).toContain('\\u003c/script>') + }) + + 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="/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 new file mode 100644 index 0000000..6887e68 --- /dev/null +++ b/apps/web/src/seo.ts @@ -0,0 +1,182 @@ +// What search engines and social cards read for each page: title, description, canonical address, structured data and the +// 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 { tools } from '@ream/tools' +import { seoOf } from '@ream/tools/seo' +import { categoryPath, toolPath, type Route, pathOf } from './routes' + +/** where the site lives: canonical addresses, the sitemap and the social card point here, also from a self-hosted copy */ +export const SITE = 'https://ream.deityhub.com' +export const OG_IMAGE = `${SITE}/og.png` + +const CATEGORY_NAME: Record<Category, { title: string; noun: string }> = { + pdf: { title: 'PDF tools', noun: 'PDF' }, + image: { title: 'Image tools', noun: 'image' }, +} + +export type PageSeo = { + title: string + description: string + /** the page's own path, which is also its canonical address */ + path: string + /** pages that should not be listed: the 404 page, the licence texts, a tool that doesn't exist */ + index: boolean + jsonLd: object[] + /** plain HTML for inside #root: what a crawler that doesn't run scripts, and the first moment of a load, show */ + html: string +} + +const esc = (s: string) => s.replace(/&/g, '&').replace(/</g, '<').replace(/>/g, '>').replace(/"/g, '"') + +const PRIVACY = + 'Ream runs entirely on your device. Your files are opened and changed by code in your own browser and are never uploaded, there is no account to make, and once you have visited, it works offline. Up to 50 files at a time, 200 MB each and 500 MB in all.' + +const ready = tools.filter((t) => t.status === 'ready') +const inCategory = (cat: Category) => ready.filter((t) => t.category === cat) + +/** the tools a visitor may want next: others of the same kind, up to six */ +export const relatedTools = (tool: Tool) => ready.filter((t) => t.category === tool.category && t.id !== tool.id).slice(0, 6) + +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), t.title)}: ${esc(t.description)}`)) + +const breadcrumb = (items: [name: string, path: string][]) => ({ + '@context': 'https://schema.org', + '@type': 'BreadcrumbList', + itemListElement: items.map(([name, path], i) => ({ '@type': 'ListItem', position: i + 1, name, item: SITE + path })), +}) + +const author = { '@type': 'Person', name: 'Chizoba Jude Ojini' } +const free = { '@type': 'Offer', price: '0', priceCurrency: 'USD' } + +export function pageSeo(route: Route, version: string): PageSeo { + const path = pathOf(route) + switch (route.page) { + case 'landing': { + const description = 'The file toolkit that runs on your computer. Convert, edit, compress and secure PDFs, images and Office files. Nothing is uploaded.' + return { + title: 'Ream: private file tools for PDFs, images and Office files', + description, + path, + index: true, + jsonLd: [ + { '@context': 'https://schema.org', '@type': 'WebSite', name: 'Ream', url: SITE + '/', description, inLanguage: 'en' }, + { + '@context': 'https://schema.org', + '@type': 'WebApplication', + name: 'Ream', + url: SITE + '/', + description, + applicationCategory: 'UtilitiesApplication', + operatingSystem: 'Any', + browserRequirements: 'Requires a current web browser', + softwareVersion: version, + isAccessibleForFree: true, + offers: free, + license: 'https://opensource.org/licenses/MIT', + author, + featureList: ready.map((t) => t.title), + }, + ], + html: `<main class="seo"><h1>The file toolkit that runs on your computer</h1><p>${esc(description)}</p><p>${esc(PRIVACY)}</p><h2>PDF tools</h2>${toolLinks(inCategory('pdf'))}<h2>Image tools</h2>${toolLinks(inCategory('image'))}<p>${link('/tools/', 'See all tools')}</p></main>`, + } + } + case 'tools': { + const cat = route.cat + const group = cat === 'all' ? ready : inCategory(cat) + const name = cat === 'all' ? 'All tools' : CATEGORY_NAME[cat].title + const title = cat === 'all' ? 'All file tools: PDF, image and Office | Ream' : cat === 'pdf' ? 'PDF tools: merge, split, compress, edit, convert | Ream' : 'Image tools: resize, convert, compress, crop | Ream' + const description = + cat === 'all' + ? `${group.length} tools to convert, edit, compress and secure PDFs, images and Office files, all running on your device. Nothing is uploaded.` + : `${group.length} ${CATEGORY_NAME[cat].noun} tools that run in your browser: ${group.slice(0, 5).map((t) => t.title.toLowerCase()).join(', ')} and more. Nothing is uploaded.` + const crumbs: [string, string][] = [['Ream', '/'], ['All tools', '/tools/']] + if (cat !== 'all') crumbs.push([name, categoryPath(cat)]) + return { + title, + 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), 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 = route.tool + if (tool.status !== 'ready') return notFound('This tool is not ready') + const s = seoOf(tool) + const cat = CATEGORY_NAME[tool.category] + return { + title: s.title, + description: s.description, + path, + index: true, + jsonLd: [ + { + '@context': 'https://schema.org', + '@type': 'WebApplication', + name: tool.title, + url: SITE + path, + description: s.description, + applicationCategory: 'UtilitiesApplication', + operatingSystem: 'Any', + browserRequirements: 'Requires a current web browser', + isAccessibleForFree: true, + offers: free, + author, + isPartOf: { '@type': 'WebSite', name: 'Ream', url: SITE + '/' }, + ...(s.points.length ? { featureList: s.points } : {}), + }, + breadcrumb([['Ream', '/'], ['All tools', '/tools/'], [cat.title, categoryPath(tool.category)], [tool.title, path]]), + ], + html: `<main class="seo"><p>${link('/tools/', 'All tools')} / ${link(categoryPath(tool.category), cat.title)}</p><h1>${esc(tool.title)}</h1><p>${esc(s.intro)}</p>${s.points.length ? `<h2>What you can do</h2>${list(s.points.map(esc))}` : ''}<h2>Private by design</h2><p>${esc(PRIVACY)}</p>${s.faq.length ? `<h2>Questions</h2><dl>${s.faq.map(([q, a]) => `<dt>${esc(q)}</dt><dd>${esc(a)}</dd>`).join('')}</dl>` : ''}<h2>More ${cat.noun} tools</h2>${toolLinks(relatedTools(tool))}</main>`, + } + } + case 'licence': + return { title: 'MIT licence | Ream', description: 'Ream is free software under the MIT licence.', path, index: false, jsonLd: [], html: '<main class="seo"><h1>Licence</h1><p>Ream is released under the MIT licence.</p></main>' } + case 'notices': + return { title: 'Third-party notices | Ream', description: 'The licences of the software and fonts Ream ships from others.', path, index: false, jsonLd: [], html: '<main class="seo"><h1>Third-party notices</h1><p>The licences of the software and fonts Ream ships from others.</p></main>' } + case 'notFound': + return notFound('Page not found') + } +} + +function notFound(title: string): PageSeo { + return { title: `${title} | Ream`, description: 'There is nothing at this address.', path: '/404.html', index: false, jsonLd: [], html: `<main class="seo"><h1>${esc(title)}</h1><p>There is nothing at this address. ${link('/tools/', 'Open the tools')}</p></main>` } +} + +const absolute = (s: PageSeo) => SITE + s.path + +/** the tags a page's head needs, as HTML (marked `data-seo` so the app can swap them): the build puts them in the file, the app sets the same values when you move between pages */ +export function headTags(s: PageSeo): string { + const url = absolute(s) + // a page that doesn't exist has no address of its own to declare + const own = s.path !== '/404.html' + const meta = (attr: 'name' | 'property', key: string, value: string) => `<meta data-seo ${attr}="${key}" content="${esc(value)}" />` + return [ + ...(own ? [`<link data-seo rel="canonical" href="${esc(url)}" />`] : []), + meta('name', 'robots', s.index ? 'index, follow, max-image-preview:large' : 'noindex, follow'), + meta('property', 'og:type', 'website'), + meta('property', 'og:site_name', 'Ream'), + meta('property', 'og:title', s.title), + meta('property', 'og:description', s.description), + ...(own ? [meta('property', 'og:url', url)] : []), + meta('property', 'og:image', OG_IMAGE), + meta('property', 'og:image:width', '1200'), + meta('property', 'og:image:height', '630'), + meta('property', 'og:image:alt', 'Ream: the file toolkit that runs on your computer'), + meta('name', 'twitter:card', 'summary_large_image'), + meta('name', 'twitter:title', s.title), + meta('name', 'twitter:description', s.description), + meta('name', 'twitter:image', OG_IMAGE), + ...s.jsonLd.map((j) => `<script data-seo type="application/ld+json">${JSON.stringify(j).replace(/</g, '\\u003c')}</script>`), + ].join('\n ') +} + +/** the sitemap: every page worth listing, one address each */ +export function sitemapXml(routes: Route[], version: string): string { + const urls = routes.map((r) => pageSeo(r, version)).filter((s) => s.index) + return `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${urls.map((s) => ` <url><loc>${SITE}${s.path}</loc></url>`).join('\n')}\n</urlset>\n` +} diff --git a/apps/web/src/seoHead.ts b/apps/web/src/seoHead.ts new file mode 100644 index 0000000..87662d7 --- /dev/null +++ b/apps/web/src/seoHead.ts @@ -0,0 +1,12 @@ +// Keeps the document's head in step with the page while moving around inside the app (a file opened at an address +// already has the right head from the build). Loaded on demand: it carries every tool's text. +import { headTags, pageSeo } from './seo' +import type { Route } from './routes' + +export function applyHead(route: Route) { + const s = pageSeo(route, __APP_VERSION__) + document.title = s.title + document.querySelector('meta[name="description"]')?.setAttribute('content', s.description) + document.head.querySelectorAll('[data-seo]').forEach((e) => e.remove()) + document.head.insertAdjacentHTML('beforeend', headTags(s)) +} diff --git a/apps/web/src/useHash.ts b/apps/web/src/useHash.ts deleted file mode 100644 index 2648f2e..0000000 --- a/apps/web/src/useHash.ts +++ /dev/null @@ -1,12 +0,0 @@ -import { useEffect, useState } from 'react' - -// hash routing needs no server rewrites (any static host serves index.html) and no router dependency -export function useHash() { - const [hash, setHash] = useState(location.hash) - useEffect(() => { - const on = () => setHash(location.hash) - addEventListener('hashchange', on) - return () => removeEventListener('hashchange', on) - }, []) - return hash -} diff --git a/apps/web/sw.js b/apps/web/sw.js index bda6ab5..48e2da9 100644 --- a/apps/web/sw.js +++ b/apps/web/sw.js @@ -32,12 +32,13 @@ self.addEventListener('fetch', (event) => { const url = new URL(request.url) if (request.method !== 'GET' || url.origin !== self.location.origin) return if (request.mode === 'navigate') { - // the page itself: the newest from the network, the kept copy when offline - event.respondWith(fetch(request).catch(() => caches.match('./', { cacheName: APP }))) + // the page itself: the newest from the network, the kept copy when offline (its own, else the app's first page: every address is a page of the app) + event.respondWith(fetch(request).catch(() => caches.match(request, { cacheName: APP, ignoreVary: true }).then((page) => page ?? caches.match('./', { cacheName: APP, ignoreVary: true })))) return } + // ignoreVary: a host that sends `Vary: Origin` would otherwise make every module script miss its kept copy (the page's request has an Origin header, the one that filled the cache has none); the names carry a hash, so one copy is the only copy event.respondWith( - caches.match(request).then( + caches.match(request, { ignoreVary: true }).then( (kept) => kept ?? fetch(request).then((response) => { diff --git a/apps/web/vite.config.ts b/apps/web/vite.config.ts index 2330d41..fbfa38d 100644 --- a/apps/web/vite.config.ts +++ b/apps/web/vite.config.ts @@ -4,6 +4,7 @@ import { join, relative } from 'node:path' import { defineConfig, type Plugin } from 'vite' import react from '@vitejs/plugin-react' import tailwindcss from '@tailwindcss/vite' +import { seoPages } from './seoPlugin' /** the release version (root package.json), shown in the footer and in the offline cache's name */ const VERSION: string = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).version @@ -11,6 +12,9 @@ const VERSION: string = JSON.parse(readFileSync(new URL('../../package.json', im /** Office look-alike fonts for scripts other than Latin: 2.7 MB nobody needs up front, kept by the worker when first used */ const LATER = /^assets\/(carlito|caladea|arimo|tinos|cousine)-(?!latin(-ext)?-\d)/ +/** not kept for offline use: the worker itself, Cloudflare's headers file, what crawlers read, the 404 page and the social card */ +const NOT_KEPT = /^(sw\.js|_headers|robots\.txt|sitemap\.xml|404\.html|og\.png)$/ + /** * Writes dist/sw.js from sw.js with the list of files to keep offline and a version that changes with any of them. * Done after the build is written, so it lists every file, the tools' workers included. @@ -32,18 +36,18 @@ const serviceWorker = (): Plugin => { } } walk(out) - // woff is only a fallback for browsers without woff2; _headers is Cloudflare's, not the site's - const keep = files.filter((f) => f !== 'sw.js' && f !== '_headers' && !f.endsWith('.woff') && !LATER.test(f)).sort() + // woff is only a fallback for browsers without woff2; _headers is Cloudflare's, not the site's; the files for crawlers and the 404 page are no use offline + const keep = files.filter((f) => !NOT_KEPT.test(f) && !f.endsWith('.woff') && !LATER.test(f)).sort() const hash = createHash('sha256') for (const f of keep) hash.update(f).update(readFileSync(join(out, f))) - // the page is kept as './': Cloudflare Pages answers index.html with a redirect to /, and a page can't load from a kept redirect - keep[keep.indexOf('index.html')] = './' + // a page is kept under its folder's address ('./', 'tool/merge-pdf/'): Cloudflare Pages answers .../index.html with a redirect, and a page can't load from a kept redirect + const addresses = keep.map((f) => (f === 'index.html' ? './' : f.endsWith('/index.html') ? f.slice(0, -'index.html'.length) : f)) const template = readFileSync(new URL('./sw.js', import.meta.url), 'utf8') - writeFileSync(join(out, 'sw.js'), template.replace("'__VERSION__'", JSON.stringify(`${VERSION}-${hash.digest('hex').slice(0, 8)}`)).replace('__FILES__', JSON.stringify(keep))) + writeFileSync(join(out, 'sw.js'), template.replace("'__VERSION__'", JSON.stringify(`${VERSION}-${hash.digest('hex').slice(0, 8)}`)).replace('__FILES__', JSON.stringify(addresses))) }, } } -// base './': asset paths are relative, so the build works from any folder of any static host +// base '/': every page has its own folder (/tool/merge-pdf/), so assets are found from the site's root; the site is served from a domain's root on Cloudflare and in the Docker image // worker format es: the worker loads each tool's engine with a dynamic import, which needs code splitting -export default defineConfig({ base: './', define: { __APP_VERSION__: JSON.stringify(VERSION) }, plugins: [react(), tailwindcss(), serviceWorker()], worker: { format: 'es' } }) +export default defineConfig({ base: '/', define: { __APP_VERSION__: JSON.stringify(VERSION) }, plugins: [react(), tailwindcss(), seoPages(VERSION), serviceWorker()], worker: { format: 'es' } }) diff --git a/docs/deploy.md b/docs/deploy.md index eec0ef4..583fc49 100644 --- a/docs/deploy.md +++ b/docs/deploy.md @@ -6,6 +6,14 @@ The site is https://ream.deityhub.com, on Cloudflare Pages. `.github/workflows/w `apps/web/public/_headers` sets the response headers: a content security policy that lets the page load only its own files (plus Fontsource and jsDelivr, for Download free fonts), no inline scripts or styles, no framing; no referrer; and a year's caching for the content-named files in `/assets`. To try the headers locally: `yarn build`, then `yarn dlx wrangler@4 pages dev apps/web/dist`. +### Search engines and AI crawlers + +`apps/web/public/robots.txt` welcomes search engines and asks AI **training** crawlers (GPTBot, ClaudeBot, CCBot, Google-Extended, Applebot-Extended, Bytespider, Meta-ExternalAgent and others; the list follows the [ai.robots.txt](https://github.com/ai-robots-txt/ai.robots.txt) project) to stay out. AI search and assistant fetchers (OAI-SearchBot, PerplexityBot, Claude-SearchBot and the like) and link-preview bots are allowed, so Ream can be found and quoted but not trained on. It also sends Cloudflare's `Content-Signal: ai-train=no`. To change the choice, edit the lists in that file; `apps/web/src/crawlers.test.ts` checks which crawlers are allowed and which are blocked. + +robots.txt is a request that well-behaved crawlers follow, not a lock. The setting that enforces it is Cloudflare's, and it is free: dashboard → ream.deityhub.com → Security → Bots → **Block AI bots** (or AI Crawl Control). If you also turn on Cloudflare's *managed robots.txt*, it adds its own rules in front of this file. + +The Cloudflare addresses of the site (`ream-bqb.pages.dev` and each preview) send `X-Robots-Tag: noindex` (host rules at the end of `_headers`), so search engines list only ream.deityhub.com. The self-hosted NGINX site leaves those rules out. + ## Installable and offline (PWA) Ream is a progressive web app. `apps/web/public/manifest.webmanifest` and the icons in `apps/web/public/icons` (drawn from `apps/web/icons/icon.svg` by `node scripts/icons.ts`) make it installable: Chrome and Edge show Install Ream on the landing page, Safari has File → Add to Dock, iPhone and iPad have Share → Add to Home Screen. The service worker (`apps/web/sw.js`, written into the build as `sw.js` with its file list by the `serviceWorker` plugin in `vite.config.ts`) keeps the app on the device: @@ -16,6 +24,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/`, `/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` 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). + ## 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..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. +- **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/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", diff --git a/packages/tools/package.json b/packages/tools/package.json index 2ccc356..c063aab 100644 --- a/packages/tools/package.json +++ b/packages/tools/package.json @@ -8,6 +8,7 @@ ".": "./src/index.ts", "./runners": "./src/runners.ts", "./image-common": "./src/image-common.ts", + "./seo": "./src/seo/index.ts", "./panels": "./src/panels.ts", "./office-preview": "./src/office-preview.ts", "./standard-fonts": "./src/fonts/standard-browser.ts" diff --git a/packages/tools/src/seo/convert.ts b/packages/tools/src/seo/convert.ts new file mode 100644 index 0000000..daaafa0 --- /dev/null +++ b/packages/tools/src/seo/convert.ts @@ -0,0 +1,74 @@ +import type { ToolSeo } from './types.ts' + +export const convertSeo: Record<string, ToolSeo> = { + 'images-to-pdf': { + title: 'Convert images to PDF online (JPG, PNG) | Ream', + description: 'Turn JPG, PNG, WebP, GIF and BMP pictures into one PDF. Choose the page size, orientation and margin. Nothing is uploaded.', + intro: 'Put pictures into a single PDF, one per page, in the order you set. Make each page the size of its picture or pick A4, US Letter and other sizes, with the orientation and margin you want. JPEG photos go in as they are, so they are not recompressed.', + points: ['JPG, PNG, WebP, GIF and BMP pictures', 'Pages as big as the picture, or A3, A4, A5, US Letter, Legal and more', 'Put the pictures in order and set the margin and orientation'], + faq: [ + ['Does it reduce the quality of my photos?', 'No. JPEG photos are placed in the PDF exactly as they are, without recompressing them. Other pictures are stored without further loss of detail.'], + ['Can I combine the result with other PDFs?', 'Yes. Make the PDF here, then join it with other files in Merge PDF.'], + ], + }, + 'pdf-to-image': { + title: 'Convert PDF to JPG or PNG images online | Ream', + description: 'Save PDF pages as PNG or JPG pictures at 36 to 600 dpi. Pick the pages you want. Runs on your device; nothing is uploaded.', + intro: 'Turn pages of a PDF into pictures you can post, paste into a document or send. Choose PNG for sharp text and graphics or JPG for smaller photographs, a resolution from 36 to 600 dpi, and which pages. Several pages download together as a ZIP.', + points: ['PNG, or JPG with a quality setting', 'From 36 to 600 dots per inch', 'All pages, or a selection such as 1-3, 5'], + faq: [ + ['Which format should I choose?', 'PNG keeps text and line art crisp and is the better choice for most pages. JPG makes smaller files for pages that are mostly photographs.'], + ['Why was my result refused as too large?', 'A big page at 600 dpi can need more pixels than a browser can hold. Ream says so before it draws anything; lower the resolution or choose fewer pages.'], + ], + }, + 'pdf-to-word': { + title: 'Convert PDF to Word (DOCX) online | Ream', + description: 'Turn a PDF into an editable Word document. The text becomes real text you can edit, and the page design is kept.', + intro: 'Get an editable .docx from a PDF without sending the file to a converter. Ream keeps the artwork of each page as a picture and puts the text on top as editable text boxes, so the document looks like the original and you can still change the words.', + points: ['The text is real text you can edit and search', 'The page\'s artwork, pictures and shapes are kept', 'Every page of the PDF becomes a page of the document'], + faq: [ + ['Will the result look exactly like the PDF?', 'Close, not identical. Text is placed in boxes over the page\'s artwork, so fonts and line breaks can differ a little. It is a good starting point for editing, not a pixel-perfect copy.'], + ['Can it convert a scanned PDF?', 'No. A scan has no text to put in the document, only a picture of it, and Ream has no text recognition (OCR) yet.'], + ], + }, + 'pdf-to-excel': { + title: 'Convert PDF tables to Excel (XLSX) online | Ream', + description: 'Get the tables in a PDF into an Excel workbook. Finds tables drawn with lines and text lined up in columns. No upload.', + intro: 'Pull tables out of a PDF report, invoice or statement and into an .xlsx file you can sort and calculate with. Ream looks for tables drawn with ruled lines and for text that lines up in columns, and writes the cells into a workbook.', + points: ['Finds tables with ruled lines and tables made of aligned text', 'Numbers in the cells become numbers where they can be read', 'Preview the workbook before you download it'], + faq: [ + ['What happens if no table is found?', 'Ream tells you instead of giving you an empty file. Text set in ordinary paragraphs is not a table; PDF to text is the better tool for it.'], + ['Does it read tables in scanned PDFs?', 'No. It needs the real text in the PDF, and Ream has no text recognition (OCR) yet.'], + ], + }, + 'pdf-to-powerpoint': { + title: 'Convert PDF to PowerPoint (PPTX) online | Ream', + description: 'Turn the pages of a PDF into slides you can edit: the design is kept and the text becomes real, editable text boxes.', + intro: 'Make a presentation out of a PDF. Each page becomes a slide, with the page\'s artwork kept in the background and its text placed on top as text boxes you can edit and move.', + points: ['One slide for every page', 'Editable text boxes over the page\'s artwork', 'Preview the slides before you download'], + faq: [ + ['Will the slides match the PDF exactly?', 'They look close to the PDF. Text is placed as lines in text boxes, so fonts and spacing can differ a little. Treat it as an editable starting point.'], + ['Does it work with scanned PDFs?', 'No. A scan has no text to place on the slides, and Ream has no text recognition (OCR) yet.'], + ], + }, + 'excel-to-pdf': { + title: 'Convert Excel (XLSX) to PDF online | Ream', + description: 'Print an Excel workbook to PDF with its formatting, merged cells, pictures and charts. Runs in your browser; nothing is uploaded.', + intro: 'Save a workbook as a PDF without opening Excel. Ream reads the .xlsx file and lays each sheet out the way it prints, with fonts, colours, borders, number formats and charts. A preview shows the result before you download.', + points: ['Keeps formatting, merged cells, pictures and charts', 'Uses the page setup and print areas saved in the workbook', 'Fonts: your installed ones, look-alikes, or ones you add'], + faq: [ + ['Will it look the same as in Excel?', 'Close, not identical. Ream draws the sheet itself and uses look-alike fonts when yours are not available, so line breaks and chart details can differ slightly. The preview is marked approximate for that reason.'], + ['Does it work with older .xls files?', 'Only .xlsx files. Save an older workbook as .xlsx first. Formulas show the results saved in the file; Ream does not recalculate them.'], + ], + }, + 'powerpoint-to-pdf': { + title: 'Convert PowerPoint (PPTX) to PDF online | Ream', + description: 'Save a presentation as a PDF with one page per slide, including shapes, tables, pictures and charts. Nothing is uploaded.', + intro: 'Turn a .pptx into a PDF to share or print, without opening PowerPoint. Ream reads the slides, layouts and theme and draws each slide as a page, with its text, shapes, tables, pictures and charts.', + points: ['One PDF page for every slide', 'Themes, layouts, shapes, tables, pictures and charts', 'Fonts: your installed ones, look-alikes, or ones you add'], + faq: [ + ['Are animations and transitions kept?', 'No. A PDF holds still pages, so each slide is saved as it appears before any animation.'], + ['Will it match PowerPoint exactly?', 'Close, not identical. Ream draws the slides itself, so unusual effects and some fonts can differ. The preview is marked approximate for that reason.'], + ], + }, +} diff --git a/packages/tools/src/seo/image.ts b/packages/tools/src/seo/image.ts new file mode 100644 index 0000000..2649e45 --- /dev/null +++ b/packages/tools/src/seo/image.ts @@ -0,0 +1,124 @@ +import type { ToolSeo } from './types.ts' + +export const imageSeo: Record<string, ToolSeo> = { + 'resize-image': { + title: 'Resize images online: pixels or percent | Ream', + description: 'Change the size of JPG, PNG, WebP, GIF and BMP pictures by pixels or percent, one or many at once. Nothing is uploaded.', + intro: 'Make pictures bigger or smaller. Type a width, a height or both in pixels, or scale by a percentage, and keep the proportions if you want. Add many pictures and they are all resized the same way, then downloaded together.', + points: ['Set the size in pixels, or as a percentage', 'Keep the aspect ratio, or set both sides', 'Resize many pictures in one go'], + faq: [ + ['Does resizing reduce the quality?', 'Making a picture smaller keeps it sharp, because Ream resamples it with a high-quality filter. Enlarging cannot add detail, so large enlargements look soft.'], + ['How big a picture can it handle?', 'Up to about 120 megapixels, which covers any phone or camera photo.'], + ], + }, + 'convert-image': { + title: 'Convert images: JPG, PNG, WebP, GIF, BMP | Ream', + description: 'Change pictures between PNG, JPG, WebP, GIF and BMP with a quality setting. Many files at once, on your device.', + intro: 'Save pictures in another format: PNG for sharp graphics, JPG for photographs, WebP for small files on the web, GIF or BMP when something needs them. Add one picture or many, and choose a quality for JPG and WebP.', + points: ['PNG, JPG, WebP, GIF and BMP in and out', 'A quality setting for JPG and WebP', 'Transparent areas turn white when you save as JPG'], + faq: [ + ['Can I convert HEIC or RAW photos?', 'Not yet. Ream opens JPG, PNG, WebP, GIF and BMP.'], + ['Does converting to JPG lose quality?', 'JPG is a lossy format, so a little detail is lost each time one is saved. Use a high quality setting to lose less, or PNG when nothing may be lost.'], + ], + }, + 'rotate-image': { + title: 'Rotate and flip images online | Ream', + description: 'Turn pictures a quarter or half turn, or mirror them left to right or top to bottom. Many at once, on your device.', + intro: 'Fix a sideways photo or mirror a picture. Turn it a quarter turn either way or a half turn, flip it horizontally or vertically, and see the result before you save. Several pictures can be done together.', + points: ['Quarter turns and half turns', 'Flip left to right or top to bottom', 'Many pictures with one set of choices'], + faq: [ + ['Does rotating lose quality?', 'The rotation itself loses nothing, because pixels are only moved. A JPG has to be saved again afterwards, which can cost a little quality.'], + ['Why does my photo show sideways?', 'Phones record how the camera was held, and some programs ignore it. Turn it here and save the picture the right way up.'], + ], + }, + 'crop-image': { + title: 'Crop images online, free and private | Ream', + description: 'Drag to choose the part of a picture to keep, then save the cropped image. Runs in your browser; nothing is uploaded.', + intro: 'Cut a picture down to what matters. Drag a rectangle over the picture, move and resize it until it is right, and save just that part. The picture is cropped by your own browser and never uploaded.', + points: ['Drag a rectangle over the picture', 'Move and resize it until it is right', 'The kept area has the resolution it had before'], + faq: [ + ['Does cropping reduce the resolution?', 'No. The part you keep has the same pixels it had; nothing is scaled.'], + ['Is the cropped-away part really gone?', 'Yes. The saved file contains only the area you kept.'], + ], + }, + 'merge-images': { + title: 'Merge images into one: row, column or grid | Ream', + description: 'Join pictures into one image, side by side, stacked or in a grid, with the gap and background you choose. No upload.', + intro: 'Combine several pictures into a single image. Place them in a row, a column or a grid, set the gap between them, choose a white or transparent background, and save the result as PNG, JPG or another format.', + points: ['Horizontal, vertical or grid layouts', 'A gap between pictures, and a background', 'Save as PNG, JPG, WebP, GIF or BMP'], + faq: [ + ['What if my pictures are different sizes?', 'In a row, every picture is scaled to the shortest height, and in a column to the narrowest width, so nothing is enlarged. In a grid, each picture is fitted inside equal cells.'], + ['Can I change the order?', 'Yes. Move the pictures up or down in the list before you merge.'], + ], + }, + 'compress-image': { + title: 'Compress images online: JPG, PNG, WebP | Ream', + description: 'Make photos and graphics smaller with a quality setting, and fewer colours for PNG and GIF. See the new size first.', + intro: 'Shrink pictures to save space or load faster. Lower the quality of JPG and WebP photos, or reduce the colours of PNG and GIF graphics, and Ream shows the new size as you adjust. A picture that cannot get smaller is returned as it was.', + points: ['A quality setting for JPG and WebP', 'Fewer colours for PNG and GIF, with or without dithering', 'Keeps the colour profile; camera data is removed unless you keep it'], + faq: [ + ['How much smaller will it be?', 'It depends on the picture. Photographs often shrink to a fraction at 70 to 80 percent quality with little visible change, and graphics shrink most by reducing colours. The size is shown while you change the settings.'], + ['Does it remove the camera and location data?', 'Yes, unless you choose to keep it. The colour profile is always kept so colours stay right.'], + ], + }, + 'animated-gif': { + title: 'Make an animated GIF from images online | Ream', + description: 'Turn pictures into a looping animated GIF. Set the delay, size, loop and fit. Runs in your browser; nothing is uploaded.', + intro: 'Build a GIF from a set of pictures: a slideshow, a before-and-after, a stop-motion. Put the pictures in order, choose how long each stays, whether it loops, the width, and how pictures of different shapes fit the frame.', + points: ['Set the delay per picture, and loop forever or once', 'Contain, cover or stretch pictures to one size', 'Play forwards and back, with up to 256 colours'], + faq: [ + ['Why is my GIF so large?', 'A GIF stores every frame in full, with at most 256 colours. Use a smaller width, fewer colours or fewer pictures. Ream accepts up to 300 pictures.'], + ['Can I turn a video into a GIF?', 'Not at the moment. Ream builds GIFs from pictures.'], + ], + }, + 'image-metadata': { + title: 'Remove EXIF and location data from photos | Ream', + description: 'See the camera, date and GPS location hidden in a photo, and remove it before you share. The picture is not touched.', + intro: 'Photos often carry details you did not mean to share: the camera model, the time and, from phones, where the picture was taken. Ream shows what a JPG or PNG contains and removes either everything or only the location, without touching the picture itself.', + points: ['See the camera, date and GPS data in a photo', 'Remove everything, or only the location', 'The picture is not re-encoded, so quality is unchanged'], + faq: [ + ['Does cleaning a photo reduce its quality?', 'No. Ream removes the metadata from the file and leaves the picture data exactly as it was.'], + ['Which files can it clean?', 'JPG and PNG files. Other formats cannot be cleaned yet.'], + ], + }, + 'watermark-image': { + title: 'Add a watermark to images online | Ream', + description: 'Stamp text or your logo on photos, once or tiled, with size, opacity, angle and position. Many pictures at once.', + intro: 'Brand or protect your pictures. Type a text or add a logo, choose where it goes, how big and how see-through it is, and tilt it if you like. Apply it to one picture or to a whole batch.', + points: ['Text or a logo as the mark', 'A single mark, or a tile repeated across the picture', 'Size, opacity, angle and position'], + faq: [ + ['Can a watermark be removed?', 'A visible watermark discourages copying but is not a lock. A mark in a corner can be cropped or retouched away; tiling it across the picture makes that harder.'], + ['Can I use a logo with a transparent background?', 'Yes. Add a PNG with transparency and it is placed without a box around it.'], + ], + }, + 'blur-image': { + title: 'Blur or hide faces and details in photos | Ream', + description: 'Blur, pixelate or cover faces, number plates and other details in a picture. Runs on your device; nothing is uploaded.', + intro: 'Hide what should not be seen. Drag over a face, a number plate or a screen, and blur it, pixelate it or cover it with a solid box. You can mark several areas, and the result is saved as a new picture.', + points: ['Blur, pixelate or a solid box', 'Several areas in one picture', 'The strength scales with the size of each area'], + faq: [ + ['Which way hides best?', 'A solid box. Blur and pixelation can sometimes be reversed or guessed by software, while a solid box replaces the original pixels.'], + ['Does it find faces automatically?', 'Not at the moment. You drag over the areas yourself.'], + ], + }, + 'filters-image': { + title: 'Photo filters and adjustments online | Ream', + description: 'Adjust brightness, contrast, colour, warmth and sharpness, or use a ready-made look. Many pictures at once.', + intro: 'Improve or restyle photos. Move the sliders for brightness, contrast, saturation, warmth, sepia, vignette, blur and sharpness, or start from a ready-made look such as black and white. See the result before you save, on one picture or many.', + points: ['Eight adjustments you can combine', 'Ready-made looks as a starting point', 'The same settings applied to every picture you add'], + faq: [ + ['Can I apply the same filter to many photos?', 'Yes. Add them all and the settings apply to every picture.'], + ['Is the original changed?', 'No. Your file stays as it is, and the edited picture is saved as a new one.'], + ], + }, + meme: { + title: 'Meme maker: add captions to any image | Ream', + description: 'Add bold top and bottom captions to a picture and download your meme. Runs in your browser; nothing is uploaded.', + intro: 'Make a meme from any picture. Type a top caption, a bottom caption or both; they are drawn as big letters with a black outline, sized to fit the picture. Download it in the picture\'s own format.', + points: ['A top caption, a bottom caption, or both', 'Bold letters with a black outline, white by default', 'Choose the caption size and colour'], + faq: [ + ['Is my picture uploaded to a meme site?', 'No. The caption is drawn by your own browser and the picture never leaves your device.'], + ['Which pictures work?', 'JPG, PNG, WebP, GIF and BMP. A GIF or BMP is saved as a PNG, and only the first frame of a GIF is used.'], + ], + }, +} diff --git a/packages/tools/src/seo/index.ts b/packages/tools/src/seo/index.ts new file mode 100644 index 0000000..9d2791f --- /dev/null +++ b/packages/tools/src/seo/index.ts @@ -0,0 +1,23 @@ +import type { Tool } from '@ream/core' +import { convertSeo } from './convert.ts' +import { imageSeo } from './image.ts' +import { pdfSeo } from './pdf.ts' +import type { ToolSeo } from './types.ts' + +export type { ToolSeo } from './types.ts' + +/** the page text of every tool, by id (`seo.test.ts` fails when a tool has none) */ +export const toolSeo: Record<string, ToolSeo> = { ...pdfSeo, ...convertSeo, ...imageSeo } + +/** a tool's page text; one made from its manifest when nothing has been written yet, so a new tool never ships without a page */ +export function seoOf(tool: Tool): ToolSeo { + return ( + toolSeo[tool.id] ?? { + title: `${tool.title} online | Ream`, + description: `${tool.description}. It runs on your device, so your files are never uploaded.`, + intro: `${tool.description}. It runs on your device, so your files are never uploaded.`, + points: [], + faq: [], + } + ) +} diff --git a/packages/tools/src/seo/pdf.ts b/packages/tools/src/seo/pdf.ts new file mode 100644 index 0000000..17b4cce --- /dev/null +++ b/packages/tools/src/seo/pdf.ts @@ -0,0 +1,184 @@ +import type { ToolSeo } from './types.ts' + +export const pdfSeo: Record<string, ToolSeo> = { + 'merge-pdf': { + title: 'Merge PDF files online, free and private | Ream', + description: 'Combine several PDFs into one file in your browser. Set the order and keep bookmarks and form fields. Nothing is uploaded.', + intro: 'Join two or more PDFs into a single document. Add the files, put them in the order you want with the arrows, and download one merged PDF. Ream does the work on your own device, so your documents are never uploaded.', + points: ['Add as many PDFs as you need and move them up or down to set the order', 'Keeps bookmarks, links and form fields from the files you combine', 'Asks for the password of a protected file instead of failing'], + faq: [ + ['Is there a limit on how many PDFs I can merge?', 'Up to 50 files at a time, 200 MB each and 500 MB in all. For more than that, merge in two rounds.'], + ['Can I merge only some pages of a PDF?', 'Not in this tool. Use Split PDF or Organize pages to make the pages you want first, then merge the results.'], + ], + }, + 'split-pdf': { + title: 'Split a PDF into pages or ranges online | Ream', + description: 'Split a PDF by page ranges like 1-3,5, or into a new file every few pages. It runs in your browser and nothing is uploaded.', + intro: 'Cut a PDF into smaller files. Type the page ranges you want, such as 1-3,5, or choose a new file every few pages. When the result has several files, they download together in one ZIP.', + points: ['Ranges such as 1-3,5-8 make one file each', 'Or start a new file every 1, 2, 5 or any number of pages', 'Pages keep their text, pictures and size exactly as they were'], + faq: [ + ['What do the page ranges mean?', '1-3 is pages one to three. A comma starts the next file, so 1-3,5 gives one file with pages 1 to 3 and another with page 5.'], + ['Can I extract just one page?', 'Yes. Enter that page number as the range, for example 7, and download the one-page PDF.'], + ], + }, + 'compress-pdf': { + title: 'Compress PDF online, free and private | Ream', + description: 'Make a PDF smaller without losing its text. Pick lossless, balanced or small, and see the new size before you save.', + intro: 'Reduce the size of a PDF so it is easier to email or upload. Ream repacks the file and, at the balanced and small levels, brings large pictures down to the resolution they are shown at. Text stays text, so it remains sharp and searchable.', + points: ['Three levels: lossless, balanced (pictures at 150 dpi) and small (96 dpi)', 'The new size is shown while you choose, before you download', 'A file that cannot get smaller is returned as it was'], + faq: [ + ['Will compressing hurt the quality?', 'Lossless keeps every picture exactly and only repacks the file. Balanced and small lower the resolution and quality of photographs, which is where most of the saving is. Text and line drawings stay sharp.'], + ['Why did my PDF barely shrink?', 'A PDF that is mostly text, or whose pictures are already small, has little left to save. Ream then keeps your original rather than making a larger file.'], + ], + }, + watermark: { + title: 'Add a text watermark to a PDF online | Ream', + description: 'Stamp text such as CONFIDENTIAL across the pages of a PDF. Set size, colour, opacity, angle and position. Runs in your browser.', + intro: 'Put a line of text over, or behind, the pages of a PDF: a status like DRAFT, a name, a notice. Choose the font, size, colour, opacity and angle, place it once per page or tile it, and pick which pages get it.', + points: ['Over or behind the content of each page', 'One mark per page, or repeated across it', 'Use your own font file for any alphabet or brand'], + faq: [ + ['Can a watermark be taken off again?', 'It is drawn into the pages of the new file, so someone with a PDF editor could cover or remove it. To hide information for good, use Redact PDF.'], + ['Can I watermark only some pages?', 'Yes. Enter the pages, such as 1-3, 5, or leave it empty to mark them all.'], + ], + }, + 'page-numbers': { + title: 'Add page numbers to a PDF online | Ream', + description: 'Number the pages of a PDF as 1, Page 1, 1 of 10 or Page 1 of 10. Choose the corner, size and colour, and skip a cover.', + intro: 'Add page numbers to a PDF that has none. Pick a style, one of six places on the page, a start number and the first page to number, so a cover can stay blank. The numbers are stamped onto each page of a new copy.', + points: ['Four styles: 1, Page 1, 1 of N and Page 1 of N', 'Top or bottom, left, centre or right', 'Start from any page, with any starting number'], + faq: [ + ['Can I leave the cover without a number?', 'Yes. Choose the page to start numbering from and the pages before it stay blank.'], + ['Do the numbers sit correctly on rotated pages?', 'Yes. They are placed as the page is displayed, so they appear in the chosen corner of landscape and rotated pages too.'], + ], + }, + 'crop-pdf': { + title: 'Crop PDF pages online, free and private | Ream', + description: 'Drag to choose the area of a PDF page to keep, for one page or all of them. Delete the rest for good, or just hide it.', + intro: 'Trim margins or cut a page down to the part you need. Drag a rectangle on the page, apply it to every page or give each page its own area, and decide whether the cropped-out part is deleted from the file or only hidden.', + points: ['Draw the area on the page itself, at any zoom', 'One area for all pages, or a different one for each page', 'Delete what is cropped away, or only hide it'], + faq: [ + ['Is the cropped-out part really gone?', 'With Delete them chosen, text, pictures and lines that lie entirely outside the selection are removed from the file. Just hide them only makes the page smaller; the edges stay in the file.'], + ['Can I crop different pages differently?', 'Yes. Switch to a separate selection for each page, and pages without one are left as they are.'], + ], + }, + 'redact-pdf': { + title: 'Redact PDF: remove text and images for good | Ream', + description: 'Remove sensitive text, pictures and lines from a PDF permanently, not just cover them. Runs on your device; nothing is uploaded.', + intro: 'Mark areas of a page and Ream removes what is under them from the file: the text itself, the parts of pictures and the lines, not only a black box drawn on top. It can also clear document properties and hidden data. Everything happens on your device.', + points: ['Draw boxes on any page, or the same boxes on every page', 'Text, picture pixels and lines under a box are taken out, so they cannot be copied', 'Optionally clears properties, metadata, thumbnails and private data'], + faq: [ + ['Is redaction permanent?', 'Yes for what is under the boxes: the text and picture data are removed from the new file, so copying, searching or opening it in another tool finds nothing there. Keep your original safe, because the redacted copy cannot be undone.'], + ['Can it find words to redact automatically?', 'Not at the moment. You mark the areas yourself.'], + ], + }, + 'fill-pdf-form': { + title: 'Fill in PDF forms online, free and private | Ream', + description: 'Type into the fields of a PDF form, tick boxes and choose from lists, then save. Optionally lock the answers. No upload.', + intro: 'Open a PDF form, type into its fields, tick the boxes and pick from the lists, then download the filled copy. If you want the answers to be final, lock them so they become part of the page and can no longer be edited.', + points: ['Text fields, check boxes, radio buttons and choice lists', 'Fields keep their limits, such as a maximum length', 'Lock the answers to make them permanent'], + faq: [ + ['Does it work with every PDF form?', 'It fills standard PDF forms (AcroForm), the usual kind. Forms built with XFA, a rare Adobe-specific format, are not supported.'], + ['What does locking the answers do?', 'It draws the answers onto the page and removes the fields, so the file looks the same everywhere and nobody can change what you typed.'], + ], + }, + 'edit-pdf': { + title: 'Edit PDF online: add text, images and shapes | Ream', + description: 'Add text, pictures, shapes, drawings, highlights, comments and form fields to a PDF, or change what is already on the page.', + intro: 'A PDF editor that runs in your browser. Add text and pictures, draw shapes and freehand lines, highlight or underline text, leave comments and create form fields. You can also change or delete the lines of text and pictures already on a page, and erase areas.', + points: ['Add text, pictures, shapes, drawings and links', 'Highlight, underline, strike out and comment on text', 'Change or remove the page\'s own text and pictures, with undo'], + faq: [ + ['Can I change the text that is already in my PDF?', 'Pick a line and change or delete it. If the file\'s own font does not have a letter you type, Ream uses a similar font for that line.'], + ['Can I edit a scanned PDF?', 'A scan is a picture of a page, so you can cover, erase or add to it, but its words are not text and cannot be changed. Ream has no text recognition (OCR).'], + ], + }, + metadata: { + title: 'Edit PDF metadata: title, author, keywords | Ream', + description: 'Change the title, author, subject and keywords stored in a PDF file. Runs in your browser; nothing is uploaded.', + intro: 'Every PDF carries properties that readers show in the title bar and the file info: title, author, subject and keywords. See what yours says, change or empty them, then download the updated file. Your original is left untouched.', + points: ['Edit the title, author, subject and keywords', 'See what the file says now before you share it', 'Download an updated copy and keep your original'], + faq: [ + ['Why edit a PDF\'s metadata?', 'The title shows in browser tabs and search results, and the author can reveal who made a file or which program they used. Setting or clearing them before you share a PDF avoids surprises.'], + ['Does it change the pages?', 'No. The pages, text and pictures are carried into the new file unchanged.'], + ], + }, + 'extract-images': { + title: 'Extract images from a PDF online | Ream', + description: 'Save the pictures inside a PDF as separate image files. Skip tiny icons with a size filter. Nothing leaves your device.', + intro: 'Pull the photographs and graphics out of a PDF. Ream finds every picture stored in the file, saves each as an image, and gives them to you together in a ZIP. A minimum size setting skips icons, bullets and thin rules.', + points: ['Finds pictures on the pages and inside nested content', 'Skips tiny pictures with a minimum size', 'Everything arrives together in one ZIP'], + faq: [ + ['Does it take a screenshot of each page?', 'No. It extracts the pictures that are stored in the file. To save whole pages as images, use PDF to image.'], + ['Why did it find fewer pictures than I see?', 'Charts and drawings are made of lines and shapes, not pictures, so there is nothing to extract from them. PDF to image saves how a page looks.'], + ], + }, + 'protect-pdf': { + title: 'Password protect a PDF online, with AES | Ream', + description: 'Lock a PDF with a password using AES-256 encryption, and choose whether printing, copying and editing are allowed.', + intro: 'Add a password so that only people who know it can open your PDF. Ream encrypts the file with AES-256 on your device, and you can also restrict printing, copying text and editing. The password is never sent anywhere.', + points: ['AES-256, or AES-128 for very old readers', 'Type the password twice to catch a slip', 'Optionally restrict printing, copying and changes'], + faq: [ + ['Can I get the file back if I forget the password?', 'No. The password is not stored anywhere, not even by Ream, and a strong one cannot be guessed. Keep it somewhere safe.'], + ['How safe is the protection?', 'AES-256 is the strongest encryption PDF supports. Restrictions on printing or copying are a request that most readers follow, but a determined person can remove them. The password to open the file is what really protects it.'], + ], + }, + 'unlock-pdf': { + title: 'Unlock a PDF: remove its password online | Ream', + description: 'Remove the password and the restrictions from a PDF you know the password of. Runs in your browser; nothing is uploaded.', + intro: 'Save a copy of a protected PDF that opens without a password and allows printing, copying and editing. You enter the password you were given, Ream decrypts the file on your device and writes it out unprotected.', + points: ['Works with the password to open and the owner password', 'Removes limits on printing, copying and editing', 'Needs the password: it does not guess or crack them'], + faq: [ + ['Can it unlock a PDF if I forgot the password?', 'No. Ream needs the password and does not try to break passwords. A file that opens freely but blocks printing or copying needs no password to unlock.'], + ['Is it all right to remove the protection?', 'Only from files you are allowed to change. A password or a restriction often reflects someone\'s wishes about the document.'], + ], + }, + 'sign-pdf': { + title: 'Sign a PDF online: draw or type your signature | Ream', + description: 'Draw, type or upload your signature and place it on a PDF page. Runs on your device, so the document is never uploaded.', + intro: 'Add your signature to a PDF without printing it. Draw it with a mouse or finger, type your name in a handwriting font, or upload a picture of your signature, then drag it into place on the last page, one page or every page.', + points: ['Draw, type or upload a signature', 'Drag and resize it on the page', 'Sign the last page, a chosen page or all of them'], + faq: [ + ['Is this a legally binding digital signature?', 'It places a picture of your signature on the page, like signing on paper. It is not a certificate-based digital signature, which proves who signed and detects later changes. Ask the recipient which kind they need.'], + ['Is my signature stored?', 'No. It exists only in the page while you work, and in the PDF you download.'], + ], + }, + 'organize-pdf': { + title: 'Organize PDF pages: reorder, rotate, delete | Ream', + description: 'See every page as a thumbnail, then reorder, rotate, copy or delete pages and save the result as a new PDF.', + intro: 'Rearrange a PDF visually. Every page is shown as a thumbnail you can move earlier or later, turn left or right, copy or delete. When it looks right, download the new file.', + points: ['Move pages to a new place', 'Turn single pages left or right', 'Copy a page to use it twice, or delete the ones you do not need'], + faq: [ + ['Do the pages lose quality?', 'No. Pages are carried into the new file as they are, not redrawn as pictures.'], + ['Can I use pages from several PDFs?', 'Not in this tool. Merge the files first with Merge PDF, then organise the result.'], + ], + }, + 'bookmarks-pdf': { + title: 'Add and edit PDF bookmarks online | Ream', + description: 'Add, rename and reorder the bookmarks (outline) of a PDF so readers can jump to sections. Nothing is uploaded.', + intro: 'Bookmarks appear in the side panel of a PDF reader and let people jump to a section. See the ones a file has, rename or reorder them, add new ones that point to a page, and save the updated PDF.', + points: ['Add a bookmark for any page', 'Rename them and put them in order', 'See the bookmarks the file already has'], + faq: [ + ['What is a PDF bookmark?', 'An entry in the outline that readers show beside the pages. Clicking it jumps to a page. Long reports and books use them as a table of contents.'], + ['Will my existing bookmarks be kept?', 'Yes. Ream reads them from the file, and you change what you want.'], + ], + }, + 'repair-pdf': { + title: 'Repair a damaged PDF online | Ream', + description: 'Recover a PDF that will not open or shows errors, and save a clean copy. Runs in your browser; nothing is uploaded.', + intro: 'Some PDFs break when a download is cut short or a program writes them badly. Ream reads what is still there, rebuilds the index of the file and writes a clean copy that opens normally, whenever the pages can be found.', + points: ['Rebuilds a broken index of the file', 'Writes a clean, tidy copy', 'Says so when there is nothing it can recover'], + faq: [ + ['Will it recover everything?', 'It recovers what is still in the file. If the damaged part held pages or pictures, those cannot be brought back.'], + ['How do I know the repair worked?', 'The preview shows the pages of the repaired file. If they look right, download it.'], + ], + }, + 'pdf-to-text': { + title: 'Convert PDF to text or Markdown online | Ream', + description: 'Get the text out of a PDF as plain text or Markdown, in reading order. Runs in your browser; nothing is uploaded.', + intro: 'Copy the text of a PDF without selecting it page by page. Choose plain text or Markdown and Ream reads each page in reading order, handling columns, and gives you one file.', + points: ['Plain text or Markdown', 'Text is read in order, including pages with columns', 'Preview the result before you download'], + faq: [ + ['Does it work on scanned PDFs?', 'Only if the PDF contains real text. A scan is a picture of a page, and Ream has no text recognition (OCR) yet, so it finds no text in it.'], + ['Will the text match what I see?', 'Mostly. Reading order is worked out from where the text sits on the page, which is a good guess for ordinary documents and less certain for unusual layouts.'], + ], + }, +} diff --git a/packages/tools/src/seo/types.ts b/packages/tools/src/seo/types.ts new file mode 100644 index 0000000..afa1779 --- /dev/null +++ b/packages/tools/src/seo/types.ts @@ -0,0 +1,17 @@ +/** + * 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. + */ +export type ToolSeo = { + /** the page's title in search results, 60 characters at most, ending in "| Ream" */ + title: string + /** the snippet under it, 70 to 155 characters */ + description: string + /** the paragraph under the heading: what the tool does, in plain words */ + intro: string + /** three short things you can do with it */ + points: string[] + /** two questions people ask, with straight answers */ + faq: [question: string, answer: string][] +} diff --git a/scripts/nginx-conf.ts b/scripts/nginx-conf.ts index 4510dd7..92b2662 100644 --- a/scripts/nginx-conf.ts +++ b/scripts/nginx-conf.ts @@ -18,6 +18,10 @@ for (const line of readFileSync(file, 'utf8').split('\n')) { } } +// rules for a whole address (https://:project.pages.dev/*) are Cloudflare's: a self-hosted copy has one host, and a +// location can't match one +for (let i = rules.length; i--; ) if (/^https?:\/\//.test(rules[i].path)) rules.splice(i, 1) + const every = rules.filter((r) => r.path === '/*').flatMap((r) => r.headers) // pages and anything without a rule of its own are checked for a newer version each time, like Cloudflare Pages does const fallback: [string, string][] = [['Cache-Control', 'public, max-age=0, must-revalidate']] @@ -37,6 +41,8 @@ const out = [ ' root /usr/share/nginx/html;', ' index index.html;', ' server_tokens off;', + // a real 404 status with the app's own page (Cloudflare Pages does the same with 404.html) + ' error_page 404 /404.html;', '', ' location / {', ' try_files $uri $uri/ =404;', diff --git a/scripts/og.ts b/scripts/og.ts new file mode 100644 index 0000000..4e6faf3 --- /dev/null +++ b/scripts/og.ts @@ -0,0 +1,40 @@ +// Draws the social card (apps/web/public/og.png, 1200x630: what a link to Ream shows in chat apps and on social sites) +// with headless Chrome. Run again after changing the wording or the look; the PNG is committed. +// node scripts/og.ts +import { readFileSync } from 'node:fs' +import { join } from 'node:path' +import { openChrome } from './chrome.ts' + +const root = join(import.meta.dirname, '..') +const font = (file: string) => readFileSync(join(root, 'node_modules/@fontsource', file)).toString('base64') +const mark = readFileSync(join(root, 'apps/web/icons/icon.svg'), 'utf8') + +// the ground, steel accent and type are the site's (packages/ui/src/theme.css, light mode) +const html = `<!doctype html><meta charset="utf-8"><style> +@font-face { font-family: 'Barlow Condensed'; font-weight: 600; src: url(data:font/woff2;base64,${font('barlow-condensed/files/barlow-condensed-latin-600-normal.woff2')}) } +@font-face { font-family: 'Barlow'; font-weight: 400; src: url(data:font/woff2;base64,${font('barlow/files/barlow-latin-400-normal.woff2')}) } +* { box-sizing: border-box } +body { margin: 0; width: 1200px; height: 630px; background: #f2f2f3; color: #1d1d1f; font-family: Barlow, sans-serif; position: relative; overflow: hidden } +.frame { position: absolute; inset: 40px; border: 2px solid #d4d4d7 } +.brand { position: absolute; left: 88px; top: 80px; display: flex; align-items: center; gap: 18px; font: 600 44px 'Barlow Condensed'; letter-spacing: 0.04em; text-transform: uppercase } +.brand img { width: 56px; height: 56px; display: block } +h1 { position: absolute; left: 88px; top: 190px; margin: 0; font: 600 108px/1.02 'Barlow Condensed'; text-transform: uppercase; letter-spacing: 0.005em } +h1 span { color: #416180 } +p { position: absolute; left: 88px; bottom: 84px; margin: 0; font-size: 30px; color: #5d5d60 } +</style> +<div class="frame"></div> +<div class="brand"><img src="data:image/svg+xml;base64,${Buffer.from(mark).toString('base64')}">Ream</div> +<h1>The file toolkit that runs on <span>your computer.</span></h1> +<p>PDFs, images and Office files. Nothing is uploaded.</p>` + +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<string, string>() +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>([^<]*)<\/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') +// 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 +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('tools/pdf/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.`)