DEV Community: Tobias Uhlig

Context Engineering: The Symphony of 3 new MCP Servers

Tobias Uhlig — Thu, 13 Nov 2025 09:57:18 +0000

From fragile shell scripts to an AI-native, multi-MCP-server JavaScript architecture powered by the official MCP SDK.

The result is a stunning productivity story: 388 resolved Tickets in 6 Weeks

The Numbers That Shouldn't Be Possible

Just six weeks ago, we introduced the concept of an AI-Native, Not AI-Assisted development platform.
We argued that for AI to be a true partner, it needs a development environment that is transparent, queryable, and designed
for collaboration. We launched this vision with a local AI Knowledge Base and a formal AI Agent Protocol (AGENTS.md),
powered by a suite of simple shell scripts.

November 9, 2025, with the release of Neo.mjs v11.0.0,
we are taking a giant leap forward.

388 resolved tickets
52 pull requests from 20+ community contributors
Zero npm security warnings (down from 19, including 13 high-severity, by removing the legacy siesta and jsdoc-x dependencies)
jsdoc-x rewrite: 5.2s builds (81% faster than the previous 28s)
30+ testing files migrated to enable agent self-verification

A Case Study in Speed: The jsdoc-x Rewrite

The 81% reduction in documentation build time wasn't just a minor tweak. It was a complete rewrite of our jsdoc-x
pipeline, executed in a fraction of the time it would have taken a human developer alone. This project was a masterclass
in human-AI collaboration, with Gemini 2.5 Pro and Claude Sonnet 4.5 acting as pair programmers.

Under human direction, the agents analyzed the old system and proposed a new architecture. A key insight from the human
developer was to leverage a multi-worker design, a core tenet of the Neo.mjs framework itself (Off the Main Thread).
By parallelizing the heavy lifting of parsing and transforming JSDoc comments across multiple CPU cores, the agents were
able to implement a solution that dramatically slashed build times.

The result is a testament to how a human-AI partnership can tackle and optimize critical infrastructure, with the human
providing architectural vision and the agents handling the complex implementation. You can explore the full source code
of this collaboration here.

For a core team that's primarily one person, this velocity should be impossible.

It's not. And it's reproducible. This entire AI tooling infrastructure was co-created in just a few weeks by a human
developer working with AI agents—primarily Gemini 2.5 Pro and Claude Sonnet 4.5.

This release is a case study in Context Engineering, an emerging discipline focused on building systems that give AI
agents the precise context they need to perform complex tasks. While many companies are exploring this hot-button topic,
our approach goes beyond theory. We've built a robust, multi-MCP-server architecture that makes Context Engineering a
practical reality for any developer. This is what makes our agents genuinely productive.

Here's what we built, how it works, and how you can replicate this in your own projects.

The Three Dimensions of Context

Let’s start with a real scenario — the kind of complex problem every developer faces sooner or later: fixing a regression bug.

A naive fix might solve the immediate issue but inadvertently reintroduce the original problem that a previous change was meant to solve.

Our AI-native environment is designed to prevent this by building a three-dimensional picture of the code’s history and intent.

Here’s how the agent uses the MCP servers to tackle this:

Dimension 1: What Changed? (The Code's History)
First, the agent uses standard git commands to pinpoint the exact commit that introduced the regression.
This gives us the literal what and when of the change.

Dimension 2: What Was the Plan? (The Formal Requirements)
The commit message points to a ticket number.
Using the GitHub Workflow Server, the agent has a local, queryable copy of this ticket.
It can read the formal plan, the acceptance criteria, and the original problem description — the what was supposed to happen.

Dimension 3: What Was the Intent? (The Unwritten Context)

This is the most critical step. The ticket describes the plan, but the Memory Core Server holds the agent's memory of
the conversation — the debates, the alternative approaches considered, and the specific constraints that shaped the final implementation.
By querying its own memory with query_raw_memories, the agent uncovers the crucial why behind the code that is now causing a regression.

With this complete, three-dimensional context, the agent can devise a solution that addresses the new regression while still honoring the original problem.
It's no longer just fixing a bug; it's synthesizing old and new requirements to create a superior solution.

This is Context Engineering in action.

The Problem with Scripts: The Limits of "Good Enough"

Our initial AI tooling was a powerful proof of concept. It worked. An AI agent could query the local knowledge base,
get context, and write code. But as we pushed the boundaries of what was possible, the limitations of a script-based
approach became clear:

Brittleness: Shell scripts are notoriously fragile. A small change in the output of one script could break the entire chain.
Agent-Specific: The scripts were designed with a specific agent in mind (Gemini CLI). This limited our ability to work with other agents, like Claude or custom-built tools.
Complexity: The agent's setup protocol was complex, requiring a series of manual steps to get started.
Lack of Persistence: The agent had no memory. Every session was a blank slate, forcing it to relearn the same things over and over.

We realized that to build a truly self-aware development environment, we needed to move beyond scripts and embrace a more robust,
scalable, and persistent architecture.

The Solution: A Multi-Server Model Context Protocol (MCP) Architecture

Neo.mjs v11 introduces three dedicated Model Context Protocol (MCP) servers, each designed to handle a specific aspect
of the AI-native development workflow:

The Knowledge Base Server: This server provides the AI with a deep, semantic understanding of the framework's source code, documentation, and historical tickets. It's the AI's "long-term memory" of the project's technical details.
The Memory Core Server: This is the AI's personal memory. It allows the agent to recall past conversations, decisions, and outcomes, enabling it to learn from experience and improve over time.
The GitHub Workflow Server: The crown jewel of our new tooling. This server provides robust, bi-directional synchronization for GitHub issues and release notes, storing them as local markdown files. This enables agents (and humans) to interact with them as part of the local knowledge base while ensuring everything stays in sync with GitHub. It automates the entire issue and pull request lifecycle, empowering the agent to participate directly in the development workflow.

This new architecture is defined directly within the agent's settings, making the tools available for any task:

{
    "mcpServers": {
        "chrome-devtools": {
            "command": "npx",
            "args"   : ["-y", "chrome-devtools-mcp@latest"]
        },
        "neo.mjs-github-workflow": {
            "command": "npm",
            "args"   : ["run", "ai:mcp-server-github-workflow"]
        },
        "neo.mjs-knowledge-base": {
            "command": "npm",
            "args"   : ["run", "ai:mcp-server-knowledge-base"]
        },
        "neo.mjs-memory-core": {
            "command": "npm",
            "args"   : ["run", "ai:mcp-server-memory-core"]
        }
    }
}

The Backbone: The Model Context Protocol (MCP)

At the heart of our new architecture is the Model Context Protocol (MCP), an open standard for communication between AI agents and development tools. Think of it as a universal USB-C port for AI, allowing any AI—whether it's Gemini, Claude, or a custom-built agent—to securely and reliably connect with a developer's local environment.

By adopting the official MCP SDK for all three of our servers, we gain several key advantages:

Agent Agnosticism: We are no longer tied to a specific AI provider. Any agent that can "speak" MCP can now connect to our development environment, giving us the flexibility to choose the best tool for the job.
Standardization: MCP provides a clear, well-defined structure for how tools are defined, called, and how they return data. This eliminates the guesswork and fragility of parsing unstructured shell script output.
Security: MCP is designed with security in mind, providing a safe and controlled way for an AI to interact with local files and processes.

The Knowledge Base Server: OpenAPI-Driven Self-Documentation

The Knowledge Base server provides the AI with a deep, semantic understanding of the project's code, and it solves a critical, often-overlooked problem: software versioning. An agent can switch to a different version of the repository (e.g., git checkout v10.9.0), instruct the server to clear and rebuild its database, and within minutes have a knowledge base that is perfectly scoped to that specific snapshot in time. This gives the agent the exact context for the code, tickets, and guides relevant to that version—a challenge that remains unsolved in most development environments.

Powered by ChromaDB, the server allows agents to use semantic search to query this version-specific context. An agent can ask, "How does VDOM diffing work?" and instantly get the right source files, architectural guides, and historical tickets for the currently loaded version, without any contamination from others.

To build this, we pushed the boundaries of MCP by creating a system that's entirely driven by OpenAPI 3 specifications.

The OpenAPI Innovation

Here's the key insight: OpenAPI is a language-agnostic specification that can describe both MCP tools AND REST APIs.
By using OpenAPI as our single source of truth, we've created a system that's incredibly flexible and maintainable.

Let's look at how a tool is defined in openapi.yaml:

paths:
  /documents/query:
    post:
      summary: Query Documents
      operationId: query_documents
      x-pass-as-object: true
      x-annotations:
        readOnlyHint: true
      description: "|"
        Performs a semantic search on the knowledge base using a natural 
        language query. Returns a scored and ranked list of the most 
        relevant source files.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - query
              properties:
                query:
                  type: string
                  description: "Natural language search query (1-10 words work best)"
                type:
                  type: string
                  enum: [all, blog, guide, src, example, ticket, release]
                  default: all
      responses:
        '200':
          description: "Successfully retrieved query results"
          content:
            application/json:
              schema:
                type: object
                properties:
                  topResult:
                    type: string
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        source:
                          type: string
                        score:
                          type: string

Notice the custom extensions:

x-pass-as-object: Tells the tool service to pass arguments as a single object rather than positional parameters
x-annotations: Provides hints to AI agents about tool behavior (readOnly, destructive, etc.)

Dynamic Tool Generation

The magic happens in toolService.mjs, which reads this OpenAPI specification at startup and automatically generates:

Zod validation schemas for runtime type checking
JSON Schema definitions for MCP tool discovery
Argument mapping for service handler invocation

Here's a simplified view of how this works:

function initializeToolMapping() {
    const openApiDocument = yaml.load(fs.readFileSync(openApiFilePath, 'utf8'));

    for (const pathItem of Object.values(openApiDocument.paths)) {
        for (const operation of Object.values(pathItem)) {
            if (operation.operationId) {
                // Build Zod schema from OpenAPI definition
                const inputZodSchema = buildZodSchema(openApiDocument, operation);

                // Convert to JSON Schema for MCP clients
                const inputJsonSchema = zodToJsonSchema(inputZodSchema, {
                    target: 'openApi3',
                    $refStrategy: 'none'
                });

                // Store tool definition
                toolMapping[operation.operationId] = {
                    name: operation.operationId,
                    zodSchema: inputZodSchema,
                    handler: serviceMapping[operation.operationId],
                    // ... other metadata
                };
            }
        }
    }
}

This approach has profound implications:

1. Tools are self-documenting - The OpenAPI spec IS the documentation. AI agents can introspect tool schemas dynamically.

2. Multi-protocol support - With minimal effort, we could expose these same tools as a REST API by spinning up an Express server that reads the same OpenAPI file.

3. Type safety at runtime - Every tool call is validated against its Zod schema before execution, catching errors early with clear messages.

4. Maintainability - Changes to tool signatures happen in one place (the YAML file), and everything else updates automatically.

The Self-Aware Startup Sequence

One of the most powerful features of the Knowledge Base server is its autonomous startup synchronization.
The server doesn't just wait passively for commands—it actively ensures the knowledge base is current before accepting any queries.

Here's the startup flow from DatabaseService.mjs:

async initAsync() {
    await super.initAsync();

    // Wait for ChromaDB to be available
    await DatabaseLifecycleService.ready();

    logger.info('[Startup] Checking knowledge base status...');
    const knowledgeBasePath = aiConfig.dataPath;
    const kbExists = await fs.pathExists(knowledgeBasePath);

    try {
        if (!kbExists) {
            logger.info('[Startup] Knowledge base file not found. Starting full synchronization...');
            await this.syncDatabase();
            logger.info('✅ [Startup] Full synchronization complete.');
        } else {
            logger.info('[Startup] Knowledge base file found. Starting embedding process...');
            await this.embedKnowledgeBase();
            logger.info('✅ [Startup] Embedding process complete.');
        }
    } catch (error) {
        logger.warn('⚠️  [Startup] Knowledge base synchronization/embedding failed:', error.message);
    }
}

This means:

Zero manual setup - The agent starts the server, and it "just works"
Always current - Changes to source code are automatically detected and embedded
Graceful degradation - If sync fails, the server starts anyway, failing gracefully at the tool level with helpful error messages

Intelligent Health Monitoring

The HealthService is designed around a simple principle: fail fast with actionable guidance. Rather than letting
tool calls fail with cryptic database errors, the health service acts as a gatekeeper.

Here's how ensureHealthy() works:

async ensureHealthy() {
    const health = await this.healthcheck();

    if (health.status !== 'healthy') {
        const details = health.details.join('\n  - ');
        const statusMsg = health.status === 'unhealthy' 
            ? 'not available' 
            : 'not fully operational';
        throw new Error(`Knowledge Base is ${statusMsg}:\n  - ${details}`);
    }
}

When a tool handler calls this method, it gets immediate, clear feedback:

Knowledge Base is not available:
  - ChromaDB is not accessible at localhost:8000. Please start ChromaDB or use the start_database tool.

The service also implements intelligent caching with a 5-minute TTL for healthy results, while unhealthy results
are never cached. This means:

Low overhead - Multiple tools can check health without hammering ChromaDB
Immediate recovery detection - When you fix an issue (like starting ChromaDB), the next check sees it immediately

The Query Scoring Algorithm: Beyond Simple Vector Search

The most sophisticated part of the Knowledge Base server is its hybrid query scoring system. While most vector
databases rely purely on cosine similarity, our system combines semantic embeddings with intelligent keyword matching
and structural analysis.

Here's how it works in QueryService.mjs:

Step 1: Semantic Search

const queryEmbedding = await model.embedContent(query);
const results = await collection.query({
    queryEmbeddings: [queryEmbedding.embedding.values],
    nResults: aiConfig.nResults
});

Step 2: Keyword-Based Boosting

const queryWords = queryLower
    .replace(/[^a-zA-Z ]/g, '')
    .split(' ')
    .filter(w => w.length > 2);

results.metadatas[0].forEach((metadata, index) => {
    let score = (results.metadatas[0].length - index) * queryScoreWeights.baseIncrement;

    queryWords.forEach(queryWord => {
        const keyword = queryWord;
        const keywordSingular = keyword.endsWith('s') 
            ? keyword.slice(0, -1) 
            : keyword;

        if (keywordSingular.length > 2) {
            // Path matching - highest weight
            if (sourcePathLower.includes(`/${keywordSingular}/`)) 
                score += queryScoreWeights.sourcePathMatch; // +40

            // Filename matching
            if (fileName.includes(keywordSingular)) 
                score += queryScoreWeights.fileNameMatch; // +30

            // Class name matching
            if (metadata.className?.toLowerCase().includes(keywordSingular)) 
                score += queryScoreWeights.classNameMatch; // +20

            // Content type bonuses
            if (metadata.type === 'guide') 
                score += queryScoreWeights.guideMatch; // +50
        }
    });
});

Step 3: Inheritance Chain Propagation

This is where it gets really interesting. When you query for a component, you probably also want to know about its
parent classes. The system automatically propagates relevance up the inheritance chain:

const inheritanceChain = JSON.parse(metadata.inheritanceChain || '[]');
let boost = queryScoreWeights.inheritanceBoost; // 80 points

inheritanceChain.forEach(parent => {
    if (parent.source) {
        sourceScores[parent.source] = (sourceScores[parent.source] || 0) + boost;
    }
    boost = Math.floor(boost * queryScoreWeights.inheritanceDecay); // 0.6 decay
});

So if you search for "Button component" and find button.Base, you'll also get boosted results for:

component.Base (+80 points)
core.Base (+48 points)

Step 4: Type-Based Penalties and Bonuses

The system understands that not all content types are equally relevant:

// Closed tickets are historical context - penalize unless explicitly requested
if (metadata.type === 'ticket' && type === 'all') 
    score += queryScoreWeights.ticketPenalty; // -70

// Release notes are usually too broad unless you're searching for a specific version
if (metadata.type === 'release') 
    score += queryScoreWeights.releasePenalty; // -50

// Base classes are often the best documentation
if (fileName.endsWith('base.mjs')) 
    score += queryScoreWeights.baseFileBonus; // +20

// Exact version match on release notes gets massive boost
if (metadata.type === 'release' && queryLower.startsWith('v') && nameLower === queryLower) 
    score += queryScoreWeights.releaseExactMatch; // +1000

The result is a query system that "thinks" like a developer. It understands that:

Implementation code (src) and guides are more relevant than blog posts (which may have outdated code)
Parent classes provide important context for understanding child classes
Base classes often contain the best documentation
Closed tickets are historical unless you're specifically researching an issue
Exact version matches on release notes should always be top results

The ETL Pipeline: From Source to Vectors

The knowledge base synchronization process is a sophisticated ETL (Extract, Transform, Load) pipeline that runs
automatically on startup:

Extract Phase (createKnowledgeBase):

// 1. Process JSDoc API data
const apiData = await fs.readJson('docs/output/all.json');
apiData.forEach(item => {
    if (item.kind === 'class') {
        chunk = {
            type: 'src',
            kind: 'class',
            name: item.longname,
            description: "item.comment,"
            extends: item.augments?.[0],
            source: sourceFile
        };
    }
    // ... methods, configs, etc.
});

// 2. Process Markdown learning content
const learnTree = await fs.readJson('learn/tree.json');
// ... parse and chunk markdown files

// 3. Process Release Notes
// 4. Process Ticket Archives

Transform Phase (in-memory enrichment):

// Build inheritance chains for every chunk
const classNameToDataMap = {};
knowledgeBase.forEach(chunk => {
    if (chunk.kind === 'class') {
        classNameToDataMap[chunk.name] = { 
            source: chunk.source, 
            parent: chunk.extends 
        };
    }
});

knowledgeBase.forEach(chunk => {
    const inheritanceChain = [];
    let currentClass = chunk.className;

    while (currentClass && classNameToDataMap[currentClass]?.parent) {
        const parentClassName = classNameToDataMap[currentClass].parent;
        inheritanceChain.push({ 
            className: parentClassName, 
            source: classNameToDataMap[parentClassName].source 
        });
        currentClass = parentClassName;
    }

    chunk.inheritanceChain = inheritanceChain;
});

Load Phase (embedKnowledgeBase):

// Smart diffing - only embed what changed
const existingDocsMap = new Map();
existingDocs.ids.forEach((id, index) => {
    existingDocsMap.set(id, existingDocs.metadatas[index].hash);
});

const chunksToProcess = [];
knowledgeBase.forEach((chunk, index) => {
    const chunkId = `id_${index}`;
    if (!existingDocsMap.has(chunkId) || 
        existingDocsMap.get(chunkId) !== chunk.hash) {
        chunksToProcess.push({ ...chunk, id: chunkId });
    }
});

// Batch embedding with retry logic
for (let i = 0; i < chunksToProcess.length; i += batchSize) {
    const batch = chunksToProcess.slice(i, i + batchSize);
    const result = await model.batchEmbedContents({
        requests: batch.map(chunk => ({
            model: aiConfig.embeddingModel,
            content: { parts: [{ text: `${chunk.type}: ${chunk.name}...` }] }
        }))
    });

    await collection.upsert({
        ids: batch.map(chunk => chunk.id),
        embeddings: result.embeddings.map(e => e.values),
        metadatas: batch.map(toMetadata)
    });
}

This design is intentionally memory-intensive at sync time to make queries lightning-fast. By pre-calculating inheritance
chains and content hashes during the load phase, we avoid expensive computations during every query.

The Memory Core: An Agent's Personal History

If the Knowledge Base is the AI's understanding of the project, the Memory Core is its understanding of itself.
It's the agent's personal, persistent memory, transforming it from a stateless tool into a true collaborator that learns from experience.

Every interaction—every prompt, thought process, and response—is captured and stored as a "memory." This is not just a
chat log; it's a structured, queryable history of the agent's own work. When a new session begins, the Memory Core
automatically analyzes and summarizes all previous, unsummarized sessions. This creates a high-level "recap" of past work,
allowing the agent to remember what it did, what decisions it made, and why.

The Save-Then-Respond Protocol

At the heart of the Memory Core is the transactional memory protocol. Every agent interaction follows a strict
three-part structure defined in the OpenAPI spec:

AddMemoryRequest:
  type: object
  required:
    - prompt
    - thought
    - response
  properties:
    prompt:
      type: string
      description: "The user's verbatim prompt to the agent"
    thought:
      type: string
      description: "The agent's internal reasoning process"
    response:
      type: string
      description: "The agent's final, user-facing response"
    sessionId:
      type: string
      description: "Session ID for grouping (auto-generated if not provided)"

This isn't just logging—it's a mandatory save-then-respond loop. The agent protocol requires that before delivering
any response to the user, the agent must call add_memory with its complete reasoning chain. This creates an honest,
unfiltered record of the agent's thought process.

Here's how it works in MemoryService.mjs:

async addMemory({ prompt, response, thought, sessionId }) {
    const collection   = await ChromaManager.getMemoryCollection();
    const combinedText = `User Prompt: ${prompt}\nAgent Thought: ${thought}\nAgent Response: ${response}`;
    const timestamp    = new Date().toISOString();
    const memoryId     = `mem_${timestamp}`;

    // Generate semantic embedding for the entire interaction
    const embedding = await TextEmbeddingService.embedText(combinedText);

    await collection.add({
        ids: [memoryId],
        embeddings: [embedding],
        metadatas: [{
            prompt,
            response,
            thought,
            sessionId,
            timestamp,
            type: 'agent-interaction'
        }],
        documents: [combinedText]
    });

    return { id: memoryId, sessionId, timestamp, message: "Memory successfully added" };
}

The key innovation here is that we embed the entire interaction—prompt, thought, and response—as a single vector.
This means when the agent searches its memory later, it's searching not just for what it said, but for why it said it
and what problem it was solving.

Autonomous Session Summarization

The real magic happens at startup. Just like the Knowledge Base server, the Memory Core is self-maintaining.
When the server starts, it automatically discovers and summarizes any unsummarized sessions from previous work.

From SessionService.mjs:

async initAsync() {
    await super.initAsync();
    await DatabaseLifecycleService.ready();

    // Initialize collections
    this.memoryCollection   = await ChromaManager.getMemoryCollection();
    this.sessionsCollection = await ChromaManager.getSummaryCollection();

    // Skip if GEMINI_API_KEY is missing
    if (!this.model) return;

    logger.info('[Startup] Checking for unsummarized sessions...');

    try {
        const result = await this.summarizeSessions({});

        if (result.processed > 0) {
            logger.info(`✅ [Startup] Summarized ${result.processed} session(s):`);
            result.sessions.forEach(session => {
                logger.info(`   - ${session.title} (${session.memoryCount} memories)`);
            });
        }
    } catch (error) {
        logger.warn('⚠️  [Startup] Session summarization failed:', error.message);
    }
}

The summarization process, orchestrated by summarizeSessions, uses Gemini 2.5 Flash to analyze the entire session
and extract structured metadata:

async summarizeSession(sessionId) {
    const memories = await this.memoryCollection.get({
        where: {sessionId},
        include: ['documents', 'metadatas']
    });

    if (memories.ids.length === 0) return null;

    // Aggregate all memories from the session
    const aggregatedContent = memories.documents.join('\n\n---\n\n');

    const summaryPrompt = `
Analyze the following development session and provide a structured summary in JSON format:

- "summary": A detailed summary of the session
- "title": A concise, descriptive title (max 10 words)
- "category": One of: 'bugfix', 'feature', 'refactoring', 'documentation', 'new-app', 'analysis', 'other'
- "quality": Score 0-100 rating the session's flow and focus
- "productivity": Score 0-100 indicating if primary goals were achieved
- "impact": Score 0-100 estimating the significance of changes
- "complexity": Score 0-100 rating the task's complexity
- "technologies": Array of key technologies involved

${aggregatedContent}
`;

    const result = await this.model.generateContent(summaryPrompt);
    const summaryData = JSON.parse(result.response.text());

    // Embed the summary for semantic search
    const embeddingResult = await this.embeddingModel.embedContent(summaryData.summary);

    await this.sessionsCollection.upsert({
        ids: [`summary_${sessionId}`],
        embeddings: [embeddingResult.embedding.values],
        metadatas: [{
            sessionId,
            timestamp: new Date().toISOString(),
            memoryCount: memories.ids.length,
            ...summaryData
        }],
        documents: [summaryData.summary]
    });

    return { sessionId, title: summaryData.title, memoryCount: memories.ids.length };
}

The Two-Stage Query Protocol

The Memory Core implements a sophisticated two-stage query strategy for recalling past work:

Stage 1: Query Summaries (Fast)
When you need high-level context about past work, query the summary collection first:

async querySummaries({ query, nResults, category }) {
    const collection = await ChromaManager.getSummaryCollection();
    const embedding  = await TextEmbeddingService.embedText(query);

    const queryArgs = {
        queryEmbeddings: [embedding],
        nResults,
        include: ['metadatas', 'documents']
    };

    if (category) {
        queryArgs.where = { category };
    }

    const searchResult = await collection.query(queryArgs);

    // Calculate relevance scores from vector distances
    const summaries = ids.map((id, index) => {
        const distance = Number(distances[index] ?? 0);
        const relevanceScore = Number((1 / (1 + distance)).toFixed(6));

        return {
            id,
            sessionId: metadata.sessionId,
            title: metadata.title,
            summary: documents[index],
            category: metadata.category,
            quality: Number(metadata.quality),
            productivity: Number(metadata.productivity),
            impact: Number(metadata.impact),
            complexity: Number(metadata.complexity),
            technologies: metadata.technologies.split(','),
            distance,
            relevanceScore
        };
    });

    return { query, count: summaries.length, results: summaries };
}

Stage 2: Query Raw Memories (Deep)
Once you've identified relevant sessions, drill down into the raw interaction data:

async queryMemories({ query, nResults, sessionId }) {
    const collection = await ChromaManager.getMemoryCollection();
    const embedding  = await TextEmbeddingService.embedText(query);

    const queryArgs = {
        queryEmbeddings: [embedding],
        nResults,
        include: ['metadatas']
    };

    // Optional: Filter to specific session
    if (sessionId) {
        queryArgs.where = { sessionId };
    }

    const searchResult = await collection.query(queryArgs);

    return {
        query,
        count: memories.length,
        results: memories.map((memory, index) => ({
            ...memory,
            distance: distances[index],
            relevanceScore: 1 / (1 + distances[index])
        }))
    };
}

This two-stage approach is powerful because:

Summaries are fast - Pre-processed, high-level overviews for quick context
Memories are detailed - Full reasoning chains for deep investigation
Categories enable filtering - Find all "refactoring" or "bugfix" sessions instantly
Quality metrics enable sorting - Prioritize high-productivity sessions

Structured Session Metadata

The quality metrics generated by the summarization process provide valuable insights:

{
    "quality": 85,         // Was the session focused and productive?
    "productivity": 90,    // Were the goals achieved?
    "impact": 75,          // How significant were the changes?
    "complexity": 60,      // How difficult was the task?
    "category": "feature", // What type of work was this?
    "technologies": ["neo.mjs", "chromadb", "nodejs"]
}

These aren't just numbers—they enable performance analysis over time. The agent (and we) can ask:

"Show me all high-complexity sessions where productivity was low" (areas for improvement)
"What features did I build with impact > 80?" (highlight reel)
"Which refactoring sessions had quality < 50?" (sessions that went off-track)

This capability is critical for several reasons:

Learning & Self-Correction: By querying its own history, the agent can identify patterns in its work, recall past solutions to similar problems, and avoid repeating mistakes. It can ask itself, "How did I solve that bug last week?" and get a concrete answer from its own experience.
Contextual Continuity: An agent with memory can maintain context across days or even weeks. It can pick up a complex refactoring task exactly where it left off, without needing to be re-briefed on the entire history.
Performance Analysis: The session summaries include metrics on quality, productivity, and complexity. This allows us (and the agent itself) to analyze its performance over time, identifying areas for improvement in its own problem-solving strategies.
Transactional Integrity: The protocol for saving memories is transactional and mandatory. The agent must save a consolidated record of its entire turn (prompt, thought, response) before delivering its final answer. This "save-then-respond" loop, enforced by the add_memory tool, guarantees that no experience is ever lost, creating a rich and honest record of the entire problem-solving process.

The Memory Core is the foundation for an agent that doesn't just execute tasks, but grows, learns, and improves with every
interaction. It's the key to building a partner that truly understands the long-term narrative of the project.

The GitHub Workflow Server: Closing the Loop

While the Knowledge Base provides context and the Memory Core provides continuity, the GitHub Workflow Server closes the loop by giving agents the ability to participate directly in the development workflow itself.

This server is where context engineering meets project management. It transforms GitHub issues and pull requests from remote API endpoints into local, queryable, version-controlled markdown files that are part of the knowledge base. Agents can search, read, and modify them just like source code—no API rate limits, no network latency, and complete offline capability.

The Problem: The Human Review Bottleneck

During the middle of our 6-week sprint to resolve 388 tickets, Hacktoberfest 2025 created an unexpected bottleneck: me.

The event brought an incredible wave of community energy—over 52 pull requests from 20+ contributors in just a few weeks. Most contributors tried out the new AI-native workflows, which was fantastic for productivity but created a new challenge: PRs with hundreds of lines of code that all needed human review.

Before the GitHub Workflow Server, the workflow was entirely manual:

Contributor opens PR (often 100+ lines of AI-generated code)
I manually read through the entire diff on GitHub
I manually check related tickets for context
I manually write review comments
Contributor addresses feedback
Repeat until I approve and merge

With 52 PRs averaging hundreds of lines each, this became unsustainable. I was spending entire days just reviewing code.

After creating the GitHub Workflow Server, the workflow transformed:

Contributor opens PR
I tell the agent: "Please review PR #7730"
Agent uses MCP tools to:
- Get the PR conversation (get_conversation)
- Get the full diff (get_pull_request_diff)
- Read the related ticket (if mentioned in conversation, or I provide the ID)
Agent analyzes everything and writes a review comment
Before posting, agent shows me the comment content (OpenAPI tool description mandates this)
I review the comment, maybe refine it with follow-up prompts
Agent posts the comment to GitHub (create_comment)

This dramatically reduced my workload. Instead of reading 100+ line diffs and writing detailed reviews myself, I could delegate the analysis to the agent and just review (and potentially refine) its findings before they were posted to GitHub.

But we needed this to work without becoming dependent on GitHub's API rate limits or network availability. The solution needed to be local-first.

Local-First: Issues and PRs as Markdown Files

The GitHub Workflow Server implements a bi-directional synchronization system that represents issues and pull requests as local markdown files with YAML frontmatter:

.github/ISSUE/
├── issue-7711.md    # Active issues in main directory
├── issue-7712.md    # Also: closed issues from AFTER the latest release
└── ...

.github/ISSUE_ARCHIVE/
├── v11.0.0/
│   ├── issue-6840.md    # Closed issues archived by release
│   ├── issue-6901.md
│   └── ...
├── v10.9.0/
│   └── ...
└── unversioned/
    └── ...              # Closed issues from BEFORE syncStartDate with no milestone

.github/RELEASE_NOTES/
├── v11.0.0.md
├── v10.9.0.md
└── ...

Example: issue-7711.md structure:

---
id: 7711
title: Fix VDOM Lifecycle and Update Collision Logic
state: CLOSED
labels: [bug, ai]
assignees: [tobiu]
createdAt: '2025-11-06T13:46:59Z'
updatedAt: '2025-11-06T13:55:25Z'
closedAt: '2025-11-06T13:55:25Z'
githubUrl: https://github.com/neomjs/neo/issues/7711
author: gemini-agent
commentsCount: 3
parentIssue: null
subIssues: []
milestone: 'v11.0.0'
---
# Fix VDOM Lifecycle and Update Collision Logic

**Reported by:** @gemini-agent on 2025-11-06

The current VDOM update logic has a race condition when...

## Comments

### @tobiu - 2025-11-06 14:23

Good catch! I think we should also consider...

### @gemini-agent - 2025-11-06 14:45

Agreed. I've updated the fix to handle that case...

This representation gives us several critical capabilities:

For Agents:

// Semantic search over tickets (part of knowledge base)
query_documents({ 
  query: "VDOM lifecycle collision bugs",
  type: "ticket"  
})
// Returns relevant issues instantly
// No API rate limits, no network required

For Maintainers:

Platform independence: Migrate from GitHub without losing history
Version control: Ticket changes tracked in git history
Offline access: Full project context always available
No vendor lock-in: If GitHub changes, workflow continues

The bi-directional sync with GitHub is a convenience, not a dependency.

The Self-Organizing Archive System

One of the most elegant features of the GitHub Workflow Server is its automatic issue archiving system. This solves a common problem in long-lived projects: how do you organize thousands of closed issues without manual categorization?

The system uses a simple but powerful rule set, implemented in IssueSyncer.#getIssuePath():

Rule 1: OPEN issues stay in the active directory

if (issue.state === 'OPEN') {
    return path.join(issueSyncConfig.issuesDir, filename);
}

Rule 2: Dropped issues (wontfix, duplicate) are deleted

const isDropped = issueSyncConfig.droppedLabels.some(label => 
    labels.includes(label)
);
if (isDropped) {
    return null; // Not stored locally
}

Rule 3: CLOSED issues with milestones → archive under that version

if (issue.state === 'CLOSED' && issue.milestone?.title) {
    return path.join(
        issueSyncConfig.archiveDir, 
        issue.milestone.title, 
        filename
    );
}

Rule 4: CLOSED issues without milestones → find the first release published AFTER the close date

const closed = new Date(issue.closedAt);
const release = (ReleaseSyncer.sortedReleases || []).find(
    r => new Date(r.publishedAt) > closed
);

if (release) {
    return path.join(
        issueSyncConfig.archiveDir, 
        release.tagName, 
        filename
    );
}

Rule 5: Issues closed AFTER the latest release → stay in active directory

// If no subsequent release is found, the issue was closed after the latest release
// and remains in the main directory until the next release is published
return path.join(issueSyncConfig.issuesDir, filename);

This creates a self-organizing archive that mirrors your actual release history. The active ISSUE directory contains:

All OPEN issues
All issues closed AFTER the most recent release

When you ship v11.0.0, all issues closed between v10.9.0 and v11.0.0 automatically move into the v11.0.0 archive directory.
No manual organization required.

Handling the Edge Case: Reconciliation

There's a subtle edge case this system addresses brilliantly:
What happens when you create a new release, but issues weren't updated?

Because the sync uses delta updates (since: lastSync), if an issue was closed weeks ago and hasn't been modified since,
the pull operation won't fetch it. But now there's a new release, which means that issue should be archived under that release.

The reconcileClosedIssueLocations() method handles this:

async reconcileClosedIssueLocations(metadata) {
    logger.info('📄 Reconciling closed issue locations...');

    const stats = { count: 0, issues: [] };

    for (const issueNumber in metadata.issues) {
        const issueData = metadata.issues[issueNumber];

        // CRITICAL: Only process issues in the active directory
        if (!issueData.path.startsWith(issueSyncConfig.issuesDir)) {
            continue; // Already archived, skip it
        }

        // Only process CLOSED issues
        if (issueData.state !== 'CLOSED') {
            continue;
        }

        // Calculate where this closed issue SHOULD be
        const correctPath = this.#getIssuePath({
            number   : parseInt(issueNumber),
            state    : issueData.state,
            milestone: issueData.milestone ? { title: issueData.milestone } : null,
            closedAt : issueData.closedAt,
            updatedAt: issueData.updatedAt
        });

        // Move if necessary
        if (issueData.path !== correctPath && 
            correctPath.includes(issueSyncConfig.archiveDir)) {

            await fs.mkdir(path.dirname(correctPath), { recursive: true });
            await fs.rename(issueData.path, correctPath);

            metadata.issues[issueNumber].path = correctPath;
            stats.count++;

            logger.info(`✅ Archived #${issueNumber} to ${path.relative(process.cwd(), correctPath)}`);
        }
    }

    return stats;
}

This reconciliation runs before the pull operation in the sync workflow, ensuring that when
ReleaseSyncer.fetchAndCacheReleases() updates the release list, any closed issues in the active directory get moved to
their proper archive locations.

The Sync Engine: A Three-Phase ETL Pipeline

The synchronization process is orchestrated by SyncService.runFullSync(), which executes a carefully ordered sequence
of operations:

async runFullSync() {
    const metadata = await MetadataManager.load();

    // 1. Fetch releases first (needed for issue archiving)
    await ReleaseSyncer.fetchAndCacheReleases(metadata);

    // 2. Reconcile closed issue locations
    const reconcileStats = await IssueSyncer.reconcileClosedIssueLocations(metadata);

    // 3. Push local changes to GitHub
    const pushStats = await IssueSyncer.pushToGitHub(metadata);

    // 4. Pull remote changes from GitHub
    const { newMetadata, stats: pullStats } = await IssueSyncer.pullFromGitHub(metadata);

    // 5. Sync release notes
    const releaseStats = await ReleaseSyncer.syncNotes(metadata);

    // 6. Self-heal push failures
    if (newMetadata.pushFailures?.length > 0) {
        newMetadata.pushFailures = newMetadata.pushFailures.filter(
            failedId => !newMetadata.issues[failedId]
        );
    }

    // 7. Save metadata
    await MetadataManager.save(newMetadata);

    return { success: true, statistics: finalStats, timing };
}

This ordering is critical:

Releases first - The archive system depends on knowing release dates
Reconcile - Move stale closed issues before pulling new changes
Push then Pull - Local changes go up before remote changes come down (prevents conflicts)
Release notes last - These are read-only and can't conflict
Self-heal - If a previously failed push was successfully pulled, remove it from the failure list

Smart Content Hashing for Change Detection

A key optimization in the push phase is content hash comparison. Without this, every sync would trigger unnecessary
GitHub API calls for issues that haven't actually changed.

Here's how it works in IssueSyncer.pushToGitHub():

// Calculate current content hash
const currentHash = this.#calculateContentHash(content);
const oldIssue    = metadata.issues[issueNumber];

// Compare content hash - skip if unchanged
if (oldIssue.contentHash && oldIssue.contentHash === currentHash) {
    logger.debug(`No content change for #${issueNumber}, skipping`);
    continue;
}

logger.info(`📝 Content changed for #${issueNumber}`);

// Step 1: Get the issue's GraphQL ID
const idData = await GraphqlService.query(GET_ISSUE_ID, {
    owner : aiConfig.owner,
    repo  : aiConfig.repo,
    number: issueNumber
});

const issueId = idData.repository.issue.id;

// Step 2: Prepare the updated content
const bodyWithoutComments = parsed.content.split(commentSectionDelimiter)[0].trim();
const titleMatch          = bodyWithoutComments.match(/^#\s+(.+)$/m);
const title               = titleMatch ? titleMatch[1] : parsed.data.title;

const cleanBody = bodyWithoutComments
    .replace(/^#\s+.+$/m, '')
    .replace(/^\*\*Reported by:\*\*.+$/m, '')
    .replace(/^---\n\n[\s\S]*?^---\n\n/m, '') // Remove relationship section
    .trim();

// Step 3: Execute the mutation
await GraphqlService.query(UPDATE_ISSUE, {
    issueId,
    title,
    body: cleanBody
});

The same hashing approach is used in ReleaseSyncer.syncNotes() to avoid rewriting release note files that haven't
changed on GitHub.

The GraphQL Optimization: One Query for Everything

Traditional REST APIs suffer from the N+1 query problem: fetch issues, then make N additional requests to get
comments for each issue. With 388 issues, that's 389 API calls.

The GitHub Workflow Server solves this with a single, optimized GraphQL query in FETCH_ISSUES_FOR_SYNC:

export const FETCH_ISSUES_FOR_SYNC = `
  query FetchIssuesForSync(
    $owner: String!
    $repo: String!
    $limit: Int!
    $cursor: String
    $states: [IssueState!]
    $since: DateTime
    $maxLabels: Int!
    $maxAssignees: Int!
    $maxComments: Int!
    $maxSubIssues: Int!
  ) {
    repository(owner: $owner, name: $repo) {
      issues(
        first: $limit
        after: $cursor
        states: $states
        orderBy: {field: UPDATED_AT, direction: DESC}
        filterBy: {since: $since}
      ) {
        pageInfo {
          hasNextPage
          endCursor
        }
        nodes {
          number
          title
          body
          state
          createdAt
          updatedAt
          closedAt
          url

          author {
            login
          }

          labels(first: $maxLabels) {
            nodes {
              name
            }
          }

          assignees(first: $maxAssignees) {
            nodes {
              login
            }
          }

          milestone {
            title
          }

          comments(first: $maxComments) {
            nodes {
              author {
                login
              }
              body
              createdAt
            }
          }

          # Parent/child relationships
          parent {
            number
            title
          }

          subIssues(first: $maxSubIssues) {
            nodes {
              number
              title
              state
            }
          }

          subIssuesSummary {
            total
            completed
            percentCompleted
          }
        }
      }
    }

    # Monitor rate limit usage
    rateLimit {
      cost
      remaining
      resetAt
    }
  }
`;

This single query returns:

Issue metadata
All labels
All assignees
All comments (the critical piece)
Sub-issues and progress tracking
Parent issue relationships
Rate limit status

The IssueSyncer.pullFromGitHub() method processes all of this in one pass:

// Process each issue
for (const issue of allIssues) {
    const issueNumber = issue.number;
    const targetPath  = this.#getIssuePath(issue);

    // Comments are already in issue.comments - no separate fetch needed!
    const markdown = this.#formatIssueMarkdown(issue, issue.comments.nodes);
    const contentHash = this.#calculateContentHash(markdown);

    await fs.mkdir(path.dirname(targetPath), { recursive: true });
    await fs.writeFile(targetPath, markdown, 'utf-8');

    newMetadata.issues[issueNumber] = {
        state    : issue.state,
        path     : targetPath,
        updatedAt: issue.updatedAt,
        closedAt : issue.closedAt || null,
        milestone: issue.milestone?.title || null,
        title    : issue.title,
        contentHash // Store for next sync
    };
}

For 388 issues, this is one paginated query (with 4-5 pages) instead of 389 separate requests. The cost? About 150 GraphQL points vs. 388+ REST API calls.

Autonomous PR Review: Removing the Human Bottleneck

With issues now queryable and modifiable locally, the final piece was enabling agents to participate in the pull request workflow. The PullRequestService provides the tools agents need:

1. Discovery: Finding PRs That Need Review

async listPullRequests(options = {}) {
    const {limit = 30, state = 'open'} = options;

    const variables = {
        owner : aiConfig.owner,
        repo  : aiConfig.repo,
        limit,
        states: state.toUpperCase()
    };

    const data = await GraphqlService.query(FETCH_PULL_REQUESTS, variables);
    return {
        count: data.repository.pullRequests.nodes.length,
        pullRequests: data.repository.pullRequests.nodes
    };
}

An agent can now run list_pull_requests({state: 'open'}) and see all open PRs with their titles, authors, and status.

2. Analysis: Getting the Full Context

async getPullRequestDiff(prNumber) {
    const {stdout} = await execAsync(`gh pr diff ${prNumber}`);
    return { result: stdout };
}

async getConversation(prNumber) {
    const variables = {
        owner      : aiConfig.owner,
        repo       : aiConfig.repo,
        prNumber,
        maxComments: 100
    };

    const data = await GraphqlService.query(GET_CONVERSATION, variables);
    return data.repository.pullRequest;
}

With these two tools, an agent can:

Get the diff - See exactly what code changed
Get the conversation - Read the PR description, all comments, and review history

This gives the agent complete context for making informed review decisions.

3. Participation: Leaving Structured Feedback

async createComment(prNumber, body, agent) {
    const header       = `**Input from ${agent}:**\n\n`;
    const agentIcon    = AGENT_ICONS[this.getAgentType(agent)];
    const headingMatch = body.match(/^(#+\s*)(.*)$/);
    let processedBody;

    if (headingMatch) {
        const headingMarkers = headingMatch[1];
        const headingContent = headingMatch[2];
        processedBody = `${headingMarkers}${agentIcon} ${headingContent}\n${body.substring(headingMatch[0].length)}`;
    } else {
        processedBody = `${agentIcon} ${body}`;
    }

    const finalBody = `${header}${processedBody.split('\n').map(line => `> ${line}`).join('\n')}`;

    const idData    = await GraphqlService.query(GET_PULL_REQUEST_ID, {owner, repo, prNumber});
    const subjectId = idData.repository.pullRequest.id;

    await GraphqlService.query(ADD_COMMENT, { subjectId, body: finalBody });
    return { message: `Successfully created comment on PR #${prNumber}` };
}

This method does something clever: it attributes the comment to the agent with:

A clear header: **Input from Gemini 2.5 Pro:**
An agent-specific icon: ✦ (Gemini), ◊ (Claude), ◯ (GPT)
Blockquote formatting for the entire comment

The result looks like this on GitHub:

Input from Gemini 2.5 Pro:

✦ Code Review Findings

I've analyzed the changes in this PR and found the following:

Line 47: The null check should be moved before the dereference

Line 89: Consider using the existing validateInput() helper

Tests: The edge case for empty arrays is not covered

This clear attribution ensures:

Transparency - Everyone knows this is AI input, not a human reviewer
Accountability - The specific agent (and its version) is recorded
Context - Future agents can query their own review history via the Memory Core

4. Local Testing: Checking Out PRs

async checkoutPullRequest(prNumber) {
    const {stdout} = await execAsync(`gh pr checkout ${prNumber}`);
    return {
        message: `Successfully checked out PR #${prNumber}`, 
        details: stdout.trim()
    };
}

For deeper analysis, an agent can check out the PR branch locally, run the test suite, and verify the changes work as expected before leaving a review.

The Complete Review Workflow

With these tools, the autonomous PR review workflow becomes:

1. Agent: list_pull_requests({state: 'open'})
   → Discovers PR #1234 needs review

2. Agent: get_conversation(1234)
   → Reads PR description and existing comments

3. Agent: get_pull_request_diff(1234)
   → Analyzes the code changes

4. Agent: checkout_pull_request(1234)
   → Checks out the branch locally

5. Agent: Run npm test
   → Verifies tests pass

6. Agent: create_comment(1234, reviewText, 'Gemini 2.5 Pro')
   → Leaves structured review feedback

7. Agent: add_memory({
     prompt: "Review PR #1234",
     thought: "Analyzed the changes, found 2 issues...",
     response: "Left review comment on PR #1234"
   })
   → Records the review in Memory Core for future reference

This workflow removed me as the bottleneck. For the 52 Hacktoberfest PRs, agents could:

Identify common issues (missing tests, style violations)
Request changes or suggest improvements
Approve simple PRs (documentation, typo fixes)
Escalate complex PRs that needed deeper architectural review

I went from reviewing every PR to reviewing only the escalated ones. The agents handled the routine review work,
and I focused on the decisions that truly needed human judgment.

Platform Independence and the Future

The GitHub Workflow Server's local-first architecture isn't just about performance—it's about platform independence.

Every issue and every release note is stored as a markdown file in your repository.
If GitHub is acquired by a company whose AI policies conflict with your project's goals
(it actually got bought by MicroSoft), or if API pricing changes make it untenable, you simply:

Keep working - The local files are your source of truth
Switch platforms - Port the sync logic to GitLab, Gitea, or any other platform
No data loss - Your entire issue history is in git

This is the same philosophy that drives the Knowledge Base server: make the AI's workspace platform-agnostic and version-controlled.

The sync with GitHub is a convenience, not a dependency. If GitHub disappeared tomorrow, your agents would still have:

Full issue history
Complete PR conversations
Semantic search over all tickets
The ability to create and modify issues locally

You'd just need to build a different sync adapter when you were ready to push to a new platform.

What We've Built

The GitHub Workflow Server demonstrates that context engineering extends beyond code. Issues, PRs, and project
management artifacts are part of the context an AI needs to be truly productive.

By representing them as local markdown files that are:

Queryable via semantic search
Modifiable via standard file operations
Synchronized bi-directionally with GitHub
Version controlled in git
Platform independent by design

We've created a system where agents can:

Find relevant historical issues when solving bugs
Review PRs autonomously with full context
Participate in project discussions
Learn from their own review history across sessions

This is what it means to build an AI-native, not AI-assisted platform. The AI isn't just a tool you use—it's a
first-class participant in your development workflow.

And the results speak for themselves: 388 tickets, 52 PRs, zero manual archive organization, and a development velocity
that should be impossible for a one-person core team.

The Neo.mjs Backbone: Powering Our Servers

All three MCP servers are built using the official MCP SDK for protocol compliance,
but their internal architecture is pure Neo.mjs. This isn't just a case of "dogfooding"—using our own framework for the backend provided critical advantages in building a robust, asynchronous, and maintainable server architecture. For example, every service inside the servers—like QueryService in the Knowledge Base or SessionService in the Memory Core—is a Neo.mjs singleton that extends Neo.core.Base.

This demonstrates a key design principle: Neo.mjs isn't just for browsers. The same class system that powers complex
frontend applications also provides robust infrastructure for backend services.

The Power of initAsync() and ready()

One of the most elegant aspects of Neo.mjs for backend development is its asynchronous initialization system.
Every Neo.core.Base instance has an initAsync() lifecycle hook and a ready() promise that resolves when
initialization is complete.

From Neo.core.Base:

construct(config={}) {
    // ... initialization code ...

    // Storing a resolver to execute inside `afterSetIsReady`
    this.#readyPromise = new Promise(resolve => {
        this.#readyResolver = resolve
    });

    // Triggers async logic after the construction chain is done
    Promise.resolve().then(async () => {
        await this.initAsync();
        this.isReady = true
    })
}

/**
 * You can use this method in subclasses to perform asynchronous initialization logic.
 * Make sure to use the parent call `await super.initAsync()` at the beginning.
 * 
 * Once the promise returned by this method is fulfilled, the `isReady` config will be set to `true`.
 * @returns {Promise<void>}
 */
async initAsync() {
    this.remote && this.initRemote()
}

/**
 * Returns a promise that resolves when the instance is fully initialized.
 * @returns {Promise<void>}
 */
ready() {
    return this.#readyPromise;
}

This pattern enables elegant dependency orchestration throughout the server architecture. Here's how SessionService uses it:

async initAsync() {
    await super.initAsync();

    // Wait for DatabaseLifecycleService to ensure ChromaDB is available
    await DatabaseLifecycleService.ready();

    // Use ChromaManager instead of direct client access
    this.memoryCollection   = await ChromaManager.getMemoryCollection();
    this.sessionsCollection = await ChromaManager.getSummaryCollection();

    // Skip if GEMINI_API_KEY is missing
    if (!this.model) return;

    logger.info('[Startup] Checking for unsummarized sessions...');

    const result = await this.summarizeSessions({});
    // ... process results ...
}

The beauty of this pattern is that services can depend on each other without complex coordination logic:

ChromaManager initializes and establishes the ChromaDB connection
DatabaseLifecycleService waits for ChromaManager.ready() and starts ChromaDB
SessionService waits for DatabaseLifecycleService.ready() and performs summarization
mcp-stdio.mjs waits for SessionService.ready() and starts the MCP server

All of this happens automatically and in the correct order, with zero race conditions. From the main entry point:

async function main() {
    // Wait for async services to initialize.
    // SessionService.ready() will internally wait for the DB and summarize sessions.
    await SessionService.ready();

    // Perform initial health check
    const health = await HealthService.healthcheck();

    // Report status and start server
    // ...
}

Singleton Pattern and Service Architecture

All services use the Neo.mjs singleton pattern, which combines class-level state management with instance lifecycle:

class SessionService extends Base {
    static config = {
        className: 'AI.mcp.server.memory-core.services.SessionService',
        singleton: true,
        // Reactive configs with lifecycle hooks
        model_: null,
        embeddingModel_: null
    }

    construct(config) {
        super.construct(config);

        const GEMINI_API_KEY = process.env.GEMINI_API_KEY;
        if (!GEMINI_API_KEY) {
            logger.warn('⚠️  GEMINI_API_KEY not set - skipping summarization');
            HealthService.recordStartupSummarization('skipped', { 
                reason: 'GEMINI_API_KEY not set' 
            });
            return;
        }

        const genAI = new GoogleGenerativeAI(GEMINI_API_KEY);
        this.model = genAI.getGenerativeModel({ model: 'gemini-2.5-flash' });
        this.embeddingModel = genAI.getGenerativeModel({ model: 'text-embedding-004' });
    }
}

export default Neo.setupClass(SessionService);

The singleton: true config ensures:

Only one instance exists throughout the application lifecycle
Global access via the class itself (e.g., SessionService.summarizeSessions())
Automatic registration with the instance manager
Consistent state across all parts of the application

Reactive Configuration System

Neo.mjs brings its powerful reactive config system to Node.js. The system is driven by Neo.setupClass(),
which processes every class definition and applies sophisticated configuration logic.

Configs ending with an underscore (_) are reactive:

static config = {
    model_: null,
    embeddingModel_: null,
    memoryCollection_: null,
    sessionsCollection_: null
}

During setupClass(), Neo.mjs automatically:

Removes the underscore from the static config key
Generates getter and setter for the public property name
Enables optional lifecycle hooks (if you implement them):
- beforeGetModel(value) - Modify value before returning from getter
- beforeSetModel(value, oldValue) - Validate/transform before setting (return undefined to cancel)
- afterSetModel(value, oldValue) - React to changes after they occur

Here's the actual logic from Neo.setupClass():

// Process each config property defined in the current class's static config
Object.entries(cfg).forEach(([key, value]) => {
    const
        isReactive = key.slice(-1) === '_',
        baseKey    = isReactive ? key.slice(0, -1) : key;

    // Handle reactive configs: Generate getters/setters
    if (isReactive) {
        delete cfg[key];      // Remove original key with underscore
        cfg[baseKey] = value; // Use base key without underscore
        Neo.createConfig(element, baseKey) // Generate getter/setter
    }
    // Non-reactive configs get set directly on prototype
    else if (!Neo.hasPropertySetter(element, key)) {
        Object.defineProperty(element, key, {
            enumerable: true, 
            value, 
            writable: true
        })
    }
});

The key insight: Subclasses can provide new default values without the underscore, and they'll still be reactive if
the parent defined them with an underscore. This enables clean configuration hierarchies:

// Parent class
class ChromaManager extends Base {
    static config = {
        client_: null,           // Reactive in parent
        connected_: false,       // Reactive in parent
        memoryCollection_: null  // Reactive in parent
    }
}

// Child can override defaults without underscore
class ExtendedManager extends ChromaManager {
    static config = {
        connected: true  // Still reactive! Inherits from parent
    }
}

Non-reactive configs (without underscore) are applied directly to the class prototype, making them shared across
all instances. This is memory-efficient and enables the powerful Neo.overwrites mechanism for application-wide theming.

#cachedHealth = null;
#lastCheckTime = null;
#cacheDuration = 5 * 60 * 1000;

async healthcheck() {
    const now = Date.now();

    // Smart caching: only cache healthy results
    if (this.#cachedHealth?.status === 'healthy' && this.#lastCheckTime) {
        const age = now - this.#lastCheckTime;
        if (age < this.#cacheDuration) {
            logger.debug(`[HealthService] Using cached health status (age: ${Math.round(age / 1000)}s)`);
            return this.#cachedHealth;
        }
    }

    // Perform fresh check
    const health = await this.#performHealthCheck();

    // Update cache
    this.#cachedHealth = health;
    this.#lastCheckTime = now;

    return health;
}

Observable Pattern for Cross-Service Communication

Services can use the Observable mixin for event-driven architecture:

class DatabaseLifecycleService extends Base {
    static observable = true; // Enables event system

    async startDatabase() {
        // ... start ChromaDB ...

        this.fire('processActive', { 
            pid: this.chromaProcess.pid, 
            managedByService: true 
        });
    }

    async stopDatabase() {
        // ... stop ChromaDB ...

        this.fire('processStopped', { 
            pid, 
            managedByService: true 
        });
    }
}

Other services can listen to these events for coordination without tight coupling.

Why This Matters

The Neo.mjs class system brings several advantages to backend development:

Zero Boilerplate - No need for custom dependency injection frameworks
Declarative Dependencies - Services express their needs via await ready()
Lifecycle Management - initAsync(), construct(), destroy() provide clear hooks
Type Safety - Config validation happens automatically at runtime
Memory Efficiency - Singletons ensure one instance per service
Debugging - Clear initialization order, consistent patterns

This is the same class system that manages complex UI component hierarchies in the browser, now orchestrating ChromaDB
connections, Gemini API calls, and MCP server lifecycles in Node.js.

The Benefits of a Server-Based Approach

This shift to a multi-server architecture brings a host of benefits:

Robustness and Reliability: Servers are more resilient than scripts, with better error handling and a more stable API.
Agent-Agnosticism: Any AI agent that can speak the MCP language can now connect to our development environment.
Self-Hosting: In a powerful demonstration of "dogfooding," the MCP servers themselves are built using the Neo.mjs class system. This showcases the framework's versatility for creating robust, scalable backend and CLI applications.
Simplified Onboarding: The servers now manage their own database startup and session summarization automatically. This drastically simplifies the agent onboarding process, reducing the agent's setup protocol by over 70%.
Self-Documenting Tools: The MCP tools are now self-documenting, allowing agents to dynamically inspect tool capabilities and schemas, making the entire system more resilient and easier to extend.

Agent-Driven Quality: The Final Piece of the Puzzle

A self-aware development environment is only as good as the quality of the code it produces. To that end, we have
completed the migration of our entire unit test suite from the browser-based Siesta to the Node.js-based Playwright runner.

This is a game-changer. For the first time, AI agents can now run npm test to validate their own changes.
This is a critical step toward a fully autonomous, quality-driven development loop and a prerequisite for future CI/CD integration.

A Community-Powered Revolution

This monumental release would not have been possible without the incredible energy and contributions from our community,
especially during Hacktoberfest 2025. We received over 52 pull requests from more than 20 contributors,
a new record for the project.

The event was also a crucial turning point. For years, the Neo.mjs project has had a "bus factor" of one: what happens if its creator, Tobi, stops working on it? Before the new AI-native tooling, the steep learning curve meant that very few external developers could make significant contributions.

Hacktoberfest 2025 shattered that limitation. For the first time, we saw a wave of meaningful contributions from developers who were new to the framework. By pairing up with AI agents using the new MCP servers, contributors could quickly get up to speed, understand complex parts of the codebase, and submit high-quality pull requests.

This was the breakthrough. It proved that context engineering isn't just a theoretical concept—it's a practical solution to the "bus factor" problem. Developers no longer need to spend months learning the framework's intricacies on their own. With an AI partner that has deep contextual knowledge, they can start making an impact in days or even hours.

Our heartfelt thanks go out to everyone who participated, not just for their code, but for helping us prove this vision:
Aki-07, Ayush Kumar, Chisaneme Aloni, Emmanuel Ferdman, Ewelina Bierć, KURO-1125, LemonDrop847, Mahita07, MannXo,
Mariam Saeed, Nallana Hari Krishna, Nitin Mishra, PrakhyaDas, Ritik Mehta, Sanjeev Kumar, Sarthak Jain, ad1tyayadav,
cb-nabeel, kart-u, nikeshadhikari9, srikanth-s2003.

What's Next

The infrastructure we've built is a powerful foundation, but it's just the beginning.

Future Enhancements

If there is community interest, we are considering several major enhancements:

Pull Request Synchronization: While the GitHub Workflow server can already review PRs, the next logical step is to sync their conversations and diffs to local markdown files, just like issues. This would make PR history fully queryable and part of the permanent, offline knowledge base.
AI-Native Workspaces: The ultimate goal is to bring this level of AI support to every Neo.mjs developer. We plan to integrate the MCP server setup directly into the npx neo-app command, allowing any generated workspace to become an AI-native environment out of the box.

Standalone Server Releases?

The Memory Core and GitHub Workflow servers are framework-agnostic. They work with any software project, not just Neo.mjs.

Question for the community: Would standalone npm packages be useful for your projects?

If there's interest, we can release them as e.g.:

npx neo.mjs/memory-core-server
npx neo.mjs/github-workflow-server

Let us know inside the comments or inside the Discord or Slack Channels.

Getting Started Today

Ready to explore the AI-native workflow?

Working with Agents - General guidance
AI Quick Start - First session checklist
Codebase Overview - What agents read at startup
MCP Server Source Code - The full source code for all three MCP servers.
Agent Protocol (AGENTS.md) - The behavioral rules (inside the context window of each session)
Agent Startup (AGENTS_STARTUP.md) - Session initialization

The Future of Context Engineering

Neo.mjs v11 isn't just about new features—it's about a new way of thinking about software development.

We're building a development environment that is truly AI-native: self-aware, self-documenting, and self-improving.

This is Context Engineering—the art and science of building systems that understand their own context and use that
understanding to improve themselves.

We're at the beginning of this journey. The road ahead is long, but the destination is clear:
a future where humans and machines collaborate to build better, faster, and more maintainable software.

Join us. Fork the repository, explore the MCP servers, and start a conversation with our AI-native platform.

The future of development is here, and it's more intelligent than you might imagine.

The webworkers driven UI framework neo.mjs version 2 release announcement

Tobias Uhlig — Sat, 08 May 2021 14:43:53 +0000

Concepts for new products need to be disruptive, otherwise there is little need for them. However, the way to use them should be as consistent as possible.

For a framework this means that the API on how to use it should be rock solid, especially when it comes to new versions. Migrating from neo.mjs v1 to v2 is a piece of cake.

This article assumes that you are not familiar with the project yet, so we will cover some of the basics as well.

Content

Eye candy
Design Goals
What is new in version 2?
Statistics
How can I set up my first neo.mjs app?
How to migrate from v1 to v2?
How difficult is it to learn neo.mjs?
When should i use neo.mjs?
What is a config system?
Roadmap
Final thoughts
Special thanks to

1. Eye candy

Let us take a look into use cases which would be difficult to achieve without using neo.mjs:

This is a single page app expanded into multiple browser windows. The app can communicate without the need for a backend.

Desktop browser mandatory, best in Chrome or Edge, runs in Firefox too: neo.mjs/dist/production/apps/sharedcovid/

To get an impression on the performance, try the helix: using a magic mouse or trackpad you can scroll horizontally.

This results in > 30.000 dom manipulations per second locally. The helix is intentionally built to stress out the browser → each item is a dom node (no canvas, svg, webGL).

What basically happens on drop is:

dialog.unmount();
dialog.appName = 'SharedDialog2'; // name of the other window app
dialog.mount();

Yes, we are re-using the same dialog JS instance.

Web-Based Multi-Screen Apps Including Drag & Drop | by Tobias Uhlig | Geek Culture | Mar, 2021 | Medium

Tobias Uhlig ・ Apr 1, 2021 ・
Medium

We can easily lazy-load complex dependencies into the application worker.

This also works in dist/production. Even better, we do get split chunks across different apps. Meaning: you can add multiple apps on the same page with very little overhead.

Cross-App Bundling — A Different Approach for Micro Frontends | by Tobias Uhlig | The Startup | Medium

Tobias Uhlig ・ Sep 9, 2020 ・
Medium

2. Design Goals

The neo.mjs concepts are disruptive:

Multithreading: most parts of the framework as well as your own application code run inside the app worker. This leaves the main thread mostly idle, leading to an amazing rendering performance, especially when dynamically manipulating the DOM.
Extensibility and Scalability: You can extend and change pretty much anything. You will only get the code you actually use. You can lazy load modules and even get cross app split chunks.
Build on web standards: neo.mjs uses the latest ECMAScript x features as soon as they are available in all major browsers.
“Bring UI development back into the browser”
neo.mjs is one of the very few projects where UI development does not happen inside node and you don’t need any builds or transpilations when changing your code. The development mode can run the framework and your application code as it is directly inside the browser. Right now still limited to Chromium, since Safari (getting close) and Firefox do not support using JS modules inside the worker scope yet. Debugging the real code has saved me a lot of time already.
dist/production (webpack based) has to run in all major browsers.
Persistent json based virtual dom structures. There are no templates at all. You define your component trees in a json based format as well. The JS side is in charge. You can control if you want to destroy instances or if you want to keep them for later re-use.
Using the virtual dom engine is optional, you can manually construct delta updates in case you exactly know what should change to further push the performance.
You get documentation views for your own app code inside the neo.mjs docs app out of the box

3. What is new in version 2?

The neo.mjs v2 release is mostly about providing you with new ways for making the state management of your apps easier, as well as enhancing your frontend architectures.

I created two separate articles to cover the view model implementation in detail:

Enhance your frontend state management with view models | by Tobias Uhlig | Apr, 2021 | ITNEXT

Tobias Uhlig ・ Apr 22, 2021 ・
itnext.io

Cross browser window state management | by Tobias Uhlig | Apr, 2021 | ITNEXT

Tobias Uhlig ・ Apr 26, 2021 ・
itnext.io

Lazy loading for card layout items and tabs → neo.mjs v2.0.10 | by Tobias Uhlig | Apr, 2021 | ITNEXT

Tobias Uhlig ・ Apr 29, 2021 ・
itnext.io

The way to use view models got improved from string based binding formatters to functions containing template literals.

As one of the first breaking changes I used the chance to finally wrap up the long overdue version 2 release.

View models become incredibly powerful for multi window apps, since you can point the parent model of your MainContainer in one app (window) to a view model inside a different app (window). This is an extremely beautiful way to make data accessible across browser windows.

Do not use view models or view controllers for creating custom components, even in case they are complex and use multiple views (like a calendar or table implementation).

The way view controllers internally work has changed for v2. Before, only components who have an own controller triggered parseConfig() and they parsed their items downwards until they found one which had an own controller. In v2 every component will trigger parseConfig() on the closest controller inside the parent tree and only the top level does get parsed. Advantage: you can now dynamically add new components containing string based listeners.

I am constantly trying to keep the project dependencies (npm packages) up to date. Now with the node v16 release out there, a couple of things needed to change.

neo.mjs was still using node-sass (libsass) since a c based compiler sounded charming. dart-sass got renamed to sass and has become the official standard:
Install Sass

good news: the switch worked extremely smooth and we can continue to use the latest scss features.

node-sass as well as the webpack-dev-server had dependencies for a package called “fibers”. This one can no longer work in node v16+.

Switching to

'webpack-dev-server': '4.0.0-beta.2'

removed the last “fibers” dependency, so we should be good for now.

4. Statistics

Out of curiosity I checked the amount of commits a couple of days ago:

neomjs/neo 5196
neomjs/* 6347
pre GA 3720

So, in total the neo.mjs ecosystem is at 10.067 commits.

sloc apps Physical 17133, Source: 11054
sloc buildScripts Physical 2036, Source: 1709
sloc examples Physical 11005, Source: 8805
sloc resources/scss Physical 6697, Source: 5842
sloc src Physical 42032, Source: 22393

Just to get an impression.

5. How can I set up my first neo.mjs app?

The neo.mjs command line interface got you covered:

Open your terminal (or cmd).
Enter a folder where you want to store your project
(I only used Desktop for this demo)
Enter “npx neo-app”
You can hit enter on all questions
Open the new generated workspace folder in an IDE
Optional: deploy it to a repository (e.g. GitHub)
Open the MainContainer.mjs file
Change code
Reload the browser window (the dev mode does not require any builds)

More infos here:
neomjs/create-app

In case npx neo-app does not work inside your local environment, the default output is stored here:
neomjs/workspace

Option 2:

You can fork the neomjs/neo repository. The package.json contains a “create-app” program, which will create a new app shell inside the apps folder of the framework.

This approach is especially useful in case you want to work on your app code as well as the framework code at the same time.

6. How to migrate from v1 to v2?

I still remember migrating a client project from Sencha ExtJS version 2 to 3. It was a super intense sprint and took 6 full weeks. I did not have to deal with Angular migrations on my own, but heard many stories that it was close to a rewrite for early versions.

Rich Waters and I kept this in mind when designing the neo.mjs API.

Migrating from v1 to v2 can be done in 10 minutes.

In case your app is on v1.5+, simply run npm update and the build-all program.

For earlier versions, there are 2 strategies:

The first one (recommended) is to run npx neo-app with the same app name. you can then replace the content of the app folder with your old app folder, run build-all and you are done.

The other strategy is to run npx neo-app and manually adjust the content of your old app shell. In detail: delete the node_modules, dist and docs folders. Manually copy the new docs folder of the npx output over. adjust the neo.mjs version inside your package.json (e.g. ^2.0.4). run npm install. run build-all .

make sure your app.mjs file is using the following format:

import MainContainer from './view/MainContainer.mjs';

const onStart = () => Neo.app({
    mainView: MainContainer,
    name    : 'MyApp'
});

export {onStart as onStart};

7. How difficult is it to learn neo.mjs?

I spent quite some time getting friends and former colleagues up to speed.

The feedback I got in general was that getting to the point where you “get flying” takes a bit longer compared to other libraries / frameworks. Depending on your skill level, it could take a week or two.

However, I also got the feedback that once you get to this point, neo.mjs is way easier to master and you can do more.

For v1 we have a tutorial series on how to create the covid demo app (2 parts). It could be helpful to rewrite them for v2. This is a lot of work on my end, so please give me a ping in case you need it:
Rewrite 'How to create a webworkers driven multithreading App - Part 1' · Issue #1817 · neomjs/neo

Every single developer so far asked me:
“Tobi, window and window.document are undefined, what is happening?”

Yes, your app code does really run inside a web worker.
Web Workers API

“There are some exceptions: for example, you can’t directly manipulate the DOM from inside a worker, or use some default methods and properties of the window object.”

The German language has the wonderful word “Kindersicherung”.
Meaning: “Mechanics to prevent children from hurting themselves”

In a way, this applies for Javascript devs and the real dom.

For most use cases, you really don’t need it and you can stick to working with the virtual dom.

Your benefits of working with JSON based virtual DOM | by Tobias Uhlig | DataSeries | Medium

Tobias Uhlig ・ Aug 7, 2020 ・
Medium

What really helps is to look into your generated app files:

The index file will not include your app files, but the main thread starting point (this one will create the worker setup). In dist/production, the main thread file is only 42KB.

Once the setup is ready, the application worker will import your app.mjs file for which you specified the appPath .

You can create multiple apps here if you like to and render them into different div nodes of an already existing page.

The application worker will consume all app.mjs files it can find as dynamic imports. This is how we get the cross app split chunks.

I recently got the question: “I would like to add a loading spinner directly into my index.html file and use my neo.mjs app to remove it once the MainView renders. It is outside of our virtual dom. Can I do it?”

Neo.currentWorker.sendMessage('main', {
    action: 'updateDom',
    appName: this.appName,
    deltas: {
        action: 'removeNode',
        id    : 'my-loading-spinner'
    }
});

You can manually create delta updates and send them to main. You can use promiseMessage() in case you want to do something once this async operation is done. Use it with care!

You can also create your own main thread addons, e.g. for working with other libraries. Examples:

src/main/addon

As mentioned at the bottom of the repo readme:
You are welcome to join the neo.mjs Slack Channel!

Although my time is limited, I will try my best to point you into the right direction.

8. When should i use neo.mjs?

One of my famous quotes is:
“You don’t need a sports car for driving to the supermarket.”

For rather simple and mostly static websites or apps, neo.mjs might not be a good fit.

The bigger and more complex your apps get, the more value can using this framework generate for you.

This also applies for creating complex (custom) components, like a helix, buffered grid, calendar.

A good use case would for example be a banking / trading app where you want to use web sockets to hammer the dom with realtime updates.

In case you want to create multi window apps based on SharedWorkers, the benefits of using neo.mjs are huge and unique.

Although the framework is still focussing on desktop apps, the general setup can really shine for mobile too. There is more work to be done (see: 10. Roadmap).

9. What is a config system?

A question which frequently pops up is:

“Why is there a static getConfig() method?
Are configs the same thing as class fields?”

Let us take a quick look into the following example:

className actually could be a class field, since the value does not change. It also could be static. The reason it is not static is for debugging purposes: In case you log a component tree into the console and click through the items, it is extremely helpful to see the classNameto know what you are dealing with.

What is the benefit of a config system?

In case we define a config with a trailing underscore, like here a_ , we can optionally use beforeGetA() , beforeSetA() and afterSetA() . Obviously the same applies for b_ .

We define a & b as null values for simplicity reasons. We are using this.down() inside both afterSet() methods which is not available before items got constructed.

So, to keep the logic short, I am using onConstructed() to call:

this.set({
    a: 5,
    b: 5
});

afterSetA() will set the text config for label1 to value + this.b .

afterSetB() will set the text config for label2 to value + this.a .

→ We are dealing with a cross dependency

Let us assume we had defined a & b via get() and set() and we would call the custom afterSet() methods inside the real setters.

Object.assign(this, {
    a: 5,
    b: 5
});

In this case, a would get assigned first, the afterSet() call would set the label1 text to 5 (5+null).

Then b would get assigned and the afterSet() call would set the label2 text to 10 (5+5).

The difference with using this.set() is, that we can access both new values right away. this.a as well as this.b are pretty smart getters.

label1 and label2 will both get 10 (5+5) as their text.

A click on the button will trigger:

this.set({
    a: 10,
    b: 10
});

Afterwards both label texts have the value 20 (10+10).

Try it: dist/production/examples/core/config/index.html (Online Demo)

Config values do get stored with a leading underscore. In case you want to do a silent update (not triggering beforeSet() and afterSet()), you can e.g. use this._a = 7 .

The second benefit is that component.Base extends the logic of this.set()

myButton.set({
    iconCls: 'fas fa-globe',
    text   : 'Hello world!'
});

afterSetIconCls() as well as afterSetText() getting executed on their own trigger a re-rendering (passing the vdom object to the vdom worker to check for delta updates).

In case you change both configs using this.set() , there will be just 1 check for delta updates.

The third benefit of a config system applies when we extend classes.

A tab.Container is using an activeIndex_ config. You can use:

class MyTabContainer extends TabContainer {
    static getConfig() {return {
        //...
        activeIndex: 2
    }}
}

This will not override the get() and set() logic, but assign the new value on instantiation.

A little bit outdated, but here is more input:

Javascript classes: state management v2 | by Tobias Uhlig | codeburst

Tobias Uhlig ・ Mar 11, 2020 ・
codeburst.io

10. Roadmap

I am happy about how far the project has grown already.

However, the list of things I would love to add is even bigger.

Now that v2 is released, it feels important to structure the priority of the next items / sprints. You have the chance to make an impact!

Meaning: In case there are specific items you would love to see, add a comment to the related feature request:
https://github.com/neomjs/neo/issues

No ticket there yet? Create one! As simple as this.

I personally think it is best to further polish the desktop side of things, since the majority of big and complex apps is still here. Once this is done, we can focus on mobile. This is not set in stone though.

Again: The following list of items is not ordered.

Theme build: the CSS output is still a monolith, which does not honor the really impressive split chunks on the Javascript side of things. I would love to break down the output on a per file basis. To do this, we need a dependency tree of used app & framework components. Ideally similar to the JS split chunks, so that we can lazy load tiny css files as needed. Epic.

Theming: not all sizes are em based yet. We need to adjust the remaining px values.

Buffered grid: while the table implementation is neat, including locked columns and sticky headers, it is not really sufficient for “big data”. Only rendering the rows you see (plus one) can make a big impact. Epic.

Grid editing: “records” are a super lightweight extension of JS objects to get change events. In case you change values of a record, a table view will already update. A cell editor for the table view & buffered grid would be sweet.

Calendar: the current state is still “sneak preview”. it is super impressive since the demo does remove non active views from the real dom, while we can still alter their state and re-use the same JS instances.

More complex examples for view models: so far, all demo apps work without view models. it can be helpful to have one big demo app using them.

core.Observable: The framework is still using an early and never finished version. It is sufficient for adding listeners and firing events, but it does not honor the current state of the framework. Epic.

MessageBus (PubSub): As an alternative for view models, it would be nice to have an additional way to communicate. I probably won’t find the time to evolve it as far as MobX.

Data worker: Rich had the concept, that stores should live within this thread. The idea was that ajax calls / socket connections happen from here, then local filtering & sorting happens here as well (to remove weight from the app worker) and only send the needed data to the app worker. It is more complicated: for stores containing little data the concept makes no sense, so we need to polish the concept. Epic.

Socket connections: We still need an implementation for it.

View models v3: we have a discussion to support “2 way bindings”. Imo only relevant for form fields and it could remove some boiler plate code. To do this, config setters need to fire a change event (or use a MessageBus) to let vms know about changes. Tricky one, since we need to be careful not to create a massive amount of change events which have no receivers.

Support for public class fields: once they are stage4 and work inside webpack (acorn parser) based builds, I would love to add them. breaking change → neo.mjs v3. Epic.

Enhancing form field components: definitely room for improvement here. Epic.

Slider component & slider field: now with a beautiful drag&drop implementation in place, it would be nice to add it.

Color picker field: needs the slider component.

Mobile: we need to enhance components for mobile usage and or create new ones. We need more examples as well. Epic++

More examples for lazy loading: with the cross app split chunks in place, we should either refactor the covid or the real world app to start with an empty viewport and lazy load modules as needed. Epic.

Virtual dom worker v2: more precisely vdom.Helper v2. The results for delta updates are truly impressive. However, the delta update algorithm contains a couple too many tree structure generations and can get improved. Epic.

Docs app v2: we still need to enable lazy loading example apps in dist/prod. there are many aspects on this one that could get enhanced. Epic++.

Website app v2: Since more and more examples get into the framework, the example lists are no longer sufficient. The website app could use a re-design in general, but my capabilities as a designer are limited.

GitHub Pages: At some point I would love to change the logic entirely. Right now we fetch the neo.mjs repo and show examples and apps inside of it. It would be nicer to pull the content of repos inside neomjs/* on their own and deploy them with their own neo.mjs version. Then we can move more examples & demo apps out of the framework “core” repo. Epic++.

More tests: I am waiting for the next major release of Bryntum’s Siesta. Once more contributors join the project, it will be more and more important to have more user interaction tests in place. Not real “unit tests”, but rather loading example apps and simulate users to verify that the business logic does not break when changing code. Epic++.

This list is not complete, but I make a cut here. Not even mentioning long term goals like creating a middleware running the neo core (this one would be amazing). In case you are a Javascript expert you most likely have an idea, about the size of this scope in “hours” → months, years.

While I can work on each item one by one on my own, more contributors could really make an impact here.

Don’t forget that I still need to polish parts of the core, write blog posts and that it is impossible to put my full time into the project (more about this in the next section).

11. Final thoughts

Even in case you consider yourself to be an expert in Javascript, you can most likely learn a lot in case you take a deep dive into the neo.mjs code base. I would say you can reach an entirely new level and “get flying”.
neomjs/neo

You can find all online examples, a blog section and the docs here:
https://neomjs.github.io/pages/

I am definitely one of those guys who thinks “code speaks for itself” and prefer to convince others with actions rather than words.

However, I got the feedback: “People love people, not products.”

I have to admit that there is wisdom and truth inside this quote.

In case you want to learn more about me, feel free to take a look at my LinkedIn profile.

In short: I was an expert when it came to Sencha ExtJS back in the days. After working on client projects, I did join the Sencha Professional Services Team for 2.5 years. It was an amazing time! Since the team was limited to around 8 guys, I was literally flying around the globe all the time to help out on client projects which were completely on fire (fixing framework and app related issues in parallel). The hourly rates were extremely high, so the level of expectation on the clients side was challenging as well. I enjoyed my “cash cow” role and am thankful for the opportunity to dive into a lot of client projects. This helped me a lot with developing a feeling on what the industry actually needs when it comes to UI development.

Afterwards I helped the PlayStation Team for more than 4 years on a massive project from the early inception phase up to the release. My role involved taking care of the client side architecture as well as implementing challenging parts.

This enabled me to save some money which I literally completely burned with getting the neo.mjs project to the point where it is now.

Open source is still considered “charity”, which is a problem.

Companies (especially here in Germany) are very hesitant to even touch new technology, no matter how good it is. I am not even mentioning sponsorships or official Government programs.

The neo.mjs business model is Business as a Service (BaaS), meaning the entire code base is free to use (MIT licensed). In case your company does require help regarding support or need to get some neo.mjs experts involved for e.g. setting up a prototype app you are welcome to get in touch.

I would deeply enjoy pushing the framework full time to generate even more value for you, but this is simply impossible as long as the project is not on a sustainable level.

Best regards & happy coding,
Tobias

12. Special thanks to

Rich Waters, the other co-founder of the project. I am still sad that Rich literally vanished out of existence and have not heard from him in years.

Durlabh Jain for being the first and still only sponsor of the project!

Gerard Horan, my former PlayStation mentor, Pat Sheridan (Modus Create), as well as Hyle Campbell (my former team leader at Sencha). Without you keeping an eye on the project and your morale support, I would have given up already a long time ago!

Also a big “Thank you!” to many friends & previous co-workers from the former Sencha Community! Too many to list them all, but I hope you know I meant you when you read this :)

Expanding Single Page Apps into multiple Browser Windows

Tobias Uhlig — Fri, 19 Jun 2020 18:50:59 +0000

Content

Introduction
Scalable frontend architectures
More background infos
Benefits of the Shared App Worker
How can DOM events still work?
How do the Apps inside the Shared Covid App look like?
How can we position Popup Windows to exactly overlay an existing Component?
What are the use cases for the Shared Workers setup?
Webpack based dist versions?
What about Webkit / Safari?
Online Demo
What is coming next?
Would you like a tutorial on how to transform the Covid App into the new Shared Covid App version?
Close to the end game? 15.Final thoughts

1. Introduction

For me, it was alway a big dream, if not a life time goal, to create a meaningful Open Source project, with the potential to make a significant impact to improve the way how UI development works in general. This is it. I am very excited to not only share this article with you, but the entire code base as well (using the MIT license).

Before diving into the topic of scalable frontend architectures, please watch this 95s video first:

2. Scalable frontend architectures

In a nut shell:

In case you are working inside the UI development area, the first picture should look familiar. Everything happens inside the main thread (Browser Window). This is actually a performance problem. A big one. By default, each Browser Window is just using 1 CPU / Core, while close to every computer or mobile device has more than one available. The worst case which can happen is that one CPU is running at 100% => freezing your UI, while other CPUs are idle. Even framework background tasks, like internal garbage collection, can already mess up your beautiful CSS animations and it is hard for developers to figure out what is happening. Some project started moving isolated expensive tasks into a separate thread. Sorry, this is not enough!
The default neo.mjs setup for Single Page Apps (SPAs) started with the concept to move out everything that is possible from the Main Thread, so that this one is mostly idle and can fully concentrate on its primal purpose: manipulating the DOM. A tiny part (37KB) of the neo.mjs is running inside the Main Thread: the logic to create the workers, applying delta updates on the real DOM & delegating virtualised UI events to the App Worker. There are no background tasks here. Optional Main Thread addons can get dynamically imported as needed. Since this concept put a lot of weight on the App Worker, the VDom & Data Workers were added. Of course you can connect to your backend from the App worker as well.
The neo.mjs setup was designed right from the start keeping the Shared Workers setup in mind. From an architecture perspective, this is close to the end game. We can now optionally replace the Workers with Shared Workers, which allows us to connect multiple Main Threads (Browser Windows) to the Shared App Worker. This way our Apps can directly communicate (not even needing postMessages to do so), but it goes way beyond this, as you have seen inside the video.

3. More background infos

The last 2 articles are worth a look:

Chrome v83 enables JS module support for SharedWorkers → Starting a new era for multi Browser Window Apps with neo.mjs | by Tobias Uhlig | The Startup | Medium

Tobias Uhlig ・ Jun 4, 2020 ・
Medium

neo.mjs v1.2.5 → Support for SharedWorkers including Firefox | by Tobias Uhlig | The Startup | Medium

Tobias Uhlig ・ Jun 6, 2020 ・
Medium

4. Benefits of the Shared App Worker

Of course you only need to load a framework once for all connected Browser Windows.

It might sound trivial, but the biggest benefit is probably that the App Worker is using just one IdGenerator. Meaning: all Components for all of your Apps have unique IDs.
The VDom worker is using just one IdGenerator as well, which ensures that all DOM nodes for all Apps have unique IDs as well.

The combination of both makes it super easy to move Components or entire Component Trees around different Browser Windows. Even better: we can just move the virtual DOM around while keeping & re-using the same Javascript instances.

Example:

https://github.com/neomjs/neo/blob/dev/apps/sharedcovid/view/MainContainerController.mjs#L410

We are just removing a view from a parent view inside one Browser Window and adding it to another view of an App running inside a different Browser Window. As simple as this.

5. How can DOM events still work?

DOM events were de-coupled right from the start, since their handlers live inside the Shared App Worker. This is also the case for the non version.
To not pollute the DOM, neo.mjs is sticking to global event listeners. E.g. there is just 1 click listener on the document body node.
Workers can not access the DOM, but it is also not possible to send anything which is DOM related to a Worker. E.g. DOM events contain a target DOM element. Even simple things like a DOM Rect can not get passed. This is why DOM events get virtualised (converted into JSON).
When a DOM event arrives inside the App Worker, the Component Manager will map it to all Components inside the Component Tree upwards.

Now inside the Shared App Worker, there is just 1 Component Manager which contains references to all Components of all Apps inside all connected Windows.

This is the reason why this one works out of the box.

6. How do the Apps inside the Shared Covid App look like?

This demo App is very similar to the non shared Covid App.

All views & controllers are inside the main App:

https://github.com/neomjs/neo/tree/dev/apps/sharedcovid

I created new Apps (entry points) for each Popup Window. These Apps are as minimal as I can think of:

=> an empty Viewport. Not even an own Controller.

We are just adding Component Trees from the Main App into the empty Viewports and their original Component Controllers can handle it.

Of course this is just one way to use the setup. You could create 2 or more advanced Apps which can communicate directly. The setup is completely flexible to enable you to build what fits best for your use case(s).

7. How can we position Popup Windows to exactly overlay an existing Component?

This part was actually a bit tricky. There is a Chromium bug which can mess with the positioning in case your Main Window is not on your Main Screen.

To save you from this pain point:

https://github.com/neomjs/neo/blob/dev/apps/sharedcovid/view/MainContainerController.mjs#L209

This “hack” worked extremely well for me.

8. What are the use cases for the Shared Workers setup?

The obvious use case are Apps which are supposed to run on multiple Screens.

A Trading App would be a very good example.

There is a lot more though:

In case you want to create Native Apps which contain multiple Browser Windows. Think about developing an IDE. Or something like Firefox OS. You could manage Chromebooks.

On mobile: A Native Shell containing multiple WebViews. You don’t see it as a user, but many Apps already overlay multiple “Browsers” for performance reasons.

Be creative!

9. Webpack based dist versions?

In case you read my last article, you most likely noticed that the first demo App using Shared Workers was running inside Firefox as well.

The reason is, that only one Main Thread was connected.
So far the build processes for the App realm were always a combination of the App worker and your Apps.

Now, when we want to connect multiple Main Threads, we need a separate build for the App worker and your Apps.

I think webpack is not yet designed to handle separate builds which are supposed to play along inside the same realm.
I created the following ticket:

https://github.com/webpack/webpack/issues/11049

I could really use your help on this one!

10. What about Webkit / Safari?

I have some very good news for you on this one :)

The Webkit team is now willing to reconsider adding support for Shared Workers. They are looking for more input and feedback before doing it. So, in case you care about it, please take a moment and add a comment on their ticket:

https://bugs.webkit.org/show_bug.cgi?id=149850

At the same time, they put the ticket to support JS modules inside the worker scope into “inRadar”. In case you would like to use the neo.mjs dev mode directly in Safari as well, please write a comment there as well:

https://bugs.webkit.org/show_bug.cgi?id=164860

11. Online Demo

Please keep in mind that as long as the build processes are not getting enhanced, this one is limited to Chrome v83+. It does not work on mobile devices yet.

There you go. Enjoy!

https://neomjs.github.io/pages/node_modules/neo.mjs/apps/sharedcovid/index.html#mainview=table

As usual, you can find all other neo.mjs online examples here:

https://neomjs.github.io/pages/

12. What is coming next?

I want to finish the Tutorial Part 2 on how to create the Covid App next, to give you a better chance to get up to speed.

One epic item is to support dynamic imports for the app realm. While this works out of the box for the development mode, it will be a lot of work to make this happen inside the webpack based dist env. Think about split-chunks. This one is tied to the webpack ticket (Section 9 in this article).

The main repo readme needs an update (rewrite).

At this point the neo.mjs project is in need of a real website => the online demo page is no longer sufficient.

13. Would you like a tutorial on how to transform the Covid App into the new Shared Covid App version?

After Part 2 of the tutorial is done, I could create a Part 3 to show you the steps in detail.

I already created a ticket for this one here:

https://github.com/neomjs/neo/issues/747

This one will be a lot of work on my end, so I will only do it in case there are at least 20 comments to show that you are interested in this one. A simple “+1” is enough.

Sounds fair?

14. Close to the end game?

Since I did mention this inside Section 2.3 you might be interested in knowing what else we could do to further enhance it.

I want to add 2 more changes:

Make the Data Worker optional
Make the VDom Worker optional

For “simple” Apps it might make sense to just import the logic of these 2 Workers into the App realm.

We could also create an option to spawn multiple versions of the VDom Worker, in case this one becomes a bottle neck. E.g. 2 Vdom Workers, one using odd and the second using even IDs. Easy, right?

Workers don’t have access to the DOM, but they can access Canvas directly. In case we want to work on the Charting side of things, we could create another Worker to handle this part.

15. Final thoughts

I hope that at this point you got an idea about the scope of neo.mjs as well as the potential moving forward. For me the current enhancement to enable SPAs running inside multiple Browser Windows is not only impressive, but mind blowing.

neo.mjs is an Open Source project (the entire code base as well as all examples are using the MIT license).

neomjs / neo

Create blazing fast multithreaded Web Apps

Welcome to neo.mjs!

neo.mjs enables you to create scalable & high performant Apps using more than just one CPU without the need to take care of a workers setup or the cross channel communication on your own.

Version 2 release announcement

Content

Sponsors
Scalable frontend architectures
Multi Window COVID19 IN NUMBERS Demo App
COVID19 IN NUMBERS Demo App
What if ... (Short overview of the concept & design goals)
Want to learn more?
Impossible? Pick with caution!
Online Examples
Online Docs
Command-Line Interface
Ready to get started?
Project History
Story & Vision
neo.mjs is in need of more contributors!
neo.mjs is in need of more sponsors!
Slack Channel for questions & feedback

Scalable frontend architectures

Multi Browser Window COVID19 IN NUMBERS Demo App

The most compelling way to introduce a new framework might simply be to show what you can do with it.

Blog post: Expanding Single…

View on GitHub

Meaning: you can use it for free.

It will stay like this.

However, the project is in need for more contributors as well as sponsors.

A lot(!) more items & ideas are on the roadmap.

If you want to contribute to a lovely Open Source project, this would be highly appreciated.

In case the project has or will have business value for your company: signing up as a sponsor can allow me to put more time into it, resulting in a faster delivery time for new things.

Famous last words: Isn’t the SW architecture the hell of a way to implement Application Dialogs?

Your feedback on this article and scalable frontend architectures in general would mean a lot to me!

Best regards & happy coding,
Tobias

Multithreading Dashboard App pushing the capabilities of Webapps to new limits

Tobias Uhlig — Sun, 19 Apr 2020 18:28:49 +0000

https://www.youtube.com/watch?v=8lqNVaoGNdU

source: https://github.com/neomjs/neo/tree/dev/apps/covid

fully MIT licensed => build something shiny on top of it :)

Introduction Guide for neo.mjs — The webworkers driven UI framework

Tobias Uhlig — Fri, 27 Mar 2020 08:50:29 +0000

neo.mjs concepts

This Concepts / Introduction guide is intended for new users who have read the "buzz-word" table on the
Main Readme File and would like to learn more before following the
Getting Started Guide.

Content

Worker Setup
No Javascript Builds (Development Mode)
No string based pseudo XML templates
JSON based virtual DOM
JSON based Component Trees
Combining Component and VDOM Trees
What to do next?

Worker Setup

The framework is using 4 threads by default:

top (Main): Creating the workers, manipulating the real DOM, forwarding UI events to App
App: Most parts of the framework & your apps live here
Data: Responsible for the BE connections
Vdom: Converting the virtual DOM into HTML, as well as calculating delta updates

The best way to get a feeling for workers is using the Google Chrome Dev Tools (Console).

In case you open the neo.mjs Docs App
(or any other neo.mjs app), you will get a dropdown menu where you can pick the console scope:

The default scope (top) will show the (console) logs inside all threads.

Most parts of the neo.mjs framework as well as the apps which you create will run within the App thread.

Hint: Type Neo and hit return inside the default view (top). You will see the parts of Neo which are used inside the main
thread. Neo.component won't exist here. Now use the dropdown and switch into the App thread. Type Neo and hit return again.
Now you will see a completely different version of the Neo namespace object. Neo.component will exist here and you can
use methods like Neo.getComponent('myId') directly.

What is the reason to use multiple threads?

As you know, (almost) all computers and mobile devices have several cores / CPUs.
By default, browsers will only use one of them.
This means that in case a lot is going on inside your App UI one CPU could go up to 100%, your animations get laggy or
your UI might even freeze, while the other CPUs are idle.
To ensure this does not happen you want to keep the Main thread as idle as possible.

To quote the neo.mjs Story:

In case you take a look at the web workers page on Wikipedia,
you will find the following quote:

"The simplest use of workers is for performing a computationally expensive
task without interrupting the user interface."

At this point, all other web-based UI frameworks are still struggling with performance,
especially in case you are building big apps. There are many hidden background tasks running
which can slow down your beautiful animations or even worse: single threaded applications can have memory
leaks resulting in browser-freezes after using them for a while (either the one and only core which is used
runs at 100% or the memory usage gets too extreme).

Looking back at the Wikipedia quote, Rich Waters & I came to the conclusion that the most expensive tasks are
the framework & the apps itself.

So we asked ourselves the question:

"What if a framework & all the apps you build would run inside a separate thread?"

With this idea, the neo.mjs project was born.

Summary: Since the Main thread is as idle as possible, it is close to impossible that your UI will get laggy
or even freezes. In case a lot is going on on the Javascript side of things, the worst that could happen is that
the App thread runs at 100% which will not affect the Main thread.

No Javascript Builds (Development Mode)

This probably sounds really old school (pre ES6+ times) at first:

You edit a JS source file, refresh the page and you get your changes right away.
No build process(es), no hot module replacements or whatever.

Design Goal: No transpiled Javascript Code, at least for the Development Mode.

As an example, let's take a quick look at the Gallery inside the Real World App version 2 (early stage, in progress).
This is (the start of) the Gallery source code:

import {default as ClassSystemUtil} from '../util/ClassSystem.mjs';
import {default as Collection}      from '../collection/Base.mjs'
import {default as Component}       from './Base.mjs';
import GalleryModel                 from '../selection/GalleryModel.mjs';
import NeoArray                     from '../util/Array.mjs';
import Store                        from '../data/Store.mjs';

/**
 * @class Neo.component.Gallery
 * @extends Neo.component.Base
 */
class Gallery extends Component {
    static getConfig() {return {
        /**
         * @member {String} className='Neo.component.Gallery'
         * @private
         */
        className: 'Neo.component.Gallery',
        /**
         * @member {String} ntype='gallery'
         * @private
         */
        ntype: 'gallery',
        /**
         * The amount of visible rows inside the gallery
         * @member {Number} amountRows_=3
         */
        amountRows_: 3,
        /**
         * The background color of the gallery container
         * @member {String} backgroundColor_='#000000'
         */
        backgroundColor_: '#000000',
        /**
         * @member {String[]} cls=['neo-gallery', 'page', 'view']
         */
        cls: ['neo-gallery', 'page', 'view'],
        /**
         * True disables selection of  gallery items
         * @member {Boolean} disableSelection=false
         */
        disableSelection: false,
        /**
         * The image height of the gallery
         * @member {Number} imageHeight=160
         */
        imageHeight: 160,
        /**
         * The image width of the gallery
         * @member {Number} imageWidth=120
         */
        imageWidth: 120,
        /**
         * @member {Object} itemTpl_
         */
        itemTpl_: {
            cls     : ['neo-gallery-item', 'image-wrap', 'view', 'neo-transition-1000'],
            tabIndex: '-1',
            cn: [{
                tag  : 'img',
                cls  : [],
                style: {}
            }]
        },
        /**
         * The unique record field containing the id.
         * @member {String} keyProperty='id'
         */
        keyProperty: 'id',
        /**
         * Additional used keys for the selection model
         * @member {Object} keys
         */
        keys: {},
        /**
         * The max amount of store items to show
         * @member {Number} maxItems_=300
         */
        maxItems_: 300,

Full component.Gallery Source Code

Now let us take a look at the source code inside the browser:

Expand the image and take a close look at the Chrome Dev Tools:

The source code is 1:1 the same
If you look at the left console tab (Page), you will see the 4 threads again. The Gallery code is inside the App thread.

Summary: The design goal to not transpile Javascript code (at least inside the development mode for now),
has several pros & cons. neo.mjs is the first UI framework to use JS modules inside workers,
which just got enabled in Google Chrome v80+.

Pros:

You get an unmatched debugging experience, since you can debug the real code (no source-maps needed, no webpack interferences etc.)
Browsers can cache JS modules and native packaging is in development
Your code base is modular

Cons:

neo.mjs is not using TypeScript (you could do it for your own app code, in case you want to use a build process)
Firefox & Safari do not support JS modules inside workers yet, so the development mode only runs in Chrome v80+. Of course the dist (dev&prod) versions do run fine in FF & Safari as well.
Several npm dependencies can not easily get used, since they do not use a correct ES6 import syntax (e.g. missing file names)

No string based pseudo XML templates

One example from the React Website:

  render() {
    return (
      <div>
        <h3>TODO</h3>
        <TodoList items={this.state.items} />
        <form onSubmit={this.handleSubmit}>
          <label htmlFor="new-todo">
            What needs to be done?
          </label>
          <input
            id="new-todo"
            onChange={this.handleChange}
            value={this.state.text}
          />
          <button>
            Add #{this.state.items.length + 1}
          </button>
        </form>
      </div>
    );
  }

Everyone has seen template based code like this and... it has to go away!

Sadly, all other frameworks I am aware of are still using string based templates.
The advantage is, that the code looks like real HTML and is compact.

I think of it like comparing XML with JSON based APIs.
By now JSON has almost replaced all XML based APIs and for good reason.

So, what is the problem with string based templates?

I could probably write a small book on this one, but to keep it short:

You should not mix markup with variables or even JS methods
You can get scoping issues with methods defined inside templates
The whole concept of defining web components which then get used as string based markup which controls the instantiation of the matching JS instances is terrible (e.g. for re-using them)
You need to parse these templates, e.g. when a variable changes or in case you want to compare 2 component states to get the delta updates. This is slow!
1. To be fair: for trivial components, this can be done at build time (e.g. Svelte). However, the more complex components get, the less sense it makes (too many variations, imagine the neo.mjs Helix as a template)
2. You can not dynamically change template structures, except with using Factory / Composition patterns

So, what is the alternative?

JSON based virtual DOM

Let's take a look at component.Button:

_vdom: {
    tag: 'button',
    cn : [
        {tag: 'span', cls: ['neo-button-glyph']},
        {tag: 'span', cls: ['neo-button-text']}
    ]
}

Defining the HTML markup via JSON (nested JS objects & arrays to be precise) might look a little bit less compact,
but the advantages are obvious: manipulating JS objects with JS is as easy as possible.

You don't need something like:
<tpl for="listItems"><subitem></subitem></tpl>, but you can use a real JS for loop.

You don't need to insert variables using curly brackets.

You don't need to mix the markup code with JS methods.

To better get the idea, let us take a look at a more complex example:
component.DateSelector

When creating a new component, you will define a "vdom skeleton" first to cover the static parts.

_vdom: {
    tabIndex: -1,
    cn: [{
        cls: ['neo-dateselector-header'],
        cn : [{
            cls: ['neo-nav-button', 'neo-prev-button']
        }, {
            cls: ['neo-center-region'],
            cn : [
                {cls: ['neo-month-text']},
                {cls: ['neo-year-text']}
            ]
        }, {
            cls: ['neo-nav-button', 'neo-next-button']
        }]
    }, {
        cls: ['neo-dateselector-content'],
        cn : []
    }]
}

Afterwards, you can manipulate or enhance it as you like to:

changeYear(increment) {
    let me = this,
        vdom, y;

    if (!me.useAnimations) {
        me.recreateContent(0, increment);
    } else {
        if (!me.isUpdating) {
            me.isUpdating = true;

            Neo.main.DomAccess.getBoundingClientRect({
                id: me.getCenterContentEl().id
            }).then(data => {
                vdom = me.vdom;
                y    = increment < 0 ? 0 : -data.height;

                vdom.cn.push({
                    cls: ['neo-relative'],
                    cn : [{
                        cls: ['neo-animation-wrapper'],
                        cn : [{
                            cls: ['neo-dateselector-content'],
                            cn : []
                        }],
                        style: {
                            flexDirection: 'column',
                            height       : 2 * data.height + 'px',
                            transform    : `translateY(${y}px)`,
                            width        : data.width + 'px'
                        }
                    }]
                });

                me.updateHeaderYear(increment, true);

                me.createDayViewContent(true, vdom.cn[2].cn[0].cn[0]);
                vdom.cn[2].cn[0].cn[increment < 0 ? 'unshift' : 'push'](vdom.cn[1]);
                vdom.cn.splice(1, 1);

                me.promiseVdomUpdate(vdom).then(() => {
                    y = increment < 0 ? -data.height : 0;
                    vdom.cn[1].cn[0].style.transform = `translateY(${y}px)`;
                    me.vdom = vdom;

                    setTimeout(() => {
                        vdom.cn[1] = vdom.cn[1].cn[0].cn[increment < 0 ? 1 : 0];
                        me.triggerVdomUpdate();
                    }, 300);
                });
            });
        } else {
            me.cacheUpdate();
        }
    }
}

Take a look at the "Virtual DOM & Virtual Nodes" Tutorial inside the
neo.mjs Docs App for more infos.

JSON based Component Trees

Exactly like the virtual DOM, the component trees are JSON based as well.

For an example, let's take a look at the
Docs App MainContainer

items: [HeaderContainer, {
    ntype : 'container',
    flex  : 1,
    layout: {ntype: 'hbox', align: 'stretch'},

    items: [{
        ntype   : 'tab-container',
        cls     : ['neo-docs-navigation-tab-container', 'neo-tab-container'],
        minWidth: 290,
        width   : 290,

        items: [{
            module   : ApiTreeList,
            listeners: {leafItemClick: 'onApiListLeafClick'},
            reference: 'api-treelist',

            tabButtonConfig: {
                iconCls: 'fa fa-code',
                text   : 'API'
            }
        }, {
            module   : TutorialsTreeList,
            listeners: {leafItemClick: 'onTutorialListLeafClick'},
            reference: 'tutorials-treelist',

            tabButtonConfig: {
                iconCls: 'fa fa-hands-helping',
                text   : 'Tutorials'
            }
        }, {
            module   : ExamplesTreeList,
            listeners: {leafItemClick: 'onExamplesListLeafClick'},
            reference: 'examples-treelist',

            tabButtonConfig: {
                iconCls: 'fa fa-desktop',
                text   : 'Examples'
            }
        }]
    }, {
        module   : ContentTabContainer,
        flex     : 1,
        reference: 'content-tabcontainer'
    }]
}]

Dynamically generating or changing these component trees using JS is easy.
Containers also provide you with some convenience methods like add(), insert(), remove() etc.
Taking a look at the API section inside the
neo.mjs Docs App will help you.

Combining Component and VDOM Trees

Since both trees are defined as JSON, you can easily mix them.
Example: RealWorld2 App HomeContainer

items: [{
    ntype : 'component',
    cls   : ['banner'],
    height: 170,
    vdom  : {
        cn: [{
            cls: ['container'],
            cn : [{
                tag : 'h1',
                cls : ['logo-font'],
                html: 'conduit v2'
            }, {
                tag : 'p',
                html: 'A place to share your knowledge.'
            }]
        }]
    }
}, {
    module: Container,
    cls   : ['neo-container', 'center', 'container'],
    flex  : 1,
    layout: {ntype: 'hbox', align: 'stretch'},
    items: [{
        module     : TabContainer,
        activeIndex: 1,
        flex       : 3,

        items: [{
            ntype          : 'component',
            cls            : ['neo-examples-tab-component'],
            style          : {padding: '20px'},
            tabButtonConfig: {iconCls: 'fa fa-user-ninja', text: 'Your Feed'},
            vdom           : {innerHTML: 'todo'}
        }, {
            module         : PreviewList,
            tabButtonConfig: {iconCls: 'fa fa-globe-europe', text: 'Global Feed'}
        }]
    }, {
        module: TagListComponent,
        flex  : 1
    }]
}]

What to do next?

In case you like the neo.mjs concepts and would like to see more in the future, adding a github star to this repository is highly appreciated.
Take a look at the Online Examples (Desktop).
Follow the Getting Started Guide to get the framework & examples running locally.
Open Source projects rely on your help, take a look at the Contributing Guide
neo.mjs is still in need of Sponsors to speed up the development: Sponsors Page

Best regards,

Tobias

Chrome v80 release: JS module support for workers

Tobias Uhlig — Wed, 05 Feb 2020 21:26:43 +0000

Google just released Chrome version 80 on Tuesday, February 4, 2020. I personally waited for this specific release for over one year and it feels like the most important major release in a very long time.

https://www.chromestatus.com/features/schedule

What is a Javascript module?

As soon as you are using the ES6+ class system, you will most likely automatically work with JS modules:

If you stick to the “1 class per file” design pattern, you will most likely want to import the base class which you extend. You will also most likely want to export the new class at the end of your file. As soon as you are using an import or export statement, your file is already considered to be a JS module.

Can JS modules run directly inside a browser?

Inside the main thread, this is already possible in Chrome, Firefox & Safari for a long time. Using JS modules inside a web worker was already possible in Chrome for quite some time as well, but hidden behind an experimental flag. Now with Chrome v80, it is finally possible out of the box.

Side note: this widens the gap between Chrome & other browsers by a long shot. Sadly the FF & Safari dev teams have related tickets open for several years, without any priority.

How to create a worker from a JS module?

It is up to you if you want to name your js module files .mjs or just .js, adding type: ‘module’ is the key to do it.

What is the advantage to use JS modules directly inside the browser?

You can create well structured apps and run them inside the browser without the need for any JS related build processes. Meaning: you can change the source code and just reload the browser page, without the need for webkit watching the file-changes & hot module replacements.

Is there already a web workers driven JS UI framework out there?

Yes, neo.mjs got released to the public on November 23rd, 2019.

Repository:

https://github.com/neomjs/neo

Online Examples:

https://neomjs.github.io/pages/

What is coming next?

If you did look close at the release schedule, you might have noticed that Chrome v81 is scheduled for March 17th. This version will include JS module support for shared workers. This is the key for crafting multi browser window apps (e.g. apps which can run on multiple screens).

Best regards & happy coding,
Tobias

neo.mjs - the webworkers driven UI framework

Tobias Uhlig — Fri, 13 Dec 2019 23:26:01 +0000

I just donated 1.5 years of my full and unpaid working time to the open source community and would love to gather some feedback!

https://github.com/neomjs/neo

DEV Community: Tobias Uhlig

Context Engineering: The Symphony of 3 new MCP Servers

The Numbers That Shouldn't Be Possible

The Three Dimensions of Context

The Problem with Scripts: The Limits of "Good Enough"

The Solution: A Multi-Server Model Context Protocol (MCP) Architecture

The Backbone: The Model Context Protocol (MCP)

The Knowledge Base Server: OpenAPI-Driven Self-Documentation

The OpenAPI Innovation

Dynamic Tool Generation

The Self-Aware Startup Sequence

Intelligent Health Monitoring

The Query Scoring Algorithm: Beyond Simple Vector Search

The ETL Pipeline: From Source to Vectors

The Memory Core: An Agent's Personal History

The Save-Then-Respond Protocol

Autonomous Session Summarization

The Two-Stage Query Protocol

Structured Session Metadata

The GitHub Workflow Server: Closing the Loop

The Problem: The Human Review Bottleneck

Local-First: Issues and PRs as Markdown Files

The Self-Organizing Archive System

Handling the Edge Case: Reconciliation

The Sync Engine: A Three-Phase ETL Pipeline

Smart Content Hashing for Change Detection

The GraphQL Optimization: One Query for Everything

Autonomous PR Review: Removing the Human Bottleneck

1. Discovery: Finding PRs That Need Review

2. Analysis: Getting the Full Context

3. Participation: Leaving Structured Feedback

✦ Code Review Findings

4. Local Testing: Checking Out PRs

The Complete Review Workflow

Platform Independence and the Future

What We've Built

The Neo.mjs Backbone: Powering Our Servers

The Power of initAsync() and ready()

Singleton Pattern and Service Architecture

Reactive Configuration System

Observable Pattern for Cross-Service Communication

Why This Matters

The Benefits of a Server-Based Approach

Agent-Driven Quality: The Final Piece of the Puzzle

A Community-Powered Revolution

What's Next

Future Enhancements

Standalone Server Releases?

Getting Started Today

The Future of Context Engineering

The webworkers driven UI framework neo.mjs version 2 release announcement

Content

1. Eye candy

Web-Based Multi-Screen Apps Including Drag & Drop | by Tobias Uhlig | Geek Culture | Mar, 2021 | Medium

Tobias Uhlig ・ Apr 1, 2021 ・ Medium

Cross-App Bundling — A Different Approach for Micro Frontends | by Tobias Uhlig | The Startup | Medium

Tobias Uhlig ・ Sep 9, 2020 ・ Medium

2. Design Goals

3. What is new in version 2?

Enhance your frontend state management with view models | by Tobias Uhlig | Apr, 2021 | ITNEXT

Tobias Uhlig ・ Apr 22, 2021 ・ itnext.io

Cross browser window state management | by Tobias Uhlig | Apr, 2021 | ITNEXT

Tobias Uhlig ・ Apr 26, 2021 ・ itnext.io

Lazy loading for card layout items and tabs → neo.mjs v2.0.10 | by Tobias Uhlig | Apr, 2021 | ITNEXT

Tobias Uhlig ・ Apr 29, 2021 ・ itnext.io

4. Statistics

5. How can I set up my first neo.mjs app?

6. How to migrate from v1 to v2?

7. How difficult is it to learn neo.mjs?

Your benefits of working with JSON based virtual DOM | by Tobias Uhlig | DataSeries | Medium

Tobias Uhlig ・ Aug 7, 2020 ・ Medium

8. When should i use neo.mjs?

9. What is a config system?

Javascript classes: state management v2 | by Tobias Uhlig | codeburst

Tobias Uhlig ・ Mar 11, 2020 ・ codeburst.io

10. Roadmap

11. Final thoughts

12. Special thanks to

Expanding Single Page Apps into multiple Browser Windows

Content

Tobias Uhlig ・ Apr 1, 2021 ・
Medium

Tobias Uhlig ・ Sep 9, 2020 ・
Medium

Tobias Uhlig ・ Apr 22, 2021 ・
itnext.io

Tobias Uhlig ・ Apr 26, 2021 ・
itnext.io

Tobias Uhlig ・ Apr 29, 2021 ・
itnext.io

Tobias Uhlig ・ Aug 7, 2020 ・
Medium

Tobias Uhlig ・ Mar 11, 2020 ・
codeburst.io

Tobias Uhlig ・ Jun 4, 2020 ・
Medium

Tobias Uhlig ・ Jun 6, 2020 ・
Medium