DEV Community: Jonás Javier Encarnación

How to hire a freelance web developer in the Dominican Republic

Jonás Javier Encarnación — Fri, 02 Oct 2026 21:45:36 +0000

Every so often I hear from someone who's already had a bad experience: they
paid for a website or a system, got something half finished, and now they have
neither the code nor access to their own domain. It's almost never a talent
problem. It's a hiring problem: no written scope, no progress to look at, and
no clarity about who owns what.

I'm a freelance full-stack developer in Santo Domingo, and I work with clients
here and abroad. This guide is what I'd ask for if I were on the other side of
the table. It works for hiring me, and it works just as well for hiring anyone
else.

Before you search: what problem are you solving?

"I need a website" is the most common starting point and the least useful one.
Before you talk to anyone, try to answer three questions:

Who will use it, and for what? A site that presents your business, a store where people pay, an internal app your team works in every day, and an app on your customers' phones are four different projects.
What does success look like? More bookings, fewer calls asking the same question, an inventory that finally adds up. If you can say it in one sentence, the developer can design for it.
What do you already have? A logo, photos, a catalog in Excel, an Instagram account that works. All of that saves time and money.

You don't need to know technology. You need to know what you want to happen
once the project is live.

Look at full case studies, not screenshots

A portfolio of pretty screenshots tells you little. What actually informs you
is a case told in full: what the problem was, what was decided and why, what
it was built with, and what happened after. If a developer can explain their
decisions, they'll be able to explain yours.

In my case, projects are published that way. OMSTA is
the management system of a real travel agency, with its mobile app, and
Delicaté is an online store running in production
on its own domain. In each one you can read the scope, the design decisions
and the engineering, and open the demo where there is one.

Two questions worth asking about any case: is it in use today? and
which part did you build? Both have honest answers and evasive answers,
and you can tell them apart.

Ask for a written proposal

"How much does it cost?" is the question everyone asks first, and the honest
answer is always the same: it depends on the scope. What you can demand is that
the scope be written down before you pay anything. A serious proposal has, at a
minimum:

What will be built, in language you understand, screen by screen or feature by feature.
What's not included. This section prevents most arguments.
A timeline in dates or weeks, not "soon".
Budget and payment terms, with what's delivered at each payment.
What's needed from you and by when: copy, photos, access, decisions.

I send that proposal after the first conversation and before writing a line of
code. If someone gives you a fixed price in their first message, having barely
asked you anything, they're guessing.

Progress you can open on your phone

The simplest way to avoid surprises is to see the project while it's being
built. Not screenshots: a real link you can open on your computer or your
phone, tap through, and show to anyone you like.

In my workflow, every milestone goes up on a link like that. It does two
things: you see that the thing exists and is moving, and we both catch what
needs changing early, while changing it is cheap.

The four steps I follow on every project. The third one, build, is the one that brings the most peace of mind: progress on a real link, not on promises.

Ask who owns the domain, the code and the accounts

This is where most people lose out. Before starting, get it in writing:

The domain is in your name. You hold the account it was registered with, not the developer. If they register it for you, they transfer it or hand you the access when the work is done.
Hosting and services (email, payment gateway, database) live in your accounts, or in accounts where you have owner access.
The code is yours once it's paid for, and you receive a copy or access to the repository.
There's a list of credentials delivered at the end, with everything someone else would need to pick up the work tomorrow if it came to that.

A serious developer isn't bothered by these questions. They're normal.

What happens after launch

A website or an app isn't finished the day it goes live. There will be
adjustments, a domain renewal every year, and one day you'll want to add
something. Ask:

Who handles publishing it and the domain?
What happens if a bug shows up in the first weeks?
How are small changes billed afterwards?

In my case, I take care of the release and the domain, and I stay around after
delivery. What matters is that you know beforehand, not that you find out when
something breaks.

Remote or in person, in English or Spanish

Working with someone in the Dominican Republic has an obvious upside if your
business is here: same time zone, same language, and meeting in person when it
helps. But hiring a freelancer no longer requires them to be in your city. I
work remotely with clients in any country, in English or Spanish, and in Santo
Domingo we can meet face to face.

What remote work does require is clear communication: an agreed channel,
answers within a reasonable time, and decisions in writing. Ask what that
communication will look like before you start.

Warning signs

A few things that, if you see them, are worth stopping for:

Nothing is in writing, or the scope is one sentence.
They can't show you a project in use, or can't explain what they did on it.
Everything will be "ready in a week", whatever it is.
They don't ask you questions about your business.
The domain or hosting is "easier if I put it in my name".
They ask for full payment up front.

None of these proves bad faith on its own. Together, they almost always do.

How I work

So you're not left with theory, this is what a project with me looks like from
start to finish:

Conversation. I learn the problem, who will use it and what success looks like.
Proposal. Scope, timeline and budget in writing, before we start.
Build. I design the interface before coding it, and every milestone goes up on a real link you can open and try.
Launch. Release, domain and support after delivery.

I build custom web applications with Django and React, online stores and
business sites, mobile apps with React Native and, when a project calls for it,
3D experiences like the ones on this site. All with published case studies you
can open before you write to me.

Write to me

If you have a project in mind, tell me about it on the
services page or straight through
Contact. I read every message and reply personally. And if all
you wanted was this guide to hire someone else, use it: that's what it's for.

Originally published on my portfolio, next to the blog. I'm Jonás Javier Encarnación, a full-stack developer and UX/UI designer in Santo Domingo, Dominican Republic: how I work.

The physics of Interstellar's black hole, seen in a simulator

Jonás Javier Encarnación — Fri, 02 Oct 2026 21:36:13 +0000

The first time I watched Interstellar I assumed Gargantua was a very good
visual effect. Years later, building
my own simulator for this site, I
understood it's closer to the opposite: very little in that image is invented.
The shadow, the disk wrapping over and under it, the thin ring of light hugging
the edge: all of it comes out of one equation, the one that describes how light
bends near an enormous mass.

This post explains that physics without hard maths, using the simulator as a
whiteboard. If you want to know how it's programmed (the shader, the steps,
the performance), that's in
How I built a black hole in WebGL.
Here the question is different: why does a black hole look like this?

What Gargantua is

Gargantua is the black hole in the film Interstellar (2014). The physicist
Kip Thorne, who advised the production and later won the Nobel Prize for the
detection of gravitational waves, asked for it to be computed for real: the
effects studio Double Negative wrote a ray tracer that followed light around a
spinning black hole, and the result was published in 2015 as a scientific paper
in the journal Classical and Quantum Gravity.

In the story, Gargantua is a supermassive black hole, about a hundred million
times the mass of the Sun, and it spins very fast. Neither detail is set
dressing: the mass decides the size of everything you see, and the spin is
what makes Miller's planet possible, where one hour equals seven years on
Earth. A black hole that didn't spin wouldn't allow an orbit that close to the
horizon, and without that closeness there'd be no time dilation that extreme.

The shadow: why the centre is black

A black hole isn't an object you see: it's a region light doesn't leave. Its
boundary is the event horizon, and for a non-spinning one its radius is the
Schwarzschild radius, rs. For a mass like the Sun's that's about three
kilometres; for Gargantua, hundreds of millions.

The curious part is that the black patch you see on screen is quite a bit
bigger than the horizon. At 1.5 times rs sits the photon sphere: the
distance at which light can circle the hole completely. Any ray that passes
inside that sphere ends up falling in. Seen from far away, that produces a
shadow whose apparent radius is √27/2 · rs, about 2.6 times the horizon. In
the simulator you can measure it: the shadow takes up 2.6 times what the
horizon would, and nobody drew it at that size. It falls out of following the
light.

Shadow view. The black in the centre isn't a texture: it's the set of rays that, traced backwards from the camera, end up inside the horizon.

The accretion disk, above and below

What glows around Gargantua is the accretion disk: gas spiralling into the
hole, heated by friction until it emits light. It's a flat disk, like Saturn's
rings. So why does it also show above and below the shadow, like a halo?

Because light leaving the back of the disk doesn't travel in a straight line.
Gravity bends it over the top of the hole and under the bottom, and it reaches
the camera from above and from below. The upper arc is the far side of the disk
seen over the shadow; the lower arc is the same far side seen under it. That's
the phenomenon called gravitational lensing, and it's why Gargantua doesn't
look like a ringed planet but like something nobody had seen before the film.

Lens view. A flat disk also appears above and below the shadow: gravity brings the hidden side all the way to the camera.

In the simulator, the Lens control turns that bending off. Without it the
disk looks like what it geometrically is, a flat ring, and the image loses
exactly what makes it recognisable.

The photon ring and the secondary images

Hugging the edge of the shadow there's a very thin, very bright ring. It's the
photon ring: light that went half a turn, or a full turn, around the hole
before escaping towards the camera. Each extra turn produces a thinner image
closer to the edge, and in theory there are infinitely many, each finer than
the last.

In the simulator, the Secondary images control decides how many of those
turns are followed. With it off, the edge of the shadow gets poorer; with it on,
the blade of light appears and, under the disk, a second, smaller image of the
hidden side. In the first version of my Gargantua that ring was drawn as a
one-pixel circle; it looked like a painted circle and I removed it. Now it's
what light does when it stacks up.

Doppler: the approaching side shines brighter

Here's the part the film decided not to show. The gas in the disk spins at a
sizeable fraction of the speed of light. The side coming towards you emits
brighter, bluer light; the side moving away, dimmer and redder. That's the
relativistic Doppler effect, the same principle that changes the pitch of a
siren as it passes, applied to light. On top of it comes gravitational
redshift: light leaving from near the hole loses energy on its way up.

A real black hole would look lopsided: one side of the disk clearly
brighter than the other. Thorne and the effects team computed it, and
Christopher Nolan chose to drop it from the film because audiences wouldn't
have understood why the disk looked skewed. It's documented in the 2015 paper:
Gargantua in the cinema is a symmetric, deliberately simplified version.

With Doppler. The approaching side shines a little over twice as bright as the receding one, and shifts towards cream while the other stays copper.

Without Doppler. This, more or less, is how the cinema preferred to show it.

In the simulator, Doppler is on by default, because I wanted to see the version
physics asks for. With the Doppler control you can turn it off and see the
"film" version. It's the control that changes the image the most of the three.

What the simulator does differently from the film

I want to be precise about what this Gargantua is and isn't:

It doesn't spin. The film's is a Kerr black hole, a rotating one. Mine uses the Schwarzschild geometry, that of a non-rotating black hole, because tracing the rotation pixel by pixel in real time in a browser was too expensive. What does spin is the gas in the disk.
The disk is further out. Around a non-spinning black hole, gas can't orbit stably inside three times the horizon. Around one spinning very fast, like Gargantua, that innermost orbit moves much closer in, which is why in the film the disk reaches almost to the shadow. In the simulator the disk starts a little inside that orbit, at 1.58 times the horizon, and extends out to 17.
Doppler is on. The film removed it; I left it in, and it can be turned off.
The disk is a drawing, not a gas simulation. Its texture is noise that rotates at different speeds with distance, as the gas would, but nobody is solving fluid equations here.

What is identical is the part that matters: light follows, ray by ray, the
geodesic equation of a black hole. The shadow, the arcs, the photon ring and the
secondary image aren't painted anywhere.

How to use the simulator

Open Gargantua in the Observatory
and switch to Study mode. There are four views:

Cinematic: the film's framing, with the disk edge-on.
Lens: closer and higher, to see both arcs and the secondary image.
Disk: the disk almost face-on, where the gas's differential rotation shows.
Shadow: the edge of the shadow up close, where the photon ring shows.

And three controls that switch real physics off: Doppler, Secondary
images and Lens. My advice is to turn them off one at a time and watch
which part of the image disappears: that's exactly what each phenomenon
contributes.

The simulator runs in any browser with WebGL2. If the device can't manage it,
or if you'd rather not spin up the graphics card, the site shows a flat version
with the same content.

Questions I get asked

Has anyone seen a real black hole? Yes. In 2019 the Event Horizon
Telescope published the image of the black hole at the centre of the galaxy
M87, and in 2022 the one at the centre of our own galaxy, Sagittarius A*. They
are blurry orange rings, very different from Gargantua, but they show the same
thing: a central shadow and light bent around it. And yes, the brighter side of
M87's ring is the one moving towards us.

Does Gargantua exist? No. It's a fictional object with a mass and a spin
chosen so the story works. What does exist is the physics it was computed with.

Why is one hour seven years on Miller's planet? Gravitational time
dilation: near an enormous mass, time runs slower. For the difference to be
that large the planet has to orbit very close to the horizon, and that's only
possible if the black hole spins almost at the limit. It's one of the places
where the film stretched the physics as far as physics allows, but not beyond.

Why is the film's disk so faint? A real disk around a black hole swallowing
a lot of gas would blaze in X-rays and fry any nearby planet. The film's is,
on purpose, a cold, anaemic disk, so the crew can get close.

Try it

Open the simulator and, before
touching anything, try to find the shadow, the two arcs and the photon ring.
Then turn Lens off and watch the halo vanish into a flat ring. That
difference is general relativity.

If what interests you is how it's built inside,
here's the shader. And if you'd
like a 3D experience like this for your product or brand, here's
how I work.

Originally published on my portfolio, next to the Observatory. I'm Jonás Javier Encarnación, a full-stack developer and UX/UI designer in Santo Domingo, Dominican Republic: how I work.

A bilingual Next.js site without middleware

Jonás Javier Encarnación — Fri, 02 Oct 2026 21:34:56 +0000

This site is fully in English and Spanish. English is the default and Spanish
is one click away, in the header. Every page has its own address in each
language — /en/about and /es/sobre-mi, /en/contact and /es/contacto —
and Google knows they're the same page in two languages, not two pages
competing with each other.

All of it is built on the Next.js 16 App Router, with no internationalisation
library and no middleware. This post walks through how, with the real code,
and above all why each decision is the way it is.

Three decisions before writing any code

Each language has its own URL. No serving English or Spanish at the same
address depending on who's asking. A page that changes with the
Accept-Language header can't be cached reliably, can't be linked knowing what
the other person will see and — most importantly for search — is always
crawled in the same language. Half the site vanishes from the index.

Routes are translated. /es/sobre-mi, not /es/about. People searching in
Spanish type in Spanish, and the URL is part of what they see in the result.
It's more work — a static folder can only have one name — and most of this post
is about paying that cost once.

One explicit default language. The root / goes to /en, and the
x-default in hreflang points to English. Spanish isn't a second-class
translation: it's the language the content is written in first. But the
audience reaching the site from outside the Dominican Republic searches in
English.

The language is the first segment

The whole site hangs from app/[locale], and that segment holds the root
layout, the one that writes <html>. That matters for a specific reason:
the lang attribute has to be in the served HTML, not patched in later with
JavaScript. It's what screen readers and search engines read.

export function generateStaticParams() {
  return PUBLISHED_LOCALES.map((locale) => ({ locale }));
}

// Only published languages exist: `/fr` or `/xx/contacto` are a straight
// 404, never rendered on demand.
export const dynamicParams = false;

dynamicParams = false makes any language not on the list an immediate 404.
Without that line, Next.js would try to render /fr on demand and cache it.

There's a price: with one root layout per language, switching language reloads
the whole document. I accepted it. It's something you do once per visit, and in
exchange each language's HTML is right from the first byte. The other
consequence is that a route outside any language has no layout to render its
404; that's what app/global-not-found.tsx is for, currently enabled with
experimental.globalNotFound.

Translated routes with one dynamic folder

The obvious way to have /es/proyectos and /en/projects is two folders. That
works for a one-off page — privacy has privacidad/ and privacy/, each only in
its own language — but it doesn't scale: every child page would have to be
duplicated, and its code with it.

The usual alternative, a rewrite (in next.config or middleware), has a trap:
usePathname returns one route on the server and another on the client, and
any component that marks "you are here" ends up out of sync.

So sections are a dynamic segment: app/[locale]/[mundo], with children in
[mundo]/[sub] and [mundo]/[sub]/[objeto]. Each section's slug lives in the
frontmatter of its content, per language:

# content/es/worlds/endurance.mdx
id: endurance
slug: proyectos

# content/en/worlds/endurance.mdx
id: endurance
slug: projects

The two versions are joined by id, never by slug. Segments that don't belong
to any section — servicios/services, gracias/thanks,
observatorio/observatory — live in a separate module with no dependencies,
so client code can read them too:

export const PATH_SEGMENTS = {
  observatory: { es: "observatorio", en: "observatory" },
  thanks: { es: "gracias", en: "thanks" },
  services: { es: "servicios", en: "services" },
  privacy: { es: "privacidad", en: "privacy" },
  blog: { es: "blog", en: "blog" },
} as const satisfies Record<string, Record<Locale, string>>;

Every dynamic page declares its generateStaticParams in both languages and
also sets dynamicParams = false. The result: the whole site is generated at
build time, and /en/proyectos — the Spanish slug under English — is a 404, not
a duplicate page.

Name pages, not URLs

This is the piece that makes everything else easy. Nowhere in the code is a page
named by its route. It's named by what it is:

export type PageRef =
  | { kind: "home" }
  | { kind: "world"; id: WorldId }
  | { kind: "project"; id: ProjectId }
  | { kind: "services" }
  | { kind: "observatory"; id: WorldId }
  | { kind: "blog" }
  | { kind: "article"; id: ArticleId }
  | { kind: "privacy" };

One function turns a PageRef into its route for a language, and another
returns the same page in every published language:

export function pageAlternates(page: PageRef): Record<Locale, string> {
  return Object.fromEntries(
    PUBLISHED_LOCALES.map((locale) => [locale, pagePath(page, locale)]),
  ) as Record<Locale, string>;
}

The language switcher, each page's hreflang, the sitemap and internal links
all draw from that function. Nobody builds a URL by hand. If /es/proyectos
were renamed /es/trabajo tomorrow, one line of frontmatter changes and
everything else — header links and sitemap included — follows.

Because PageRef is a discriminated union, the switch that walks it is
exhaustive: adding a new page without saying what its route is becomes a
TypeScript error, not a broken link in production.

hreflang and x-default

Without hreflang, Google sees /es/sobre-mi and /en/about as two pages on
the same topic and picks one, or alternates between them. With it, it knows
they're the same page and shows each person the one in their language.

Each page's metadata comes from the same source:

export function pageAlternatesMetadata(page: PageRef, locale: Locale) {
  const alternates = pageAlternates(page);
  return {
    canonical: alternates[locale],
    languages: { ...alternates, "x-default": alternates[DEFAULT_LOCALE] },
  };
}

Each page states its canonical URL — its own, in its language — and declares
its siblings. x-default tells the search engine what to show someone who
searches in neither language: English.

Two details that are easy to forget:

The relationship must be reciprocal. If the English version points to the Spanish one, the Spanish one has to point back. Since both come from the same function, they can't disagree.
Open Graph has a language too. Each page declares og:locale (en_US or es_DO) and the other one as og:locale:alternate, so a social preview knows what it is.

The sitemap says it as well

Search engines read the sitemap before crawling, so the language relationship
goes there too. Next.js generates each entry's xhtml:link rel="alternate"
from alternates.languages:

export default function sitemap(): MetadataRoute.Sitemap {
  return PAGES.flatMap(({ page, priority, changeFrequency }) => {
    const alternates = pageAlternates(page);
    const languages = Object.fromEntries(
      Object.entries(alternates).map(([locale, path]) => [locale, absoluteUrl(path)]),
    );
    return PUBLISHED_LOCALES.map((locale) => ({
      url: absoluteUrl(alternates[locale]),
      changeFrequency,
      priority,
      alternates: { languages },
    }));
  });
}

One deliberate choice: the sitemap has no lastModified. Stamping every
URL with the build date would claim a change that didn't happen, and search
engines learn to ignore an unreliable lastmod.

The language switcher is made of links

The EN | ES switcher in the header isn't a button that flips some state. It's
two <a> links to the same page in the other language:

<a
  href={languages[locale]}
  hrefLang={locale}
  lang={locale}
  aria-current={locale === current ? "true" : undefined}
  onClick={() => {
    document.cookie = `${LANGUAGE_COOKIE}=${locale}; path=/; max-age=31536000; samesite=lax`;
  }}
>

That brings several things a button doesn't: it works without JavaScript, it
can be opened in another tab, search engines follow it and screen readers
announce it for what it is. Its accessible name is the language's name in that
language — "English", "Español" — because that's how people recognise it.

They're plain <a> rather than Next.js <Link> on purpose: switching language
switches root layout, and Next.js would reload the document anyway. A <Link>
would only add a useless prefetch.

The root: a redirect, not middleware

All JavaScript adds to the switcher is remembering the choice in a cookie. What
for? The root. Someone who chose Spanish and comes back through
jonasjavier.dev should land in Spanish. Two static redirects in
next.config.ts handle that, without middleware:

async redirects() {
  return [
    {
      source: "/",
      has: [{ type: "cookie", key: LANGUAGE_COOKIE, value: "es" }],
      destination: "/es",
      permanent: false,
    },
    { source: "/", destination: "/en", permanent: false },
  ];
}

Both are temporary (307): the root hasn't moved, it just depends on a
preference. And Accept-Language isn't consulted, for the reasons at the top:
a home page that changes with who's asking can't be cached or linked safely,
and the search engine always sees the English one, which is what x-default
declares.

With no middleware there's no code running before every request, and pages are
still generated at build time.

Interface text lives with its component

There are two kinds of text. Content — each section's prose, the case
studies, these posts — lives in content/es and content/en as MDX, compiled
by Velite. Interface text — buttons, labels, states — lives in the
component itself, in an object with both languages:

export function defineCopy<T>(table: { es: T; en: NoInfer<T> }): Record<Locale, T> {
  return table;
}

const COPY = defineCopy({
  es: { label: "Idioma" },
  en: { label: "Language" },
});

NoInfer is the important part. Without it, TypeScript would infer the type
from the union of both objects, and a key forgotten in English would slip
through. With it, Spanish fixes the type and English has to match it: a missing
key fails the typecheck.

For content, the guarantee is in the build. Velite checks that every piece
exists exactly once in each published language and that no two pieces share a
slug in the same language. If a section's translation is missing, the site
doesn't ship.

What isn't translated word for word

The English titles and descriptions aren't translations of the Spanish ones:
they're written for English searches. «Desarrollador full-stack en República
Dominicana» doesn't become "Developer full-stack in Dominican Republic": in
English people search for "Full-Stack Developer", in a different order.

Structured data follows the same logic: the person behind the site has a single
@id in both languages — it's the same person — but their job title and
description are in the page's language.

How it's tested

A Playwright suite covers what can break: that the root goes to English and,
with the cookie, to Spanish; that each pair of routes has its lang, canonical
and crossed hreflang; that a route in one language is a 404 in the other; that
the switcher leads to the same page and remembers the choice; that English pages
speak English; and that the contact form validates in the page's language. And
a unit test requires every internal link in these posts to point to a page that
exists, in the post's language.

Try it

Switch language in the header from any page: you land on the same page in the
other language, not on the home page. If you're building something that needs
to speak two languages, here's how I work. And if
you're curious about the 3D side of the site, start with
the black hole.

Originally published on my portfolio, next to the blog. I'm Jonás Javier Encarnación, a full-stack developer and UX/UI designer in Santo Domingo, Dominican Republic: how I work.

A 3D portfolio Google can read and a phone can run

Jonás Javier Encarnación — Fri, 02 Oct 2026 21:23:28 +0000

3D portfolios have a bad reputation for two reasons, and both are fair. To a
search engine they're usually an empty <canvas>: all the text lives inside the
scene and there's nothing to index. And on a phone they're usually a black
screen that takes a while to start, heats up and drains the battery.

This site has a black hole traced pixel by pixel in a shader, with six bodies
around it. This post covers the rules and pieces that keep it readable for
Google and usable on a phone, with the measured numbers — and with what still
isn't solved.

The rule: the scene is never the content

Before a single line of Three.js, one non-negotiable rule was written down:
every page's served HTML contains the real text, without JavaScript. The
scene sits behind, decorates and orients, but it's not where the meaning
lives.

In practice that comes down to four things:

The <canvas> is aria-hidden, fixed behind the page (position: fixed; z-index: -1; pointer-events: none) and contains not one word.
On the home page, the name and role are in a real <h1>, and the six destinations are six real <a href> links with a minimum 44 px touch target. The clickable "bodies" over the scene are copies hidden from screen readers (aria-hidden, out of the tab order): the link that counts is the text one.
On the server, the effect level is always flat. Next.js renders the HTML without knowing whether the visitor has a GPU, so that HTML never depends on WebGL.
The canvas must not be the largest contentful paint (LCP): by design, what paints first is light HTML and CSS.

What someone without JavaScript sees

The most direct test is to turn JavaScript off and load the home page. This is
what you get:

The home page with JavaScript turned off. The system is drawn with SVG and CSS, and the six destinations are text links a search engine can follow.

It isn't an "enable JavaScript" screen: it's the site. The links work, the text
is there and the composition is the same. It's also, almost pixel for pixel,
what a visitor sees without WebGL2 or with effects turned off.

Three levels: flat, orbit and deep

Having WebGL doesn't mean a browser should run the scene. A device with a
software GPU takes seconds to draw a single frame of the raymarch: measured on
SwiftShader, one frame blocks the main thread for about 6 seconds. So the site
chooses between three levels — flat, orbit and deep — with a pure function
that takes signals and returns a verdict:

if (!signals.hasWebGL2) {
  return { level: "flat", reason: "sin-webgl2", canOverride: false };
}
// …
function weakDevice(signals: CapabilitySignals): CapabilityVerdict | null {
  if (isSoftwareRenderer(signals.renderer)) {
    return { level: "flat", reason: "gpu-por-software", canOverride: true };
  }
  if (signals.effectiveType === "slow-2g" || signals.effectiveType === "2g") {
    return { level: "flat", reason: "red-lenta", canOverride: true };
  }
  if (signals.deviceMemory !== undefined && signals.deviceMemory <= 2) {
    return { level: "flat", reason: "memoria-corta", canOverride: true };
  }
  return null;
}

A few details that matter:

A software GPU is detected, not guessed. A throwaway canvas reads the renderer name through WEBGL_debug_renderer_info and checks it against swiftshader, llvmpipe, softpipe and so on. It then releases that context with WEBGL_lose_context and caches the answer for the session.
A missing signal doesn't count against you. Safari exposes neither deviceMemory nor the connection type; treating that absence as "weak device" would leave every iPhone without the scene.
The visitor decides. The motion button, bottom right, turns everything off; and whoever turns it on deliberately gets the scene even if the device looks weak. The code reserves the top level, deep (more steps per pixel in the black hole), for desktops with green signals: a screen at least 1100 px wide, a fine pointer and eight cores or eight gigabytes, or no data.

The flat level isn't a punishment

The flat level isn't an apologetic error page. It's an atlas drawn with SVG and
CSS with the same composition as the scene: Gargantua with its disk, the
planets, the ships and the tesseract — the last one computed with the same
function as the 3D version. Each body's coordinates are hand-directed for three
screen formats (wide, portrait and short).

And it downloads zero bytes of 3D: three.js and the scene are only
requested at orbit or deep. If the browser loses the WebGL context mid-visit
or the load fails, the scene drops to flat and doesn't try again during that
visit: a flat site beats one that flickers.

The same home page at the orbit level: the black hole is traced in a shader every frame. On top, the same HTML as the flat version.

Load the 3D once it's out of the way

On the home page the scene is the star and loads as soon as the page is ready.
On every other page — where the content covers the scene — there's no point in
it competing with the main image and with hydration. There it waits until the
page has loaded and the browser is idle:

function whenIdle() {
  if (typeof window.requestIdleCallback === "function") {
    window.requestIdleCallback(settle, { timeout: 2000 });
  } else {
    window.setTimeout(settle, 0);
  }
}
// …
if (document.readyState === "complete") whenIdle();
else window.addEventListener("load", whenIdle, { once: true });

Safari has no requestIdleCallback; there it fires right after load. A fixed
delay instead used to collide with the user's first interaction. Once reached,
the state holds for the whole visit: navigating doesn't wait again.

Even the level decision waits. That WebGL probe costs about 250 ms on a Chrome
without a GPU — the one PageSpeed uses — and Lighthouse multiplies CPU by four,
so it was a task of nearly a second on every page. three.js comes in through a
dynamic import() and never in the initial load.

Compile shaders without freezing the page

The black hole shader is about 140 KB of GLSL. Compiling it all at once
blocked the page for 2.4 to 2.7 seconds when arriving on the home page. The fix
was compileAsync, which uses the KHR_parallel_shader_compile extension to
compile in parallel before the first frame:

if (renderer.extensions.has("KHR_parallel_shader_compile")) {
  const compiled = Promise.all([
    renderer.compileAsync(marchScene, quadCamera),
    renderer.compileAsync(bodyScene, bodyCamera),
    canAccumulate ? renderer.compileAsync(displayScene, quadCamera) : null,
  ]);
  void compiled.catch(() => undefined).then(startLoop);
} else {
  startLoop();
}

Measured with mobile Lighthouse on a machine with a real integrated GPU: Total
Blocking Time went from 7.95 s to about 2.0 s, Time to Interactive from 12.0
to 7.5 s and Speed Index from 7.1 to 4.1 s. Firefox lacks the extension and
keeps the old path.

Images: what gets painted, not what fits

Half of the site's performance gains had nothing to do with 3D. A
page-by-page Lighthouse review found three classic problems:

A lying sizes. The photos in the About constellation, painted at about 114 px on a phone (the portrait at 174), declared a much larger size, and the phone downloaded the 640 and 960 px versions: about 700 KB for a handful of thumbnails. With sizes set to what's actually painted (120 and 180 px), that stopped.
Phone crops. Header images have their own portrait crop: 92 KB instead of 214 KB, and 53 KB instead of 195 KB. Each one is preloaded with fetchPriority: "high" and its own media, so the phone doesn't download the desktop version.
Steps and quality. An 800 px step and WebP quality 80 nearly halved the image weight of four pages: from 1313 to 725 KB, 1030 to 549, 756 to 407 and 601 to 327.

A phone isn't a small desktop

On a phone the scene starts at one render pixel per screen point. From there, a
small governor measures the real frame pace and raises resolution to 1.25 and
1.5 only if the device can sustain it:

Constant	Value	Purpose
Steps	1 → 1.25 → 1.5 px per point	Never above `devicePixelRatio`
Window	45 frames	~0.75 s at 60 Hz
Settling	30 frames	Discarded after each change
Fast	p75 ≤ 18.5 ms	Step up
Slow	p75 ≥ 26 ms	Step down and close the ceiling
Tolerance	×1.15 over its best pace	90 and 120 Hz screens

const p75 = sorted[Math.floor(sorted.length * 0.75)];
pace = Math.min(pace, p75);
const held = p75 <= pace * PACE_TOLERANCE;
if (index > 0 && (p75 >= SLOW_MS || !held)) {
  index -= 1; ceiling = index; restart(); return true; // undo and close the ceiling
}
if (held && p75 <= FAST_MS && index < ceiling) {
  index += 1; restart(); return true;
}

The first version compared against a fixed 60 fps and got 90 and 120 Hz screens
wrong: 60 fps counted as "headroom" while the phone was dropping frames. Now
each device is compared with its own best pace. And a step that can't be
sustained isn't tried again: the phone doesn't flip between two resolutions.
The governor pauses during transitions, with the tab hidden and while the scene
is covered, so it never measures the wrong thing.

Never two contexts drawing

Several pages have their own WebGL: Miller's ocean, the wormhole on Contact,
the Observatory. If the background scene kept drawing behind them, the phone
would render two scenes at once and only show one.

On pages that cover it, the scene stops requesting frames. The Observatory goes
further: its canvas fills the screen for the whole visit, so there the
persistent scene releases its WebGL context and video memory, and recreates
it on the way out. Pausing the loop wasn't enough: the context stayed alive.

Measure without cheating

One more project rule: code whose only purpose is to change an audit result is
forbidden. No sniffing Lighthouse's user agent to serve it a lighter page.

Lighthouse is audited with ?no3d=1, which is exactly the same as pressing the
motion button: any visitor can type it. Continuous integration runs Lighthouse
three times on the home page in each language and takes the median, with
thresholds that fail the build:

every category ≥ 0.9;
CLS ≤ 0.1;
Total Blocking Time ≤ 300 ms.

The improvements were measured with local Lighthouse against next start,
three runs, median, always A/B against the previous version. A local machine's
absolute numbers aren't PageSpeed's, but the difference between A and B is
reliable. Some results from that work:

Page	Before	After
Projects	66	79–82 (TBT 762 → ~250 ms)
Creativity	72	84
Experiments	74	81–92
Education	68	81

The last full measurement of the home page without the scene (?no3d=1,
locally, three runs) scored 98 for performance and 100 for accessibility, best
practices and SEO, with a median LCP of 2.32 s and a TBT of 66.5 ms.

What isn't solved yet

It would be dishonest to stop here. Two things still weigh:

The framework's JavaScript. The Next.js 16 plus React 19 baseline is already around 146 KB compressed before writing a line, and on a simulated phone that code takes nearly two seconds of CPU. LCP is tied to it.
The server. With no CDN in front, time to first byte is between 300 and 600 ms.

Neither is fixed with more tricks in the scene.

The rest of SEO, briefly

Everything above is what makes the page readable. What helps it be
understood is the usual, done properly: structured data for the person, the site
and each piece of work; a sitemap with images and the relationship between
languages; and a canonical and hreflang on every page. The languages part has
its own post.

Try it

Open the home page and press the motion button, bottom right: the scene
switches off and the flat atlas remains, with the same content. If you want to
see the black hole up close, it's in the
Observatory, and here's
how it's built.

If you have a product that needs to look good and load fast at the same time,
here's how I work.

Originally published on my portfolio, next to the blog. I'm Jonás Javier Encarnación, a full-stack developer and UX/UI designer in Santo Domingo, Dominican Republic: how I work.

How I drew a 4D tesseract in Three.js

Jonás Javier Encarnación — Fri, 02 Oct 2026 21:19:14 +0000

The Tesseract is the Experiments world on this site: a glass hypercube floating
next to Gargantua that you can look at full screen in the
Observatory. It isn't an animated 3D
model. It's a four-dimensional object that rotates in four dimensions and is
projected, every frame, into the three a screen can show. This post covers how
it's built, from the sixteen vertices to the stroke of light that traces it.

What a tesseract is

A square is a segment dragged in a new direction. A cube is a square dragged in
a direction perpendicular to the two it already has. A tesseract is the same
move one step further: a cube dragged in a fourth direction, perpendicular to
the three of our space, which I'll call W.

Counting it is easy even if picturing it isn't. Every time you drag a shape,
its vertices double and a new edge appears for each original vertex. A square
has 4 vertices and 4 edges; a cube, 8 and 12; a tesseract, 16 vertices and 32
edges, with 24 square faces and 8 cubic cells. What you see on screen — a
cube inside a cube, joined at the corners — is that object's shadow in three
dimensions, the same way a drawing of a cube on paper is its shadow in two.

Sixteen vertices from four bits

The cleanest way to generate a tesseract is to think in bits rather than
coordinates. Each vertex is a number from 0 to 15, and each of its four bits
says whether it sits on the negative or positive side of an axis: bit 0 is X,
1 is Y, 2 is Z and 3 is W. The coordinates are ±0.5.

With that numbering, two vertices share an edge exactly when their numbers
differ in a single bit. XOR finds them without searching:

const edges: [number, number][] = [];
for (let vertex = 0; vertex < 16; vertex++) {
  for (let axis = 0; axis < 4; axis++) {
    const other = vertex ^ (1 << axis);
    if (vertex < other) edges.push([vertex, other]);
  }
}

Out come the 32 edges, eight per axis. The eight along W are the ones joining
the inner cube to the outer one, and they're the most interesting to watch:
they run in a direction that doesn't exist in the room you're sitting in.

One stroke: the Eulerian circuit

On the site the tesseract doesn't appear all at once: a point of light draws it
edge by edge, like a pen. For that pen never to lift or jump from one vertex to
another, the path has to cover all 32 edges exactly once and return to its
start. That's an Eulerian circuit, and graph theory says when one exists:
when every vertex has even degree.

In a tesseract every vertex touches four edges, one per axis. Four is even, so
the circuit exists, and Hierholzer's algorithm builds it with a stack in a
dozen lines:

const remaining = edges.map(() => true);
const stack = [0];
const circuit: number[] = [];
while (stack.length) {
  const vertex = stack[stack.length - 1];
  const index = edges.findIndex(([a, b], i) => remaining[i] && (a === vertex || b === vertex));
  if (index < 0) circuit.push(stack.pop()!);
  else {
    remaining[index] = false;
    stack.push(edges[index][0] === vertex ? edges[index][1] : edges[index][0]);
  }
}
circuit.reverse();

It runs once when the module loads, and a test checks the three things that
matter: the stroke is continuous, no edge repeats and every vertex keeps degree
four. The point of light covers all 32 edges every 18 seconds and leaves a
trail that fades over about thirteen of them.

Rotating in four dimensions

In three dimensions we say something rotates "around an axis". In four that
sentence stops working: what makes sense is rotating in a plane. A rotation
in the XY plane moves X and Y and leaves Z and W alone. There are six possible
planes (XY, XZ, XW, YZ, YW, ZW), and the three that don't touch W are ordinary
rotations: they show nothing new.

So the site's tesseract only rotates in the three planes that mix one of our
axes with W: XW, YW and ZW. Those are the rotations that make the inner cube
grow, pass through the outer one and come out the other side. Each is a
two-coordinate rotation, applied in sequence:

const t = rhythm(seconds);
const angles = [t * 0.19 + 0.35, t * 0.137 + 0.48, t * 0.083 + 0.16];
// …
for (let axis = 0; axis < 3; axis++) {
  const a = p[axis], w = p[3];
  p[axis] = a * cos[axis] - w * sin[axis];
  p[3] = a * sin[axis] + w * cos[axis];
}

The three speeds (0.19, 0.137 and 0.083 radians per unit of time) have no
simple ratio between them, so the shape doesn't repeat the same sequence of
poses every few seconds.

Six moments of one rotation. Nothing deforms in four dimensions: what changes is the shadow the object casts in three.

Two decisions in that function aren't obvious, and both matter.

Time is absolute. The pose is computed from elapsed seconds, not by adding
an increment every frame. If it added increments, a 120 Hz screen would spin
the shape twice as fast as a 60 Hz one. With absolute time, the same moment
gives the same pose on any device, and a test checks it up to six hours in.

The clock has rhythm. At a constant speed, after a few seconds the brain
decides "fine, it's spinning" and stops looking at the shape. And the path
isn't even: some poses read instantly — the cube inside the cube — and some
stretches flatten the projection into confusion. So time is warped with two
harmonics:

function rhythm(seconds: number): number {
  return seconds
    + 0.3151 * Math.sin((2 * Math.PI * (seconds - 7.5)) / 18)
    + 0.2722 * Math.sin((2 * Math.PI * (seconds - 3.5)) / 9);
}

The measured result: the shape moves at 0.71 of its average speed on the
readable poses, 1.21 on the confusing ones, and never drops below 0.7. Since
the speed never reaches zero, the clock never runs backwards: an animation that
rewinds half a second reads as a bug, not as rhythm. With a single harmonic the
peaks and troughs landed nine seconds apart and missed the poses that needed
slowing down; the second one, at half the period, moves them into place.

From four dimensions to three: perspective from W

After rotating, each vertex still has four coordinates. To see it you have to
project it, and the projection is the same idea as an ordinary camera's
perspective, one dimension up: a camera at W = 1.65 looking at the origin.
Whatever is closer to it in W looks bigger.

const perspective = 1.65 / (1.65 - p[3]);
const x = p[0] * perspective, y = p[1] * perspective, z = p[2] * perspective;

That's the whole secret of the "cube inside a cube": there aren't two cubes of
different sizes, there are two identical cells at different distances from the
camera in the fourth dimension. Then a fixed pose presents it diagonally in 3D
(0.6, 0.45 and 0.28 radians), and each sample is re-centred and scaled so the
farthest vertex always sits 1.5 units from the centre. Without that
normalisation the shape "breathes" as it rotates, and the click area and the
brackets that target it on the map would move with it.

Not a cage

The first version with all of this working was unreadable. Thirty-two edges of
the same thickness and brightness don't read as a four-dimensional object: they
read as a wire cage. Raising the exposure didn't help; it just made a brighter
cage.

What fixed it was hierarchy. The same perspective that sets the size also
says how close each vertex is in W, and that value, normalised from 0 to 1 every
frame, drives the thickness and light of each edge:

Each tube's radius goes from 0.58 to 1.42 times the base depending on its depth in W, so the near cell is thick and the far one thin.
In the shader, brightness follows the same scale: 0.26 + 0.52 · cell + 0.22 · nearness.

Depth in W as hierarchy: the near cell thick and bright, the far one thin and dim. It's what separates the two cubes.

It's normalised every frame rather than against a fixed range for a specific
reason: the spread in W changes with the rotation, and with a fixed scale the
hierarchy vanished exactly in the poses where the cube faces you most squarely.

Four meshes, one shader

The tesseract is drawn with four Three.js meshes that share the same GLSL and
are told apart by a uniform, uLayer:

Layer	What it is	How it blends
Glass edges	Six-sided tubes, near-black body with a Fresnel rim	Opaque, writes depth
Stroke light	The point and its trail	Additive, no depth test
Glass sheets	Six of the 24 faces	Transparent, double-sided
Occluder	A ribbon that only writes depth	No colour

A few details that took more work than they look:

Only six glass faces. With all 24 the shape filled in and stopped reading by its edges. Empty space has to stay the dominant surface.
Per-corner normals, not per-face. With flat normals the six-sided tubes look faceted; with each corner's radial normal they shade round without a single extra triangle.
The occluder is a ribbon, not a tube. Edges in front had to hide the trail on the edges behind. A full tube would have pushed the scene from 19,500 to 20,001 vertices and broken a budget a test enforces; a ribbon of four vertices per edge, turned to face the camera in the vertex shader, costs 128.

Rebuilding the geometry every frame

Because the shape changes form — not just position — its vertices are rewritten
every frame: the two tubes (768 vertices each), the occluder ribbon and the
sheets, about 1,700 vertices in all. That sounds expensive and isn't, with three
precautions:

Every buffer that changes is created with DynamicDrawUsage, which tells WebGL it will be rewritten often. UVs and indices never change and are left alone.
Temporary vectors are allocated once outside the loop: the loop creates no objects and the garbage collector has nothing to do.
Bounding spheres are fixed at a radius of 1.56 instead of being recomputed: since the shape is already normalised, that radius never changes.

Without WebGL: the same tesseract in SVG

Not everyone sees the 3D scene. Without WebGL2, on a software GPU or with
effects turned off, the site shows a flat atlas drawn in SVG. The tesseract in
that atlas isn't a separate drawing: it calls the same function with
seconds = 0, uses the same topology — the same six faces and the same
32-edge circuit — and projects the vertices into a 140 × 140 viewBox. Each
line's width and opacity come from the same depth in W.

The same object with and without WebGL. The SVG doesn't animate or run JavaScript, but it shares topology and hierarchy with the scene.

Having both profiles say the same thing was a requirement, not a detail: if the
Experiments destination were an animated cube on one device and something else
on another, the site would be telling two different stories depending on who
was looking.

Pointing at the fourth dimension

In the Observatory, in Study mode, there's an instrument only the tesseract
has: the probe. Move the pointer near an edge and it marks it and tells you
which one it is, which axis it runs along, how deep it is in W and how far away
it sits. It's the only place on the page where you can literally point at the
fourth dimension.

The probe on one of the eight W edges. The reading sits next to the reticle, not in a corner of the screen.

It doesn't use Three.js's Raycaster. It re-samples the shape at the same
instant, projects the 16 vertices to screen pixels and measures the pointer's
distance to each of the 32 segments. That's 32 point-to-segment checks: cheaper
than casting rays against tubes and exact for the question being asked. In the
first version the reading appeared in the top-left corner, far from the edge,
and came across as a message rather than a measurement. Now it sits next to the
reticle and flips side near the screen edge.

What I left out

A corridor of frames. The first idea was architectural: a corridor of frames repeating inwards. It became a hypercube of glass edges traced by a line of light, which is more honest about what a tesseract is.
Particles, rays and glows. Anything added around it competed with the shape. They stayed out.
A "ghost" trail of previous poses. It was proposed as an A/B test with one condition: if it looked like an After Effects effect, it wouldn't go in. It didn't.

Try it

The tesseract is in the Observatory:
switch to Study, try the three views and turn the probe on over the edges that
join the two cubes. If you want to know how the rest was made, the black hole
has its own post.

And if you're thinking about something like this for your product — a 3D
visualisation, an interactive piece or a website people remember — here's
how I work and what I do.

Originally published on my portfolio, next to the Observatory. I'm Jonás Javier Encarnación, a full-stack developer and UX/UI designer in Santo Domingo, Dominican Republic: how I work.

How I built a black hole in WebGL

Jonás Javier Encarnación — Fri, 02 Oct 2026 21:17:45 +0000

Gargantua is the centre of this site: the black hole the six sections are
arranged around, inspired by the one in Interstellar. In the
Observatory you can see it full
screen, switch between four views and turn its effects off one by one. This
note explains how it's built and what each part cost me.

Don't draw the black hole: follow the light

The first version was a five-layer trick: a disk, a halo and even an Einstein
ring baked onto a plane. You could see the seam between the ring and the disk,
and a seam is exactly what gives away that something is drawn.

The current version does the opposite. For every pixel, a shader casts a ray
from the camera and lets it fall towards the black hole following the equation
of light around a mass. If the ray falls in, the pixel is black. If it escapes,
it samples the stars in the direction it left. If it crosses the disk, it
picks up its light.

The photon orbit equation, d²u/dφ² = −u + 1.5·rs·u², can be rewritten as a
central force in Cartesian coordinates, a = −1.5·rs·h²·r / |r|⁵, where
h² = |r × v|² is computed once per ray. With that, each step is a two-line
Verlet integrator:

vec3 acc = -1.5 * uRs * h2 * pos / (r2 * r2 * r);
vec3 nextPos = pos + dir * dt + 0.5 * acc * (dt * dt);
float n2 = dot(nextPos, nextPos);
vec3 nextAcc = -1.5 * uRs * h2 * nextPos / (n2 * n2 * sqrt(n2));
vec3 nextDir = dir + 0.5 * (acc + nextAcc) * dt;

The beautiful part is what you get for free: the photon ring, the arc of the
disk's far side passing over the shadow, the secondary image beneath it, the
correct shadow size (a radius of √27/2 · rs, about 2.6 times the horizon) and
the Einstein ring of the background stars. None of it is painted: it's what the
light does.

An honest note: the film's Gargantua spins (it's a Kerr black hole). Here the
spacetime is that of a non-rotating one, Schwarzschild, because tracing Kerr
per pixel in real time was too expensive for a browser. What does spin is the
disk.

Lens view. Rays that circle the hole cross the disk plane again and bring its hidden side above and below the shadow.

Steps that follow the curve

A ray doesn't advance in fixed steps. Each step covers a constant angle around
the hole (dt = scale · r² / h), capped near the horizon, and relaxes up to
2.4 times as the ray spends its budget. That doubles the turns a ray can make
at no extra cost.

The previous rule made steps proportional to the distance from the horizon. It
looked reasonable and drew a dark ring that doesn't exist: near the photon
sphere, where light loops several times, rays ran out of steps before getting
out. The budget is 190 steps per pixel on the normal tier and 340 on the deep
one, and a ray stops early if it's certain to fall in (inside 1.5 times the
horizon and heading inwards, about 40 iterations saved) or if nothing ahead of
it can be seen any more.

The disk: noise that spins like Kepler

The disk runs from 1.58 to 17 times the horizon radius. Its texture is fractal
noise, evaluated only at the two or three points where each ray crosses the
plane, not at every step, and written in log-radius coordinates that rotate
with the material.

The rotation is Keplerian: the inner edge spins about 35 times faster than the
outer one. That has a catch: over time, the differential rotation winds the
noise up forever, and within minutes the disk turned into concentric rings
thinner than a pixel. The fix is two copies of the disk, half a cycle apart,
that fade into each other every 20 seconds: the winding never passes a limit
and the handover can't be seen.

Doppler: why one side is brighter

The gas on the side coming towards you shines brighter than the side moving
away. It's the relativistic Doppler effect, combined with gravitational
redshift:

float v = min(sqrt(0.5 * uRs / max(r - uRs, 0.30 * uRs)), 0.80);
float gamma = inversesqrt(max(1.0 - v * v, 1e-3));
float beaming = 1.0 / max(gamma * (1.0 - v * mu), 1e-3);
float gravity = sqrt(max(1.0 - uRs / r, 0.0));
float g = gravity * mix(1.0, beaming, uDoppler);
float boost = clamp(pow(g, 3.3), 0.24, 6.6);

In the final image, the approaching side is a little over twice as bright as
the receding one, and it also shifts towards cream while the other turns
copper. In the Observatory the Doppler control turns it off, and it's the
control that changes the image most of the three.

With Doppler: the approaching side (left) is more than twice as bright as the receding one.

The same frame without Doppler: both sides of the disk even out.

The shadow the bloom was lighting up

Bloom, the glow that makes bright things feel bright, had a flaw: it spilled
the disk's light into the shadow, and the shadow stopped being black. Darkening
a circle by hand didn't work, because it would erase real lensed arcs: the true
black measures 118 × 73 pixels inside a 142-pixel shadow.

The fix was to save the image before bloom and bring it back only where the
scene was already dark and inside the shadow:

vec2 offset = (vUv - uCentre) / max(uRadius, vec2(1e-4));
float inside = 1.0 - smoothstep(uInner, 1.0, length(offset));
float lum = dot(clean, vec3(0.2126, 0.7152, 0.0722));
float dark = 1.0 - smoothstep(uDarkGate.x, uDarkGate.y, lum);
gl_FragColor = vec4(mix(bloomed, clean, inside * dark * uAmount), 1.0);

The brightness at the centre of the shadow dropped from 106.8 to 18.2, and
nothing changed outside it.

Shadow view. Black has to be black: the edge is what tells you there's a hole there and not a lamp.

What I took out

A drawn photon ring. There was a one-pixel circle at the critical radius. An exact one-pixel circle is a circle painted on top; now the edge comes from higher-order images stacking up on their own.
A spotlight blob. The point where highlights start to compress dropped from 9.6 to 4.2, and pure-white pixels went from 2177 to 1268.
A lopsided edge. The disk looked heavy on one side. It wasn't the shape: it was the handedness of the spiral, proven by reversing it. The winding went from 1.15 down to 0.60.

Making it run on any device

All of this is a single draw call: a four-vertex rectangle and one material.
To smooth the edges, the image is accumulated over eight frames with tiny
offsets, and when nothing moves the Observatory stops drawing.

There are three tiers. The normal one uses 190 steps. The deep one uses 340
and higher resolution, and only switches on with a mouse, a wide screen, eight
cores and eight gigabytes of memory. Without WebGL2, on a software GPU, on 2G
or with little memory, the site serves a flat 2D version with the same text
and the same routes.

And two things outside the shader:

Compiling in parallel. With compileAsync and KHR_parallel_shader_compile, the 2.4–2.7 second task that froze the page on arrival disappeared. In Lighthouse mobile, blocking time went from 7.95 s to about 2 s.
Resolution that adapts on phones. The scene starts at one pixel per point and steps up to 1.25 and 1.5 only while the phone keeps its own pace; if it stutters, it steps back down and stays there.

Try it

Open the Gargantua Observatory, switch
to Study and go through the four views: Cinematic, Lens, Disk and Shadow.
Then turn Doppler, Secondary images and Lens off one by one and see
which part of the image was physics and which wasn't.

If you'd like a 3D experience like this for your product or brand, here's
how I work.

Originally published on my portfolio, next to the Observatory. I'm Jonás Javier Encarnación, a full-stack developer and UX/UI designer in Santo Domingo, Dominican Republic: how I work.