feat(ssr-sidecar): add a Node 24 HTML embed sidecar

[pjeweb]

Summary

• Add @mapsight/ssr-sidecar, a generic Node 24 process with GET /health, POST /v1/render, and POST /purge. There is no POST /render.
• Ship a package Dockerfile. CI smokes the image HTTP contract and, on a changesets publish, pushes ghcr.io/open-mapsight/ssr-sidecar:beta alongside the npm beta dist-tag.
• Hosts pull the image and bind-mount their render.js. The image does not bake a host bundle.

Test plan

• pnpm --filter @mapsight/ssr-sidecar typecheck
• pnpm --filter @mapsight/ssr-sidecar lint
• pnpm --filter @mapsight/ssr-sidecar test (18 tests, including HTTP 404 for /render)
• pnpm --filter @mapsight/ssr-sidecar build
• pnpm run check
• pnpm changeset status --since=origin/main — @mapsight/ssr-sidecar minor
• CI: SSR sidecar image job builds and smokes /health, /v1/render, /purge, and 404 /render
• After merge + Version Packages: npm view @mapsight/ssr-sidecar dist-tags includes beta
• After publish: docker pull ghcr.io/open-mapsight/ssr-sidecar:beta

---

Note

Medium Risk
New network-facing SSR process and release-time GHCR publishing add operational surface area, though the design keeps host bundles out of the image and documents keeping the sidecar off public ingress.

Overview
Introduces @mapsight/ssr-sidecar, a generic Node 24 HTTP process for Mapsight HTML embed SSR. Hosts run ghcr.io/open-mapsight/ssr-sidecar and bind-mount their product render.js via MAPSIGHT_SSR_MODULE; the image ships only the server plus a contract stub, not a host bundle.

The public API is GET /health, POST /v1/render (JSON { v: 1, html, state, pageMeta, meta }), and POST /purge. There is no POST /render (404). The server dynamically loads the render module, supports optional renderEnvelope() / purge(), v1 error codes, body size limits, and env-driven HTTP proxy plus https→http origin rewrite for hairpin fetches.

CI gains path classification for ssr_sidecar, an ssr-sidecar-image job (build package, Docker build, smoke /health, /v1/render, /purge, 404s), and on changesets publish pushes ghcr.io/open-mapsight/ssr-sidecar:beta and a version tag. Docs (README, SSR_HYDRATION.md) now point CMS integrators at POST /v1/render and the published image.

^{Reviewed by Cursor Bugbot for commit ae95757. Bugbot is set up for automated code reviews on this repo. Configure here.}

[changeset-bot]

🦋 Changeset detected

Latest commit: ae95757

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@mapsight/ssr-sidecar	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit f4cfbe5. Configure here.}