🐞 Patch Stoplight mosaic storage fallback

[JFWooten4]

In a similar spirit to #2415, this PR fixes working environments where memory cleanup struggles. It applies a root-clear fix to actually delete the requested data. This same error fix sometimes fixes the warning while actually applying the intent, acting as a first line of defense against the build error.

Changes

This patch makes Stoplight Mosaic’s theme persistence safer in non-browser and partial-storage environments.

It adds removeItem support to Mosaic’s in-memory storage fallback, avoids reading document.documentElement when document is unavailable, and falls back to memory storage when localStorage.removeItem is missing.

This prevents Mosaic’s Zustand-backed theme store from failing when rendered in environments that do not provide a complete browser storage API.

[Copilot]

Pull request overview

Adds a patch-package patch for @stoplight/mosaic@1.53.4 to make Mosaic’s theme persistence more resilient in SSR/non-browser and partial Storage API environments.

Changes:

• Add removeItem to Mosaic’s in-memory storage fallback.
• Avoid reading document.documentElement when document is unavailable.
• Fall back to in-memory storage when localStorage.removeItem is missing.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[ElliotFriend]

I dug into this one: the bug is real (confirmed memoryStorage lacks removeItem in the installed mosaic 1.53.5) and your fix targets the right layer. Good find.

But I'm going to hold off on merging a package patch here. A repo policy I'd like to propose: dependency patches are a last resort — they freeze us to a version, they don't get upstream fixes, and they rot silently (case in point: the repo's move to pnpm in #2493 left this PR's patch-package file inert, which is why CI is green — it currently changes nothing).

Path forward:

1. First step is an upstream issue at @stoplight/mosaic with your diagnosis — you did the work, you should get the credit. Happy to co-sign and add repo context.
2. If upstream doesn't move in a reasonable window, we'll revisit this as a pnpm patch against the then-current version, with the upstream issue linked from the patch so we know when we can delete it.

The failure mode this fixes (broken storage in private browsing on API pages) is low-severity enough that we lose little by sequencing it this way. I'll leave this open for now with a note; if you file the upstream issue, link it here.

[JFWooten4]

Thanks for digging into this. I agree with treating dependency patches as a last resort.

I filed the upstream issue here: stoplightio/elements#2945

Since the existing patch-package file became inert after the pnpm migration, I will not convert it into a pnpm patch unless upstream stalls and we decide that carrying the fix locally is warranted. I’ll leave this PR open for tracking as requested.

[ElliotFriend]

thanks @JFWooten4!!

[JFWooten4]

Quick follow-up: upstream issue stoplightio/elements#2945 is still open and hasn’t received a maintainer response. I followed up there on August 10 asking whether elements is the right repository, but there has not been a reply.

I rechecked this against current main before reviving the patch: pnpm build still emitted the Zustand warning that mosaic-theme does not contain a removeItem method. Since upstream has stalled, I’ve rebased this PR onto current main and migrated the fix from patch-package to pnpm’s native patchedDependencies against the current @stoplight/mosaic@1.53.5, with the upstream issue linked in pnpm-workspace.yaml.

I also validated the pnpm-patched build end-to-end: the patch applies successfully and the build completes without the removeItem warning. The clean PR branch additionally passes the repository’s normal frozen-lock pnpm install.