Skip to content

Open source alternative to Semrush and Ahrefs

Customize report share images and simplify report titles (#636)

Ben Senescubf4f2da000c4
diff --git a/.agents/skills/seo-report/SKILL.md b/.agents/skills/seo-report/SKILL.md
index 3e45ddeb..7dfbe1a9 100644
--- a/.agents/skills/seo-report/SKILL.md
+++ b/.agents/skills/seo-report/SKILL.md
@@ -34,7 +34,9 @@ Use a template only when the user names it, or asks for the kind of report a tem
## Title and summary
-- `title`: names the subject and the period, under 120 characters. "badseo.dev SEO audit, Sep 2026". Never "SEO Report" or "Analysis".
+- `title`: names the report type or specific subject and the full report date, under 120 characters. Use "Competitive Landscape — Sep 17, 2026" or "Keyword Research — Sep 17, 2026". Use the actual report date in `MMM D, YYYY` format, including the day and four-digit year; put the data coverage period in the report body. Never a generic "SEO Report" or "Analysis".
+- Omit the website from the title when the report is about the project's website. Compare hostnames, ignoring the protocol, `www.`, and trailing slash. If the subject is a different website, include its bare hostname, for example "Competitor Analysis: example.com — Sep 17, 2026". Also include the subject hostname when the project has no website set. Never put `https://` or a full URL in the title.
+- Use the same title in `save_report`, the HTML `<title>`, and the visible `<h1>` so the report list, share preview, and report agree.
- `summary`: markdown under 2,500 characters, in this order — the verdict, the single top action, then the key numbers. This is what `list_reports` returns and what you or another agent read instead of the HTML, so write it for a reader who will never open the page.
## The closing section: how this report was made
@@ -74,7 +76,7 @@ Copy this, keep the CSS as it is, and replace the ALL-CAPS placeholders. Each pr
<!doctype html>
<html lang="en"><head><meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
-<title>DOMAIN — REPORT TITLE</title>
+<title>REPORT TITLE</title>
<style>
/* One light look, on screen and on paper. The report is read inside the app,
which has its own theme toggle, and a saved document has no way to hear about
diff --git a/docs/LOCAL_DEVELOPMENT.md b/docs/LOCAL_DEVELOPMENT.md
index 60a763d0..104919ec 100644
--- a/docs/LOCAL_DEVELOPMENT.md
+++ b/docs/LOCAL_DEVELOPMENT.md
@@ -49,6 +49,19 @@ pnpm dev:agents
When using a git worktree, [portless](https://github.com/vercel-labs/portless) prefixes the branch name, for example `http://feature-name.open-seo.localhost:1355`.
+## Report share images
+
+To test a real report end to end, run the app with `AUTH_MODE=hosted`, share a
+local report, and open its `/s/<token>/og.png` URL. Inspect the share page's
+initial HTML for `og:image` and `twitter:image`, then revoke the share and check
+that the image returns 404. Report saves and changes to the displayed project
+hostname update the image URL's version. If rendering fails for a valid share,
+the image route redirects to the existing OpenSEO marketing card.
+Social platforms may retain their own previews; our image responses are
+`no-store` and check access on each request. An actual social crawler needs a
+publicly reachable page and image; the Access-protected preview environment
+supports manual inspection but cannot be fetched by those crawlers.
+
## Website and BadSEO
The marketing website (`web/`) and audit test site (`badseo/`) are separate
diff --git a/package.json b/package.json
index 755162a5..fe67e0c7 100644
--- a/package.json
+++ b/package.json
@@ -115,6 +115,7 @@
"robots-parser": "^3.0.1",
"sonner": "^2.0.7",
"tailwindcss": "^4.1.16",
+ "takumi-js": "2.13.7",
"tldts": "^7.0.25",
"yaml": "^2.9.0",
"zod": "^4.1.12"
diff --git a/plugins/openseo/skills/seo-report/SKILL.md b/plugins/openseo/skills/seo-report/SKILL.md
index 3e45ddeb..7dfbe1a9 100644
--- a/plugins/openseo/skills/seo-report/SKILL.md
+++ b/plugins/openseo/skills/seo-report/SKILL.md
@@ -34,7 +34,9 @@ Use a template only when the user names it, or asks for the kind of report a tem
## Title and summary
-- `title`: names the subject and the period, under 120 characters. "badseo.dev SEO audit, Sep 2026". Never "SEO Report" or "Analysis".
+- `title`: names the report type or specific subject and the full report date, under 120 characters. Use "Competitive Landscape — Sep 17, 2026" or "Keyword Research — Sep 17, 2026". Use the actual report date in `MMM D, YYYY` format, including the day and four-digit year; put the data coverage period in the report body. Never a generic "SEO Report" or "Analysis".
+- Omit the website from the title when the report is about the project's website. Compare hostnames, ignoring the protocol, `www.`, and trailing slash. If the subject is a different website, include its bare hostname, for example "Competitor Analysis: example.com — Sep 17, 2026". Also include the subject hostname when the project has no website set. Never put `https://` or a full URL in the title.
+- Use the same title in `save_report`, the HTML `<title>`, and the visible `<h1>` so the report list, share preview, and report agree.
- `summary`: markdown under 2,500 characters, in this order — the verdict, the single top action, then the key numbers. This is what `list_reports` returns and what you or another agent read instead of the HTML, so write it for a reader who will never open the page.
## The closing section: how this report was made
@@ -74,7 +76,7 @@ Copy this, keep the CSS as it is, and replace the ALL-CAPS placeholders. Each pr
<!doctype html>
<html lang="en"><head><meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
-<title>DOMAIN — REPORT TITLE</title>
+<title>REPORT TITLE</title>
<style>
/* One light look, on screen and on paper. The report is read inside the app,
which has its own theme toggle, and a saved document has no way to hear about
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index ed312346..9c74e28b 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -144,6 +144,9 @@ importers:
tailwindcss:
specifier: ^4.1.16
version: 4.2.1
+ takumi-js:
+ specifier: 2.13.7
tldts:
specifier: ^7.0.25
version: 7.0.25
@@ -2594,6 +2597,88 @@ packages:
peerDependencies:
vite: ^5.2.0 || ^6 || ^7
+ '@takumi-rs/[email protected]':
+ resolution: {integrity: sha512-Jbe1ik4bcVOOHDpa5RCjm5fe+LfJjjyebvvPBMekhEKXg6hlTbIEFmhr/GCxMOKUfaNsvb4amZ/bVCo0NDSCjA==}
+ engines: {node: '>=18'}
+ cpu: [arm64]
+ os: [darwin]
+
+ '@takumi-rs/[email protected]':
+ resolution: {integrity: sha512-PvmSmhjbSosM3XaHZ9VhFm1x7Xc9oZ5GqXlskiwZblKIi5S4EI43buhUd28xzcBlKkB/vC3c15Cj417XjnUk4g==}
+ engines: {node: '>=18'}
+ cpu: [x64]
+ os: [darwin]
+
+ '@takumi-rs/[email protected]':
+ resolution: {integrity: sha512-TGvDidIF3dtb7TMoJRF+0BET/v6eAuQxV8AXo/57GqO3TM9wjLt3AbkrFkzxSsaIRXlBQxCfb+GsS0YdGnpo4w==}
+ engines: {node: '>=18'}
+ cpu: [arm64]
+ os: [linux]
+ libc: [glibc]
+
+ '@takumi-rs/[email protected]':
+ resolution: {integrity: sha512-CL92+JeFbqlPfWI2SSQqLtcjWpxEsPYQ+wNhaqUWLnlTMfZfj+Fl3ERFLbmK+lYnGs7bzpPXLisd3GJQ37rTYw==}
+ engines: {node: '>=18'}
+ cpu: [arm64]
+ os: [linux]
+ libc: [musl]
+
+ '@takumi-rs/[email protected]':
+ resolution: {integrity: sha512-ZxoapyUDlInik93WIA9+Sk/ByOb3QGO7GaL9PA7OOdIlK5ovK9v9q88tZb1cvfxtIVzdE9HPBUhb5quNMcuXWg==}
+ engines: {node: '>=18'}
+ cpu: [x64]
+ os: [linux]
+ libc: [glibc]
+
+ '@takumi-rs/[email protected]':
+ resolution: {integrity: sha512-OqoVTd7mrlIwjKYYFizUwz+3zpnVsbrpLFPXFC+BmUxdFYNZwKa0R+Pk56EslyBZS3CuBy+RnBusHCvNC7+09g==}
+ engines: {node: '>=18'}
+ cpu: [x64]
+ os: [linux]
+ libc: [musl]
+
+ '@takumi-rs/[email protected]':
+ resolution: {integrity: sha512-evSyi/y3uV03U+PJfLeG2V3aRsmmWJ6elrFpkLtHebWwi49kXazTL5TYsCkPj5hA4i+rNs6z/t/BygLj1Krp8Q==}
+ engines: {node: '>=18'}
+ cpu: [arm64]
+ os: [win32]
+
+ '@takumi-rs/[email protected]':
+ resolution: {integrity: sha512-GawtljFxuJemQynlF5wryxtSLv18XNuKSjMt52xf66WMaBKt4eN6/b7yIZp9QqKPof8ip8uqFOt7fWVSUN+gHQ==}
+ engines: {node: '>=18'}
+ cpu: [x64]
+ os: [win32]
+
+ '@takumi-rs/[email protected]':
+ resolution: {integrity: sha512-FBkglt8kGBZwT2CHr+kppN+FH72Oy8gLIZz1BIbD9vNcocLrvtLsh1Y0nB18mOPmaROKGUVUXLPnIuWo49CRng==}
+ engines: {node: '>=18'}
+ peerDependencies:
+ csstype: '*'
+ peerDependenciesMeta:
+ csstype:
+ optional: true
+
+ '@takumi-rs/[email protected]':
+ resolution: {integrity: sha512-6AKk/ixuvoCEZD9/LPAz3kxTcwWHeZh15quhHIHYiVxFRl4x2LyKN8j6eZngiepYYsORXAuJ5YlTGA7uIRfeMQ==}
+ engines: {node: '>=18'}
+ peerDependencies:
+ preact: ^10.0.0
+ react: ^18.0.0 || ^19.0.0
+ peerDependenciesMeta:
+ preact:
+ optional: true
+ react:
+ optional: true
+
+ '@takumi-rs/[email protected]':
+ resolution: {integrity: sha512-tc2IFETJ9HtZpS94cL3qSTiecJhhR4RUTXbb3E8cyz6WKdyoZSFkL2r67xnidVtcv22RKTyfVJ2gxV7eWvF+mA==}
+ engines: {node: '>=20.19'}
+ peerDependencies:
+ csstype: '*'
+ peerDependenciesMeta:
+ csstype:
+ optional: true
+
'@tanstack/[email protected]':
resolution: {integrity: sha512-f85ZJXJnDIFOoykG/BFIixuAevJovCvJF391LPs6YjBAPhGYC50NWlx1y4iF/UmK5/cCMx+/JqI5SBOz7FanQQ==}
engines: {node: '>=18'}
@@ -5559,6 +5644,10 @@ packages:
resolution: {integrity: sha512-/tBrSQ36vCleJkAOsy9kbNTgaxvGbyOamC30PRePTQe/o1MFwEKHQk4Cn7BNGaPtjp+PuUrByJehM1hgxfq4sw==}
+ resolution: {integrity: sha512-6CuATUv1O6X/aD3T0OQIkv0nyesefJibamskfQxcQqKVl2CCk6kIX9E0e+glMTILTJC2I1IcrcFEPlmDlcexgQ==}
+ engines: {node: '>=20.19'}
+
resolution: {integrity: sha512-g9ljZiwki/LfxmQADO3dEY1CbpmXT5Hm2fJ+QaGKwSXUylMybePR7/67YW7jOrrvjEgL1Fmz5kzyAjWVWLlucg==}
engines: {node: '>=6'}
@@ -8031,6 +8120,61 @@ snapshots:
tailwindcss: 4.2.1
+ '@takumi-rs/[email protected]':
+ optional: true
+
+ '@takumi-rs/[email protected]':
+ optional: true
+
+ '@takumi-rs/[email protected]':
+ optional: true
+
+ '@takumi-rs/[email protected]':
+ optional: true
+
+ '@takumi-rs/[email protected]':
+ optional: true
+
+ '@takumi-rs/[email protected]':
+ optional: true
+
+ '@takumi-rs/[email protected]':
+ optional: true
+
+ '@takumi-rs/[email protected]':
+ optional: true
+
+ dependencies:
+ '@takumi-rs/helpers': 2.13.7([email protected])([email protected])
+ optionalDependencies:
+ '@takumi-rs/core-darwin-arm64': 2.13.7
+ '@takumi-rs/core-darwin-x64': 2.13.7
+ '@takumi-rs/core-linux-arm64-gnu': 2.13.7
+ '@takumi-rs/core-linux-arm64-musl': 2.13.7
+ '@takumi-rs/core-linux-x64-gnu': 2.13.7
+ '@takumi-rs/core-linux-x64-musl': 2.13.7
+ '@takumi-rs/core-win32-arm64-msvc': 2.13.7
+ '@takumi-rs/core-win32-x64-msvc': 2.13.7
+ csstype: 3.2.3
+ transitivePeerDependencies:
+ - preact
+ - react
+
+ optionalDependencies:
+ preact: 10.29.3
+ react: 19.2.4
+
+ dependencies:
+ '@takumi-rs/helpers': 2.13.7([email protected])([email protected])
+ optionalDependencies:
+ csstype: 3.2.3
+ transitivePeerDependencies:
+ - preact
+ - react
+
'@tanstack/[email protected]':
dependencies:
'@tanstack/devtools-event-client': 0.4.3
@@ -11382,6 +11526,16 @@ snapshots:
+ dependencies:
+ '@takumi-rs/helpers': 2.13.7([email protected])([email protected])
+ transitivePeerDependencies:
+ - csstype
+ - preact
+ - react
+
diff --git a/src/routeTree.gen.ts b/src/routeTree.gen.ts
index fd5314f5..8790835d 100644
--- a/src/routeTree.gen.ts
+++ b/src/routeTree.gen.ts
@@ -37,6 +37,7 @@ import { Route as STokenIndexRouteImport } from './routes/s/$token/index'
import { Route as AuthenticatedOnboardingIndexRouteImport } from './routes/_authenticated.onboarding.index'
import { Route as AppSettingsIndexRouteImport } from './routes/_app/settings/index'
import { Route as STokenRawRouteImport } from './routes/s/$token/raw'
+import { Route as STokenOgDotpngRouteImport } from './routes/s/$token/og[.]png'
import { Route as ApiAutumnSplatRouteImport } from './routes/api/autumn/$'
import { Route as ApiAuthSplatRouteImport } from './routes/api/auth/$'
import { Route as AppSettingsOrganizationRouteImport } from './routes/_app/settings/organization'
@@ -208,6 +209,11 @@ const STokenRawRoute = STokenRawRouteImport.update({
path: '/s/$token/raw',
getParentRoute: () => rootRouteImport,
} as any)
+const STokenOgDotpngRoute = STokenOgDotpngRouteImport.update({
+ id: '/s/$token/og.png',
+ path: '/s/$token/og.png',
+ getParentRoute: () => rootRouteImport,
+} as any)
const ApiAutumnSplatRoute = ApiAutumnSplatRouteImport.update({
id: '/api/autumn/$',
path: '/api/autumn/$',
@@ -409,6 +415,7 @@ export interface FileRoutesByFullPath {
'/settings/organization': typeof AppSettingsOrganizationRoute
'/api/auth/$': typeof ApiAuthSplatRoute
'/api/autumn/$': typeof ApiAutumnSplatRoute
+ '/s/$token/og.png': typeof STokenOgDotpngRoute
'/s/$token/raw': typeof STokenRawRoute
'/settings/': typeof AppSettingsIndexRoute
'/onboarding/': typeof AuthenticatedOnboardingIndexRoute
@@ -464,6 +471,7 @@ export interface FileRoutesByTo {
'/settings/organization': typeof AppSettingsOrganizationRoute
'/api/auth/$': typeof ApiAuthSplatRoute
'/api/autumn/$': typeof ApiAutumnSplatRoute
+ '/s/$token/og.png': typeof STokenOgDotpngRoute
'/s/$token/raw': typeof STokenRawRoute
'/settings': typeof AppSettingsIndexRoute
'/onboarding': typeof AuthenticatedOnboardingIndexRoute
@@ -523,6 +531,7 @@ export interface FileRoutesById {
'/_app/settings/organization': typeof AppSettingsOrganizationRoute
'/api/auth/$': typeof ApiAuthSplatRoute
'/api/autumn/$': typeof ApiAutumnSplatRoute
+ '/s/$token/og.png': typeof STokenOgDotpngRoute
'/s/$token/raw': typeof STokenRawRoute
'/_app/settings/': typeof AppSettingsIndexRoute
'/_authenticated/onboarding/': typeof AuthenticatedOnboardingIndexRoute
@@ -582,6 +591,7 @@ export interface FileRouteTypes {
| '/settings/organization'
| '/api/auth/$'
| '/api/autumn/$'
+ | '/s/$token/og.png'
| '/s/$token/raw'
| '/settings/'
| '/onboarding/'
@@ -637,6 +647,7 @@ export interface FileRouteTypes {
| '/settings/organization'
| '/api/auth/$'
| '/api/autumn/$'
+ | '/s/$token/og.png'
| '/s/$token/raw'
| '/settings'
| '/onboarding'
@@ -695,6 +706,7 @@ export interface FileRouteTypes {
| '/_app/settings/organization'
| '/api/auth/$'
| '/api/autumn/$'
+ | '/s/$token/og.png'
| '/s/$token/raw'
| '/_app/settings/'
| '/_authenticated/onboarding/'
@@ -742,6 +754,7 @@ export interface RootRouteChildren {
RReportIdRoute: typeof RReportIdRoute
ApiAuthSplatRoute: typeof ApiAuthSplatRoute
ApiAutumnSplatRoute: typeof ApiAutumnSplatRoute
+ STokenOgDotpngRoute: typeof STokenOgDotpngRoute
STokenRawRoute: typeof STokenRawRoute
STokenIndexRoute: typeof STokenIndexRoute
ApiGa4OauthCallbackRoute: typeof ApiGa4OauthCallbackRoute
@@ -946,6 +959,13 @@ declare module '@tanstack/react-router' {
preLoaderRoute: typeof STokenRawRouteImport
parentRoute: typeof rootRouteImport
}
+ '/s/$token/og.png': {
+ id: '/s/$token/og.png'
+ path: '/s/$token/og.png'
+ fullPath: '/s/$token/og.png'
+ preLoaderRoute: typeof STokenOgDotpngRouteImport
+ parentRoute: typeof rootRouteImport
+ }
'/api/autumn/$': {
id: '/api/autumn/$'
path: '/api/autumn/$'
@@ -1368,6 +1388,7 @@ const rootRouteChildren: RootRouteChildren = {
RReportIdRoute: RReportIdRoute,
ApiAuthSplatRoute: ApiAuthSplatRoute,
ApiAutumnSplatRoute: ApiAutumnSplatRoute,
+ STokenOgDotpngRoute: STokenOgDotpngRoute,
STokenRawRoute: STokenRawRoute,
STokenIndexRoute: STokenIndexRoute,
ApiGa4OauthCallbackRoute: ApiGa4OauthCallbackRoute,
diff --git a/src/routes/s/$token/index.tsx b/src/routes/s/$token/index.tsx
index 123f2a7d..423cb0b0 100644
--- a/src/routes/s/$token/index.tsx
+++ b/src/routes/s/$token/index.tsx
@@ -12,9 +12,6 @@ import { loadSharePage } from "@/server/features/reports/sharePage";
// content always carries this chrome.
const MARKETING_URL = "https://openseo.so/?utm_source=shared_report";
-// The marketing site's card. Absolute because a link preview crawler resolves
-// og:image against nothing, and the app domain does not serve this asset.
-const SOCIAL_CARD_URL = "https://openseo.so/social-card.jpg";
// The share sheet on touch devices only; on desktop macOS anchors it to the
// window rather than the button, so the clipboard is used instead.
@@ -59,10 +56,17 @@ export const Route = createFileRoute("/s/$token/")({
]
: []),
{ property: "og:url", content: data.url },
- { property: "og:image", content: SOCIAL_CARD_URL },
- { property: "og:image:width", content: "1200" },
- { property: "og:image:height", content: "630" },
- { name: "twitter:card", content: "summary_large_image" },
+ ...(data.state === "ok"
+ ? [
+ { property: "og:image", content: data.imageUrl },
+ { property: "og:image:width", content: "1200" },
+ { property: "og:image:height", content: "630" },
+ { property: "og:image:alt", content: `${data.title} · OpenSEO` },
+ { name: "twitter:image", content: data.imageUrl },
+ { name: "twitter:image:alt", content: `${data.title} · OpenSEO` },
+ { name: "twitter:card", content: "summary_large_image" },
+ ]
+ : []),
],
};
},
diff --git a/src/routes/s/$token/og[.]png.ts b/src/routes/s/$token/og[.]png.ts
new file mode 100644
index 00000000..cd8249ce
--- /dev/null
+++ b/src/routes/s/$token/og[.]png.ts
@@ -0,0 +1,46 @@
+import { createFileRoute } from "@tanstack/react-router";
+import { ReportRepository } from "@/server/features/reports/repositories/ReportRepository";
+import {
+ SHARE_TOKEN_PATTERN,
+ sharesEnabled,
+} from "@/server/features/reports/shareAccess";
+import { textResponse } from "@/shared/report-sandbox";
+
+export async function handleReportSocialImage(
+ token: string,
+): Promise<Response> {
+ if (!(await sharesEnabled()) || !SHARE_TOKEN_PATTERN.test(token)) {
+ return textResponse("This report isn't shared.", 404);
+ }
+ const report = await ReportRepository.getSharedReportByToken(token);
+ if (!report || report.archived) {
+ return textResponse("This report isn't shared.", 404);
+ }
+
+ // Keep the renderer and WASM out of the app's eager startup graph, and do
+ // not initialize either for invalid, revoked, or archived shares.
+ try {
+ const { renderReportSocialImage } =
+ await import("@/server/features/reports/reportSocialImage");
+ return await renderReportSocialImage(report.title, report.projectDomain);
+ } catch (error) {
+ console.error("Report social image rendering failed", error);
+ return new Response(null, {
+ status: 302,
+ headers: {
+ Location: "https://openseo.so/social-card.jpg",
+ "Cache-Control": "no-store",
+ "Referrer-Policy": "no-referrer",
+ "X-Robots-Tag": "noindex, nofollow",
+ },
+ });
+ }
+}
+
+export const Route = createFileRoute("/s/$token/og.png")({
+ server: {
+ handlers: {
+ GET: ({ params }) => handleReportSocialImage(params.token),
+ },
+ },
+});
diff --git a/src/server/features/reports/reportSocialImage.tsx b/src/server/features/reports/reportSocialImage.tsx
new file mode 100644
index 00000000..186cd198
--- /dev/null
+++ b/src/server/features/reports/reportSocialImage.tsx
@@ -0,0 +1,89 @@
+import { ImageResponse } from "takumi-js/response";
+import { domainField } from "@/types/schemas/domain";
+import logo from "../../../../public/android-chrome-192x192.png?inline";
+
+/** One template for all reports. Assets stay local; titles never go to an image service. */
+export async function renderReportSocialImage(
+ title: string,
+ projectDomain?: string | null,
+): Promise<Response> {
+ // Projects normally store a bare domain. Also handle older full URLs, and
+ // omit missing/invalid websites rather than failing an otherwise valid card.
+ const domain = domainField.safeParse(projectDomain);
+ const response = new ImageResponse(
+ <div
+ style={{
+ width: "100%",
+ height: "100%",
+ position: "relative",
+ display: "flex",
+ flexDirection: "column",
+ padding: 64,
+ backgroundColor: "#f5f4ef",
+ color: "#1d2925",
+ }}
+ >
+ <div style={{ display: "flex", alignItems: "center", gap: 20 }}>
+ <img src={logo} width={64} height={64} style={{ borderRadius: 14 }} />
+ <div style={{ fontSize: 34, fontWeight: 600, letterSpacing: -1 }}>
+ OpenSEO
+ </div>
+ </div>
+ <div
+ style={{
+ display: "flex",
+ flex: 1,
+ alignItems: "center",
+ paddingTop: 24,
+ }}
+ >
+ <div
+ style={{
+ fontSize: title.length > 85 ? 54 : title.length > 48 ? 64 : 80,
+ fontWeight: 700,
+ letterSpacing: -2,
+ lineHeight: 1.12,
+ overflowWrap: "anywhere",
+ }}
+ >
+ {title}
+ </div>
+ </div>
+ {domain.success && (
+ <div
+ style={{
+ position: "absolute",
+ right: 64,
+ bottom: 28,
+ maxWidth: "80%",
+ fontSize: 24,
+ fontWeight: 400,
+ color: "#65716b",
+ whiteSpace: "nowrap",
+ overflow: "hidden",
+ textOverflow: "ellipsis",
+ }}
+ >
+ {domain.data}
+ </div>
+ )}
+ </div>,
+ {
+ width: 1200,
+ height: 630,
+ format: "png",
+ // No title-dependent network calls for emoji assets.
+ emoji: "from-font",
+ headers: {
+ // Like the share page, the image contains report content. Always check
+ // access again rather than letting a revoked title live in our CDN.
+ "Cache-Control": "no-store",
+ "X-Robots-Tag": "noindex, nofollow",
+ "X-Content-Type-Options": "nosniff",
+ },
+ },
+ );
+ // Catch rendering failures before a 200 response has already been sent.
+ await response.ready;
+ return response;
+}
diff --git a/src/server/features/reports/repositories/ReportRepository.ts b/src/server/features/reports/repositories/ReportRepository.ts
index 545f880f..b58668c4 100644
--- a/src/server/features/reports/repositories/ReportRepository.ts
+++ b/src/server/features/reports/repositories/ReportRepository.ts
@@ -190,6 +190,7 @@ async function getSharedReportByToken(token: string): Promise<{
id: string;
projectId: string;
organizationId: string;
+ projectDomain: string | null;
title: string;
summary: string;
skill: string | null;
@@ -201,6 +202,7 @@ async function getSharedReportByToken(token: string): Promise<{
id: reports.id,
projectId: reports.projectId,
organizationId: projects.organizationId,
+ projectDomain: projects.domain,
title: reports.title,
summary: reports.summary,
skill: reports.skill,
diff --git a/src/server/features/reports/shareImageRoute.test.ts b/src/server/features/reports/shareImageRoute.test.ts
new file mode 100644
index 00000000..2b1f7a37
--- /dev/null
+++ b/src/server/features/reports/shareImageRoute.test.ts
@@ -0,0 +1,110 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { handleReportSocialImage } from "@/routes/s/$token/og[.]png";
+
+const mocks = vi.hoisted(() => ({
+ sharesEnabled: vi.fn(),
+ getSharedReportByToken: vi.fn(),
+ renderReportSocialImage: vi.fn(),
+}));
+
+vi.mock("@/server/features/reports/shareAccess", () => ({
+ sharesEnabled: mocks.sharesEnabled,
+ SHARE_TOKEN_PATTERN: /^[A-Za-z0-9_-]{32}$/,
+}));
+vi.mock("@/server/features/reports/repositories/ReportRepository", () => ({
+ ReportRepository: { getSharedReportByToken: mocks.getSharedReportByToken },
+}));
+vi.mock("@/server/features/reports/reportSocialImage", () => ({
+ renderReportSocialImage: mocks.renderReportSocialImage,
+}));
+
+const TOKEN = "a".repeat(32);
+
+beforeEach(() => {
+ mocks.sharesEnabled.mockResolvedValue(true);
+ mocks.getSharedReportByToken.mockResolvedValue({
+ title: "Acme SEO audit",
+ projectDomain: "acme.com",
+ archived: false,
+ });
+ mocks.renderReportSocialImage.mockResolvedValue(new Response("image"));
+});
+
+describe("report social image access", () => {
+ it("renders the title from the authorized report", async () => {
+ const response = await handleReportSocialImage(TOKEN);
+ expect(mocks.getSharedReportByToken).toHaveBeenCalledWith(TOKEN);
+ expect(mocks.renderReportSocialImage).toHaveBeenCalledWith(
+ "Acme SEO audit",
+ "acme.com",
+ );
+ expect(await response.text()).toBe("image");
+ });
+
+ it("falls back to the marketing card on rendering failure and retries next time", async () => {
+ const error = new Error("Renderer failed");
+ const log = vi.spyOn(console, "error").mockImplementation(() => {});
+ mocks.renderReportSocialImage.mockRejectedValueOnce(error);
+ const response = await handleReportSocialImage(TOKEN);
+ expect(response.status).toBe(302);
+ expect(response.headers.get("Location")).toBe(
+ "https://openseo.so/social-card.jpg",
+ );
+ expect(response.headers.get("Cache-Control")).toBe("no-store");
+ expect(response.headers.get("Referrer-Policy")).toBe("no-referrer");
+ expect(log).toHaveBeenCalledWith(
+ "Report social image rendering failed",
+ error,
+ );
+ expect(await (await handleReportSocialImage(TOKEN)).text()).toBe("image");
+ mocks.getSharedReportByToken.mockResolvedValue(null);
+ const revoked = await handleReportSocialImage(TOKEN);
+ expect(revoked.status).toBe(404);
+ expect(revoked.headers.get("Location")).toBeNull();
+ });
+
+ it("does not hide report lookup failures behind the fallback", async () => {
+ mocks.getSharedReportByToken.mockRejectedValue(
+ new Error("Database unavailable"),
+ );
+ await expect(handleReportSocialImage(TOKEN)).rejects.toThrow(
+ "Database unavailable",
+ );
+ expect(mocks.renderReportSocialImage).not.toHaveBeenCalled();
+ });
+
+ it.each(["missing", "archived"])(
+ "does not reveal a %s report's title",
+ async (state) => {
+ mocks.getSharedReportByToken.mockResolvedValue(
+ state === "missing" ? null : { title: "Private title", archived: true },
+ );
+ const response = await handleReportSocialImage(TOKEN);
+ expect(response.status).toBe(404);
+ expect(response.headers.get("Location")).toBeNull();
+ expect(response.headers.get("Cache-Control")).toContain("no-store");
+ expect(await response.text()).toBe("This report isn't shared.");
+ expect(mocks.renderReportSocialImage).not.toHaveBeenCalled();
+ },
+ );
+
+ it.each(["disabled", "invalid"])(
+ "skips both lookup and rendering when sharing is %s",
+ async (state) => {
+ mocks.sharesEnabled.mockResolvedValue(state !== "disabled");
+ expect(
+ (await handleReportSocialImage(state === "invalid" ? "bad" : TOKEN))
+ .status,
+ ).toBe(404);
+ expect(mocks.getSharedReportByToken).not.toHaveBeenCalled();
+ expect(mocks.renderReportSocialImage).not.toHaveBeenCalled();
+ },
+ );
+
+ it("checks access again after revocation", async () => {
+ await handleReportSocialImage(TOKEN);
+ mocks.getSharedReportByToken.mockResolvedValue(null);
+ expect((await handleReportSocialImage(TOKEN)).status).toBe(404);
+ expect(mocks.renderReportSocialImage).toHaveBeenCalledTimes(1);
+ });
+});
diff --git a/src/server/features/reports/sharePage.test.ts b/src/server/features/reports/sharePage.test.ts
index 14a19f5a..a2f6d219 100644
--- a/src/server/features/reports/sharePage.test.ts
+++ b/src/server/features/reports/sharePage.test.ts
@@ -27,6 +27,7 @@ const SHARED_REPORT = {
title: "badseo.dev SEO audit",
summary: "\nFix the titles first.\n\nThen the meta descriptions.",
updatedAt: "2026-09-01T10:00:00.000Z",
+ projectDomain: "badseo.dev",
archived: false,
};
@@ -42,11 +43,56 @@ describe("loadSharePage", () => {
title: "badseo.dev SEO audit",
description: "Fix the titles first.",
url: `https://app.example.com/s/${TOKEN}`,
+ imageUrl: `https://app.example.com/s/${TOKEN}/og.png?v=2026-09-01T10%3A00%3A00.000Z&domain=badseo.dev`,
updatedAt: "2026-09-01T10:00:00.000Z",
});
expect(mocks.setResponseStatus).not.toHaveBeenCalled();
});
+ it.each([
+ ["old.example.com", "new.example.com"],
+ ["old.example.com", null],
+ [null, "new.example.com"],
+ ])(
+ "changes the image URL when the website changes from %s to %s",
+ async (before, after) => {
+ mocks.getSharedReportByToken.mockResolvedValue({
+ ...SHARED_REPORT,
+ projectDomain: before,
+ });
+ const original = await loadSharePage(TOKEN);
+ mocks.getSharedReportByToken.mockResolvedValue({
+ ...SHARED_REPORT,
+ projectDomain: after,
+ });
+ const updated = await loadSharePage(TOKEN);
+ expect(updated.updatedAt).toBe(original.updatedAt);
+ expect(updated.imageUrl).not.toBe(original.imageUrl);
+ expect(new URL(updated.imageUrl).searchParams.get("domain")).toBe(
+ after ?? "",
+ );
+ },
+ );
+
+ it("versions by the displayed hostname, not URL formatting", async () => {
+ const original = await loadSharePage(TOKEN);
+ mocks.getSharedReportByToken.mockResolvedValue({
+ ...SHARED_REPORT,
+ projectDomain: "https://www.badseo.dev/path?query=value",
+ });
+ expect((await loadSharePage(TOKEN)).imageUrl).toBe(original.imageUrl);
+ });
+
+ it("changes the image URL when a report is saved again", async () => {
+ const original = await loadSharePage(TOKEN);
+ mocks.getSharedReportByToken.mockResolvedValue({
+ ...SHARED_REPORT,
+ title: "Updated audit",
+ updatedAt: "2026-09-02T10:00:00.000Z",
+ });
+ expect((await loadSharePage(TOKEN)).imageUrl).not.toBe(original.imageUrl);
+ });
+
// The reader is told the project is archived; the report's own title is
// content the link no longer grants access to.
it("names the archived state without naming the report", async () => {
@@ -58,6 +104,7 @@ describe("loadSharePage", () => {
await expect(loadSharePage(TOKEN)).resolves.toMatchObject({
state: "archived",
title: "Report unavailable",
+ imageUrl: "",
});
expect(mocks.setResponseStatus).toHaveBeenCalledWith(404);
});
@@ -82,6 +129,7 @@ describe("loadSharePage", () => {
await expect(loadSharePage(TOKEN)).resolves.toMatchObject({
state: "missing",
+ imageUrl: "",
});
expect(mocks.setResponseStatus).toHaveBeenCalledWith(404);
});
diff --git a/src/server/features/reports/sharePage.ts b/src/server/features/reports/sharePage.ts
index 8e703043..d37cc47b 100644
--- a/src/server/features/reports/sharePage.ts
+++ b/src/server/features/reports/sharePage.ts
@@ -10,6 +10,7 @@ import {
sharesEnabled,
} from "@/server/features/reports/shareAccess";
import { sharePath } from "@/shared/report-share";
+import { domainField } from "@/types/schemas/domain";
/** What `/s/<token>` renders, and all it is told. No report or project id. */
type SharePageData = {
@@ -19,6 +20,8 @@ type SharePageData = {
description: string;
/** Absolute canonical URL, for og:url. */
url: string;
+ /** Absolute image URL, versioned by the saved report and displayed hostname. */
+ imageUrl: string;
/** When the report was last saved, for the bar's "Updated …". */
updatedAt: string;
};
@@ -68,6 +71,7 @@ export const loadSharePage = createServerOnlyFn(
title: "Report unavailable",
description: "",
url: canonical,
+ imageUrl: "",
updatedAt: "",
};
};
@@ -82,11 +86,20 @@ export const loadSharePage = createServerOnlyFn(
if (!report) return unavailable("missing");
if (report.archived) return unavailable("archived");
+ const domain = domainField.safeParse(report.projectDomain);
+ // These parameters only version the URL; the image route reads its content
+ // from the authorized report, never from query parameters.
+ const imageVersion = new URLSearchParams({
+ v: report.updatedAt,
+ domain: domain.success ? domain.data : "",
+ });
+
return {
state: "ok",
title: report.title,
description: shareDescription(report.summary),
url: canonical,
+ imageUrl: `${canonical}/og.png?${imageVersion}`,
updatedAt: report.updatedAt,
};
},
diff --git a/src/server/mcp/tools/report-tools.ts b/src/server/mcp/tools/report-tools.ts
index 264ce43e..0b0fe083 100644
--- a/src/server/mcp/tools/report-tools.ts
+++ b/src/server/mcp/tools/report-tools.ts
@@ -64,7 +64,7 @@ const saveInputSchema = {
.string()
.min(1)
.describe(
- `Specific title shown in the report list, e.g. "badseo.dev SEO audit, Sep 2026". Never a generic label like "SEO Report". Max ${REPORT_MAX_TITLE_CHARS} characters.`,
+ `Report type or specific subject and full report date, e.g. "Competitive Landscape — Sep 17, 2026". Omit the project's website; include the subject's bare hostname only when it differs from the project website or the project has no website. Use the same title in the HTML title and h1. Never a generic label like "SEO Report". Max ${REPORT_MAX_TITLE_CHARS} characters.`,
),
summary: z
.string()
@@ -115,7 +115,7 @@ export const saveReportTool = {
config: {
title: "Save report",
description:
- "Saves a finished HTML report to this project, where anyone in the workspace can read and print it. Uses no credits. Call list_reports first and pass the matching reportId to replace that report instead of creating a near-duplicate — a save whose title already exists in the project is refused. Give the report a specific title (the subject and the period), a summary carrying the verdict, the top action and the key numbers, and the skill slug you are running. Then reply with the returned url, a one-line verdict and the single top action; do not paste the report into chat.",
+ "Saves a finished HTML report to this project, where anyone in the workspace can read and print it. Uses no credits. Call list_reports first and pass the matching reportId to replace that report instead of creating a near-duplicate — a save whose title already exists in the project is refused. Give the report a specific title (the report type or subject and full report date), a summary carrying the verdict, the top action and the key numbers, and the skill slug you are running. Then reply with the returned url, a one-line verdict and the single top action; do not paste the report into chat.",
inputSchema: saveInputSchema,
outputSchema: saveOutputSchema,
annotations: {
diff --git a/web/content/docs/skills/seo-report.mdx b/web/content/docs/skills/seo-report.mdx
index deb825df..48d112d1 100644
--- a/web/content/docs/skills/seo-report.mdx
+++ b/web/content/docs/skills/seo-report.mdx
@@ -18,7 +18,7 @@ You do not run it on its own. When your agent finishes an audit, a keyword study
## What you get back
-A report page in your project with a title that names the subject and the period, like "badseo.dev SEO audit, Sep 2026". Open it from the Reports page in the sidebar. The menu beside it exports a PDF, opens the report full screen, or opens it in its own tab.
+A report page in your project with a title like "Competitive Landscape — Sep 17, 2026". Titles include the full report date and omit the project's website. A report about another website includes that domain to keep the subject clear; so does a report in a project with no website set. Open it from the Reports page in the sidebar. The menu beside it exports a PDF, opens the report full screen, or opens it in its own tab.
Reports are free. They do not spend credits, and there is no practical limit on how many a project holds. The Reports page shows the 100 most recent.