Skip to content

Resolve release sync conflicts for release/17.0 - #2194

Merged
David Pine (IEvangelist) merged 4 commits into
release/17.0from
release-sync/17.0
Nov 17, 2026
Merged

David Pine (IEvangelist) merged 4 commits into
release/17.0from
release-sync/17.0

Conversation

@aspire-repo-bot

@aspire-repo-bot aspire-repo-bot Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Merge main (24fa655677788e02b297ec5f2f6c78ad8275f92d) into release/17.0 without replacing the release's Aspire 17 package and API data with main's Aspire 13 data.

  • Restored src/frontend/src/data/ exactly to the release branch snapshot. The final PR has no data changes relative to release/17.0.
  • Eric resolved the OG renderer conflict, preserving main's cached-layer rendering optimization and release's per-card fact sheets.
  • Added a renderer regression covering per-card facts, distinct fact values, and cached-base isolation.

The recurring sync policy is fixed separately in #2195: data groups unchanged on release merge normally; groups changed on release keep their release snapshot.

Prefer Create a merge commit when landing this repair so main ancestry remains recorded. Release sync remains paused while this PR is open.

Third-party links and affiliations

None

Validation

  • From src/frontend: node node_modules\vitest\vitest.mjs run --config vitest.config.ts tests/unit/og-image-renderer.vitest.test.ts tests/unit/page-metadata.vitest.test.ts — passed, 65 tests. The renderer regression initially failed on the unresolved conflict markers; the tested resolution exactly matches Eric's committed resolution.
  • From src/frontend: node node_modules\eslint\bin\eslint.js src\utils\og-image-renderer.ts tests\unit\og-image-renderer.vitest.test.ts --max-warnings 0 — passed.
  • git diff --exit-code origin/release/17.0 HEAD -- src/frontend/src/data — passed after rebasing onto Eric's resolution.
  • git diff --cached --check — passed.
  • Production build not run locally; CI remains responsible for the complete frontend build.

## Summary

The `/og/**/*.png` social cards were a large share of build time.
Profiling showed satori layout took ~9 ms per card, but **rasterizing
its SVG with sharp/librsvg took ~300 ms**. This PR reworks
`src/frontend/src/utils/og-image-renderer.ts` so cards render about **9x
faster on Linux CI** and look the same.

### Changes

- **Cached base layer.** The layers shared by every card (background
image, gradient, "Read on aspire.dev" CTA chip and its shadow) are
rasterized once per process into a raw RGB buffer. Each card now
rasterizes only its own overlay and composites it onto that base.
Previously every card embedded the 400 KB background PNG as base64 in
the SVG and decoded it again.
- **No per-card box-shadows.** satori emits `boxShadow` as SVG
`feGaussianBlur` filters, which accounted for ~65% of rasterization
time. The shadows on the topic pill and title/description bubbles were
invisible against the dark gradient, so they're removed. The CTA chip
keeps its shadow because it's baked into the base layer.
- **Redundant masks stripped.** For `overflow: hidden` elements satori
emits both a rectangular `clip-path` and an equivalent rectangular
`mask`. librsvg renders each mask offscreen, so the mask reference is
dropped wherever the element already has a clip-path. Output is
pixel-identical. If satori's output ever changes shape, the regex just
stops matching.
- **RGB output.** Cards are fully opaque, so they're encoded without an
alpha channel.
- **PNG `compressionLevel` 9 → 6.** Level 9 cost ~27 ms more per card
for <2% smaller files.
- **Single satori `fonts` array.** satori caches its font loader per
array instance.

The sample OG route (`/og/reference/samples/*.png`) also benefits
because its fallback cards use the same renderer.

### Performance

Measured in a Linux container matching the CI build job
(`8-core-ubuntu-latest`): glibc, Bun 1.4.4, 8 CPUs, sharp 0.35.4, satori
0.28.1. The harness reproduced Astro's `parallelPrerender` setup (4
worker threads × 4 concurrent renders) and rendered 600 cards.

| Renderer | 600 cards | Per card |
|---|---|---|
| Before | ~58 s | ~97 ms |
| After | ~6.5 s | ~11 ms |

Single-process on Windows: 292 → 37 ms per card one at a time, and 66 →
10 ms when rendering concurrently.

The output is visually indistinguishable: mean pixel difference vs. the
old renderer is ~1–1.8/255, and PNGs are ~10% smaller. Cards with emoji,
long wrapping titles, and no description were checked visually.

### sharp tuning evaluated (no changes)

Per the [sharp performance
guide](https://sharp.pixelplumbing.com/performance/), I benchmarked
`UV_THREADPOOL_SIZE` (8, 16), `MALLOC_ARENA_MAX=2` with and without
per-image threads pinned to 1, 8 prerender workers, and build
concurrency 8. All results fell within run-to-run noise (6.0–7.5 s for
600 cards), and `MALLOC_ARENA_MAX=2` alone was slower because it gives
each image 8 threads on 8 cores. sharp's glibc default of 1 thread per
image already fits a build that renders many images in parallel, so no
CI settings were changed.

### Incremental builds

Changing the renderer module invalidates the cached OG routes once.
After that, CI's restored `node_modules/.astro` cache keeps skipping
unchanged cards as before.

## Third-party links and affiliations

None. The sharp performance guide linked above is reference material
only.

## Validation

- `bunx eslint src/utils/og-image-renderer.ts`: passed.
- `bunx tsc --noEmit -p tsconfig.json`: no errors in the renderer. The
only error was `astro:content` not found in `src/pages/og/[...slug].ts`,
because `astro sync` hadn't been run in the fresh worktree.
- Ad-hoc benchmarks (temporary scripts, not committed) compared old and
new renderers on timing and pixel diff, on Windows and in the Linux
container.
- No full `astro build` was run locally; CI covers it.

---------

Co-authored-by: David Pine <7679720+IEvangelist@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…sync/17.0

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

# Conflicts:
#	src/frontend/src/utils/og-image-renderer.ts
Keep the cached base-layer renderer and port the details fact sheet into the overlay tree.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Restore the release data snapshot and cover per-card facts with cached OG rendering.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@aspire-repo-bot

Copy link
Copy Markdown
Contributor Author

Frontend HTML artifact ready

The latest frontend build uploaded the frontend-dist artifact for PR #2194. Use the VS Code button below to open this PR with GitHub Artifacts Explorer and browse the built HTML locally.

VS Code: Open PR #2194 artifacts

This comment updates automatically when a new frontend build artifact is uploaded.

@IEvangelist
David Pine (IEvangelist) marked this pull request as ready for review November 17, 2026 17:41
Copilot AI balanced review requested due to automatic review settings November 17, 2026 17:41
@IEvangelist
David Pine (IEvangelist) merged commit 7efd903 into release/17.0 Nov 17, 2026
18 checks passed
@IEvangelist
David Pine (IEvangelist) deleted the release-sync/17.0 branch November 17, 2026 17:41

Copilot AI 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.

🟢 Approval recommended

No active review issues remain for the cached Open Graph rendering and per-card fact sheet changes.

No open issues 🎉

What changed in this PR

Resolves the main merge into release/17.0, preserving the release’s Aspire 17 data while combining cached Open Graph rendering with per-card fact sheets. The recurring data-sync policy is handled separately in #2195.

Changes:

  • Caches shared image layers and fonts while rendering card-specific content separately.
  • Adds regression coverage for distinct fact values, PNG dimensions, and cached-base isolation.
File Description
src/​frontend/​tests/​unit/​og-image-renderer.vitest.test.ts Adds regression coverage for per-card facts and cache isolation.
src/​frontend/​src/​utils/​og-image-renderer.ts Combines cached base rendering with per-card overlays and resets derived caches in the test helper.

Review effort: Balanced

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.

3 participants