but the site looks the same

i've been on leave from work for surgery and recovery, so naturally, in all the downtime my temporary unemployment has afforded me, i've gone and done exactly what i would otherwise do at work and did a bunch of web dev stuff.¹ namely, i've rewritten the entire website that you're looking at right now.

now if you've been here before, there's a very reasonable question you might ask, one that i've heard a few times now:

what do you mean you rewrote the site? it looks the exact same.²

to put it exactly, here's the generated image diff between the site immediately before all my work, and now.

ok fine, the text is larger and my coffee order is tamer.³ but what the hell was even the point of all of this?

.
├── index.html ## the home page
├── about-apple/
│   ├── apple-leadership.html
│   ├── career-opportunities.html
│   ├── investors.html
│   └── ...
├── where-to-buy/
│   ├── find-an-apple-store.html
│   ├── shop-online.html
│   ├── find-a-reseller.html
│   └── ...
└── for-business/
    ├── apple-and-business.html
    └── shop-for-business.html

state of the site before

this website is served from two hosts, neocities⁴ and a virtual private server.⁵ the difference between the two comes from neocities' strict content security policy that bans site scripts from fetching data from another web server, say data about if i'm online on twitch or data for a personal project.⁶ the codebase for this personal portfolio then had to accommodate the website and the server.

the frontend code used to create a single page application. that is to say that the entire html content of the page was a skeleton that instructs the browser to grab a bundle of javascript. there's no content on the page itself until the javascript loads and tells the browser how to fill in that skeleton. in practice, here's what the browser actually sees at first when you go to the site:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta http-equiv="X-UA-Compatible" content="IE=edge" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <script defer src="/main.js"></script>
</head>
<body>
  <div id="root"></div>
</body>
</html>

a perfect completely blank page until that main.js loads in. even if the client will load in the contents eventually, the issue with an initial blank page load is (from least handwave-y to most handwave-y):

1. some search engines' web crawlers don't bother with loading in and running javascript and don't index over any of the page content.⁷
2. waiting for javascript to render all the content bumps up the first contentful paint metric, doubly degrading the site seo.
3. users with slow connections and old devices might see a completely blank page for longer amounts of time.
4. transient dropped connections while fetching the javascript bundle will leave the page completely blank forever. the bundle is a single point of failure.
5. leaning on javascript to render non-interactive content where plain html will suffice is overkill at best, bloatware at worst.⁸

so what's in main.js anyway? it's a bundle of a bunch of other javascript written in a framework called react. it scripts out what html to render, how interactivity works, and how links navigate between pages -- everything the site is and does bundled into a single javascript file 444kB large.⁹

let's linger on that last point for a second. since javascript controlled routing between pages and the rendered content of the page, the static build of the website did not generate a directory structure that could be statically served; in the end, so long as the client got the skeleton and the big javascript bundle, it would visually render the right content. so when the static build sitting in neocities looked like this:

.
├── main.js
├── index.html
└── not_found.html ## an exact copy of index.html

clients got this nonsense 404 on a perfectly valid page:

$ curl -s -o /dev/null -w "%{http_code}\n" https://alts-alt.neocities.org/links
404 ## Not Found

in neocities, when a file isn't found, it falls back to serving a magic not_found.html.¹⁰ since javascript handled all the rendering for any page, i found it suitable to make not_found.html a verbatim copy of index.html. this meant that navigating to the links page caused a 404 that sent back the exact same html as the home page that javascript rendered to look the links page. the deployment on the virtual private server was no better since it copied neocities behavior exactly -- static file server with a fallback on a copy of the home page's html.

all in all, the whole system is a mess. the blank html confused search engines. the massive javascript file bloated the bundle. the client side routing created static builds that confused servers. what in the world was 2025 me thinking?

state of the site now

everything kind of makes sense now. i took a second to migrate the entire front end off of a javascript monobundle single page application and onto a static site generation framework called astro that generates contentful html at build time and doesn't require javascript to write it out. now, when the browser goes to the home page, it sees:

<!DOCTYPE html>
<html lang="en" class="dark">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width">
  <link rel="icon" href="/favicon.ico">
</head>
<body>
  <header>
    <nav>
      <a class="homeLink" href="/" aria-label="Home">alts_alt_</a>
      <a href="/links" aria-label="Links">/links</a>
      <a href="/projects" aria-label="Projects">/projects</a>
    </nav>
  </header>
  <main>
    <div class="container">
      <div class="username">alts_alt_:</div>
      <div>hi i'm alt!</div>

cleaned up and truncated for ease of reading, but it's actual content!

when the website source code is built and sent off to neocities, the canonical structure of the site is actually reflected in the file structure:

.
├── index.html
├── not_found.html
├── links.html
├── blog/
│   └── but-the-site-looks-the-same.html
└── projects/
    ├── pixel-svg-maker.html
    ├── palette-posterizer.html
    └── kennel-club.html

which means that neocities' static file servers correctly recognize when a page actually exists.

$ curl -s -o /dev/null -w "%{http_code}\n" https://alts-alt.neocities.org/links
200 ## OK

as for the virtual private server, because i run the server and write all the source code myself, i realized that i didn't actually need to just serve a static file server the same way that neocities does.

astro has an option to ship its own server that enables on-demand html prerendering,¹¹ so i migrated my web server to use that instead.¹² this meant building out a dual-target deployment strategy: one static build for neocities and one server build for the vps. this also meant writing up some amount of logic to forward webpage requests over to that astro server,¹³ but now that it's all said and done, the site is at a point where javascript is more or less only used for controlling interactivity.

so where do we stand on the issues listed above? the quick flash of a blank page is no longer there, and i assume that for folks with slower connections, it's a far less jarring experience. and for the first time, the website actually shows up when you google it.¹⁴

other random things i changed

i also took care of a bunch of random other stuff during this work (asset optimizations, a kind-of design system library, fixing up the default contrast of color tokens) but here are the ones that deserve some explanation:

dropdown menus

if you've talked to me at any point in the last year, you'll have seen this coming. if you want a brand new brain worm, try going to a webpage that has a pop up menu that opens when you click it and navigating the menu with your arrow keys. better yet, if you have access to a screen reader,¹⁵ try turning it on and see what happens.

i'll wait.

you'll find that about 80% of the time, it either looks weird (good ending) or the interaction is a little strange (medium ending) or it just doesn't work (bad ending). and if you do this across a couple of sites, even with the ones that work, you'll find that they all work just a little bit differently. this to me is a damn shame from an accessibility standpoint, especially because there's very clear and detailed specs for expected behaviors for this kind of user interaction.¹⁶

and so, putting my money where my mouth is, the dropdowns on my site now follow this spec

kennel club collision engine

i've spent truly an undue amount of time on my kennel club project that has creatures representing my friends' websites running around a little kennel. for the longest time, it was one lonesome creature walking around, mostly napping, with frames ticking at 1 fps. i decided that as long as i was revamping my site, i would bump it up to six creatures with frames ticking at 12 fps.

i don't know what i expected, but of course the collision algorithm immediately broke. that's truly what i get for thinking that i could just brain blast it on my own in a programming language that i didn't (and arguably still don't) understand.

so i went back to the books and did a bunch of research to find a canonical 2d collision resolution algorithm, and landed on implementing the one that box2d uses.¹⁷

i've got nothing to say except that it actually works now. i'm curious to know how many simultaneous connections to the server will topple it over, so if you see that the photo that i put below hasn't loaded, you should submit an issue on github to the kennel club repo.