pulse-js-framework 1.7.32 → 1.7.37

package/types/native.d.ts

@@ -0,0 +1,282 @@
+/**
+ * Pulse Framework - Native Mobile Bridge Type Definitions
+ * @module pulse-js-framework/runtime/native
+ */
+
+import { Pulse } from './pulse';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/** Supported platform identifiers */
+export type Platform = 'ios' | 'android' | 'web';
+
+/** Network connectivity status */
+export interface NetworkStatus {
+  connected: boolean;
+  type: string;
+}
+
+/** Device information data */
+export interface DeviceInfoData {
+  platform: string;
+  userAgent: string;
+  language: string;
+  [key: string]: unknown;
+}
+
+// ============================================================================
+// Interfaces
+// ============================================================================
+
+/** Reactive native storage with automatic persistence */
+export interface NativeStorage {
+  /**
+   * Get a reactive value from native storage.
+   * Returns a Pulse signal that auto-persists changes.
+   *
+   * @param key - Storage key
+   * @param defaultValue - Default value if key not found
+   * @returns A Pulse that syncs with native storage
+   *
+   * @example
+   * const storage = createNativeStorage('app_');
+   * const theme = storage.get('theme', 'light');
+   * theme.set('dark'); // Auto-saves to storage
+   */
+  get<T = unknown>(key: string, defaultValue?: T): Pulse<T>;
+
+  /**
+   * Remove a value from storage
+   *
+   * @param key - Storage key to remove
+   */
+  remove(key: string): Promise<void>;
+
+  /**
+   * Clear all storage entries with the configured prefix
+   */
+  clear(): Promise<void>;
+}
+
+/** Reactive device information */
+export interface DeviceInfo {
+  /** Device info as a reactive Pulse */
+  info: Pulse<DeviceInfoData | null>;
+
+  /** Network status as a reactive Pulse */
+  network: Pulse<NetworkStatus>;
+
+  /** Current platform */
+  readonly platform: Platform;
+
+  /** Whether running in a native app */
+  readonly isNative: boolean;
+
+  /** Whether the device is currently online */
+  readonly isOnline: boolean;
+}
+
+// ============================================================================
+// Functions
+// ============================================================================
+
+/**
+ * Check if PulseMobile bridge is available and valid.
+ *
+ * Security: This function validates the bridge structure, version,
+ * and API surface before returning true. Malicious or malformed
+ * bridges will be rejected.
+ *
+ * @returns True if a valid PulseMobile bridge is available
+ */
+export declare function isNativeAvailable(): boolean;
+
+/**
+ * Get the PulseMobile instance (validated).
+ *
+ * @throws {Error} If bridge is not available or validation failed
+ * @returns The validated PulseMobile bridge object
+ */
+export declare function getNative(): object;
+
+/**
+ * Get current platform.
+ *
+ * @returns 'ios', 'android', or 'web'
+ */
+export declare function getPlatform(): Platform;
+
+/**
+ * Check if running in a native environment.
+ *
+ * @returns True if running inside a Pulse native mobile app
+ */
+export declare function isNative(): boolean;
+
+/**
+ * Create reactive native storage.
+ * Syncs between native storage and Pulse reactivity system.
+ * Falls back to localStorage on web.
+ *
+ * @param prefix - Key prefix for all storage operations (default: '')
+ * @returns A NativeStorage instance with reactive get, remove, and clear methods
+ *
+ * @example
+ * const storage = createNativeStorage('app_');
+ * const theme = storage.get('theme', 'light');
+ * theme.set('dark'); // Auto-persists to storage
+ * await storage.remove('theme');
+ * await storage.clear();
+ */
+export declare function createNativeStorage(prefix?: string): NativeStorage;
+
+/**
+ * Create reactive device info.
+ * Provides platform, network status, and device details as reactive Pulses.
+ *
+ * @returns A DeviceInfo object with reactive properties
+ *
+ * @example
+ * const device = createDeviceInfo();
+ * device.info.get();      // { platform, userAgent, language, ... }
+ * device.network.get();   // { connected: true, type: 'wifi' }
+ * device.isOnline;        // true/false
+ * device.platform;        // 'ios' | 'android' | 'web'
+ */
+export declare function createDeviceInfo(): DeviceInfo;
+
+/**
+ * Register a callback for when the app is paused/backgrounded.
+ * On web, this listens for visibilitychange events.
+ *
+ * @param callback - Function to call when app is paused
+ */
+export declare function onAppPause(callback: () => void): void;
+
+/**
+ * Register a callback for when the app is resumed/foregrounded.
+ * On web, this listens for visibilitychange events.
+ *
+ * @param callback - Function to call when app is resumed
+ */
+export declare function onAppResume(callback: () => void): void;
+
+/**
+ * Register a callback for the Android back button.
+ * Only works in native Android environments.
+ *
+ * @param callback - Function to call when back button is pressed
+ */
+export declare function onBackButton(callback: () => void): void;
+
+/**
+ * Register a callback for when the native bridge is ready.
+ * If the bridge is already ready, the callback is called asynchronously.
+ *
+ * @param callback - Function to call with platform details
+ *
+ * @example
+ * onNativeReady(({ platform }) => {
+ *   console.log('Native ready on', platform);
+ * });
+ */
+export declare function onNativeReady(callback: (detail: { platform: Platform }) => void): void;
+
+/**
+ * Exit the app (Android only).
+ * Logs a warning on non-Android platforms.
+ *
+ * @returns Promise that resolves when the app exits
+ */
+export declare function exitApp(): Promise<void>;
+
+/**
+ * Minimize the app.
+ * Only works in native environments.
+ *
+ * @returns Promise that resolves when the app is minimized
+ */
+export declare function minimizeApp(): Promise<void>;
+
+/**
+ * Clear the bridge validation cache.
+ * Useful for testing or after bridge changes.
+ */
+export declare function clearBridgeValidationCache(): void;
+
+/**
+ * Get the last bridge validation error (if any).
+ *
+ * @returns The validation error message, or null if validation passed
+ */
+export declare function getBridgeValidationError(): string | null;
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+/** Native UI helpers (toast, vibration) */
+export declare const NativeUI: {
+  /**
+   * Show a toast message.
+   * Falls back to console logging on web.
+   *
+   * @param message - Toast message text
+   * @param isLong - Whether to show a long-duration toast (default: false)
+   */
+  toast(message: string, isLong?: boolean): Promise<void>;
+
+  /**
+   * Trigger haptic feedback / vibration.
+   * Falls back to navigator.vibrate on web.
+   *
+   * @param duration - Vibration duration in ms (default: 100)
+   */
+  vibrate(duration?: number): Promise<void>;
+};
+
+/** Native clipboard helpers */
+export declare const NativeClipboard: {
+  /**
+   * Copy text to clipboard.
+   * Falls back to navigator.clipboard on web.
+   *
+   * @param text - Text to copy
+   */
+  copy(text: string): Promise<void>;
+
+  /**
+   * Read text from clipboard.
+   * Falls back to navigator.clipboard on web.
+   *
+   * @returns The clipboard text content
+   */
+  read(): Promise<string>;
+};
+
+// ============================================================================
+// Default Export
+// ============================================================================
+
+declare const native: {
+  isNativeAvailable: typeof isNativeAvailable;
+  getNative: typeof getNative;
+  getPlatform: typeof getPlatform;
+  isNative: typeof isNative;
+  createNativeStorage: typeof createNativeStorage;
+  createDeviceInfo: typeof createDeviceInfo;
+  NativeUI: typeof NativeUI;
+  NativeClipboard: typeof NativeClipboard;
+  onAppPause: typeof onAppPause;
+  onAppResume: typeof onAppResume;
+  onBackButton: typeof onBackButton;
+  onNativeReady: typeof onNativeReady;
+  exitApp: typeof exitApp;
+  minimizeApp: typeof minimizeApp;
+  clearBridgeValidationCache: typeof clearBridgeValidationCache;
+  getBridgeValidationError: typeof getBridgeValidationError;
+};
+
+export default native;

package/types/pulse.d.ts

@@ -172,11 +172,80 @@ export interface ReactiveContext {
 
 /**
  * Global reactive context
+ * @deprecated Use globalContext instead
  */
-export declare const context: ReactiveContext;
+export declare const context: ReactiveContextClass;
+
+/**
+ * Global reactive context instance
+ */
+export declare const globalContext: ReactiveContextClass;
+
+/**
+ * Reactive context class for isolated state management (testing, SSR)
+ */
+export declare class ReactiveContextClass {
+  readonly name: string;
+  currentEffect: EffectFn | null;
+  batchDepth: number;
+  pendingEffects: Set<EffectFn>;
+  isRunningEffects: boolean;
+
+  constructor(options?: { name?: string });
+
+  /** Run a function within this context */
+  run<T>(fn: () => T): T;
+
+  /** Reset context to initial state */
+  reset(): void;
+}
 
 /**
  * Reset the reactive context to initial state.
  * Use this in tests to ensure isolation between test cases.
  */
 export declare function resetContext(): void;
+
+/**
+ * Create an isolated reactive context for testing or SSR
+ */
+export declare function createContext(options?: { name?: string }): ReactiveContextClass;
+
+/**
+ * Get the currently active reactive context
+ */
+export declare function getActiveContext(): ReactiveContextClass;
+
+/**
+ * Run a function within a specific reactive context
+ */
+export declare function withContext<T>(ctx: ReactiveContextClass, fn: () => T): T;
+
+/**
+ * Effect error with context information
+ */
+export declare class EffectError extends Error {
+  readonly effectId: string;
+  readonly phase: string;
+  readonly cause: Error;
+}
+
+/**
+ * Register a global error handler for effect errors
+ * @returns Cleanup function
+ */
+export declare function onEffectError(handler: (error: EffectError) => void): () => void;
+
+/**
+ * Create a reactive prop from component props object
+ */
+export declare function useProp<T>(props: Record<string, unknown>, name: string, defaultValue?: T): Pulse<T>;
+
+/** HMR support - set the current module for effect tracking */
+export declare function setCurrentModule(moduleId: string): void;
+
+/** HMR support - clear the current module */
+export declare function clearCurrentModule(): void;
+
+/** HMR support - dispose all effects registered to a module */
+export declare function disposeModule(moduleId: string): void;

package/types/security.d.ts

@@ -0,0 +1,286 @@
+/**
+ * Pulse Security Module - Type Definitions
+ * @module pulse-js-framework/runtime/security
+ *
+ * Centralized security utilities and constants for the Pulse framework.
+ * Provides protection against:
+ * - Prototype pollution
+ * - XSS attacks
+ * - Injection attacks
+ */
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+/**
+ * Properties that could be used for prototype pollution attacks.
+ * These should never be accepted as user-provided keys.
+ *
+ * Includes: `__proto__`, `constructor`, `prototype`, `eval`, `Function`,
+ * and various property descriptor manipulation methods.
+ */
+export declare const DANGEROUS_KEYS: Set<string>;
+
+/**
+ * Event handler attributes that could execute JavaScript.
+ *
+ * Includes all standard DOM event handler attributes such as
+ * `onclick`, `onerror`, `onload`, `oninput`, etc.
+ */
+export declare const EVENT_HANDLER_ATTRS: Set<string>;
+
+/**
+ * Dangerous URL protocols that could execute JavaScript.
+ *
+ * Includes: `javascript:`, `vbscript:`, `data:`, `blob:`
+ */
+export declare const DANGEROUS_PROTOCOLS: Set<string>;
+
+/**
+ * Safe URL protocols that are allowed by default.
+ *
+ * Includes: `http:`, `https:`, `mailto:`, `tel:`, `sms:`, `ftp:`, `sftp:`
+ */
+export declare const SAFE_PROTOCOLS: Set<string>;
+
+/**
+ * Default HTML tags allowed in sanitized HTML output.
+ *
+ * Includes text formatting (`p`, `strong`, `em`, etc.), headings,
+ * lists, tables, links, images, and semantic elements.
+ */
+export declare const DEFAULT_ALLOWED_TAGS: Set<string>;
+
+/**
+ * Default attributes allowed in sanitized HTML output.
+ *
+ * Includes global attributes (`id`, `class`, `title`), link attributes
+ * (`href`, `target`, `rel`), image attributes (`src`, `alt`, `width`, `height`),
+ * table attributes (`colspan`, `rowspan`), and accessibility attributes
+ * (`role`, `aria-label`, `tabindex`, etc.).
+ */
+export declare const DEFAULT_ALLOWED_ATTRS: Set<string>;
+
+// =============================================================================
+// Options Interfaces
+// =============================================================================
+
+/**
+ * Options for sanitizing object keys against prototype pollution.
+ */
+export interface SanitizeObjectKeysOptions {
+  /**
+   * Throw an error when a dangerous key is encountered instead of
+   * silently filtering it out.
+   * @default false
+   */
+  throwOnDangerous?: boolean;
+
+  /**
+   * Log warnings to the console when dangerous keys are filtered.
+   * @default true
+   */
+  logWarnings?: boolean;
+}
+
+/**
+ * Options for HTML sanitization.
+ */
+export interface SanitizeHtmlOptions {
+  /**
+   * Set of HTML tags to allow in the output.
+   * Tags not in this set will be removed (their children are preserved).
+   * @default DEFAULT_ALLOWED_TAGS
+   */
+  allowedTags?: Set<string>;
+
+  /**
+   * Set of attributes to allow on elements.
+   * Attributes not in this set will be stripped.
+   * @default DEFAULT_ALLOWED_ATTRS
+   */
+  allowedAttrs?: Set<string>;
+
+  /**
+   * Allow `data:` URLs in `src` and `href` attributes.
+   * Even when enabled, `data:text/html` and `data:text/javascript` are blocked.
+   * @default false
+   */
+  allowDataUrls?: boolean;
+}
+
+/**
+ * Options for URL sanitization.
+ */
+export interface SanitizeUrlOptions {
+  /**
+   * Allow `data:` URLs.
+   * Even when enabled, `data:text/html` and `data:text/javascript` are blocked.
+   * @default false
+   */
+  allowData?: boolean;
+
+  /**
+   * Allow `blob:` URLs.
+   * @default false
+   */
+  allowBlob?: boolean;
+
+  /**
+   * Allow relative URLs (URLs without a protocol).
+   * @default true
+   */
+  allowRelative?: boolean;
+}
+
+// =============================================================================
+// Validation Functions
+// =============================================================================
+
+/**
+ * Check if a key is potentially dangerous (prototype pollution risk).
+ *
+ * @param key - The key to check
+ * @returns `true` if the key is in the {@link DANGEROUS_KEYS} set
+ *
+ * @example
+ * ```typescript
+ * if (isDangerousKey(userProvidedKey)) {
+ *   throw new Error('Invalid key');
+ * }
+ * ```
+ */
+export declare function isDangerousKey(key: string): boolean;
+
+/**
+ * Validate and filter an object's keys to prevent prototype pollution.
+ * Recursively processes nested objects and arrays, removing any keys
+ * found in {@link DANGEROUS_KEYS}.
+ *
+ * @template T - The type of the object being sanitized
+ * @param obj - Object to validate
+ * @param options - Sanitization options
+ * @returns Cleaned object with dangerous keys removed
+ *
+ * @example
+ * ```typescript
+ * const safeData = sanitizeObjectKeys(userInput);
+ *
+ * // Throw on dangerous keys instead of silently filtering
+ * const strict = sanitizeObjectKeys(userInput, { throwOnDangerous: true });
+ * ```
+ */
+export declare function sanitizeObjectKeys<T>(
+  obj: T,
+  options?: SanitizeObjectKeysOptions
+): T;
+
+// =============================================================================
+// HTML Sanitization
+// =============================================================================
+
+/**
+ * Escape HTML special characters to prevent XSS.
+ *
+ * Escapes the following characters: `&`, `<`, `>`, `"`, `'`
+ *
+ * @param str - String to escape (null/undefined returns empty string)
+ * @returns Escaped string safe for HTML insertion
+ *
+ * @example
+ * ```typescript
+ * const safe = escapeHtml('<script>alert("xss")</script>');
+ * // Returns: '&lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;'
+ * ```
+ */
+export declare function escapeHtml(str: string | null | undefined): string;
+
+/**
+ * Sanitize an HTML string to remove potentially dangerous content.
+ *
+ * Uses the browser's DOMParser for safe parsing when available.
+ * In non-browser environments, falls back to stripping all tags.
+ *
+ * This is a basic sanitizer. For production use with untrusted content,
+ * consider using a dedicated library like DOMPurify.
+ *
+ * @param html - HTML string to sanitize
+ * @param options - Sanitization options
+ * @returns Sanitized HTML string with only allowed tags and attributes
+ *
+ * @example
+ * ```typescript
+ * const safe = sanitizeHtml('<script>alert("xss")</script><p>Hello</p>');
+ * // Returns: '<p>Hello</p>'
+ *
+ * // Custom allowed tags
+ * const minimal = sanitizeHtml(userHtml, {
+ *   allowedTags: new Set(['p', 'br', 'strong', 'em']),
+ *   allowedAttrs: new Set(['class'])
+ * });
+ * ```
+ */
+export declare function sanitizeHtml(
+  html: string | null | undefined,
+  options?: SanitizeHtmlOptions
+): string;
+
+// =============================================================================
+// URL Sanitization
+// =============================================================================
+
+/**
+ * Sanitize a URL to prevent JavaScript execution.
+ *
+ * Blocks `javascript:` and `vbscript:` protocols. Optionally allows
+ * `data:` and `blob:` URLs. Decodes HTML entities and URI encoding
+ * to catch encoded attacks.
+ *
+ * @param url - URL to sanitize
+ * @param options - Sanitization options
+ * @returns Sanitized URL string, or `null` if the URL is dangerous
+ *
+ * @example
+ * ```typescript
+ * const safe = sanitizeUrl('javascript:alert("xss")');
+ * // Returns: null
+ *
+ * const valid = sanitizeUrl('https://example.com');
+ * // Returns: 'https://example.com'
+ *
+ * // Allow data: URLs for images
+ * const dataUrl = sanitizeUrl('data:image/png;base64,...', { allowData: true });
+ * ```
+ */
+export declare function sanitizeUrl(
+  url: string | null | undefined,
+  options?: SanitizeUrlOptions
+): string | null;
+
+// =============================================================================
+// Default Export
+// =============================================================================
+
+declare const security: {
+  // Constants
+  DANGEROUS_KEYS: typeof DANGEROUS_KEYS;
+  EVENT_HANDLER_ATTRS: typeof EVENT_HANDLER_ATTRS;
+  DANGEROUS_PROTOCOLS: typeof DANGEROUS_PROTOCOLS;
+  SAFE_PROTOCOLS: typeof SAFE_PROTOCOLS;
+  DEFAULT_ALLOWED_TAGS: typeof DEFAULT_ALLOWED_TAGS;
+  DEFAULT_ALLOWED_ATTRS: typeof DEFAULT_ALLOWED_ATTRS;
+
+  // Validation
+  isDangerousKey: typeof isDangerousKey;
+  sanitizeObjectKeys: typeof sanitizeObjectKeys;
+
+  // HTML
+  escapeHtml: typeof escapeHtml;
+  sanitizeHtml: typeof sanitizeHtml;
+
+  // URL
+  sanitizeUrl: typeof sanitizeUrl;
+};
+
+export default security;