feat: Neural Link Driven Playwright Integration (#8851)

Resolves #8851, #9782, #9783

- Updated Bridge and ConnectionService to track test clients and App Names.

- Created neuralLink test fixture exposing MCP state observation.

- Added end-to-end smoke test validating God Mode access.

Author: tobiu

ai/mcp/server/neural-link/Bridge.mjs

@@ -136,6 +136,9 @@ class Bridge extends Base {
 
             if (role === 'agent') {
                 this.registerAgent(id, ws);
+            } else if (role === 'test') {
+                logger.info(`Bridge: Test client connected [${id}]`);
+                this.registerAgent(id, ws);
             } else {
                 // Default to app if no role specified (backward compatibility)
                 this.registerApp(id, ws, appName);

ai/mcp/server/neural-link/services/ConnectionService.mjs

@@ -295,10 +295,12 @@ class ConnectionService extends Base {
 
     /**
      * @param {String} appWorkerId
+     * @param {String} [appName='Unknown']
      */
-    handleAppConnected(appWorkerId) {
-        logger.info(`App Worker connected: ${appWorkerId}`);
+    handleAppConnected(appWorkerId, appName = 'Unknown') {
+        logger.info(`App Worker connected: ${appWorkerId} (${appName})`);
         this.sessionData.set(appWorkerId, {
+            appName,
             connectedAt: Date.now(),
             logs       : [],
             sessionId  : appWorkerId
@@ -342,7 +344,7 @@ class ConnectionService extends Base {
 
             switch (payload.type) {
                 case 'app_connected':
-                    this.handleAppConnected(payload.appWorkerId);
+                    this.handleAppConnected(payload.appWorkerId, payload.appName);
                     break;
                 case 'app_disconnected':
                     this.handleAppDisconnected(payload.appWorkerId);
@@ -497,6 +499,40 @@ class ConnectionService extends Base {
             setTimeout(resolve, 2000);
         });
     }
+
+    /**
+     * Waits for a session matching the given ID or AppName to become active.
+     * @param {String} target The appWorkerId or appName to wait for.
+     * @param {Number} [timeout=10000] Ms to wait before rejecting.
+     * @returns {Promise<String>} The matched appWorkerId.
+     */
+    async waitForSession(target, timeout = 10000) {
+        const check = () => {
+             for (const [id, meta] of this.sessionData.entries()) {
+                 if (id === target || meta.appName === target) {
+                     return id;
+                 }
+             }
+             return null;
+        };
+
+        let found = check();
+        if (found) return found;
+
+        return new Promise((resolve, reject) => {
+            const startTime = Date.now();
+            const interval = setInterval(() => {
+                found = check();
+                if (found) {
+                    clearInterval(interval);
+                    resolve(found);
+                } else if (Date.now() - startTime > timeout) {
+                    clearInterval(interval);
+                    reject(new Error(`waitForSession timed out looking for: ${target}`));
+                }
+            }, 100);
+        });
+    }
 }
 
 export default Neo.setupClass(ConnectionService);

resources/content/sandman_handoff.md

@@ -17,13 +17,9 @@ This file tracks topological conflict alerts generated during overnight REM slee
 
 Based on the latest Tri-Vector Synthesis and Topological Priorities, the following tasks are mathematically recommended as the next immediate focus:
 
-1. **issue-9673**: Score 11.00 (Semantic: 5.00, Structural: 1.00)
+1. **issue-9673**: Score 3.54 (Semantic: 1.27, Structural: 1.00)
    - *Technical Awareness: Hybrid GraphRAG (Native Edge Graph & App Mapping)*
-2. **issue-9637**: Score 11.00 (Semantic: 5.00, Structural: 1.00)
-   - *Grid Multi-Body: E2E Telemetry Adjustments for Dual-Pipeline Scrolling*
-3. **issue-9636**: Score 11.00 (Semantic: 5.00, Structural: 1.00)
-   - *Grid Multi-Body: Simplify GridDragScroll Scrollbar Hit Detection*
-- **[Codebase Gap]** Node `Zombie Ollama Runner Processes`: [DOC_GAP] No documentation or tests found regarding the handling, detection, or cleanup of zombie Ollama runner processes in the provided directory tree. (Source Session: 67b641b1-4354-4bd5-ba22-0ed333a6847b)
-- **[Codebase Gap]** Node `Neo.canvas.Base`: [DOC_GAP] The 'Neo.canvas.Base' class is a critical foundation for high-performance canvas renderers (OffscreenCanvas in Workers). While 'learn/guides/advanced/CanvasArchitecture.md' exists and explains the conceptual architecture and a specific implementation (Luminous Flux), it lacks a formal API reference for the 'Neo.canvas.Base' class itself. There is no documentation describing the methods 'initGraph', 'clearGraph', 'updateSize', 'updateMouseState', and hooks like 'onGraphMounted' or 'updateResources'. Developers cannot know the API surface of the base class without reading the source code. Additionally, there is no unit test coverage for the base class in 'test/playwright/unit/'. (Source Session: f971ec44-5ad6-48b9-92e0-790524267d09)
-- **[Codebase Gap]** Node `Neo.canvas.Header`: [DOC_GAP] Class `Neo.canvas.Header` implements complex 'Luminous Flux' visual theme, Zero-Allocation geometry buffers, and specific physics for UI diversion (detailed in code comments but not in native documentation). No corresponding doc file exists in `docs/` or `learn/` that explains this architectural approach or the theme's configuration. (Source Session: f971ec44-5ad6-48b9-92e0-790524267d09)
-- **[Codebase Gap]** Node `Neo.component.CanvasShared`: [DOC_GAP] The class `Neo.app.SharedCanvas` (implemented in `src/app/SharedCanvas.mjs`) provides a critical abstraction for connecting App Workers to SharedWorker canvas renderers. While `learn/guides/advanced/CanvasArchitecture.md` discusses the high-level architecture and uses a conceptual `HeaderCanvas` example, there is no API reference or developer guide specifically for the `Neo.app.SharedCanvas` base class itself. Developers need documentation on its required config properties (`rendererClassName`, `rendererImportPath`) and its lifecycle methods to properly implement their own SharedWorker-backed components. (Source Session: f971ec44-5ad6-48b9-92e0-790524267d09)
+2. **issue-9299**: Score 3.40 (Semantic: 1.20, Structural: 1.00)
+   - *Implement Agent Self-Discovery via Neural Link Introspection*
+3. **issue-9298**: Score 3.39 (Semantic: 1.19, Structural: 1.00)
+   - *Implement Moltbook Demo Agent using Chrome DevTools MCP*

test/playwright/e2e/NeuralLink.spec.mjs

@@ -0,0 +1,37 @@
+import { test, expect } from '../fixtures.mjs';
+
+test.describe('Neural Link Driven Playwright Integration', () => {
+    // Shared Worker environments can take time to spin up
+    test.setTimeout(90000);
+
+    test('God Mode access to internal worker state', async ({ page, neuralLink }) => {
+        console.log('[NeuralLink.spec.mjs] Loading Portal App...');
+        // 1. Setup - Let Playwright load the actual App UI
+        await page.goto('/apps/portal/');
+
+        // 2. Connect via Neural Link SDK (bypassing normal DOM observation)
+        console.log('[NeuralLink.spec.mjs] Requesting SDK connection...');
+        const app = await neuralLink.connectToApp('Portal');
+        
+        console.log(`[NeuralLink.spec.mjs] Connected to App Session ID: ${app.sessionId}`);
+
+        // Get the dynamic ID of the Viewport to avoid guessing "neo-viewport-1"
+        await page.waitForSelector('.neo-viewport', { timeout: 30000 });
+        const viewportId = await page.evaluate(() => document.querySelector('.neo-viewport').id);
+
+        // 3. Inspect internal structural state directly from worker memory
+        const rootProps = await app.getComponent(viewportId);
+        
+        // Assertions against the internal truth, not the DOM snapshot
+        expect(rootProps).toBeTruthy();
+        expect(rootProps.ntype).toBe('viewport');
+        expect(rootProps.windowId).toBeDefined();
+
+        // 4. Test Mutations (Write Access)
+        // Adjust the app internal configuration values live and instantly assert Playwright recognizes the DOM change
+        await app.setProperties(viewportId, { style: { backgroundColor: 'rgb(123, 12, 123)' } });
+
+        // Verify the reactive system pumped the virtual DOM update instantly
+        await expect(page.locator('.neo-viewport').first()).toHaveCSS('background-color', 'rgb(123, 12, 123)');
+    });
+});

test/playwright/fixtures.mjs

@@ -1,5 +1,11 @@
 import { test as base, expect } from '@playwright/test';
 import * as RmaHelpers from './util/RmaHelpers.mjs';
+import {
+    NeuralLink_ConnectionService,
+    NeuralLink_InstanceService,
+    NeuralLink_DataService,
+    NeuralLink_RuntimeService
+} from '../../ai/services.mjs';
 
 export const test = base.extend({
     neo: async ({ page }, use) => {
@@ -59,6 +65,65 @@ export const test = base.extend({
         };
 
         await use(neo);
+    },
+
+    neuralLink: async ({ page }, use) => {
+        // 1. Ensure Bridge connects
+        await NeuralLink_ConnectionService.manageConnection({action: 'start'});
+
+        // 2. Define the Neural Link Fixture object
+        const nl = {
+            /**
+             * Waits for the Test's specific App Worker to connect to the Bridge and returns an SDK wrapper.
+             * @param {String} [appName] Optional explicitly named app to wait for. Mostly we wait for this specific page's workerId.
+             */
+            async connectToApp(appName) {
+                let inferredAppName = null;
+
+                try {
+                    // Give the page a moment to initialize Neo
+                    await page.waitForFunction(() => window.Neo && window.Neo.config, { timeout: 2000 }).catch(() => {});
+                    inferredAppName = await page.evaluate(() => {
+                        const path = window.Neo?.config?.appPath;
+                        return path ? path.split('/').slice(-2, -1)[0] : null;
+                    });
+                } catch (e) {
+                    // Ignore, page might not exist or be blank
+                }
+
+                // If user passed 'Portal', prefer that, otherwise use the inferred appName like 'portal'
+                const targetId = appName || inferredAppName;
+                if (!targetId) {
+                    throw new Error('neuralLink.connectToApp requires either an initialized Neo environment or an explicit appName to wait for.');
+                }
+
+                // Lowercase for the connection service match
+                const sessionId = await NeuralLink_ConnectionService.waitForSession(targetId.toLowerCase());
+
+                return {
+                    sessionId,
+
+                    async getComponent(id) {
+                        const response = await NeuralLink_InstanceService.getInstanceProperties({ sessionId, id, properties: ['ntype', 'windowId', 'cls', 'className', 'vnode'] });
+                        return response.properties;
+                    },
+
+                    async getStore(storeId) {
+                        return NeuralLink_DataService.inspectStore({ sessionId, storeId });
+                    },
+
+                    async callMethod(id, method, args = []) {
+                        return NeuralLink_RuntimeService.callMethod({ sessionId, id, method, args });
+                    },
+
+                    async setProperties(id, properties) {
+                        return NeuralLink_InstanceService.setInstanceProperties({ sessionId, id, properties });
+                    }
+                };
+            }
+        };
+
+        await use(nl);
     }
 });