refactor: replace custom MSW handlers with MSWPlugin + protocol broker shim

ROADMAP.md

@@ -648,6 +648,7 @@ ObjectUI is a universal Server-Driven UI (SDUI) engine built on React + Tailwind
 - [x] `EditAppPage` merges wizard output with original app config to preserve fields not in wizard (e.g. `active`)
 - [x] `client.meta.saveItem('app', name, schema)` — persists app metadata to backend on create/edit
 - [x] MSW PUT handler for `/meta/:type/:name` — dev/mock mode metadata persistence
+- [x] MSW handler refactored to use `MSWPlugin` + protocol broker shim — filter/sort/top/pagination now work correctly in dev/mock mode (Issue #858)
 - [x] Draft persistence to localStorage with auto-clear on success
 - [x] `createApp` i18n key added to all 10 locales
 - [x] 13 console integration tests (routes, wizard callbacks, draft persistence, saveItem, CommandPalette)

apps/console/src/__tests__/MSWServer.test.tsx

@@ -1,7 +1,12 @@
 /**
- * Simple MSW Integration Test
+ * MSW Integration Tests
  * 
- * Minimal test to verify MSW server is working
+ * Verifies the MSW server (powered by MSWPlugin) correctly handles:
+ * - Basic CRUD operations via the ObjectStack protocol
+ * - Query parameters: filter, sort, top, skip
+ *
+ * MSWPlugin routes all requests through the ObjectStack protocol stack,
+ * ensuring behaviour is identical to server mode (HonoServerPlugin).
  */
 
 import { describe, it, expect, beforeAll, afterAll } from 'vitest';
@@ -40,4 +45,54 @@ describe('MSW Server Integration', () => {
     expect(newContact.name).toBe('Test User');
     expect(newContact.email).toBe('test@example.com');
   });
+
+  // ── Protocol-level query tests (filter / sort / top) ───────────────────
+  // These tests hit the MSW HTTP layer via fetch, which MSWPlugin routes
+  // through HttpDispatcher → ObjectStack protocol. If the protocol handles
+  // filter/sort/top correctly, these will pass.
+
+  it('should support top (limit) via HTTP', async () => {
+    const res = await fetch('http://localhost/api/v1/data/contact?top=3');
+    expect(res.ok).toBe(true);
+    const body = await res.json();
+
+    // HttpDispatcher wraps in { success, data: { value: [...] } }
+    const data = body.data ?? body;
+    const records = data.value ?? data.records ?? data;
+    expect(Array.isArray(records)).toBe(true);
+    expect(records.length).toBeLessThanOrEqual(3);
+  });
+
+  it('should support sort via HTTP', async () => {
+    const res = await fetch('http://localhost/api/v1/data/contact?sort=name');
+    expect(res.ok).toBe(true);
+    const body = await res.json();
+
+    const data = body.data ?? body;
+    const records = data.value ?? data.records ?? data;
+    expect(Array.isArray(records)).toBe(true);
+    expect(records.length).toBeGreaterThan(0);
+
+    // Verify records are sorted by name ascending
+    const names = records.map((r: any) => r.name);
+    const sorted = [...names].sort((a: string, b: string) => a.localeCompare(b));
+    expect(names).toEqual(sorted);
+  });
+
+  it('should support filter via HTTP', async () => {
+    // Filter contacts where priority = "high" using tuple format
+    const filter = JSON.stringify(['priority', '=', 'high']);
+    const res = await fetch(`http://localhost/api/v1/data/contact?filter=${encodeURIComponent(filter)}`);
+    expect(res.ok).toBe(true);
+    const body = await res.json();
+
+    const data = body.data ?? body;
+    const records = data.value ?? data.records ?? data;
+    expect(Array.isArray(records)).toBe(true);
+    expect(records.length).toBeGreaterThan(0);
+    // All returned records should have priority 'high'
+    for (const record of records) {
+      expect(record.priority).toBe('high');
+    }
+  });
 });

apps/console/src/mocks/browser.ts

@@ -1,22 +1,23 @@
 /**
  * MSW Browser Worker Setup via ObjectStack Runtime
  *
- * Uses the shared createKernel() factory to bootstrap the ObjectStack kernel,
- * then creates MSW handlers via the shared handler factory.
+ * Uses the shared createKernel() factory to bootstrap the ObjectStack kernel
+ * with MSWPlugin, which automatically exposes all ObjectStack API endpoints
+ * via MSW. This ensures filter/sort/top/pagination work identically to
+ * server mode.
  *
  * This pattern follows @objectstack/studio — see https://github.com/objectstack-ai/spec
  */
 
 import { ObjectKernel } from '@objectstack/runtime';
 import { InMemoryDriver } from '@objectstack/driver-memory';
-import { setupWorker } from 'msw/browser';
-import appConfig, { sharedConfig } from '../../objectstack.shared';
+import type { MSWPlugin } from '@objectstack/plugin-msw';
+import appConfig from '../../objectstack.shared';
 import { createKernel } from './createKernel';
-import { createHandlers } from './handlers';
 
 let kernel: ObjectKernel | null = null;
 let driver: InMemoryDriver | null = null;
-let worker: ReturnType<typeof setupWorker> | null = null;
+let mswPlugin: MSWPlugin | null = null;
 
 export async function startMockServer() {
   // Polyfill process.on for ObjectKernel in browser environment
@@ -35,36 +36,27 @@ export async function startMockServer() {
 
   if (import.meta.env.DEV) console.log('[MSW] Starting ObjectStack Runtime (Browser Mode)...');
 
-  const result = await createKernel({ appConfig });
-  kernel = result.kernel;
-  driver = result.driver;
-
-  // Create MSW handlers that match the response format of HonoServerPlugin
-  // Include both /api/v1 and legacy /api paths so the ObjectStackClient can
-  // reach the mock server regardless of which base URL it probes.
-  // Pass sharedConfig (pre-defineStack) so handlers can enrich object metadata
-  // with listViews that defineStack's Zod parse strips.
-  const v1Handlers = createHandlers('/api/v1', kernel, driver, sharedConfig);
-  const legacyHandlers = createHandlers('/api', kernel, driver, sharedConfig);
-  const handlers = [...v1Handlers, ...legacyHandlers];
-
-  // Start MSW service worker
-  worker = setupWorker(...handlers);
-  await worker.start({
-    onUnhandledRequest: 'bypass',
-    serviceWorker: {
-      url: `${import.meta.env.BASE_URL}mockServiceWorker.js`,
+  const result = await createKernel({
+    appConfig,
+    mswOptions: {
+      enableBrowser: true,
+      baseUrl: '/api/v1',
+      logRequests: import.meta.env.DEV,
     },
   });
+  kernel = result.kernel;
+  driver = result.driver;
+  mswPlugin = result.mswPlugin ?? null;
 
   if (import.meta.env.DEV) console.log('[MSW] ObjectStack Runtime ready');
   return kernel;
 }
 
 export function stopMockServer() {
-  if (worker) {
-    worker.stop();
-    worker = null;
+  if (mswPlugin) {
+    const worker = mswPlugin.getWorker();
+    if (worker) worker.stop();
+    mswPlugin = null;
   }
   kernel = null;
   driver = null;

apps/console/src/mocks/createKernel.ts

@@ -4,24 +4,94 @@
  * Creates a fully bootstrapped ObjectStack kernel for use in both
  * browser (MSW setupWorker) and test (MSW setupServer) environments.
  *
+ * Uses MSWPlugin from @objectstack/plugin-msw to expose the full
+ * ObjectStack protocol via MSW. This ensures filter/sort/top/pagination
+ * work identically to server mode.
+ *
  * Follows the same pattern as @objectstack/studio's createKernel —
  * see https://github.com/objectstack-ai/spec
  */
 
 import { ObjectKernel, DriverPlugin, AppPlugin } from '@objectstack/runtime';
 import { ObjectQLPlugin } from '@objectstack/objectql';
 import { InMemoryDriver } from '@objectstack/driver-memory';
+import { MSWPlugin } from '@objectstack/plugin-msw';
+import type { MSWPluginOptions } from '@objectstack/plugin-msw';
 
 export interface KernelOptions {
   /** Application configuration (defineStack output) */
   appConfig: any;
   /** Whether to skip system validation (useful in browser) */
   skipSystemValidation?: boolean;
+  /** MSWPlugin options; when provided, MSWPlugin is added to the kernel. */
+  mswOptions?: MSWPluginOptions;
 }
 
 export interface KernelResult {
   kernel: ObjectKernel;
   driver: InMemoryDriver;
+  /** The MSWPlugin instance (if mswOptions was provided). */
+  mswPlugin?: MSWPlugin;
+}
+
+/**
+ * Install a lightweight broker shim on the kernel so that
+ * HttpDispatcher (used by MSWPlugin) can route data/metadata
+ * calls through the ObjectStack protocol service.
+ *
+ * A full Moleculer-based broker is only available in server mode
+ * (HonoServerPlugin). In MSW/browser mode we bridge the gap with
+ * this thin adapter that delegates to the protocol service.
+ */
+async function installBrokerShim(kernel: ObjectKernel): Promise<void> {
+  let protocol: any;
+  try {
+    protocol = await kernel.getService('protocol');
+  } catch {
+    return;
+  }
+  if (!protocol) return;
+
+  (kernel as any).broker = {
+    async call(action: string, params: any = {}) {
+      const [service, method] = action.split('.');
+
+      if (service === 'data') {
+        switch (method) {
+          case 'query':
+            return protocol.findData({ object: params.object, query: params.query ?? params });
+          case 'get':
+            return protocol.getData({ object: params.object, id: params.id });
+          case 'create':
+            return protocol.createData({ object: params.object, data: params.data });
+          case 'update':
+            return protocol.updateData({ object: params.object, id: params.id, data: params.data });
+          case 'delete':
+            return protocol.deleteData({ object: params.object, id: params.id });
+          case 'batch':
+            return protocol.batchData?.({ object: params.object, ...params }) ?? { results: [] };
+        }
+      }
+
+      if (service === 'metadata') {
+        if (method === 'types') return protocol.getMetaTypes({});
+        if (method === 'getObject') {
+          return protocol.getMetaItem({ type: 'object', name: params.objectName });
+        }
+        if (method === 'saveItem') {
+          return protocol.saveMetaItem?.({ type: params.type, name: params.name, item: params.item });
+        }
+        if (method.startsWith('get')) {
+          const type = method.replace('get', '').toLowerCase();
+          return protocol.getMetaItem({ type, name: params.name });
+        }
+        // list-style calls: metadata.objects, metadata.apps, etc.
+        return protocol.getMetaItems({ type: method, packageId: params.packageId });
+      }
+
+      throw new Error(`[BrokerShim] Unhandled action: ${action}`);
+    },
+  };
 }
 
 /**
@@ -31,7 +101,7 @@ export interface KernelResult {
  * so that kernel setup logic is not duplicated.
  */
 export async function createKernel(options: KernelOptions): Promise<KernelResult> {
-  const { appConfig, skipSystemValidation = true } = options;
+  const { appConfig, skipSystemValidation = true, mswOptions } = options;
 
   const driver = new InMemoryDriver();
 
@@ -43,7 +113,24 @@ export async function createKernel(options: KernelOptions): Promise<KernelResult
   await kernel.use(new DriverPlugin(driver, 'memory'));
   await kernel.use(new AppPlugin(appConfig));
 
+  let mswPlugin: MSWPlugin | undefined;
+  if (mswOptions) {
+    // Install a protocol-based broker shim BEFORE MSWPlugin's start phase
+    // so that HttpDispatcher (inside MSWPlugin) can resolve data/metadata
+    // calls without requiring a full Moleculer broker.
+    await installBrokerShim(kernel);
+
+    mswPlugin = new MSWPlugin(mswOptions);
+    await kernel.use(mswPlugin);
+  }
+
   await kernel.bootstrap();
 
-  return { kernel, driver };
+  // Re-install broker shim after bootstrap to ensure the protocol service
+  // is fully initialised (some plugins register services during start phase).
+  if (mswOptions) {
+    await installBrokerShim(kernel);
+  }
+
+  return { kernel, driver, mswPlugin };
 }