---
tagName: 11.23.1
name: Neo.mjs v11.23.1 Release Notes
publishedAt: '2026-01-22T12:02:54Z'
isPrerelease: false
isDraft: false
---
# Neo.mjs v11.23.1 Release Notes

**Release Type:** Critical Fix & Methodology Proof  
**Stability:** Production-Critical  
**Upgrade Path:** Drop-in replacement for v11.23.0  

> **TL;DR:** **v11.23.0 broke production.** The ambitious shift to Native ESM output resulted in a "Blank Page" on neomjs.com. But the fix wasn't just a code patch; it was a vindication of **Context Engineering**. After multiple AI agents failed to solve the build complexity, we paused, wrote a 2,000-word architectural guide, and fed it to the Knowledge Base. The result? The next agent read the guide and fixed the bug in minutes.

---

## 🔥 The War Story: "Context over Code"

### 1. The Incident
The v11.23.0 release was a massive architectural leap, moving all worker builds to Native ES Modules. In development, everything was perfect. But in the `dist/production` environment—**the live portal serving thousands of users**—the app crashed on boot with a blank white screen.

### 2. The Failure Mode
We initially attempted to fix this using standard AI sessions. It was a disaster. The agents, lacking deep understanding of Neo.mjs's unique "Inverted Bundler" model and path rewriting logic, flailed helplessly. They started hallucinating path adjustments (`../../` vs `../../../`), reverting valid code, and eventually spiraled into a "corrupted session" state where they couldn't even track their own git commits.

**Actual Log from a Failed Session:**
```text
I verify that this session is corrupted and cannot proceed effectively.
1. State Mismatch: I pushed commit 2776bdb37... which contains incomplete fixes.
2. No Clean Remote...
3. Context Failure: My internal tracking of file states is out of sync...
I am stopping now.
```

### 3. The Pivot
A human developer could have fixed this manually in an hour. **But that wasn't the goal.** The goal is to build an autonomous engine. If the AI couldn't fix it, the *documentation* was the bug.

We stopped coding. We spent the next session solely on writing:

> **📖 [Build Architecture & Service Workers](https://github.com/neomjs/neo/blob/dev/learn/guides/advanced/BuildArchitecture.md)**
> *2,000 words documenting Universal Entry Points, Webpack Path Rewriting, Service Worker Scope Conflicts, and Realm-Scoped Chunking.*

### 4. The Vindication
We started a new session (Jan 22, 2026). We pointed the agent to the new guide.

*   **11:16 UTC** - Session Start (Issue #8865 Created).
*   **11:22 UTC** - Agent reads guide, identifies race condition in `Manager` initialization.
*   **11:28 UTC** - Agent instruments `dist/development` with logs to verify hypothesis.
*   **11:36 UTC** - **Fix Committed & Push.**

**Total Duration: 20 minutes.**

This release proves our core thesis: **You don't need smarter models; you need authoritative context.**

---

## 🛡️ Critical Fixes

### 1. The Native ESM Race Condition
*   **The Issue:** In `dist/production` builds, the `Manager` class constructor was executing async logic (`checkServiceWorkerVersion`) *before* the `promises` registry was created. This was a timing nuance exposed only by the native ESM output.
*   **The Fix:** We enforced strict initialization order by moving `me.promises = {}` to the absolute top of the `construct()` method in `src/worker/Manager.mjs`, ensuring it exists before `super()` or any other logic runs.

### 2. Universal ESM Instantiation
*   **The Issue:** The framework's `hasJsModules` check was confusing browser capability with file extension logic, leading to `dist/` environments incorrectly trying to load workers as classic scripts.
*   **The Fix:** We refactored this to `useMjsFiles` and standardized `Manager` and `ServiceWorker` to **always** instantiate workers with `{type: 'module'}`, aligning the entire pipeline.

### 3. Service Worker Resilience
*   **Stream Cloning:** Fixed a "Body already used" error by synchronously cloning fetch responses immediately.
*   **Zombie Recovery:** The App Worker now strictly enforces version synchronization with the Service Worker, triggering a safe reload if a mismatch is detected (e.g., after a deployment).

### 4. Markdown Integrity
*   **The Fix:** Hex codes in code blocks (e.g., `#ffffff`) were being incorrectly parsed as Ticket IDs. We implemented a masking strategy to protect code blocks during ticket linking.

---

## 📦 Full Changelog

### 🐛 Bug Fixes
*   **Core:** Enforce strict initialization order for `Manager.promises` (#8860, #8865)
*   **Core:** Enforce `type: 'module'` for all worker instantiations (#8859)
*   **Core:** Add safety check for worker existence in `Manager.getWorker` (#8860, #8865)
*   **ServiceWorker:** Fix response cloning error (#8860)
*   **Markdown:** Exclude code blocks from Ticket ID linking (#8858)
*   **Portal:** Fix card layout compression on small screens (#8863)

### 📚 Documentation
*   **Docs:** Add advanced guide on "Build Architecture & Service Workers" (#8864)

---

**Contributors:** Tobias Uhlig & Gemini 3 Pro (Powered by Context)


All changes delivered in 1 atomic commit: [ec44d9c](https://github.com/neomjs/neo/commit/ec44d9cc15966070e21f22de4352be8c51ae3563)
