Skip to content

Share card that survives a square crop, with a versioned URL - #22

Merged
craig-o-curtis merged 4 commits into
mainfrom
share-card-square-safe
Nov 8, 2026
Merged

craig-o-curtis merged 4 commits into
mainfrom
share-card-square-safe

Conversation

@craig-o-curtis

@craig-o-curtis craig-o-curtis commented Nov 8, 2026 •

Copy link
Copy Markdown
Contributor
Image

The share card for northguild.dev/ is redrawn so it still reads when an app crops it to a square, and its URL now changes when the image does.

What changed

  • The card. scripts/build-og-card.mjs draws it: the aurora sky, the shield above the Michroma wordmark, and "Open-source tools for developers." All the text and the shield sit inside the centre square (x 285–915), so a square crop keeps them. The panel has the theme's bevelled corners. Text contrast is at least 4.5:1.
  • Size. og.png is 145 KB, down from 538 KB. WhatsApp shows no preview for images over 300 KB.
  • Versioned URL. og:image and twitter:image end in ?v= plus the first 12 hex characters of the PNG's SHA-256, read at build time. Facebook caches an image by URL, so a redrawn card is now a new URL.
  • og:locale is en_US, the Open Graph form.
  • Upload copy. apps/site/assets/share/ holds the card and the old one, with a README. context/share-card.md says how to redraw it.
  • robots.txt names https://northguild.dev/worktree/sitemap-index.xml. Crawlers read robots.txt only at the host root.

The script runs by hand, not in the build, and gives the same bytes every run.

Validation

  • pnpm lint, pnpm format:check, pnpm check and pnpm build pass.
  • The built index.html carries og.png?v=080dc75a492b, which matches the file's hash.
  • After deploy: Facebook Sharing Debugger, LinkedIn Post Inspector, X, Slack, Discord, WhatsApp and iMessage each show the card; a square crop keeps the whole wordmark.

Related: northguild/gmt#478 (the same work for the GMT docs), northguild/worktree#286 and northguild/worktree#287.

The card is redrawn by scripts/build-og-card.mjs: the shield, wordmark and line sit inside the
centre square, the panel has bevelled corners, and the PNG is 145 KB, under the 300 KB WhatsApp
loads. og:image and twitter:image end in ?v= and the first 12 hex of its SHA-256, so a redrawn
card is a new URL to every cache. og:locale is en_US.
Crawlers read robots.txt only at the host root, so the root file names every sitemap under it.
@craig-o-curtis

Copy link
Copy Markdown
Contributor Author

/craig-review

@craigs-reviewer craigs-reviewer Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

code-reviewer: needs changes

This PR redraws the share card so it survives a square crop and cuts it to about 145 KB. It also versions og:image and twitter:image with a hash of the PNG read at build time, adds og:locale and adds a worktree sitemap line to robots.txt. The direction is sound, but the generator writes og.png before it runs the contrast check, so a failed run still replaces the site's card. The wordmark gradient also looks unlikely to render as the script intends. I could not see astro.config or the route list, so whether Base.astro is ever rendered on demand on Cloudflare is an assumption to check.


Reviewed 95c446c for craig-o-curtis · claude-opus-5-5 · 8 files · left out: pnpm-lock.yaml · $0.21

Comment thread scripts/build-og-card.mjs Resolved
Comment thread scripts/build-og-card.mjs Resolved
Comment thread apps/site/src/layouts/Base.astro Resolved
…wordmark gradient, hash og.png once per build
@craig-o-curtis

Copy link
Copy Markdown
Contributor Author

/craig-review

@craigs-reviewer craigs-reviewer Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

code-reviewer follow-up: looks good

Since 95c446c, the contrast check runs before either PNG is written, and the wordmark gradient code that never rendered is gone. The card's hash is now computed once in astro.config.mjs and passed to Base.astro through vite.define, so the layout no longer reads the file system. All three earlier comments are addressed, and the new changes raise no further issues.

Earlier comments


Reviewed 61ece3c (changes since 95c446c) for craig-o-curtis · claude-opus-5-5 · 5 files · $0.13

@baldurpan baldurpan left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I re-read this at 61ece3c, after the fixes for craigs-reviewer's three threads, and they hold:

  • The contrast check now runs before either writeFileSync, and the error names both values.
  • The gradient code and CYAN_BRIGHT are gone, and nothing in scripts/, context/share-card.md or the share README still mentions a fade. public/og.png and assets/share/og-1200x630.png are both still blob 95bbe91, so the card and its ?v=080dc75a492b are unchanged.
  • astro.config.mjs resolves the card from its own import.meta.url, Base.astro no longer touches the file system, and the **/* include picks up src/env.d.ts.

The rest holds up too:

  • The panel spans x 299–901, inside the 285–915 square.
  • The RGB triples match packages/theme/tokens.css, and the shield paths match NorthGuildMark.astro exactly.
  • The robots.txt line is within the current CLAUDE.md rule ("Add a line only for a new sitemap"), and https://northguild.dev/worktree/sitemap-index.xml returns 200.
  • The Worker already serves /og.png?v=… as image/png.

That leaves one naming nit, inline, from context/coding-standards.md. Rename the functions or tell me you'd rather not, and I'll approve either way.

Comment thread scripts/build-og-card.mjs Resolved

@baldurpan baldurpan left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved at 61bb7b9. The card fits a square crop, comes in under WhatsApp's 300 KB limit, and changes its URL whenever its bytes change. Every review thread is closed and CI is green.

@craig-o-curtis
craig-o-curtis merged commit c119b7e into main Nov 8, 2026
1 check passed
@craig-o-curtis
craig-o-curtis deleted the share-card-square-safe branch November 8, 2026 13:01
craig-o-curtis added a commit to northguild/gmt that referenced this pull request Nov 8, 2026
…X-G6) (#478)

Closes #448
Closes #456

New OG images:

<img width="819" height="424" alt="Image"
src="https://github.com/user-attachments/assets/bce3fb5e-d188-44d6-9ae9-e4a778685473"
/>

Method pages og images:

<img width="849" height="436" alt="Image"
src="https://github.com/user-attachments/assets/34374576-5bdb-44ea-85ee-a22d477a4596"
/>

Makes `northguild.dev/gmt/` easier for search engines and AI answer
engines to crawl, index and quote. Everything follows documented
mechanics: crawlable text, accurate sitemaps, one indexable URL per
page, lighter pages, and an `llms.txt` that fits in an agent's context.
AI crawlers stay allowed. No `packages/gmt` change and no changeset.

## Search descriptions

- No two indexable pages share a meta description. A reference
function's description is its TSDoc summary. Where sibling functions
share one, a qualifier names the value kind or the namespace.
- Each namespace has one written summary. It is both the namespace
page's meta description and its line in `llms.txt`, and it replaces 13
identical boilerplate descriptions.
- A test on the built site fails when two indexable pages share a
description, and lists them.

## Crawling and `llms.txt`

- Generated pages carry a real Last updated date from the newest commit
of their inputs. The sitemap's `<lastmod>` is copied from that footer
date, so the two agree.
- A tracked `_headers` file caches hashed `/gmt/_astro/*` files for a
year as immutable, and marks the `.md` twins and `llms*.txt` files
`noindex`.
- The 404 page carries `noindex` and no canonical.
- The root `/gmt/llms.txt` fits in 64 KiB (it was about 213 KB). Its
Reference section links one `llms.txt` per namespace. Every page carries
`rel="describedby"` pointing at its namespace file, or at the root file
outside the reference.
- Each page keeps its own namespace's tree in the sidebar, and every
other namespace shows one collapsed Overview link. Page HTML is 33% to
47% smaller on the four pages measured, and previous and next links are
unchanged.
- `deploy-smoke.mjs` checks the crawl rows after each deploy.

## Share cards and tags

- Every share card shows the Earth, with its text inside the centre
square that link-preview apps crop to. Cards stay under 300 KB. No card
text is cut with an ellipsis; a title that does not fit fails the build.
- Share tags: `og:locale` is `en_US`, `og:image:type` is set,
`og:image:alt` and `twitter:image:alt` describe the card, and both image
URLs end in `?v=<hash of the PNG>` so a redrawn card is a new URL.
- A test on the built site checks every indexable page for exactly one
of each tag, equal image URLs and a hash that matches the PNG.
- Upload-ready copies of the cards are in `apps/dox/assets/share/`.

## Changelog pages

- The changelog is one page per release line (`/changelog/1-21/`) plus
an index, so no page nears 1 MB. Apple's Messages preview reads only the
first 1 MB of a page, and the single page was 1,546,542 bytes. The
largest page is now 729,975 bytes, and a build test fails on any page
over 1,048,576 bytes.

## Root site card (other repo)

The landing page `northguild.dev/` is a separate site. Its search data
and card are made in `northguild/northguild.dev`, and both PRs are
merged:

- northguild/northguild.dev#21: sitemap, logo and Organization data.
- northguild/northguild.dev#22: a card that survives a square crop,
under 300 KB, with a versioned image URL.

## Globe, LCP and INP

- The home globe starts when the page is idle and sets up in slices that
yield to the main thread, so no task runs long.
- Every globe pauses while off screen, while the tab is hidden, and
while the search dialog or the mobile menu covers it.
- Where the globe falls back to canvas 2D, it draws in a module Web
Worker on an `OffscreenCanvas`. Input no longer waits for a globe frame.
A probe compares text rasterisation on both paths first; if they differ,
or the worker fails, the main-thread renderer takes over. The look is
unchanged.
- The hero clock loads `@northguild/gmt` by dynamic import beside the
star list, which keeps the Temporal polyfill off the first-paint path.
- The clock list measures its rows in one pass after writing them.
- `apps/dox/scripts/web-vitals.mjs` measures LCP, CLS, TBT and INP by
hand.

Local lab numbers for the home page on mobile, before then after: TBT
464 ms to 149 ms; LCP 3.0 s (varying between runs) to 2.26 s; INP at 4x
CPU throttling 256 ms to 96 ms with WebGPU, and 392 ms to 96 ms with
canvas 2D. Guide and reference pages were already good.

## Owner steps

From `context/domination/issues/CORE-86/search-and-crawlers.md` (runbook
§8).

- [x] Rich Results Test on `https://northguild.dev/`
(northguild/northguild.dev#21): Organization, 0 errors, 0 warnings.
- [ ] **O1** Search Console: submit both sitemaps and record the Pages
report.
- [ ] **O2** Search Console URL Inspection on `/gmt/` and two reference
pages.
- [ ] **O3** Bing Webmaster Tools: import from Search Console, then
submit the sitemaps.
- [ ] **O4** AI Crawl Control: record the 30-day request counts per
crawler.
- [ ] **O5** Crawler Hints: turn it on. Turn it off if Bing lists no
IndexNow URLs within a week.

## Open checks after deploy

These run against the live site, so they stay open. The list is also in
`context/dox/built.md`.

- [ ] Facebook Sharing Debugger, LinkedIn Post Inspector, X, Slack,
Discord, WhatsApp: the card shows for `/gmt/`, a guide, a reference page
and `/gmt/changelog/`; WhatsApp shows the whole title in a square crop.
- [ ] iMessage: the rich preview shows for the same URLs, including a
changelog line page.
- [ ] The same platform checks for `https://northguild.dev/`.
- [ ] `node apps/dox/scripts/deploy-smoke.mjs` passes against
`https://northguild.dev`.
- [ ] Rich Results Test and validator.schema.org read the Organization
data on `https://northguild.dev/`.
- [ ] `node scripts/web-vitals.mjs --live https://northguild.dev` with
`PSI_API_KEY` set records PageSpeed Insights and CrUX numbers.

## Baseline

Search Console, Bing and AI Crawl Control numbers from before deploy:

_To be filled in by the owner._

## Validation

- Each slice was checked by a tester against its definition of done:
- Search, crawl and `llms.txt`: the Dox Vitest suite, every built-site
test on a fresh build, `astro check`, lint, a local Wrangler run of
`deploy-smoke.mjs`, and a whole-site HTML comparison against `main`'s
build.
- Lean sidebar: the browser and keyboard checks, and the HTML sizes
listed above.
- Share cards and tags: card unit tests (text inside the square,
contrast at least 4.5:1, no ellipsis) and `share-preview.test.ts` on a
fresh build.
  - Changelog pages: the size test on a fresh build.
- Globe: pixel comparison of the worker against the main-thread
renderer, and the pause rules, in Chromium. Interior pixels differ by 1
to 14 levels where the ocean pattern is filled, and the clock card can
show one frame before the globe when it mounts. Both are accepted.
- Every test that reads the built site now runs in CI, found by rule
(`apps/dox/scripts/dist-tests.mjs`). All 11 files pass on a fresh build.
- CI on 9a3fee6: every job passed, including the Dox gates. The review
fixes are in d516fc3.
- Local Lighthouse, mobile, home page: performance 78 to 84 on `main`,
93 to 95 here.
- `pnpm deps:sync`: no change to any `Blocked by` cell.

Not verified:

- `verdict validate` has not run locally: the scratch copy it would run
in is not a git checkout. CI runs the same build, lint and test steps.
- The globe worker has not run in real Firefox or Safari. Firefox would
not start on the test machine.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants