PRDCT-360: rework the 404 page and add the Ink-dash octopus game

[Iamfle4ka]

What

Reworks the 404 page so it helps with the most common way people land there — a typo — and turns the octopus into something worth playing without letting it take the page over.

The 404 was an entry in the docs collection, so it inherited chrome that makes no sense there: the right-hand "On this page" rail, the Copy as Markdown split button (whose View as Markdown led nowhere), the section eyebrow pill and prev/next pagination. It opened with a 400×390 PNG whose baked-in white background rendered as a white square in the dark theme, then a long tail of links.

It is now a real Astro page rendered through <StarlightPage>. The sidebar stays — on a 404 the sidebar is the answer to "where was I supposed to go" — and everything else goes.

Helping with the typo

Visiting /storage/data-strems/ used to produce a page that never said which path had failed, offered nothing close to it, and opened the search box empty although the URL already said what was wanted. Now it:

• names the address that failed, on one quiet grey line that doubles as the lead-in to the guesses — /storage/data-strems/ · did you mean:, or · nothing matches that address when nothing scores. Michal asked for this line to go; not naming the address is precisely what led him to read a working link as broken, so it stayed and stopped shouting instead;
• offers up to three closest real pages (Data Streams first for that example);
• falls back to the longest existing ancestor section (/storage/), which helps even when nothing scores well;
• ends in the two moves that always work: Home and Search, side by side. Home is a real <a href="/"> so middle-click and open-in-new-tab behave; Search opens Starlight's modal, prefilled with the top guess (and empty on /404.html). Both carry Starlight's not-content class, because its prose link rule outranks a plain class and painted the Home label accent-blue on the accent-blue fill — an empty blue rectangle. The Documentation home bullet left the list below, since it is now the same link twice.

Matching runs against a list of real slugs embedded at build time, not through Pagefind. The problem is a mistyped address and Pagefind indexes content: searching "data strems" returns Snowflake and Streamlit pages, while distance-to-real-slugs returns Data Streams first. It also keeps working in npm run dev, where Pagefind isn't built, with nothing async to race. ~297 pages cost about 20 KB of raw JSON on a page that is already 95 KB of HTML.

It stays quiet when it should: nothing above a similarity threshold, so /wp-login.php gets no invented guess, and the whole block hides on /404.html and /, where claiming "there's no page at /404.html" would be false.

The game: a scene that is compact until you play

Three shapes were tried and the third is the one that holds. A permanently tall framed panel pushed the recovery links below the fold. A frameless Chrome-dinosaur strip fixed that and killed the game — flat, unreadable, "decoration" in the sense of nothing. What ships is compact while resting, full field only while playing: ~215px at rest, 462px once a game starts, and start() scrolls the grown field into view when it does not fit.

Where it sits was tried both ways. Michal's note offered "a bit of spacing or right at the top", we took the top, and in place it put the octopus ahead of everything that actually recovers the visit. It now follows the Home/Search buttons and precedes the fallback link list — failed address, closest pages, the two exits, and only then the thing to do if none of that helped. Measured at an 800px-tall viewport: suggestions at 215, buttons at 387, panel 459–675, links heading 707, first link 748. Game-first those were 463 / 634 / 215 / 714 / 755 — the recovery block used to start halfway down the screen, while the link list lands in the same place either way. The compact resting state (~215px) is what keeps any of this affordable, and the full field is only taken while somebody is playing and nobody is reading the links.

The scene is open water: no seabed, no floor line (both were added for the shallow strip and made it read as a tank). Depth comes from four things instead:

• a saturated wash — sea blue #cfe6f5 → #7fb4d8 in the light theme, deep navy #0a1b30 → #16456e in the dark one — with a third stop a third of the way down, because a plain two-stop ramp left the light theme's upper half near white and the whole panel read as a marketing banner;
• three slanted light shafts, breathing in alpha only;
• particulate whose size, speed and opacity are correlated, so the small faint slow motes read as far away, with a handful of large ones drifting in front of the player;
• a vignette, so the panel has a centre rather than meeting its frame at full strength.

Cubes and enemies carry a halo drawn from a cached radial-gradient bitmap per colour and theme — ctx.shadowBlur is the obvious way and costs a full-canvas blur per object, which is a measurable stall at twenty of them on a phone.

The other half of the cure was scale: the world is 840 units wide, not 960, so everything is drawn ~16% bigger in the same box, and the octopus is back to the proportions of the first version — big, centred and mid-water at rest, with the copy as one centred row along the bottom instead of a stack that forced it small or off to one side.

Enemies, and the level-15 squid

The roster is a data table, not scattered conditionals: 404, 500, 403, 429, 502 drift in one new code per level, level 6 introduces 504 as a chaser that steers instead of bouncing, and level 15 introduces 503 — a big squid.

The squid is the only enemy that moves in bursts. It stalks the octopus at a steady 2 units (the player's cap is 7), winds up for ~0.4s — arms gathered, mantle squashed, which is the tell the dodge is owed — and then jets at 12.4 with no steering at all: the direction is sampled once and everything after that is ballistic, bouncing off walls until friction or the timer returns it to a stalk. Radius 30 against the jellyfish 18, with a forgiving hitbox so it feels like the mantle rather than the tentacle spread. One from level 15, a second at 19, a third at 23.

With a squid on the field the swarm gets out of its way: 4 jellyfish instead of the usual 9, 3 once there are two squids. A full field plus a charging boss was unreadable chaos — the boss is the level.

The difficulty curve, after playtesting

Michal played it repeatedly and every run ended the same way: level 10, all three lives gone, nobody ever reaching the boss. The numbers explained it. Speed climbed linearly (1.7 + 0.28 per level) and passed the player's own cap of 7 around level 20 — those levels were not hard, they were unplayable, with nothing to dodge to. The crowd hit its ceiling of 11 at level 9. Lives were fixed at three. And a hit always respawned the player at the same spot with 1.2s of grace, which on a crowded level means landing back in the crowd that just hit them — the rest of the lives went in seconds.

Four changes, aimed at you can keep playing, not at it is easy now:

• speed is asymptotic, 1.7 + 3(1 − e^−(level−1)/6), approaching 4.7 and staying well under 7 — pressure past the plateau comes from density and from the chasers, which a player can answer;
• the crowd grows every other level and stops at 9;
• a life back every fifth level, capped at five, announced on the level banner (Level 10 · +1 life): three at the start, four from 5, five from 10;
• respawn picks the emptiest of six candidate spots — the one whose nearest enemy is furthest — and grace goes 1.2s → 1.5s.

level	speed old → new	enemies	lives
5	2.82 → 3.16	7 → 6	4
9	3.94 → 3.91	11 → 9	4
10	4.22 → 4.03	11 → 9	5
15	5.62 → 4.41	4 (boss)	5
19	6.74 → 4.55	3 (2 bosses)	5
23	7.86 → 4.62	3 (3 bosses)	5

Early levels come out a touch faster (2.55 vs 2.26 on level 3) with one fewer enemy — a wash. The boss stays on 15: the point was to make 15 reachable, not to move it.

Enemies differ by silhouette, not by their number: dome drifters, a spiked diamond chaser, and the squid drawn along its heading with head and tentacles leading and mantle and fins trailing, plus a lighter rim so the darkest body in the roster still separates from deep navy. Labels are dropped below ~7 CSS px, so on a phone the number is invisible and the shape has to carry it.

Two fixes worth calling out

Sticking to the walls. The player's position was clamped at the field edges but the velocity was not. Holding a direction into a wall kept accelerating, so vx sat at -MAX_SPEED while the octopus looked parked, and letting go left friction plus the opposite input a full second of work before anything moved — it read as being stuck. The into-wall component is now zeroed; zeroed, not reflected, because a player bouncing off scenery reads as losing control too. Pointer targets are clamped into the play area for the same reason: a finger dragged up into the HUD band used to leave the octopus pushing at the ceiling forever.

The Stop button is half the size it was (74×40 → 43×21). It is an escape hatch for anyone without an Esc key, not something anybody aims for, and at full size it took a visible bite out of the field's corner. It only looks that small: a ::before gives it a 44px tap target, because on a phone it is the only way out — there is no Esc, and drag-to-swim means the field's edges are not an exit either.

Cost, because this is an easter egg and not an engine

• The loop stops entirely when the panel is off-screen (IntersectionObserver) or the tab is in the background, and resumes with a fresh clock so dt cannot jump.
• The resting panel runs at half rate, carrying skipped time forward so the drift keeps its speed rather than halving.
• The wash and vignette gradients are built once per box/theme/level instead of once per frame.
• Particulate capped at 40 motes (was up to 60), shafts 3 (was 4).

The whole component is 14 486 bytes of JS, up from 11 350 before the squid and the scene. No new dependencies, no sprite assets — everything is still drawn in code, so it stays crisp on retina and follows the theme.

Deployment contract

The output path does not move. Astro still emits dist/404.html at the root, which is what production serves. Starlight ships its own routes/static/404.astro, which collides with a user page at that route — a warning now, a hard error in later Astro versions — so disable404Route: true is set.

Note for anyone sharing the page: /overview/404.html is not a route (it never was). Vercel answers any unmatched path with 404.html, so that URL does show this page — which has already led one reviewer to conclude the link was broken. Share a plausible-typo URL like /storage/data-strems/ instead; it is also the honest experience, suggestions included.

Notes for review

Each of these was a bug first:

• The keyboard is never stolen. Movement keys are preventDefault-ed only while a game runs. Starting is a real <button> covering the panel, so click, tap, space and Enter all work without a global space handler — hijacking space would have taken scrolling from the page.
• Teardown on astro:before-swap. This site runs ClientRouter, and a broken internal link reaches the 404 through a client-side swap; without teardown the rAF loop and window listeners leak.
• Init does not depend on catching the initial astro:page-load. Astro emits page-level scripts after </html>, which is why the search button silently never bound at first.
• The search button defers its click. Starlight's openModal() registers a window-level click-outside-closes-me handler as it opens, so triggering it synchronously let our own still-bubbling click close the modal instantly.
• The auto-scroll uses window.scrollTo, not element.scrollIntoView. An ancestor in the Starlight layout is itself a scroll container, and scrollIntoView moved the page all of 5px while the field stayed below the fold.
• HUD text is sized in CSS pixels, not world units — fixed world-unit text rendered the score at ~5px on a phone.
• CSS owns the panel's size (two aspect ratios plus a min-height per state); the script only reads it. Both states share one world width, which is what keeps the octopus the same size when the panel grows.
• Below a phone width the panel stops shrinking and the world narrows instead. At 87px tall the Stop button alone covered a third of the play area.
• Enemies spawn across the whole field, clear of the player and each other, with radius-scaled distances so the squid gets the room it needs.
• Literal #fff on accent-coloured buttons: Starlight flips --sl-color-white to near black in the light theme.

Verification

npm run build clean. dist/404.html at the root and no dist/404/; page absent from the Pagefind index and marked noindex.

Typo helper, in a production preview: /storage/data-strems/ shows the quiet lead line, suggests Data Streams first and offers /storage/; /compentns/ suggests Components; /zzz/qqq/ shows "nothing matches that address" with no guesses; /404.html hides the block but keeps both buttons; search opens prefilled with "Data Streams" on the typo and empty on /404.html; Home resolves to /; the recovery list now starts at connection.keboola.com.

A page-walk of the deployed preview (Playwright, four viewports, both themes, reduced motion) found two real bugs, both fixed here. Search prefill was garbage on the one URL that started all this: /overview/404.html published its raw last segment, so the page's own call to action opened Pagefind on "404.html" — eight irrelevant hits, confirming the "this is broken" reading it exists to dispel. The fallback query is now sanitised and, when nothing sensible remains, not published at all. Arrow keys stopped scrolling the page while a game ran off-screen: the keyboard gate now also requires the panel to be in the viewport, measured with getBoundingClientRect at the moment the key arrives rather than read from the IntersectionObserver, which is async, carries an 80px margin and never fires in a background tab. Same pass: the hint line measured 3.71:1 on the light theme's water and is now theme white; the "optional game" note moved ahead of the button and is tied to it with aria-describedby; start() no longer drops focus to <body>; Stop keeps its 43×21 look but gets a 44px tap target; and below 600px the hint swaps to "Drag to swim · tap Stop to leave" instead of disappearing.

Game, in a production build: both themes in both states; the 338px-wide panel (min-height holds, the world narrows, labels stay legible, HUD compacts to L15 · ●●● · 0); auto-scroll on Play from a scrolled-to-top page; death gives "Caught by a 404 — score N." and Esc/Stop return to the compact panel; the depth ramp measured per level (#87b7d8 → #698cc6 in the light theme, navy to indigo in the dark one); one rAF loop surviving two view-transition reboots (59 → 61 fps).

Level 15 was checked by temporarily starting the game at that level in a local build — the override is not in this branch: one squid plus four jellyfish, the banner "Level 15 · 503 incoming", and "Caught by a 503" on death.

On this PR's deployed preview: /404.html returns 200 with the game present; the shipped bundle carries the squid behaviour, the wall-clamp fix, the viewport-aware keyboard gate and both pause paths; page order is suggestions → Home/Search → game → recovery links. prefers-reduced-motion holds up under emulation — canvas pixels byte-identical over 600ms.

Not verified live, and worth a reviewer's eyes: per-frame timings and the off-screen pause as a measurement rather than as code plus a bundle check; the squid's wind-up frame never caught in a screenshot; levels 19 and 23 (two and three squids); and touch on a real phone, where only the narrow-panel geometry was exercised.

Known, not fixed here: the suggestion index holds canonical slugs only, so /transformations/pyhton/ misses Python Transformation (a redirect alias) and prefills the search with "dbt Transformation"; and eight duplicate-title pairs (extractor vs writer PostgreSQL, MySQL, BigQuery…) can rank the wrong one first — the grey path under each guess is what disambiguates. Outside this PR: /api/ is shadowed by Vercel's functions directory and answers with Vercel's own raw 404, and /wp-login.php is stopped by the firewall with a 403, so the bot-noise threshold never actually engages in production.

Note on hosting

The site is served by Vercel, so 404.html at the build root is what production returns for an unmatched path — verified on this PR's preview: /compentns (no trailing slash) returns 404 with this page, /components/ returns 200. The aws s3 sync step in .github/workflows/main.yml still runs on every push to main and AGENTS.md still calls it the production deploy; that description is out of date (corrected in #1057) but does not affect this change.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
connection-docs	Ready	Preview	Aug 5, 2026 5:35pm

[linear-code]

PRDCT-360