feat(website): add release OG image generator

scripts/dictionary.txt

@@ -4,6 +4,7 @@ antd
 apng
 apos
 applescript
+artboard
 Asus
 atrules
 autodocs
@@ -54,6 +55,7 @@ fnames
 frontends
 fullhash
 gzipped
+Grotesk
 icss
 idents
 iife
@@ -116,7 +118,9 @@ publint
 pxtorem
 quasis
 quxx
+rasterizes
 rebranded
+resvg
 rolldown
 rootdir
 rsbuild

website/AGENTS.md

@@ -14,8 +14,36 @@ This is the documentation website for Rstest, built with [Rspress](https://rspre
 pnpm dev      # Start dev server
 pnpm build    # Build for production
 pnpm preview  # Preview production build
+pnpm gen:og   # Generate a release Open Graph image (see below)
 ```
 
+## Open Graph image generation
+
+Per-release og images live in [rstackjs/rstack-design-resources](https://github.com/rstackjs/rstack-design-resources) and are served by the `assets.rspack.rs` CDN. The template lives **in this repo** to keep design-resources as a passive PNG store.
+
+- `scripts/og-image/cli.mts` — entry, parses `--version`/`--description`/`--out`
+- `scripts/og-image/render.mts` — fetches the Rstest logo SVG → rasterizes → composes with [satori](https://github.com/vercel/satori) → renders with [@resvg/resvg-js](https://github.com/yisibl/resvg-js) at 2x zoom for retina
+- `scripts/og-image/template.mts` — [satori-html](https://github.com/natemoo-re/satori-html) template, modeled after the `Rsbuild og image 1.0` artboard in design-resources
+
+### Release workflow
+
+1. Run `pnpm gen:og --version <ver> --description "<tagline>"` from `website/`. Use `--out` to write directly into a local clone of the design-resources repo at `rstest/assets/rstest-og-image-v{version-with-hyphens}.png` (e.g. `v0-5.png`).
+2. Commit the PNG in the design-resources repo and open a PR — that repo is the only place release PNGs are stored.
+3. After CDN deploy, the per-blog-post URL becomes available at `assets.rspack.rs/rstest/assets/rstest-og-image-v0-5.png`. The `head` function hook in `rspress.config.ts` routes each blog `routePath` to its matching URL.
+
+### Do
+
+- Use Space Grotesk (committed under `scripts/og-image/assets/fonts/` with SIL OFL license)
+- Render at 2x via `Resvg({ fitTo: { mode: 'zoom', value: 2 } })` so the PNG stays crisp on retina displays
+- Before committing the PNG to design-resources, run it through [TinyPNG](https://tinypng.com) (or Squoosh / ImageOptim / `pngquant`) — the raw resvg output is ~500 KB, palette quantization drops it to ~140 KB with no visible loss
+- Fetch the logo from the canonical CDN URL at generation time, not from a committed copy
+
+### Don't
+
+- Don't depend on packages like `geist` that pull in framework peer deps (`next>=13.2`); commit raw `.ttf` files directly instead
+- Don't write generated PNGs into this repo; they belong in design-resources
+- Don't bake the logo into a static asset; always fetch the SVG so logo updates propagate automatically
+
 ## Writing style guidelines
 
 When writing or editing documentation, follow these principles:

website/README.md

@@ -15,3 +15,7 @@ The same as Rspack: [Writing style guide](https://github.com/web-infra-dev/rspac
 For images you use in the document, it's better to upload them to the [rstackjs/rstack-design-resources](https://github.com/rstackjs/rstack-design-resources) repository, so the size of the current repository doesn't get too big.
 
 After you upload the images there, they will be automatically deployed under the <https://assets.rspack.rs/>.
+
+## Open Graph images
+
+`scripts/og-image/` generates per-release Open Graph images used by the `og:image` and `twitter:image` meta tags on each release blog post. See [AGENTS.md](./AGENTS.md#open-graph-image-generation) for the template architecture and release workflow.

website/package.json

@@ -9,9 +9,11 @@
     "build": "rspress build",
     "build:agent-install": "node scripts/buildAgentInstall.mjs",
     "dev": "rspress dev",
+    "gen:og": "node --experimental-strip-types scripts/og-image/cli.mts",
     "preview": "rspress preview"
   },
   "devDependencies": {
+    "@resvg/resvg-js": "^2.6.2",
     "@rsbuild/plugin-sass": "^1.5.2",
     "@rspress/core": "2.0.11",
     "@rspress/plugin-algolia": "2.0.11",
@@ -26,6 +28,8 @@
     "rsbuild-plugin-open-graph": "^1.1.2",
     "rspress-plugin-font-open-sans": "^1.0.3",
     "rspress-plugin-sitemap": "^1.2.1",
+    "satori": "^0.26.0",
+    "satori-html": "^0.3.2",
     "typescript": "^6.0.3"
   }
 }

website/scripts/og-image/assets/fonts/LICENSE.txt

@@ -0,0 +1,93 @@
+Copyright 2020 The Space Grotesk Project Authors (https://github.com/floriankarsten/space-grotesk)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

website/scripts/og-image/cli.mts

@@ -0,0 +1,47 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import { renderOgImage } from './render.mts';
+
+const { values } = parseArgs({
+  options: {
+    version: { type: 'string', short: 'v' },
+    description: { type: 'string' },
+    out: { type: 'string', short: 'o' },
+    help: { type: 'boolean', short: 'h' },
+  },
+});
+
+if (values.help || !values.version) {
+  console.log(`Usage: pnpm gen:og --version <ver> [options]
+
+Options:
+  --version, -v       Release version, e.g. 0.5 (required)
+  --description       Optional tagline rendered below the version
+  --out, -o           Output PNG path
+                      (default: rstest-og-image-v<ver>.png in cwd)
+  --help, -h          Show this help
+
+After generating, commit the PNG to rstackjs/rstack-design-resources
+under rstest/assets/ so the assets.rspack.rs CDN can serve it.`);
+  process.exit(values.help ? 0 : 1);
+}
+
+const versionSlug = values.version.replace(/\./g, '-');
+const outPath = path.resolve(
+  values.out ?? `rstest-og-image-v${versionSlug}.png`,
+);
+
+const png = await renderOgImage({
+  version: values.version,
+  description: values.description,
+});
+
+await mkdir(path.dirname(outPath), { recursive: true });
+await writeFile(outPath, png);
+
+console.log(`Wrote ${outPath} (${(png.length / 1024).toFixed(1)} KB)`);
+console.log(
+  'Tip: compress the PNG before committing — typically drops the file to ~1/4 the size with no visible loss.',
+);
+console.log('  https://tinypng.com (or Squoosh / ImageOptim)');

website/scripts/og-image/render.mts

@@ -0,0 +1,144 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Resvg } from '@resvg/resvg-js';
+import satori from 'satori';
+import {
+  buildTemplate,
+  CANVAS_HEIGHT,
+  CANVAS_WIDTH,
+  type TemplateOptions,
+} from './template.mts';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const fontsDir = path.join(here, 'assets/fonts');
+
+const LOGO_URL = 'https://assets.rspack.rs/rstest/rstest-logo.svg';
+
+// Lucide-mirrored icon node markup, normalized to a 24x24 viewBox.
+// Sources: lucide-react `circle-check`, `circle-x`, `loader`, `circle-dashed`
+// — the same icons rendered by @rstest/browser-ui for pass / fail / running /
+// skip status, see packages/browser-ui/src/utils/constants.tsx.
+const ICON_PATHS = {
+  pass: '<circle cx="12" cy="12" r="10"/><path d="m9 12 2 2 4-4"/>',
+  fail: '<circle cx="12" cy="12" r="10"/><path d="m15 9-6 6"/><path d="m9 9 6 6"/>',
+  running:
+    '<path d="M12 2v4"/><path d="m16.2 7.8 2.9-2.9"/><path d="M18 12h4"/><path d="m16.2 16.2 2.9 2.9"/><path d="M12 18v4"/><path d="m4.9 19.1 2.9-2.9"/><path d="M2 12h4"/><path d="m4.9 4.9 2.9 2.9"/>',
+  skip: '<path d="M10.1 2.182a10 10 0 0 1 3.8 0"/><path d="M13.9 21.818a10 10 0 0 1-3.8 0"/><path d="M17.609 3.721a10 10 0 0 1 2.69 2.7"/><path d="M2.182 13.9a10 10 0 0 1 0-3.8"/><path d="M20.279 17.609a10 10 0 0 1-2.7 2.69"/><path d="M21.818 10.1a10 10 0 0 1 0 3.8"/><path d="M3.721 6.391a10 10 0 0 1 2.7-2.69"/><path d="M6.391 20.279a10 10 0 0 1-2.69-2.7"/>',
+} as const;
+
+type IconKind = keyof typeof ICON_PATHS;
+
+// Hues mirror @rstest/browser-ui status colors (green/amber/red/gray Geist
+// family) so the background reads as "test runner status" at first glance.
+const ICON_COLORS: Record<IconKind, string> = {
+  pass: '#16a34a',
+  running: '#d97706',
+  fail: '#dc2626',
+  skip: '#71717a',
+};
+
+const ICON_KINDS: IconKind[] = ['pass', 'running', 'fail', 'skip'];
+
+// The center vignette is baked into the SVG (rather than layered via CSS) so
+// satori's `background` shorthand doesn't have to handle a
+// `radial-gradient(...), url(...)` layering with data URIs — which it
+// doesn't.
+function buildBackgroundSvg(width: number, height: number): string {
+  // iconSize=70 is the largest value that divides the vertical axis cleanly
+  // (rowSpacing = 1.5 * 70 = 105, 630 / 105 = 6 → rows=7 with the last row
+  // landing exactly on y=height). Horizontal can't divide cleanly at the
+  // same iconSize (1200/105 ≈ 11.43), so cols=12 with colSpacing forced to
+  // 1200/11 ≈ 109.09 — a ~4px deviation. The integer constraint for both
+  // axes simultaneously only admits iconSize ≤ 20 (GCD(800, 420) = 20),
+  // which is too small to read as a test status icon.
+  const iconSize = 70;
+  const scale = iconSize / 24;
+  const rows = 7;
+  const cols = 12;
+  const rowSpacing = height / (rows - 1);
+  const colSpacing = width / (cols - 1);
+  const OPACITY_BASE = 0.16;
+  const OPACITY_SPREAD = 0.1;
+
+  let icons = '';
+  for (let r = 0; r < rows; r++) {
+    // Brick pattern: offset by colSpacing/2 (not iconSize/2 — colSpacing is
+    // wider), intentionally breaking first/last-column alignment on odd rows.
+    const rowOffset = r % 2 === 1 ? colSpacing / 2 : 0;
+    const cy = r * rowSpacing;
+    for (let c = 0; c < cols; c++) {
+      const cx = c * colSpacing + rowOffset;
+      if (cx > width + iconSize / 2) continue;
+      const kind = ICON_KINDS[Math.floor(Math.random() * ICON_KINDS.length)]!;
+      const color = ICON_COLORS[kind];
+      // Only `running` (an 8-spoke loader) reads as "spinner caught mid-tick"
+      // when rotated. Pass/fail/skip are radially symmetric — rotating them
+      // just looks like a wobble.
+      const rotation =
+        kind === 'running' ? (Math.random() * 360).toFixed(1) : '0';
+      const opacity = (
+        OPACITY_BASE +
+        (Math.random() * 2 - 1) * OPACITY_SPREAD
+      ).toFixed(3);
+      icons += `<g transform="translate(${cx.toFixed(1)} ${cy.toFixed(1)}) rotate(${rotation}) scale(${scale.toFixed(3)}) translate(-12 -12)" stroke="${color}" stroke-opacity="${opacity}" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" fill="none">${ICON_PATHS[kind]}</g>`;
+    }
+  }
+
+  const vignette = `<defs><radialGradient id="vig" cx="50%" cy="55%" r="60%"><stop offset="0%" stop-color="#ffffff" stop-opacity="0.85"/><stop offset="100%" stop-color="#ffffff" stop-opacity="0"/></radialGradient></defs><rect width="${width}" height="${height}" fill="url(#vig)"/>`;
+
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}"><rect width="${width}" height="${height}" fill="#ffffff"/>${icons}${vignette}</svg>`;
+}
+
+function svgToPngDataUrl(svg: string, width: number): string {
+  const png = new Resvg(svg, { fitTo: { mode: 'width', value: width } })
+    .render()
+    .asPng();
+  return `data:image/png;base64,${png.toString('base64')}`;
+}
+
+async function fetchLogoSvg(): Promise<string> {
+  const response = await fetch(LOGO_URL);
+  if (!response.ok) {
+    throw new Error(
+      `Failed to fetch logo from ${LOGO_URL}: ${response.status} ${response.statusText}`,
+    );
+  }
+  return response.text();
+}
+
+export type RenderOptions = Omit<
+  TemplateOptions,
+  'logoDataUrl' | 'backgroundDataUrl'
+>;
+
+export async function renderOgImage(opts: RenderOptions): Promise<Buffer> {
+  const [regular, bold, logoSvg] = await Promise.all([
+    readFile(path.join(fontsDir, 'SpaceGrotesk-Regular.ttf')),
+    readFile(path.join(fontsDir, 'SpaceGrotesk-Bold.ttf')),
+    fetchLogoSvg(),
+  ]);
+
+  const tree = buildTemplate({
+    ...opts,
+    // 512px source stays crisp when the og PNG is rendered at 2x.
+    logoDataUrl: svgToPngDataUrl(logoSvg, 512),
+    backgroundDataUrl: svgToPngDataUrl(
+      buildBackgroundSvg(CANVAS_WIDTH, CANVAS_HEIGHT),
+      CANVAS_WIDTH,
+    ),
+  });
+
+  const svg = await satori(tree, {
+    width: CANVAS_WIDTH,
+    height: CANVAS_HEIGHT,
+    fonts: [
+      { name: 'Space Grotesk', data: regular, weight: 400, style: 'normal' },
+      { name: 'Space Grotesk', data: bold, weight: 700, style: 'normal' },
+    ],
+  });
+
+  // 2x zoom for retina; 2400x1260 fits Twitter/Facebook's ~5MB / 8192px limits.
+  const resvg = new Resvg(svg, { fitTo: { mode: 'zoom', value: 2 } });
+  return resvg.render().asPng();
+}