feat(core): support declarative remote configs for instance IPC (#9546)

- Removed the singleton-only restriction from `remote` config in `src/core/Base.mjs`.
- Updated `initRemote` to pre-generate proxy functions directly onto the `this.remote` object for non-singletons, resolving `this.remoteId` dynamically at call time.
- Implemented robust intent-driven JSDoc comments to document the Instance-to-Instance Handshake pattern.
- Refactored `Neo.data.Pipeline` to define its IPC methods declaratively via `static config = { remote: { data: ['create', 'read', 'update'] } }`.
- Replaced the procedural `generateRemote` hacks in Pipeline methods with clean, pre-bound `this.remote.data[operation]()` calls.

Author: tobiu

src/core/Base.mjs

@@ -453,24 +453,6 @@ class Base {
         return value
     }
 
-    /**
-     * Triggered before the remote config gets changed
-     * @param {Object|null} value
-     * @param {Object|null} oldValue
-     * @returns {Object|null}
-     * @protected
-     */
-    beforeSetRemote(value, oldValue) {
-        let me = this;
-
-        // Only allow remote access for singletons or main thread addons
-        if (value && !me.singleton && !me.isMainThreadAddon) {
-            throw new Error('Remote method access is only functional for Singleton classes ' + me.className)
-        }
-
-        return value
-    }
-
     /**
      * @param {String} fn               The name of a function to find in the passed scope object.
      * @param {Object} originName       The name of the method inside the originScope.
@@ -644,27 +626,76 @@ class Base {
      * @protected
      */
     async initRemote() {
-        let {className, remote} = this,
+        let me                  = this,
+            {className, remote} = me,
             {currentWorker}     = Neo;
 
         if (!Neo.config.isMiddleware && !Neo.config.unitTestMode) {
-            if (Neo.workerId !== 'main' && currentWorker.isSharedWorker) {
-                if (remote.main) {
-                    currentWorker.remotesToRegister.push({className, methods: remote.main})
+            // SetupClass applies `singleton` to the instance prototype if configured.
+            if (me.singleton === true) {
+                // Singleton Routing (Namespace-Driven)
+                if (Neo.workerId !== 'main' && currentWorker.isSharedWorker) {
+                    if (remote.main) {
+                        currentWorker.remotesToRegister.push({className, methods: remote.main})
+                    }
+
+                    if (!currentWorker.isConnected) {
+                        await new Promise(resolve => {
+                            currentWorker.on('connected', () => resolve(), me, {once: true})
+                        })
+                    }
+                } else if (Neo.workerId === 'service') {
+                    if (remote.app) {
+                        currentWorker.remotesToRegister.push({className, methods: remote.app})
+                    }
                 }
 
-                if (!currentWorker.isConnected) {
-                    await new Promise(resolve => {
-                        currentWorker.on('connected', () => resolve(), this, {once: true})
+                await Base.promiseRemotes(className, remote)
+            } else {
+                // Instance-to-Instance Routing (ID-Driven)
+                // Unlike Singletons which broadcast their existence globally via 'registerRemote',
+                // instances dynamically build a `me.remote` object containing pre-bound proxy functions.
+                // This establishes a localized IPC channel for cross-thread architecture (e.g. data.Pipeline).
+                let remoteObj = {};
+
+                Object.entries(remote).forEach(([worker, methods]) => {
+                    remoteObj[worker] = {};
+
+                    methods.forEach(method => {
+                        remoteObj[worker][method] = (data, buffer) => {
+                            let origin = Neo.workerId === 'main' ? Neo.worker.Manager : Neo.currentWorker,
+                                opts   = {
+                                    action         : 'remoteMethod',
+                                    data,
+                                    destination    : worker,
+                                    remoteClassName: className,
+                                    remoteMethod   : method
+                                };
+
+                            // The destination ID is resolved at execution time. This accommodates
+                            // the "Handshake" pattern where `me.remoteId` is populated asynchronously
+                            // after the target instance is created in the remote thread.
+                            if (me.remoteId) {
+                                opts.remoteId = me.remoteId
+                            } else if (data?.remoteId) {
+                                opts.remoteId = data.remoteId
+                            }
+
+                            if (worker === 'main' && data?.windowId) {
+                                opts.destination = data.windowId
+                            }
+
+                            if (origin.isSharedWorker) {
+                                origin.assignPort(data, opts)
+                            }
+
+                            return origin.promiseMessage(opts.destination, opts, buffer)
+                        }
                     })
-                }
-            } else if (Neo.workerId === 'service') {
-                if (remote.app) {
-                    currentWorker.remotesToRegister.push({className, methods: remote.app})
-                }
-            }
+                });
 
-            await Base.promiseRemotes(className, remote)
+                me.remote = remoteObj
+            }
         }
     }
 

src/data/Pipeline.mjs

@@ -61,6 +61,13 @@ class Pipeline extends Base {
          * @reactive
          */
         parser_: null,
+        /**
+         * @member {Object} remote
+         * @protected
+         */
+        remote: {
+            data: ['create', 'read', 'update']
+        },
         /**
          * The ID of the corresponding Pipeline instance in the remote worker.
          * @member {String|null} remoteId=null
@@ -278,13 +285,7 @@ class Pipeline extends Base {
             if (me.isDestroyed) return null;
 
             try {
-                let remoteRead = Neo.currentWorker.generateRemote({
-                    origin   : 'data',
-                    className: me.className,
-                    id       : me.remoteId
-                }, 'read');
-
-                const response = await remoteRead(params);
+                const response = await me.remote.data.read(params);
 
                 if (response === null && attempt <= maxRemoteRetries) {
                     // Potential remote instance loss or silent failure
@@ -359,13 +360,7 @@ class Pipeline extends Base {
 
             if (me.isDestroyed) return null;
 
-            let remoteMethod = Neo.currentWorker.generateRemote({
-                origin   : 'data',
-                className: me.className,
-                id       : me.remoteId
-            }, operation);
-
-            return await remoteMethod(params);
+            return await me.remote.data[operation](params);
         } else {
             let rawData;
 

src/worker/mixin/RemoteMethodAccess.mjs

@@ -37,20 +37,27 @@ import Base from '../../core/Base.mjs';
  *   the original method is synchronous.
  *
  * **Routing Modes:**
- * RMA supports two distinct routing modes for executing remote methods:
+ * RMA supports two distinct routing modes for executing remote methods, orchestrated by `Neo.core.Base.initRemote`:
  *
  * 1. **Singleton Routing (Namespace-Driven):**
- *    Historically, RMA was used exclusively for singletons. Remote access is resolved via static namespaces
- *    (e.g., `Neo.ns('Neo.main.addon.LocalStorage')`). The calling thread must know the full class name.
+ *    Historically, RMA was used exclusively for singletons. When a singleton class defines a `remote` config,
+ *    the framework broadcasts a `registerRemote` message. The target threads generate proxy functions and attach
+ *    them directly to the static namespace (e.g., `Neo.main.addon.LocalStorage.readLocalStorageItem`).
+ *    This mode supports an `interceptRemotes` config. Calls arriving before a singleton is `isReady`
+ *    can be intercepted and queued until the singleton is fully functional.
  *
  * 2. **Instance-to-Instance Routing (ID-Driven):**
  *    RMA can also route messages to specific class instances across worker boundaries using `remoteId`.
  *    Because each worker has an isolated memory space and its own `Neo.manager.Instance` registry, an ID
  *    (like 'pipeline-1') only refers to an object within its local thread.
+ *    For non-singleton instances, `core.Base.initRemote` automatically generates proxy functions and attaches
+ *    them to a `this.remote` object on the instance itself (e.g., `this.remote.data.read()`), rather than
+ *    broadcasting globally.
+ *    
  *    To establish an instance-to-instance connection, instances must perform a **Handshake**:
  *    - Thread A creates an instance in Thread B (via `worker.createInstance()`), passing its own local ID in the config.
  *    - Thread B instantiates the object, registers it locally, and returns its new local ID to Thread A.
- *    - Now, both instances can use `generateRemote` by providing `id` alongside `origin` (the destination worker).
+ *    - Now, both instances can call their local `this.remote` proxies, which dynamically resolve the destination ID at execution time.
  *    RMA intercepts messages with a `remoteId` and resolves them dynamically via `Neo.manager.Instance.get(remoteId)`.
  *
  * **Architectural Note:**
@@ -81,14 +88,9 @@ import Base from '../../core/Base.mjs';
  *
  * @example
  * // 3. Instance-to-Instance Usage
- * // App Worker Pipeline generating a proxy to call `read()` on its Data Worker counterpart
- * let remoteRead = this.generateRemote({
- *     origin   : 'data',         // Target worker
- *     className: this.className,
- *     id       : this.remoteId   // The local ID of the instance in the Data Worker
- * }, 'read');
- *
- * let response = await remoteRead({ page: 1 });
+ * // App Worker Pipeline calling `read()` on its Data Worker counterpart.
+ * // The proxy was pre-generated by `core.Base.initRemote` onto `this.remote`.
+ * let response = await this.remote.data.read({ page: 1 });
  *
  * @class Neo.worker.mixin.RemoteMethodAccess
  * @extends Neo.core.Base