@u-devtools/core 0.1.5 → 0.2.0

package/src/schemas/rpc.ts

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+
+/**
+ * Zod schema for RPC message validation.
+ * Validates the structure of RPC messages used for communication between Server and Client contexts.
+ */
+export const RpcMessageSchema = z.object({
+  /** Unique message identifier */
+  id: z.string().min(1),
+  /** Message type: 'request' for RPC calls, 'response' for replies, 'event' for broadcasts */
+  type: z.enum(['request', 'response', 'event']),
+  /** RPC method name (for requests and events) */
+  method: z.string().optional(),
+  /** Message payload data */
+  payload: z.unknown().optional(),
+  /** Error information (for error responses) */
+  error: z.unknown().optional(),
+});
+
+/**
+ * Type inferred from RpcMessageSchema
+ */
+export type RpcMessageType = z.infer<typeof RpcMessageSchema>;
+
+/**
+ * Validates an unknown value as an RPC message.
+ * @param data - Data to validate
+ * @returns Validated RPC message or null if validation fails
+ */
+export function validateRpcMessage(data: unknown): RpcMessageType | null {
+  const result = RpcMessageSchema.safeParse(data);
+  if (result.success) {
+    return result.data;
+  }
+  return null;
+}

package/src/schemas/settings.ts

@@ -0,0 +1,125 @@
+import { z } from 'zod';
+
+/**
+ * Zod schema for setting type validation.
+ */
+export const SettingTypeSchema = z.enum(['string', 'number', 'boolean', 'select', 'array']);
+
+/**
+ * Zod schema for setting option (used in select type).
+ */
+export const SettingOptionSchema = z.object({
+  label: z.string(),
+  value: z.unknown(),
+});
+
+/**
+ * Zod schema for setting schema definition.
+ * Recursive schema using z.lazy for items field.
+ */
+export const SettingSchemaDefSchema: z.ZodType<any> = z.lazy(() =>
+  z.object({
+    /** Display label for the setting */
+    label: z.string().min(1),
+    /** Optional description/tooltip text */
+    description: z.string().optional(),
+    /** Setting type (determines input component) */
+    type: SettingTypeSchema,
+    /** Default value */
+    default: z.unknown().optional(),
+    /** Options for 'select' type settings */
+    options: z.array(SettingOptionSchema).optional(),
+    /** Schema for array items (for 'array' type with object items) */
+    items: z.record(z.string(), SettingSchemaDefSchema).optional(),
+    /** Item type for 'array' type with primitive items ('string' or 'number') */
+    itemType: z.enum(['string', 'number']).optional(),
+  })
+);
+
+/**
+ * Zod schema for plugin settings schema (record of setting definitions).
+ */
+export const PluginSettingsSchemaSchema = z.record(z.string(), SettingSchemaDefSchema);
+
+/**
+ * Type inferred from SettingSchemaDefSchema
+ */
+export type SettingSchemaDefType = z.infer<typeof SettingSchemaDefSchema>;
+
+/**
+ * Type inferred from PluginSettingsSchemaSchema
+ */
+export type PluginSettingsSchemaType = z.infer<typeof PluginSettingsSchemaSchema>;
+
+/**
+ * Validates a setting schema definition.
+ * @param data - Data to validate
+ * @returns Validated setting schema definition or null if validation fails
+ */
+export function validateSettingSchemaDef(data: unknown): SettingSchemaDefType | null {
+  const result = SettingSchemaDefSchema.safeParse(data);
+  if (result.success) {
+    return result.data;
+  }
+  return null;
+}
+
+/**
+ * Validates a plugin settings schema.
+ * @param data - Data to validate
+ * @returns Validated plugin settings schema or null if validation fails
+ */
+export function validatePluginSettingsSchema(data: unknown): PluginSettingsSchemaType | null {
+  const result = PluginSettingsSchemaSchema.safeParse(data);
+  if (result.success) {
+    return result.data;
+  }
+  return null;
+}
+
+/**
+ * Validates a setting value against its schema definition.
+ * @param value - Value to validate
+ * @param schemaDef - Setting schema definition
+ * @returns True if value is valid, false otherwise
+ */
+export function validateSettingValue(value: unknown, schemaDef: SettingSchemaDefType): boolean {
+  switch (schemaDef.type) {
+    case 'string':
+      return typeof value === 'string';
+    case 'number':
+      return typeof value === 'number' && !Number.isNaN(value);
+    case 'boolean':
+      return typeof value === 'boolean';
+    case 'select':
+      if (!schemaDef.options) return false;
+      return schemaDef.options.some((opt: { label: string; value: unknown }) => opt.value === value);
+    case 'array':
+      if (!Array.isArray(value)) return false;
+      if (schemaDef.itemType) {
+        // Primitive array items
+        return value.every((item) => {
+          if (schemaDef.itemType === 'string') return typeof item === 'string';
+          if (schemaDef.itemType === 'number') return typeof item === 'number';
+          return false;
+        });
+      }
+      if (schemaDef.items) {
+        // Object array items - validate each item
+        const itemsSchema = schemaDef.items;
+        return value.every((item) => {
+          if (typeof item !== 'object' || item === null) return false;
+          for (const [key, itemSchema] of Object.entries(itemsSchema)) {
+            const itemValue = (item as Record<string, unknown>)[key];
+            if (!validateSettingValue(itemValue, itemSchema)) {
+              return false;
+            }
+          }
+          return true;
+        });
+      }
+      return true; // Array without constraints
+    default:
+      return false;
+  }
+}

package/src/transport.ts

@@ -0,0 +1,172 @@
+import type { RpcMessage } from './index';
+import { validateRpcMessage } from './schemas/rpc';
+import { extractErrorMessage } from '@u-devtools/utils';
+
+/**
+ * Unique ID generator for RPC requests
+ */
+const uuid = () => Math.random().toString(36).substring(2, 15);
+
+/**
+ * Abstract class for message transport.
+ * Provides common logic for RPC calls and event subscriptions.
+ */
+export abstract class Transport {
+  protected handlers = new Map<
+    string,
+    { resolve: (value: unknown) => void; reject: (error: Error) => void }
+  >();
+  protected eventListeners = new Map<string, Set<(data: unknown) => void>>();
+  protected disposed = false;
+  protected timeout = 5000; // Default timeout
+
+  /**
+   * Send a message through the transport
+   */
+  protected abstract sendMessage(type: string, data: unknown): void;
+
+  /**
+   * Subscribe to messages from the transport
+   */
+  protected abstract subscribe(type: string, handler: (data: unknown) => void): () => void;
+
+  /**
+   * Unsubscribe from transport messages
+   */
+  protected abstract unsubscribe?(type: string, handler: (data: unknown) => void): void;
+
+  /**
+   * RPC method call
+   */
+  call<T = unknown>(method: string, payload?: unknown): Promise<T> {
+    if (this.disposed) {
+      return Promise.reject(new Error('Transport has been disposed'));
+    }
+
+    const id = uuid();
+    return new Promise<T>((resolve, reject) => {
+      this.handlers.set(id, {
+        resolve: resolve as (value: unknown) => void,
+        reject,
+      });
+
+      // Send request
+      this.sendMessage('request', { id, type: 'request', method, payload });
+
+      // Timeout
+      setTimeout(() => {
+        const handler = this.handlers.get(id);
+        if (handler) {
+          this.handlers.delete(id);
+          const error = new Error(`RPC Timeout: ${method}`);
+          console.error('[RPC Timeout]', {
+            method,
+            payload,
+            stack: error.stack,
+            timestamp: new Date().toISOString(),
+          });
+          handler.reject(error);
+        }
+      }, this.timeout);
+    });
+  }
+
+  /**
+   * Subscribe to events
+   */
+  on(event: string, fn: (data: unknown) => void): () => void {
+    if (!this.eventListeners.has(event)) {
+      this.eventListeners.set(event, new Set());
+    }
+    
+    this.eventListeners.get(event)?.add(fn);
+
+    // Subscribe to transport events
+    const unsubscribe = this.subscribe('event', (data: unknown) => {
+      const msg = data as RpcMessage;
+      if (msg.method === event) {
+        fn(msg.payload);
+      }
+    });
+
+    // Return unsubscribe function
+    return () => {
+      const listeners = this.eventListeners.get(event);
+      if (listeners) {
+        listeners.delete(fn);
+      }
+      unsubscribe();
+    };
+  }
+
+  /**
+   * Unsubscribe from events
+   */
+  off(event: string, fn: (data: unknown) => void) {
+    const listeners = this.eventListeners.get(event);
+    if (listeners) {
+      listeners.delete(fn);
+    }
+  }
+
+  /**
+   * Handle incoming messages (called by transport)
+   */
+  protected handleMessage(data: unknown) {
+    if (this.disposed) return;
+
+    // Validate message structure using Zod
+    const msg = validateRpcMessage(data);
+    if (!msg) {
+      console.warn('[Transport] Invalid RPC message structure:', data);
+      return;
+    }
+
+    // Handle RPC responses
+    if (msg.type === 'response') {
+      const handler = this.handlers.get(msg.id);
+      if (handler) {
+        if (msg.error) {
+          // Extract error message using utility function
+          const errorMessage = extractErrorMessage(msg.error);
+          handler.reject(new Error(errorMessage));
+        } else {
+          handler.resolve(msg.payload);
+        }
+        this.handlers.delete(msg.id);
+      }
+      return;
+    }
+
+    // Handle events
+    if (msg.type === 'event') {
+      const method = msg.method || '';
+      const listeners = this.eventListeners.get(method);
+      if (listeners && listeners.size > 0) {
+        for (const fn of listeners) {
+          try {
+            fn(msg.payload);
+          } catch (err) {
+            console.error('[Transport] Error in listener:', err);
+          }
+        }
+      }
+    }
+  }
+
+  /**
+   * Clean up all handlers and subscriptions
+   */
+  dispose() {
+    this.disposed = true;
+
+    // Reject all pending requests
+    for (const [id, handler] of this.handlers.entries()) {
+      handler.reject(new Error(`Transport disposed: request ${id} was cancelled`));
+    }
+    this.handlers.clear();
+
+    // Clear all event subscriptions
+    this.eventListeners.clear();
+  }
+}

package/src/transports/broadcast-transport.ts

@@ -0,0 +1,174 @@
+import { Transport } from '../transport';
+
+/**
+ * Transport based on BroadcastChannel
+ * Used for communication between App (window) and Client (iframe)
+ * Does not support RPC (call), only events (send/on)
+ */
+export class BroadcastTransport extends Transport {
+  private channel: BroadcastChannel;
+  private messageHandler?: (e: MessageEvent) => void;
+  private namespace: string;
+
+  constructor(namespace: string) {
+    super();
+    this.namespace = namespace;
+    this.channel = new BroadcastChannel(`u-devtools:${namespace}`);
+
+    this.messageHandler = (e: MessageEvent) => {
+      const { event, data } = e.data as { event: string; data: unknown };
+      // BroadcastChannel is only used for events, not for RPC
+      const listeners = this.eventListeners.get(event);
+      if (listeners) {
+        listeners.forEach((fn) => {
+          fn(data);
+        });
+      }
+    };
+
+    this.channel.onmessage = this.messageHandler;
+  }
+
+  /**
+   * Extract values from Vue reactive objects (ref, computed, reactive)
+   */
+  private unwrapVueReactive(value: unknown): unknown {
+    // Check if this is a Vue ref/computed
+    if (value && typeof value === 'object') {
+      // Vue 3 ref/computed have __v_isRef or _value property
+      if ('__v_isRef' in value || '_value' in value) {
+        const refValue = (value as { _value?: unknown; value?: unknown })._value ?? (value as { value?: unknown }).value;
+        return this.unwrapVueReactive(refValue);
+      }
+      // Vue reactive objects may have circular references
+      if (Array.isArray(value)) {
+        return value.map(item => this.unwrapVueReactive(item));
+      }
+      // Regular objects - process recursively
+      const result: Record<string, unknown> = {};
+      const seen = new WeakSet();
+      for (const key in value) {
+        if (Object.prototype.hasOwnProperty.call(value, key)) {
+          const val = (value as Record<string, unknown>)[key];
+          // Skip circular references and Vue internal properties
+          if (key.startsWith('__') || key.startsWith('_') && key !== '_value') {
+            continue;
+          }
+          if (val && typeof val === 'object') {
+            if (seen.has(val as object)) {
+              result[key] = '[Circular]';
+              continue;
+            }
+            seen.add(val as object);
+          }
+          result[key] = this.unwrapVueReactive(val);
+        }
+      }
+      return result;
+    }
+    return value;
+  }
+
+  /**
+   * Send event (not RPC)
+   */
+  send(event: string, data?: unknown): void {
+    try {
+      // Extract values from Vue reactive objects before sending
+      const serializableData = data !== undefined ? this.unwrapVueReactive(data) : undefined;
+      this.channel.postMessage({ event, data: serializableData });
+    } catch (e) {
+      // Ignore errors if channel is closed
+      if (
+        e instanceof DOMException &&
+        (e.name === 'InvalidStateError' || e.message?.includes('closed'))
+      ) {
+        console.warn(`[BroadcastTransport:${this.namespace}] Cannot send event "${event}": channel is closed`);
+        return;
+      }
+      
+      // DataCloneError - add detailed information
+      if (e instanceof Error && (e.name === 'DataCloneError' || e.message?.includes('circular'))) {
+        const stack = new Error().stack;
+        const dataType = data === null ? 'null' : data === undefined ? 'undefined' : typeof data;
+        let dataPreview = '';
+        try {
+          dataPreview = typeof data === 'object' && data !== null 
+            ? JSON.stringify(data, (key, value) => {
+                if (typeof value === 'function') return '[Function]';
+                if (value instanceof Node) return `[${value.nodeName}]`;
+                if (value instanceof Error) return `[Error: ${value.message}]`;
+                // Skip Vue internal properties
+                if (key.startsWith('__') || (key.startsWith('_') && key !== '_value')) return undefined;
+                return value;
+              }, 2).slice(0, 200)
+            : String(data).slice(0, 100);
+        } catch {
+          dataPreview = '[Unable to serialize]';
+        }
+        
+        console.error(
+          `[BroadcastTransport:${this.namespace}] DataCloneError: Failed to send event "${event}".\n` +
+          `Data type: ${dataType}\n` +
+          `Data preview: ${dataPreview}\n` +
+          `This usually means the data contains non-serializable objects (functions, DOM nodes, Vue refs, etc.).\n` +
+          `Stack trace:\n${stack?.split('\n').slice(0, 5).join('\n') || 'N/A'}`
+        );
+        return; // Don't throw error, just log
+      }
+      
+      throw e;
+    }
+  }
+
+  /**
+   * RPC calls are not supported in BroadcastChannel
+   */
+  override call<T = unknown>(_method: string, _payload?: unknown): Promise<T> {
+    return Promise.reject(
+      new Error('RPC calls are not supported in BroadcastTransport. Use send() for events.')
+    );
+  }
+
+  protected sendMessage(_type: string, _data: unknown): void {
+    // BroadcastChannel does not support RPC
+    throw new Error('sendMessage is not supported in BroadcastTransport. Use send() instead.');
+  }
+
+  protected subscribe(event: string, handler: (data: unknown) => void): () => void {
+    // Subscription is already handled via messageHandler
+    if (!this.eventListeners.has(event)) {
+      this.eventListeners.set(event, new Set());
+    }
+    const listeners = this.eventListeners.get(event);
+    if (listeners) {
+      listeners.add(handler);
+    }
+    // Return unsubscribe function
+    return () => {
+      const listeners = this.eventListeners.get(event);
+      if (listeners) {
+        listeners.delete(handler);
+      }
+    };
+  }
+
+  protected unsubscribe(event: string, handler: (data: unknown) => void): void {
+    const listeners = this.eventListeners.get(event);
+    if (listeners) {
+      listeners.delete(handler);
+    }
+  }
+
+  override dispose() {
+    super.dispose();
+    this.channel.close();
+  }
+
+  /**
+   * Close channel (alias for dispose)
+   */
+  close() {
+    this.dispose();
+  }
+}

package/src/transports/hmr-transport.ts

@@ -0,0 +1,82 @@
+import { Transport } from '../transport';
+
+/**
+ * Transport based on Vite HMR (Hot Module Replacement)
+ * Used for communication between client (iframe) and server (Node.js)
+ */
+export class HmrTransport extends Transport {
+  private responseHandler?: (data: unknown) => void;
+  private eventHandler?: (data: unknown) => void;
+
+  constructor(
+    private hot: {
+      send: (event: string, data: unknown) => void;
+      on: (event: string, handler: (data: unknown) => void) => void;
+      off?: (event: string, handler: (data: unknown) => void) => void;
+    }
+  ) {
+    super();
+    if (!hot) throw new Error('Hot Module Replacement is required for HmrTransport');
+
+    // Listen for responses from server
+    this.responseHandler = (data: unknown) => {
+      this.handleMessage(data);
+    };
+    hot.on('u-devtools:response', this.responseHandler);
+
+    // Listen for events from server
+    this.eventHandler = (data: unknown) => {
+      this.handleMessage(data);
+    };
+    hot.on('u-devtools:event', this.eventHandler);
+  }
+
+  /**
+   * Override on() for HMR, as subscription is already set up in constructor
+   */
+  override on(event: string, fn: (data: unknown) => void): () => void {
+    if (!this.eventListeners.has(event)) {
+      this.eventListeners.set(event, new Set());
+    }
+    this.eventListeners.get(event)?.add(fn);
+
+    // Return unsubscribe function
+    return () => {
+      const listeners = this.eventListeners.get(event);
+      if (listeners) {
+        listeners.delete(fn);
+      }
+    };
+  }
+
+  protected sendMessage(type: string, data: unknown): void {
+    if (type === 'request') {
+      this.hot.send('u-devtools:request', data);
+    }
+  }
+
+  protected subscribe(_type: string, _handler: (data: unknown) => void): () => void {
+    // HMR is already subscribed in constructor, just return empty function
+    // as handling happens through responseHandler and eventHandler
+    return () => {
+      // Unsubscription is handled in dispose
+    };
+  }
+
+  protected unsubscribe(_type: string, _handler: (data: unknown) => void): void {
+    // HMR doesn't support unsubscribing individual handlers directly
+    // Unsubscription happens through dispose
+  }
+
+  override dispose() {
+    super.dispose();
+
+    // Unsubscribe from HMR events if API supports off
+    if (this.hot.off && this.responseHandler) {
+      this.hot.off('u-devtools:response', this.responseHandler);
+    }
+    if (this.hot.off && this.eventHandler) {
+      this.hot.off('u-devtools:event', this.eventHandler);
+    }
+  }
+}