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:

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 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