The Docs Describe a Different Runtime

The import worked everywhere except the one place it had to. Same line, same package, same syntax I'd used a hundred times, and inside the artifact renderer it failed without an error, in a way the documentation had never mentioned was possible.

The package was coming from esm.sh, the standard modern way to pull an ES module straight off a CDN. It's the documented path. It's the path that works in every normal browser context. Inside the renderer where the tool actually had to run, it didn't. No note about it in the docs. No warning. Just an environment that didn't behave the way the environment was described.

The fix was to stop using the documented path and use an older one, a UMD build off a different CDN, the kind of module format that predates the clean modern import and works in more places precisely because it assumes less. The current, recommended, well-documented approach failed. The older, uglier, less-recommended approach held. That inversion is the whole lesson.

The Storage That Wasn't There

The same gap showed up in storage. Reach for localStorage, the obvious, universal, taught-in-every-tutorial way to persist a little state in a browser, and it isn't there. Not disabled, not throwing a permission error you could catch and handle. Just absent, in a context where the mental model says it should exist. The runtime offers a different mechanism instead, one you only find by discovering that the expected one is missing.

So you write the storage layer twice. Once the way the documentation implies, and then again, defensively, feature-detecting whether the thing you expected even exists and falling back when it doesn't. The second version is the one that survives. The first version is the one that reads well in a tutorial.

Two Documents Nobody Merges

There's the documented environment, the platform as it was described, as the getting-started guide presents it, as the API reference assumes it. And there's the real runtime, the platform as it actually executes, with its missing globals and its failed imports and its behaviors that no one wrote down because no one hit them until you did.

Those are two different documents. The gap between them comes from the fact that the person writing the docs was describing the platform they built, and the platform you get is the one that actually runs, and nobody is assigned to reconcile those two things for you. That reconciliation is your job. You do it by hitting the wall the docs didn't mention and writing down where the wall actually is.

Every environment has this gap. The mature ones have a smaller one. None of them have none. The documentation describes the platform someone intended. The runtime is the platform you actually got, and the only way to learn the difference is to run code until the difference shows up.