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.

[rakesh2OO5]

Hi @coseeian — I’ve pushed an updated commit that resolves both the desktop sidebar flash and the mobile nav regression with a minimal diff (+19/-7).

Whenever you have a moment, I’d really appreciate a review. Thanks!

[coseeian]

While the root cause lies in the nav component's default state, I’m concerned that toggling it to true simply shifts the "flash" issue from desktop to mobile.

As shown in the recording below, although the issue of nav height is resolved, the hamburger menu button and chevron button in the top right flip states immediately after the page loads. (It's more visible if you slow down the playback speed).

Screen.Recording.2026-01-25.at.18.04.23.mov

Since we can't determine device type server-side in this project (correct me if I'm wrong), a client-side React state fix might always result in same issue. An alternative is to refactor and decouple the nav into two device-specific sub-components, each with its own appropriate initial state.

Trade-offs to consider:

• Bundle size: this would introduce more code to the client.
• CSS complexity: we would need to carefully manage the hidden styles via CSS media queries for each component.

Pinging @stalgiag for your thoughts on whether this structural change is worth the overhead.

[stalgiag]

That is correct @coseeian. When I originally wrote the issue though, I thought that we could simplify even further by moving away from Preact with dedicated subcomponents that hide/show via CSS (which feels like a workaround) and instead use Astro components. If I remember correctly the only reason for moving to Preact was to handle the default open state (different on mobile vs desktop).

I think based on my foggy memory that a small refactor could make it so that the server-rendered HTML picks the right initial CSS classes. Since the server doesn't know the viewport width, we'd want the default HTML to have no open class on either panel, and use a CSS media query to handle the desktop default:

  @media (min-width: $breakpoint-tablet) {                                                                                                                                
    .main-nav, .jumpto {                                                                                                                                                  
      // desktop default styles (expanded)                                                                                                                                
    }                                                                                                                                                                     
  }                                                                                                                                                                       

All of the interactivity could live in a in a small inline script with matchMedia and class toggling.

[rakesh2OO5]

Thanks for the detailed feedback @coseeian and @stalgiag — that makes sense, and I agree the root issue is the SSR vs hydration mismatch rather than just the client-side default state.

My intent with this PR was mainly to address the visible regression/flash as a short-term fix with a minimal diff, but I agree that a CSS-first + SSR approach (media queries for desktop defaults, no “open” classes in the server HTML, and a small matchMedia/toggle script for interactivity) is the more robust long-term direction and aligns better with the original goal of #477.

If you think it makes sense, I’m happy to:

-Treat this PR as a stopgap to resolve the current regression, and
-Follow up with a separate PR that refactors the nav toward the Astro/CSS default-state approach you outlined.

Let me know which path you’d prefer and I’m glad to take this forward .