And for a few months, it had been getting worse.

What we're building​

I work at Rukia Labs, a learning platform for organizations that train people. Coding schools, bootcamps, and company L&D teams. Each customer gets their own branded space: students take courses there, instructors write and publish the material, and admins run the whole thing.

Under the hood that's four separate React applications sharing one component library. A student app, an instructor console, an admin console, and a platform console for us. They live in one repository, so a button looks the same everywhere, and they're deployed to Cloudflare Pages.

The symptom​

Authors would open the editor, start writing, and watch the browser tab climb past 400MB of memory. Then keystrokes would start arriving late. Then the page would stop responding altogether. Students got a milder version of the same thing on the lesson page.

The bug reports were the kind you can't act on. "It hangs." "It's heavy today." "I lost a paragraph." Nobody could reproduce it on demand, because it wasn't a crash. It was a slide.

I want to write up what we found, partly because the main cause is something I've never seen flagged in a code review, and partly because my first diagnosis was confidently wrong in a way that cost me an afternoon.

A note for readers who don't build web apps for a living: I've kept the jargon to a minimum and explained the rest as it comes up. If you know what a bundle is, skim the indented notes. If you don't, they're the whole story.

Bundle, chunk, build output. Browsers can't run a folder of a thousand source files efficiently, so before we ship, a tool called a bundler stitches them into a handful of larger files. Each of those files is a chunk. The collection is the bundle. Modern bundlers are clever enough to split it up so a page only downloads the chunks it needs, which is called code splitting. Remember that phrase. It's where this goes wrong.

Starting in the wrong place​

The first thing I did was look at the built output of the admin app, sorted by size.

1220K  MarkdownRenderer-8084fe48.js
 772K  MarkdownEditor-49c46f2f.js
 764K  emacs-lisp-93221a04.js
 612K  cpp-ccf25956.js
 608K  wasm-cd10bedf.js
 544K  mermaid.core-90442b6d.js
 436K  cytoscape.esm-b0e8ddfb.js
 260K  wolfram-e51de66a.js

460 chunks, 18MB total. Somewhere in there, our learning platform was shipping syntax-highlighting rules for Cobol, Fortran, and Wolfram Language, which I think we can agree nobody was asking for.

Syntax highlighting is the colouring you see in code snippets: keywords one colour, strings another. To do it, a library needs a grammar for each language: a big set of rules describing what Python looks like, what Rust looks like, and so on. There are hundreds of languages, so there are hundreds of grammars, and each one has real weight.

So I assumed the big renderer chunk and the pile of language chunks were the same problem. One syntax highlighter, configured badly, easy fix.

That was wrong.

There were two syntax highlighters. Not one misconfigured highlighter. Two entirely separate ones that didn't know about each other.

Our markdown renderer used Prism, through a package called react-syntax-highlighter. Our AI chat components used Shiki. They'd been added about two years apart, by different people solving different problems, and neither had any reason to notice the other existed. If you only look at the list of chunk names, two tidy highlighters and one messy one produce output that looks the same.

The Prism side was the worse of the two because of how that library's default entry point behaves.

import { Prism as SyntaxHighlighter } from 'react-syntax-highlighter';

That single import pulls in refractor/all, which registers around 237 grammars into memory the moment the file is loaded. Not lazily. Not on first use. A lesson made entirely of prose, with no code in it at all, paid for every one of them.

The Shiki side was the full bundle: roughly 290 languages and 60 themes, each emitted as its own chunk. Hence, emacs-lisp at 764K, sitting in a build for a school that teaches Python and JavaScript.

The part I hadn't seen before​

Here's the code that actually mattered. I'll show it the way it appeared in the file, because I don't think most people would look twice at it.

import InstructorChatPanel from "@/pages/course-master/components/InstructorChatPanel"

// ... about 600 lines later ...

{!editorFullscreen && showChat && (
  <InstructorChatPanel onClose={() => setShowChat(false)} />
)}

showChat starts as false. Most authors never open the chat at all. The render is conditional and correct, and it had been through code review more than once.

But InstructorChatPanel imports a message component, which imports a library called streamdown, whose own dependencies include Mermaid (for diagrams), Shiki (highlighter number two), KaTeX (for maths), and a stack of markdown plugins. Mermaid in turn brings in a graph-layout library and a separate chunk per diagram type.

None of that is gated by showChat.

Static versus dynamic imports. A normal import X from "..." at the top of a file is a static import. The bundler treats it as "this file needs that file, always", and follows the chain outwards: what does that file need, and what does that one need. The result is a graph, and everything in it ships and runs when the page loads.

A dynamic import, written import("..."), is a promise. It says "fetch this later, if I ask". That's the one the bundler is allowed to split off into a chunk that only downloads on demand.

The conditional {showChat && <Panel />} happens far later, at render time, and only decides whether React puts an element on screen. By then every module in that graph has already been fetched, parsed and executed.

Opening the lesson editor was downloading and running roughly 1.9MB of source for a panel that stayed shut.

The bit that actually stung was finding this in our own student app, in a different file, written months earlier:

// Lazy, and deliberately so. FloatingChatWidget pulls in ChatPage, which pulls
// MarkdownRenderer (katex + react-syntax-highlighter -> refractor) and
// ai-elements' streamdown - around 1.9MB of source that ended up in the ENTRY
// chunk... None of it is needed to paint a dashboard, and most visitors never
// open the chat at all.
const FloatingChatWidget = lazy(() => import('@/pages/ChatPage/FloatingChatWidget'));

Someone had already worked this out. Same libraries, same 1.9MB, and they'd left a clear note explaining exactly why the lazy wrapper was there.

Then we built the lesson routes and reintroduced the identical problem in three more places.

A comment only reaches the person already reading that file. It has no way of stopping the next person doing the same thing somewhere else. Hold that thought, because it's where this ends up.

Why it got worse as you typed​

Bundle weight explains a slow page load. It doesn't explain a page that's fine for ten minutes and then isn't. That turned out to be somewhere else entirely.

export const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 30 * 1000,
      gcTime: 24 * 60 * 60 * 1000,   // 24 hours
    },
  },
})

const persister = createSyncStoragePersister({
  storage: window.localStorage,
  throttleTime: 1000,
})

persistQueryClient({ queryClient, persister, maxAge: 24 * 60 * 60 * 1000 })

Every line of this is reasonable on its own.

What this code does. We use a library that caches data fetched from our API, so moving between pages doesn't refetch everything. gcTime is how long an unused cache entry sticks around: 24 hours here, so coming back to a page tomorrow paints instantly instead of showing a spinner. persistQueryClient writes that cache into the browser's localStorage, so even a full page reload doesn't lose it. throttleTime: 1000 limits those writes to at most one a second, which sounds like the safety rail.

Put the three together on a page that holds course content, and you get something else.

Writing to localStorage means converting the entire cache into a single text string first, using JSON.stringify. That happens on the main thread, which is the one thread the browser also uses to respond to your keyboard. And it happens whenever anything in the cache changes, up to once a second.

There was no filter on what got persisted, so "the entire cache" meant every course outline we'd loaded, and each of those carried its topics with all their lessons, quizzes, and assignments expanded inline.

Now follow an edit through. The author saves. The save succeeds. The app marks the course data stale and refetches it. The cache updates. The whole thing gets converted to a string again while they're partway through the next sentence. With gcTime at 24 hours, nothing was ever evicted, so every course anyone had opened that shift was still in there, being stringified along with it.

There's a second failure hiding inside the first. localStorage tops out at around 5MB. Go past it and the write throws an error, and a cache that can't be written is a cache that restores nothing. You don't get a red message in the console. You get a feature that quietly stopped doing the job it was added for, with no signal that anything changed.

The ordinary React mistakes​

The rest was nothing clever. Just normal patterns at a size where normal stops working.

Two full serializations of the document, on every render, to work out one true-or-false question:

const isDirty =
  lessonDraft && JSON.stringify(lessonDraft) !== JSON.stringify(originalDraft)

This asks, "Has the author changed anything?" by converting the entire lesson to a string twice and comparing. It sits at the top of the component with no caching, so it runs on every single render. On a 200 KB lesson at typing speed, that's megabytes a second of throwaway text.

Comparing the fields one by one answers the same question almost for free, because an unedited body is literally the same object in memory on both sides. The computer can check that with a single pointer comparison instead of reading 200,000 characters twice.

Then this one, which I think is the most common version of this mistake:

const components = buildComponents(theme);   // 26 fresh closures, every render

Why a "new object every time" is expensive. React skips re-rendering a component when its inputs haven't changed, and it decides that by checking whether the inputs are the same object, not whether they look the same. Build a fresh object on every render and React can never take the shortcut.

react-markdown compares this prop by identity. Handing it a new object each time meant the entire markdown document re-rendered, and every code block got re-highlighted whenever anything on the page changed. Caching that one object was a single line and probably the best return of the whole exercise.

An entire second editor, mounted permanently and hidden with CSS:

<div className={cn("absolute inset-0", isSourceMode ? "opacity-100" : "opacity-0")}>
  <Editor /* Monaco */ options={{ automaticLayout: true }} />
</div>

Our editor has two modes: a rich text view and a raw markdown view. The raw view uses Monaco, the same editor that powers VS Code. It was never unmounted. It was just made invisible.

So every markdown editor on the page carried a live Monaco instance, its document model, its tokenizer, and a resize observer, sitting alongside the rich text editor; in the default mode most sessions never leave. Our quiz question form mounts two editors, so it was doing all of that twice.

opacity-0 doesn't unmount anything. Neither does display: none, or pushing something off-screen with a transform. If the hidden thing owns an editor, a video player, or a map, it is fully alive and fully costing you.

And one that scaled badly: the quiz review screen renders two markdown blocks per question, and each one, if you don't tell it which theme to use, sets up its own watcher on the page to detect dark mode. Forty questions meant eighty watchers on the same element. Toggling dark mode fired eighty updates, each re-parsing and re-highlighting a full document inside a single frame.

The number we should have been tracking​

Total bundle size caught none of this. It's 18MB before and 18MB after, because code splitting means most of it is never fetched. The number tells you nothing about what any given page actually costs.

What you want is the static closure of a route: start at the chunk for one page, follow only the static imports, and add up the bytes. That's what the browser really downloads and runs before that page becomes usable. Dynamic imports are excluded on purpose, because deferring them is the entire point of them.

It's about twenty lines of Node.

const fs = require('fs'), path = require('path');
const [dir, entryPattern] = process.argv.slice(2);

const entry = fs.readdirSync(dir)
  .find(f => f.startsWith(entryPattern) && f.endsWith('.js'));

const seen = new Set();
const stack = [entry];
let total = 0;

while (stack.length) {
  const file = stack.pop();
  if (seen.has(file)) continue;
  seen.add(file);

  const full = path.join(dir, file);
  if (!fs.existsSync(full)) continue;
  total += fs.statSync(full).size;

  const src = fs.readFileSync(full, 'utf8');
  // Static edges only: `from"./x.js"` and `import"./x.js"`.
  // Not `import("./x.js")`, since a dynamic import is exactly what we want to skip.
  for (const m of src.matchAll(/(?:from|import)"\.\/([^"]+\.js)"/g)) {
    stack.push(m[1]);
  }
}

console.log(`${entryPattern}: ${seen.size} chunks, ${(total / 1048576).toFixed(2)} MB`);

Point it at your build output and a page's chunk name. The pattern-matching in it assumes Rollup or Vite output, so adjust that line for other bundlers.

The variant I've found more useful doesn't measure anything at all. It just asks whether a given library is reachable from a given page by filtering the list of visited files instead of adding up their sizes.

LessonExperiencePage closure matching /mermaid|cytoscape|refractor/: NONE

That line is an assertion. Put it in your continuous integration, and "somebody statically imported the chat panel again" becomes a failing build instead of a support ticket eight months later. Unlike a size budget, there's no threshold to argue about. It's true or it's false.

Where we ended up​

markdown renderer chunk      1220K              ->  704K
student lesson route         3.4MB / 38 chunks  ->  2.50MB / 24 chunks
admin lesson editor route    not measured       ->  2.60MB / 39 chunks

Mermaid, the graph library, and the 237 Prism grammars are no longer reachable from any of the three lesson pages, which is the result I actually care about.

The heavy chunks still exist in the build. They're only reachable from the lazily loaded chat now, because streamdown bundles its own copy of Shiki, and getting rid of that means replacing the library. That's a behavior change, not a performance fix, so we left it alone.

I think that distinction is worth holding onto. We weren't trying to make the build folder smaller. We were trying to stop a page paying for things it doesn't use. Those are different goals that happen to overlap sometimes, and confusing them leads you to optimize the wrong number.

I'm Manasseh, and I am part of the team building Rukia Labs. If you're running training programs and fighting your tooling instead of teaching, come say hello.

The browser told us which organisation this request is for, and we believed it.

What multi-tenancy has to guarantee​

Every organisation on the platform has its own courses, its own people, its own grades and its own uploaded files. The guarantee is simple to state: a signed-in user of one organisation must not be able to read or write anything belonging to another.

It is simple to state and easy to get wrong, because almost every request has to carry an organisation id somewhere, and an id in a request looks the same whether the server verified it or merely received it.

The first one: a file-storage worker​

Uploads used to go through a small worker that sat in front of object storage. The browser called it with the file, the target path, and the organisation id.

Two things were true of that worker:

• It read orgId out of the request body.
• It authenticated the caller with a shared secret that the browser had to hold in order to make the call at all.

So the credential proving "this request is allowed" was the same string for every user of every tenant, and it was shipped to every browser. And the field deciding which tenant's files to touch was supplied by the caller.

Anyone signed in to any organisation — or anyone who opened the network tab and read the secret — could list, read, write or delete in any other organisation's bucket. Not through a flaw in the logic. Through the logic working as written.

The second one: an AI service​

Eighteen months later we added an assistant. The agent service behind it sits on a private network and identifies callers with an internal shared secret, which is correct for a service-to-service boundary.

Five call sites across three applications then fetched it straight from the browser, passing X-Org-Id and X-User-Id as headers.

The agent service verifies nothing. That is not a bug in it — it was built to be called by another service that had already done the verifying. Pointed at from a browser, its contract becomes "tell me who you are and I will believe you". Any signed-in user of any tenant could read another tenant's conversation threads and spend their rate limit, silently.

Same shape. Different decade of the codebase.

The rule we now hold​

orgId is a claim the server verifies, never an instruction it follows.

Concretely, three things changed and all three matter:

The organisation moved into the path, and the path is checked. Asset calls go to /orgs/{orgId}/assets/* on our own API. The API resolves the caller from their access token, then requires a membership row joining that user to that organisation before it touches a bucket. The id in the URL is a claim being tested, not a parameter being honoured.

The browser stopped holding credentials. There is no shared secret in any bundle. The only thing the browser carries is the signed-in user's own token, which identifies exactly one person and grants exactly what that person has.

Every call to the private service goes through our API. The assistant's requests are proxied. The API resolves the caller, checks their membership, and forwards the organisation's verified internal id — a value the browser never sees and therefore cannot choose.

The old worker's path now answers 410 Gone rather than quietly disappearing, so anything still pointed at it fails loudly.

What we would tell someone auditing their own system​

Ask where each id came from, not whether it is correct. "Is this org id valid?" is the wrong question — it was valid, it just belonged to someone else. The right question is "could the caller have chosen this value?"

A shared secret in a browser is not a secret. If the client must hold it to make the call, every client holds it. It authenticates the application, which is not a thing you needed to authenticate; it says nothing about the person.

A service that trusts its caller is fine until its caller is a browser. The agent service was not wrong. It was correct for the boundary it was designed for, and we moved it to a different boundary without moving its assumptions. That is the version of this mistake that is easiest to make and hardest to see in review, because the diff that introduces it is a URL change.

Rotate, do not just remove. The storage secret was shipped to browsers for as long as it existed. Deleting the variable does not un-ship it.

The check that would have caught both​

Not a code review. Both of these passed code review — the code was clear, and each change was locally reasonable.

What catches it is a boundary question asked at design time: for each trust boundary in this request path, what is verified, by whom, and against what? Both holes are visible in a single sentence once somebody asks it. Neither is visible from inside the file where it lives.

docs.rukialabs.com            Rukia Labs' own colours
yourorg.rukialabs.com/docs    your organisation's colours

Same words, same pages, same build inputs. Only the branding differs — and, less obviously, the path everything is mounted at.

Why not just one​

An organisation's documentation should look like their product, because inside their programme it is their product. Sending a learner from a branded console to a page in somebody else's orange is a seam where there does not need to be one.

And the general site has to exist too, for everyone who has not signed in to anything yet.

The colours are the easy half​

Branding already arrives at the edge, injected into the HTML before the page runs — see Branding that arrives before the JavaScript does, earlier on this blog. The docs read the same value and repaint their palette from it.

The one subtlety is ordering. The injected configuration lands at the very end of <head>, so anything in the head runs too early to see it. The repaint happens in the first tag of <body> instead: after the whole head, before anything is painted. Late enough to have the data, early enough that nobody sees the default first.

A version of this that ran at hydration would also be correct, eventually, and would flash on every page load — which is the whole thing we were avoiding.

The path is the hard half​

A static site generator compiles its base path into everything: every link, every asset URL, the client router's notion of where the root is. Ours is no exception.

That makes one build physically unable to answer at both mounts. Served under /docs, a build made for / emits a link to /guides/intro — and the first click walks the reader out of the documentation and into the learner application, which has never heard of that route.

Rewriting the HTML at the edge does not save it either. You can re-base the href in the markup; you cannot re-base the base path already compiled into the router bundle. The first click is client-side and never reaches the edge at all.

So it is two builds of one directory, differing in a single variable. Same content, same theme, same everything — two artifacts, because the mount point is a build input rather than a runtime one.

The bit we nearly got wrong​

Two copies of identical content on different hostnames is a duplicate-content problem. Left indexable, an organisation's copy competes with the general site for the same queries, and search engines pick a winner we did not choose.

The per-organisation mounts are noindex. They are for the people already inside that organisation; the copy meant for everyone else is the one that gets indexed.

Not a deep insight, but the kind of thing that is free to get right on the day and expensive to notice six months later.

Then we shipped a fix for something unrelated, and the dialog came back on its own. The search and filter bar stopped working instead.

What it looked like​

The symptom was always the same shape, and the shape is what made it hard.

One feature, in one part of the app, doing nothing. Not failing — nothing. The surrounding page was fine. Reloading did not help. And the feature that was broken changed between deploys, which is the detail that sent us looking in the wrong place for a week.

A broken feature that moves reads as a race condition, or as state getting corrupted, or as a caching problem. It does not read as a deployment problem, because deployments are supposed to fail in all-or-nothing ways.

The network tab​

One 404. A single JavaScript file:

GET /assets/BulkEnrollCohortDialog-DhoHOVP-.js   404
GET /assets/CohortDetailPage-a7f31c2e.js         200
GET /assets/EnrollStudentsDialog-9b04dd1a.js     200

Every neighbouring file was fine. The file that 404'd was present in the build output on disk, had been uploaded, and was listed in the deployment.

Look at its name.

Cloudflare Pages will not serve a file whose name ends in a hyphen​

That is the whole bug.

BulkEnrollCohortDialog-DhoHOVP-.js — note the hyphen immediately before the extension. Every file named like that answers 404 from the edge. Every file that does not is served normally.

Vite hashes chunk filenames so that a changed file gets a new name and can be cached forever. Rollup's default alphabet for those hashes is base64url, which includes - and _ alongside the letters and digits. So roughly one chunk in thirty ends up with a hash whose last character is one of those two.

Which chunk that happens to is decided by the content hash. Change anything in the application and the hashes shuffle, the affected files change, and the broken feature moves. It moves on every deploy, which is exactly what we saw and exactly why we did not believe it was the build.

The fix​

One line in each app's Vite config:

build: {
  rollupOptions: {
    output: {
      hashCharacters: "hex",
    },
  },
}

Hex is [0-9a-f]. It cannot produce a hyphen or an underscore, so it cannot produce a filename the edge refuses.

It is in all five applications now, and the comment beside it names the two chunks that actually broke, because a bare hashCharacters: "hex" is the kind of line somebody removes while tidying.

Checking a build for it​

Cheap enough to run anywhere:

ls dist/assets | grep -E '[-_]\.(js|css)$'   # must print nothing

If that prints anything, that deployment has a feature which will 404 for every user, and nothing else in the build will tell you.

What we took from it​

A symptom that moves between releases is evidence about the build, not against it. We reasoned the opposite way for several days. Application bugs are usually stable; it is the build that is different every time, so a wandering symptom points at the layer that changes on every deploy.

"Works in preview" was a false negative. A local preview server serves whatever is on disk. The file was on disk. Only the edge refused it, so the one environment that could reproduce the problem was the one we could not easily poke at.

Defaults inherit assumptions. Nobody chose base64url; it is Rollup's default, and it is a perfectly good default in most places. It only becomes a bug where it meets a host with a rule about filenames. Two reasonable decisions, made by people who never spoke, producing something that neither of them is wrong about.

That last one keeps coming up. It is the same shape as the chat panel nobody opened, where two syntax highlighters arrived two years apart and neither had any reason to notice the other.

yourorg.rukialabs.com/            learner
yourorg.rukialabs.com/instructor  authoring and grading
yourorg.rukialabs.com/admin       administration

They are three builds, from three directories, with three bundles. They share a domain, a session and a design system, and a person moving between them does not sign in again.

Why not one application​

The three audiences barely overlap. A learner never opens the grading queue; an administrator rarely takes a course. Built as one application, everyone downloads all three — and the admin console, the heaviest of them, is the one the fewest people open.

Why not three domains​

Because of the session. Three domains means the sign-in state has to be shared across origins, and every mechanism for doing that is either a third-party cookie — increasingly not a mechanism at all — or a redirect dance that is visible to the user and fragile in exactly the situations where it matters.

One origin means one cookie jar. The session problem disappears rather than being solved.

The part that is genuinely awkward​

Serving three applications from one origin means each has to know where it lives. A build served at /admin has to request its assets from /admin/assets/…, and its router has to know that /admin is the root and not a route.

That value is compiled in at build time. Which means the same source, built for a different mount point, is a different artifact — and if the mount point and the build disagree, the failure is not subtle. You get a blank page and a console full of 404s for JavaScript files that exist, at a path nobody asked for.

We have hit this from both directions. A build that captured the browser's path into a post-sign-in redirect — a path that already contained the prefix — and replayed it through a router that prepends the prefix itself, landing everyone on /instructor/instructor/. The learner console escaped it because its prefix is empty, which is exactly why it took a while to see: the bug was invisible in the application we look at most.

What holds it together​

A router at the edge decides which application serves a path, and rewrites the asset URLs in the HTML on the way back so the browser only ever sees the public layout. The applications behind it can be one deployment or several, at their own roots or under their prefixes, and the choice is configuration rather than code.

That flexibility earns its keep during migrations, and costs something the rest of the time: there are now two places a mount point is decided, and they have to agree. Our defence is that disagreement fails loudly — an unconfigured application returns an error naming the variable to set, rather than quietly falling back to a default that serves the wrong environment's code under the right hostname.

That specific failure — "not configured" and "working" being indistinguishable — is worth more attention than it usually gets. A fallback that makes a broken configuration look healthy does not prevent the outage. It just moves it to a worse moment.

Nobody had written a bug. Every one of those numbers came out of code that was individually reasonable.

How one mark becomes three​

Three applications each needed to turn a score into something a person reads. None of them had a shared helper for it, so each re-derived the arithmetic from whatever fields it happened to have in hand.

The API was not sending the denominator. So each app invented a fallback for it, and they invented four different ones:

Divide 120 by each of those and you get the three numbers above, plus a division by zero that rendered as Infinity% until something else swallowed it.

Every fallback was written by somebody being pragmatic about a value that was sometimes absent. Each is defensible on its own. Collectively they meant the platform had four opinions about a learner's grade and no way to notice.

The part that actually mattered​

The wrong numbers were not the worst of it. None of them was marked as uncertain. A confident 300% and a confident 72% render identically: same font, same colour, same position on the card. A learner reading one has no signal that the platform is guessing.

That is the failure worth naming. Not "we computed the wrong number" but "we presented a guess as a fact".

One rule​

There is now exactly one module that turns a mark into something a human reads, and it is built on a single rule:

A missing denominator is unknown. It is not zero and it is not one.

Every function in it can return null, and callers render —.

export function scorePercent(score, total) {
  const s = toNumber(score)
  const t = toNumber(total)
  if (s === null || t === null || t <= 0) return null
  return Math.round((s / t) * 100)
}

Note what is not null: a score of zero. Zero is a real result and returns 0. Only a missing or non-positive total makes the answer unknown. Conflating "they scored nothing" with "we do not know what they scored" would reintroduce the original bug from the other direction.

Being silent about a mark we cannot compute is recoverable — somebody asks, and we find out why the denominator was missing. Being confidently wrong about a learner's grade is not.

The dash is a diagnostic​

An unexpected benefit: because the dash means one specific thing, it points at one specific cause.

A dash where a number belongs almost always means an assignment was created with no maximum score. That is a two-minute fix by whoever authored it. Before, the same condition produced a plausible-looking percentage that nobody ever questioned, so the underlying data stayed broken indefinitely.

A visible unknown gets fixed. A silent guess does not.

Totals above 100​

The same module owns one more decision that used to be made three different ways.

Our grading engine adds bonus points on top of the 100 that the weighted categories divide between them, and only clamps the sum when the course's grade scale says extra credit may not exceed full marks. Where a scale allows it, a final mark of 108 is a real and correct result.

Rendering that as 108 / 100 (108%) states a ceiling that is not the ceiling and a percentage that reads as arithmetic gone wrong. So there is one predicate for "is this over the scale", and callers drop the denominator when it is true.

Three surfaces render that total — both consoles and the learner's own progress page — and before there was one predicate to agree on, they disagreed about it.

What we would say to anyone with the same shape of problem​

A formatting helper is not a formatting concern when what it formats is somebody's grade. It decides a number that affects a person, and it belongs in one tested place for the same reason the grading engine does.

Count your fallbacks. Four different defaults for one missing value is not four small pragmatic decisions. It is the absence of a decision, made four times.

Make uncertainty visible in the output. If your renderer cannot distinguish "zero" from "unknown", your users cannot either, and neither can you when you go looking.

The flash​

Fetching branding on mount produces a sequence: the app boots with defaults, asks the server who this organisation is, and repaints. On a fast connection that is a flicker. On a slow one it is two seconds of the wrong logo.

It is worst exactly where it matters most — the sign-in page, the first thing a new learner sees. They arrive at their own organisation's address and are shown somebody else's brand while the page makes up its mind.

No amount of optimising the fetch fixes this. The request cannot start until the bundle runs, and the bundle cannot run until it is downloaded. The branding is always at least one round trip behind the first paint.

Moving the work in front of the app​

Every request to an organisation's address already passes through our router at the edge, which is what decides which application serves it. That router knows the hostname before any application does, and the hostname is precisely what identifies the organisation.

So it looks the organisation up and writes the result into the HTML on its way past:

<script>window.__TENANT__ = { "name": "…", "logoUrl": "…", "settings": { … } }</script>
</head>

By the time the browser parses the document, the branding is already in it. The application reads a value that is present before it starts rather than fetching one, and the first painted frame is correct. There is nothing to flash from.

What it cost​

Three things, none of them free.

The HTML cannot be shared. A page carrying one organisation's name must never be served to another, so these responses are no-store. The HTML shell is small and the hashed assets behind it still cache normally, so the trade is mostly fine — but it is a real one, and it is the reason this technique does not generalise to every page on the internet.

Lookups have to be fast. A per-request database query in front of every page load is not viable. The lookup reads a key-value store at the edge, written by the platform whenever an organisation's settings change, with a short in-process cache in front of it. Which means writes have to invalidate that cache — a cache that also caches misses, so a newly-created organisation stays "not found" for the length of the TTL unless someone purges it. We learned that the direct way.

The fallback has to stay. Injection can fail: a misconfigured host, a lookup that times out, local development where there is no edge at all. The application still fetches its own configuration when the injected value is absent. The fast path is an optimisation, never a requirement — the moment it becomes a requirement, every one of those cases becomes an outage.

Where else it goes​

Once the shell is being rewritten at the edge for one reason, other things want the same treatment. Shared badge and certificate pages now get their og: tags injected the same way, because link-preview crawlers do not run JavaScript either — a credential pasted into Slack used to preview as the generic application shell.

Same mechanism, same constraint: if it has to be in the HTML, it cannot wait for the bundle.