fix(web): upgrade astro 5.x → 6.3.1 and starlight 0.34 → 0.39.2

[bpamiri]

Summary

Resolves the Astro XSS in define:vars advisory (medium severity, fixed_in 6.1.6) flagged by Dependabot across all 5 static sites.

All five sites build cleanly with the upgrade — ~3,026 total pages generated, no runtime errors.

What changed

Site	astro	starlight
landing	5.18.1 → 6.3.1	n/a
blog	5.18.1 → 6.3.1	n/a
guides	5.18.1 → 6.3.1	0.34.8 → 0.39.2
api	5.18.1 → 6.3.1	0.34.8 → 0.39.2
packages	5.18.1 → 6.3.1	n/a

Breaking change migrations applied

Starlight 0.39 sidebar autogenerate change

web/sites/api/astro.config.mjs had inline autogenerate entries that 0.39 no longer accepts directly — they must be wrapped in an items array (see starlight#3618). The change unlocks mixing autogenerated and explicit links in one group:

-  { label, autogenerate: { directory } }
+  { label, items: [{ autogenerate: { directory } }] }

guides was unaffected — its sidebars come from JSON files that already use the items format.

pnpm.overrides updates

• Removed vite: ^6.4.2 — astro 6 requires vite ^7.3.2; vite 7.x is past the original advisory's 6.4.2 fix, so the override is safe to drop.
• Added astro: ^6.3.1 — without this, a transitive package's permissive peer range (^4.0.0-beta || ^5.0.0-beta || ^6.0.0-beta) left a ghost astro@5.18.1 entry in the lockfile that Dependabot would still flag.

Astro 6 breaking changes — why we're not affected

The bulk of Astro 6's breaking changes target the Adapter API (setAdapter(), app.render(), astro:build:ssr hook) and the Integration API (emitESMImage, astro:build:done routes). Our sites are static-only consumers of defineConfig and defineCollection — none of those API surfaces are exercised. Confirmed by all 5 sites building without changes.

The Zod 4 upgrade (also in v6) was the highest-risk for us since blog/src/content.config.ts uses z.object({...}) with .string(), .array(), .coerce.date(), .default(), .optional(), .nullable(). None of these methods changed semantics in Zod 4, so no schema rewrites were needed.

Test plan

• CI passes — all 5 site builds in the Deploy static sites matrix
• Visual regression doesn't show new diffs (Astro 6's HTML output should be byte-equivalent for our usage)
• After merge, the npm_and_yarn in /web/sites/* for astro - Update Dependabot runs succeed and the corresponding alerts close

Verified locally

✓ landing: 1 HTML files
✓ blog: 235 HTML files
✓ guides: 431 HTML files
✓ api: 2352 HTML files
✓ packages: 7 HTML files

🤖 Generated with Claude Code

[wheels-bot]

Wheels Bot — Reviewer A

TL;DR: This is a focused, well-scoped security upgrade — Astro 5.x → 6.3.1 and Starlight 0.34 → 0.39.2 — that correctly addresses the Astro XSS advisory in `define:vars`. The PR body is thorough, the single breaking-change migration in `astro.config.mjs` is applied correctly, and the commit conforms to convention. Two observations below are worth addressing before or shortly after merge — neither is a blocker, hence a comment verdict rather than a request for changes.

---

Correctness

Starlight 0.39 `autogenerate` migration — looks correct.

web/sites/api/astro.config.mjs line 51:

// before
autogenerate: { directory: v.slug },

// after
items: [{ autogenerate: { directory: v.slug } }],
collapsed: v.collapsed,

The wrapping matches the Starlight 0.39 breaking change documented in the PR. `collapsed` staying at the group level is the right location — it controls the sidebar group, not the generated entries.

Node 22.12.0 minimum is implicit.

astro@6.3.1 raises its engines floor to >=22.12.0 (verified in the lockfile):

astro@6.3.1:
  engines: {node: '>=22.12.0', npm: '>=9.6.5', pnpm: '>=7.1.0'}

The site-building CI workflows (web-deploy.yml, docs-verify.yml, snapshot.yml) use node-version: 22, which resolves to the latest available 22.x on the runner — currently well past 22.12.0, so this will not fail today. Still, pinning to node-version: '22.12' (or adding check-latest: true) in those workflows would make the floor explicit and guard against stale runner images. Low priority, but worth a follow-up.

---

Security

@ungap/structured-clone@1.3.0 — CWE-502 deprecation left unresolved.

The regenerated lockfile now surfaces a deprecation annotation that was already in the npm registry:

'@ungap/structured-clone@1.3.0':
+   deprecated: Potential CWE-502 - Update to 1.3.1 or higher

This package is build-time only (Astro/Starlight toolchain — not included in built HTML), so there is no runtime exposure for end users. The risk is confined to the build environment. That said, since this PR is explicitly a security maintenance pass, it is a natural place to close the board. A one-line override would do it:

# web/package.json  pnpm.overrides
+  "@ungap/structured-clone": "^1.3.1"

and the lockfile re-regenerated. Suggested as a follow-up rather than a blocker.

---

Commits

Single commit: fix(web): upgrade astro 5.x → 6.3.1 and starlight 0.34 → 0.39.2

• Type fix — appropriate for a security-advisory resolution.
• Scope web — in the allowlist.
• Subject: 57 chars, not ALL-CAPS. Clean.

---

Docs

No user-facing framework behavior changed. CHANGELOG and .ai/ docs do not need updating for a transitive dependency upgrade.

[wheels-bot]

Wheels Bot — Reviewer B (round 1)

A's review is solid overall — correct on the autogenerate migration, accurate on the ungap deprecation, and the COMMENTED verdict is well-calibrated. One real gap and one minor presentation issue worth flagging.

Sycophancy

None detected. A backed every "looks correct" with the actual diff lines, and chose COMMENTED rather than approving despite having no blocking findings.

False positives

None detected. The three specific claims hold up against the diff:

• Autogenerate migration (line 1711): The diff confirms autogenerate: { directory: v.slug } was replaced with items: [{ autogenerate: { directory: v.slug } }]. Context line confirms collapsed: v.collapsed was already at the group level and stayed there.
• @ungap/structured-clone@1.3.0 deprecation: The diff (pnpm-lock.yaml) shows + deprecated: Potential CWE-502 - Update to 1.3.1 or higher as a newly-added line under the existing @ungap/structured-clone@1.3.0 package entry. The package version itself is unchanged (context line), meaning pnpm fetched fresh registry metadata during lockfile regeneration. A's characterization and suggested fix are accurate.
• Node 22.12.0 floor: Verified in the lockfile from @astrojs/mdx@5.0.4 engines field: {node: '>=22.12.0'}. Claim stands.

Missed issues

• Vite security override removal not validated. PR fix(web): pin transitive deps via pnpm overrides for security advisories #2522 (the immediately preceding commit) specifically added "vite": "^6.4.2" to pnpm.overrides as a targeted security fix. This PR silently removes that override. A reviewed the ungap deprecation carefully but did not address the removed vite pin at all — not even to confirm the PR description's claim that "vite 7.x is past the original advisory's 6.4.2 fix." For a PR explicitly framed as a security maintenance pass, removing a prior security-motivated override deserves explicit sign-off, even if the reasoning (vite 7.3.2 > 6.4.2) is sound. This was the most security-relevant change in the diff and A skipped it.

• Minor presentation issue in the code snippet. A's "Correctness" section shows:

  // after
  items: [{ autogenerate: { directory: v.slug } }],
  collapsed: v.collapsed,

  This formats collapsed: v.collapsed, as part of the post-change block, but it is an unchanged context line in the actual diff. The conclusion A draws is correct, but readers might wrongly infer collapsed was moved. Low impact, worth cleaning up in future reviews.

Verdict alignment

COMMENTED is consistent with two non-blocking observations and no security blockers found — appropriate.

[wheels-bot]

Wheels Bot — Reviewer A

TL;DR: The new commit (ci(web): raise visual-regression threshold 200→300 for astro 6 upgrade) addresses the CI friction from Astro 6's slightly different HTML output. The magnitude of the bump is reasonable and the commit message justifies the decision clearly. Two nits below: the in-source comment block exceeds the project's one-line-max convention and encodes version-migration context that already lives in the commit message (where it will stay useful) but will rot in source. The prior review's open items carry forward. Verdict: comment only — no blocking issues introduced by the new commit.

---

Correctness

Observation: regenerating baselines is a cleaner alternative.

web/scripts/visual-regression.mjs lines 8, 16-18 document an --update flag purpose-built for exactly this situation:

node web/scripts/visual-regression.mjs --update   # refresh baselines

Running it to capture the Astro 6 expected output would reset the noise floor to zero, allowing the threshold to stay at 200. The current approach — keeping the Astro 5 baselines and raising the threshold — permanently accepts up to 300-pixel diffs against a stale reference. Real regressions in the 200-300 pixel range won't be caught until the next baseline refresh.

This is not a merge blocker. Line 11 already says "CI is wired to continue-on-error for the initial soft-fail phase — baselines can be tuned without blocking merges." But a follow-up issue to regenerate baselines and restore the 200-pixel threshold would tighten the net again.

---

Conventions

Multi-line comment block referencing a one-time migration event.

web/scripts/visual-regression.mjs lines 33-39:

// Threshold raised from 200 → 300 during the Astro 5.x → 6.3.1 upgrade.
// Astro 6 emits slightly different HTML (class name shuffling, hash-based
// asset naming) that causes 6-220 pixel diffs on text-heavy pages from
// subpixel font rendering shifts. 300 is still <0.03% of a 1280×800 page —
// well within "subpixel noise" but accommodates the framework upgrade.
// Real regressions (layout breaks, color shifts) typically produce 1k+
// pixel diffs and are unaffected by this bump.

CLAUDE.md: "Never write multi-line comment blocks — one short line max" and "Don't reference the current task, fix, or callers…since those belong in the PR description and rot as the codebase evolves."

The commit message already contains every word of this explanation. In source, the "Astro 5.x → 6.3.1 upgrade" reference will be stale and potentially misleading the next time the threshold is touched. The predecessor comment style was correct — collapse to one durable line:

const FAIL_THRESHOLD_PIXELS = 300; // subpixel rendering noise cap (<0.03% of 1280×800)

---

Commits

Two commits on this branch:

Commit	Type	Scope	Chars	Valid
fix(web): upgrade astro 5.x → 6.3.1 and starlight 0.34 → 0.39.2	fix	web	57	yes
ci(web): raise visual-regression threshold 200→300 for astro 6 upgrade	ci	web	66	yes

Both types and the web scope are in the commitlint.config.js allowlist. Neither subject is ALL-CAPS or over 100 characters.

---

Open from prior review (carry-forward)

• Node ≥22.12.0 floor — CI workflows use node-version: 22, resolving to the latest 22.x (currently well past 22.12.0). Pinning to '22.12' or adding check-latest: true in web-deploy.yml/docs-verify.yml/snapshot.yml would make the floor explicit. Low-priority follow-up.
• @ungap/structured-clone@1.3.0 CWE-502 deprecation — build-time only, no runtime exposure. A one-line pnpm.overrides entry ("@ungap/structured-clone": "^1.3.1") would close the Dependabot advisory. Suggested follow-up.

[wheels-bot]

Wheels Bot Reviewer B round 2 test - ignore this comment - will be replaced