Fix reference sidebar flash by server-rendering directory

[rakesh2OO5]

Fixes #477

Summary

Server-renders the reference directory to prevent the initial sidebar flash and layout shift caused by client-only hydration.

Changes

• Added a server-rendered Astro component for the reference directory
• Kept client-side filtering as a progressive enhancement
• Updated ReferenceLayout to render the directory during SSR

Result

• Sidebar appears immediately on load
• No visible flash or layout jump
• Filtering behavior remains unchanged

[stalgiag]

Thanks! I will try to review this some time in the next month. If any other reviewers gets here first, please by all means feel free to review ahead of me.

[coseeian]

I pulled the changes to test them locally, but I noticed some unexpected UX on the page, and it seems like we’re still seeing the flash in the original nav (screenshot below).

Screen.Recording.2026-01-20.at.06.20.01.mov

It looks like the 'flashing' persists because the issue might be rooted deeper in how the global NavPanels component handles initial resizing on the client side (the desktop isOpen state being false by default): https://github.com/processing/p5.js-website/blob/main/src/components/Nav/NavPanels.tsx

Since this affects every page and not just the Reference section, I think we might need to shift our focus to that core component to truly solve the flash issue described in #477.

[rakesh2OO5]

Thanks for the detailed investigation and for pointing me to NavPanels.tsx.
I’ve converted this PR to draft while I rework the fix to address the root hydration mismatch in the global nav rather than just the reference directory.
I’ll mark it ready for review once the revised approach is pushed.

[rakesh2OO5]

Thanks again for pointing me to NavPanels.tsx — that was the key.
I’ve opened a clean follow-up PR that fixes the root hydration mismatch in the global nav with a minimal diff: #1102(closed currently)

I’m leaving this PR in draft as context for the earlier investigation. Happy to close it if you prefer.

[davepagurek]

@rakesh2OO5 it is probably easier to follow the discussion if you continue to commit to the same PR rather than opening new ones, as it contains everything to one place.

[rakesh2OO5]

That makes sense — thanks for the guidance.
I’ll move the fix into this PR and keep everything here so it’s easier to follow.

[rakesh2OO5]

Thanks for the guidance earlier — I’ve now consolidated the fix into this PR with a minimal diff (+36/-26) that addresses the root hydration mismatch in NavPanels and removes the sidebar flash without changing existing behavior.

@coseeian if you have a moment, I’d really appreciate a review on this updated version. Happy to iterate if anything needs adjustment.

[coseeian]

I pulled this PR down and test locally by navigation to /reference/p5/arc/. Noticed regression on mobile. It looks like the changes to address issue on desktop are affecting mobile nav behavior.

Expected: Nav should be closed by default.

Actual: menu nav keep opened, and reference nav closed with flash.

Screen.Recording.2026-01-23.at.07.09.50.mov

Please have a look. Thanks.

[rakesh2OO5]

Thanks for flagging this — agreed, mobile behavior should stay consistent with the expected default (nav closed).
I’ll adjust the logic to preserve the mobile default state and clean up the indentation in this block. Will push an update shortly.