@ccheever/exact-ibex-runtime 0.1.0

package/src/native/NativeModules.ts

@@ -0,0 +1,354 @@
+/**
+ * Native Module Interfaces
+ *
+ * These interfaces define the bridge between JavaScript and native code.
+ * The native side (Swift/Rust) must implement these for production use.
+ * JavaScript fallbacks exist for testing.
+ */
+
+// =============================================================================
+// Timer Module (MUST BE NATIVE)
+// Native implementation handles event loop integration
+// =============================================================================
+export interface NativeTimerModule {
+  setTimeout(callback: () => void, delay: number): number;
+  clearTimeout(id: number): void;
+  setInterval(callback: () => void, delay: number): number;
+  clearInterval(id: number): void;
+}
+
+// =============================================================================
+// Performance Module (MUST BE NATIVE)
+// Native implementation provides monotonic clock
+// =============================================================================
+export interface NativePerformanceModule {
+  /** High-resolution timestamp in milliseconds since timeOrigin */
+  now(): number;
+  /** Unix timestamp when the runtime started */
+  timeOrigin: number;
+}
+
+// =============================================================================
+// Crypto Module (MUST BE NATIVE)
+// Native implementation uses CryptoKit/RustCrypto for security
+// =============================================================================
+export interface NativeCryptoModule {
+  /** Fill array with cryptographically secure random bytes */
+  getRandomValues(array: Uint8Array): Uint8Array;
+  /** Generate a random UUID v4 */
+  randomUUID(): string;
+  /** SHA-256 hash */
+  sha256(data: Uint8Array): Promise<ArrayBuffer>;
+  /** SHA-384 hash */
+  sha384(data: Uint8Array): Promise<ArrayBuffer>;
+  /** SHA-512 hash */
+  sha512(data: Uint8Array): Promise<ArrayBuffer>;
+  /** SHA-1 hash (legacy, not recommended) */
+  sha1(data: Uint8Array): Promise<ArrayBuffer>;
+  /** Generic hash digest */
+  digest?: (hash: string, data: Uint8Array) => Promise<ArrayBuffer>;
+  /** Native HMAC sign helper */
+  hmacSign?: (hash: string, key: Uint8Array, data: Uint8Array) => Promise<ArrayBuffer>;
+  /** Native HMAC verify helper */
+  hmacVerify?: (hash: string, key: Uint8Array, signature: Uint8Array, data: Uint8Array) => Promise<boolean>;
+}
+
+// =============================================================================
+// Encoding Module (SHOULD BE NATIVE for large strings)
+// Native implementation is faster for large payloads
+// =============================================================================
+export interface NativeEncodingModule {
+  /** Encode string to UTF-8 bytes */
+  encodeUTF8(input: string): Uint8Array;
+  /** Decode UTF-8 bytes to string */
+  decodeUTF8(input: Uint8Array, fatal?: boolean): string;
+}
+
+// =============================================================================
+// Console Module (Native output)
+// Native handles actual logging to system console/debugger
+// =============================================================================
+export interface NativeConsoleModule {
+  log(level: string, message: string): void;
+}
+
+// =============================================================================
+// Fetch Module (MUST BE NATIVE)
+// Native implementation uses URLSession/OkHttp
+// =============================================================================
+export interface NativeFetchModule {
+  fetch(
+    url: string,
+    options: {
+      method?: string;
+      headers?: Record<string, string>;
+      body?: Uint8Array | string;
+      signal?: { aborted: boolean };
+    }
+  ): Promise<{
+    status: number;
+    statusText: string;
+    headers: Record<string, string>;
+    body: Uint8Array;
+  }>;
+}
+
+// =============================================================================
+// WebSocket Module (MUST BE NATIVE)
+// Native implementation uses platform WebSocket
+// =============================================================================
+export interface NativeWebSocketModule {
+  create(url: string, protocols?: string[], instance?: any): number; // Returns socket ID
+  send(id: number, data: string | Uint8Array): void;
+  close(id: number, code?: number, reason?: string): void;
+  pause?(id: number): void;
+  resume?(id: number): void;
+  setFlowControlled?(id: number, enabled: boolean): void;
+  // Events are dispatched via callbacks set during creation
+}
+
+// =============================================================================
+// Storage Module (MUST BE NATIVE - SQLite in Rust kernel)
+// =============================================================================
+export interface NativeStorageModule {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void; // May throw QuotaExceededError
+  removeItem(key: string): void;
+  clear(): void;
+  key(index: number): string | null;
+  length(): number;
+  estimate?(): { usage: number; quota: number } | Promise<{ usage: number; quota: number }>;
+  persist?(): boolean | Promise<boolean>;
+  persisted?(): boolean | Promise<boolean>;
+}
+
+// =============================================================================
+// File System Module (MUST BE NATIVE)
+// Sandboxed access to app directories
+// =============================================================================
+export interface NativeFileSystemModule {
+  /** Read file as bytes */
+  readFile(path: string): Promise<Uint8Array>;
+  /** Write bytes to file */
+  writeFile(path: string, data: Uint8Array): Promise<void>;
+  /** Append bytes to file */
+  appendFile(path: string, data: Uint8Array): Promise<void>;
+  /** Check if file exists */
+  exists(path: string): Promise<boolean>;
+  /** Delete file */
+  unlink(path: string): Promise<void>;
+  /** Get file metadata */
+  stat(path: string): Promise<{ size: number; mtime_ms: number; is_dir: boolean; is_file: boolean; mode: number }>;
+  /** Get file metadata (no symlink follow) */
+  lstat(path: string): Promise<{ size: number; mtime_ms: number; is_dir: boolean; is_file: boolean; is_symlink: boolean; mode: number }>;
+  /** List directory entries */
+  readdir(path: string): Promise<string[]>;
+  /** Create directory */
+  mkdir(path: string, options?: { recursive?: boolean }): Promise<void>;
+  /** Remove empty directory */
+  rmdir(path: string): Promise<void>;
+  /** Rename file or directory */
+  rename(oldPath: string, newPath: string): Promise<void>;
+  /** Copy a file */
+  copyFile(src: string, dest: string): Promise<void>;
+  /** Check access permissions */
+  access(path: string, mode?: number): Promise<void>;
+  /** Change file permissions */
+  chmod(path: string, mode: number): Promise<void>;
+  /** Resolve to canonical absolute path */
+  realpath(path: string): Promise<string>;
+  /** Create temporary directory */
+  mkdtemp(prefix: string): Promise<string>;
+  /** Get app documents directory */
+  getDocumentsDir(): string;
+  /** Get app cache directory */
+  getCacheDir(): string;
+  /** Get temp directory */
+  getTempDir(): string;
+}
+
+// =============================================================================
+// Global native module registry
+// Native side calls these setters during bootstrap
+// =============================================================================
+
+let _timerModule: NativeTimerModule | null = null;
+let _performanceModule: NativePerformanceModule | null = null;
+let _cryptoModule: NativeCryptoModule | null = null;
+let _encodingModule: NativeEncodingModule | null = null;
+let _consoleModule: NativeConsoleModule | null = null;
+let _fetchModule: NativeFetchModule | null = null;
+let _webSocketModule: NativeWebSocketModule | null = null;
+let _storageModule: NativeStorageModule | null = null;
+let _fileSystemModule: NativeFileSystemModule | null = null;
+
+export function setNativeTimerModule(module: NativeTimerModule): void {
+  _timerModule = module;
+}
+
+export function getNativeTimerModule(): NativeTimerModule | null {
+  return _timerModule;
+}
+
+export function setNativePerformanceModule(module: NativePerformanceModule): void {
+  _performanceModule = module;
+}
+
+export function getNativePerformanceModule(): NativePerformanceModule | null {
+  return _performanceModule;
+}
+
+export function setNativeCryptoModule(module: NativeCryptoModule): void {
+  _cryptoModule = module;
+}
+
+export function getNativeCryptoModule(): NativeCryptoModule | null {
+  return _cryptoModule;
+}
+
+export function setNativeEncodingModule(module: NativeEncodingModule): void {
+  _encodingModule = module;
+}
+
+export function getNativeEncodingModule(): NativeEncodingModule | null {
+  return _encodingModule;
+}
+
+export function setNativeConsoleModule(module: NativeConsoleModule): void {
+  _consoleModule = module;
+}
+
+export function getNativeConsoleModule(): NativeConsoleModule | null {
+  return _consoleModule;
+}
+
+export function setNativeFetchModule(module: NativeFetchModule): void {
+  _fetchModule = module;
+}
+
+export function getNativeFetchModule(): NativeFetchModule | null {
+  return _fetchModule;
+}
+
+export function setNativeWebSocketModule(module: NativeWebSocketModule): void {
+  _webSocketModule = module;
+}
+
+export function getNativeWebSocketModule(): NativeWebSocketModule | null {
+  return _webSocketModule;
+}
+
+export function setNativeStorageModule(module: NativeStorageModule): void {
+  _storageModule = module;
+}
+
+export function getNativeStorageModule(): NativeStorageModule | null {
+  return _storageModule;
+}
+
+export function setNativeFileSystemModule(module: NativeFileSystemModule): void {
+  _fileSystemModule = module;
+}
+
+export function getNativeFileSystemModule(): NativeFileSystemModule | null {
+  return _fileSystemModule;
+}
+
+/**
+ * Check if all required native modules are available
+ */
+export function hasRequiredNativeModules(): boolean {
+  return (
+    _timerModule !== null &&
+    _performanceModule !== null &&
+    _cryptoModule !== null &&
+    _consoleModule !== null
+  );
+}
+
+/**
+ * Get list of missing native modules
+ */
+export function getMissingNativeModules(): string[] {
+  const missing: string[] = [];
+  if (!_timerModule) missing.push("timer");
+  if (!_performanceModule) missing.push("performance");
+  if (!_cryptoModule) missing.push("crypto");
+  if (!_consoleModule) missing.push("console");
+  if (!_fetchModule) missing.push("fetch");
+  if (!_storageModule) missing.push("storage");
+  return missing;
+}
+
+// =============================================================================
+// Scheduling Module (SHOULD BE NATIVE for vsync integration)
+// =============================================================================
+export interface NativeSchedulingModule {
+  requestAnimationFrame(callback: () => void): void;
+  requestIdleCallback?(callback: (deadline: { didTimeout: boolean; timeRemaining: () => number }) => void, options?: { timeout?: number }): void;
+}
+
+let _schedulingModule: NativeSchedulingModule | null = null;
+
+export function setNativeSchedulingModule(module: NativeSchedulingModule): void {
+  _schedulingModule = module;
+}
+
+export function getNativeSchedulingModule(): NativeSchedulingModule | null {
+  return _schedulingModule;
+}
+
+/**
+ * Map of module names to their types for type-safe access
+ */
+export interface NativeModuleMap {
+  timer: NativeTimerModule;
+  performance: NativePerformanceModule;
+  crypto: NativeCryptoModule;
+  encoding: NativeEncodingModule;
+  console: NativeConsoleModule;
+  fetch: NativeFetchModule;
+  websocket: NativeWebSocketModule;
+  storage: NativeStorageModule;
+  filesystem: NativeFileSystemModule;
+  scheduling: NativeSchedulingModule;
+}
+
+/**
+ * Type-safe getter for native modules by name.
+ * Returns null if the module is not available.
+ * 
+ * @example
+ * const crypto = getNativeModule('crypto');
+ * if (crypto) {
+ *   crypto.getRandomValues(new Uint8Array(16)); // Type-safe!
+ * }
+ */
+export function getNativeModule<K extends keyof NativeModuleMap>(
+  name: K
+): NativeModuleMap[K] | null {
+  switch (name) {
+    case 'timer':
+      return _timerModule as NativeModuleMap[K] | null;
+    case 'performance':
+      return _performanceModule as NativeModuleMap[K] | null;
+    case 'crypto':
+      return _cryptoModule as NativeModuleMap[K] | null;
+    case 'encoding':
+      return _encodingModule as NativeModuleMap[K] | null;
+    case 'console':
+      return _consoleModule as NativeModuleMap[K] | null;
+    case 'fetch':
+      return _fetchModule as NativeModuleMap[K] | null;
+    case 'websocket':
+      return _webSocketModule as NativeModuleMap[K] | null;
+    case 'storage':
+      return _storageModule as NativeModuleMap[K] | null;
+    case 'filesystem':
+      return _fileSystemModule as NativeModuleMap[K] | null;
+    case 'scheduling':
+      return _schedulingModule as NativeModuleMap[K] | null;
+    default:
+      return null;
+  }
+}

package/src/native/index.ts

@@ -0,0 +1 @@
+export * from "./NativeModules";

package/src/navigator/Navigator.ts

@@ -0,0 +1,351 @@
+/**
+ * Navigator implementation for Ibex runtime
+ * 
+ * Provides browser-like navigator object with device/platform info.
+ * @see https://html.spec.whatwg.org/multipage/system-state.html#the-navigator-object
+ */
+
+import { USER_AGENT } from '../identity.generated';
+import { LockManager } from '../locks/LockManager';
+import { Clipboard } from '../clipboard/Clipboard';
+import { StorageManager } from '../storage/StorageManager';
+import { getGeolocation } from '../location';
+import { getExactLocaleSnapshot } from '../locale';
+
+function runtimePlatform(): string {
+  const g = globalThis as any;
+  if (typeof g.__exactPlatform === 'string' && g.__exactPlatform.length > 0) {
+    return g.__exactPlatform.toLowerCase();
+  }
+  if (
+    g.process &&
+    typeof g.process.platform === 'string' &&
+    g.process.platform.length > 0
+  ) {
+    return g.process.platform.toLowerCase();
+  }
+  return 'ios';
+}
+
+function platformLabelForNavigator(): string {
+  const p = runtimePlatform();
+  if (p === 'android') return 'Android';
+  if (p === 'web' || p === 'browser') return 'MacIntel';
+  if (p === 'macos' || p === 'mac' || p === 'darwin') return 'MacIntel';
+  if (p === 'windows' || p === 'win32') return 'Win32';
+  if (p === 'linux') return 'Linux x86_64';
+  return 'iPhone';
+}
+
+function platformLabelForAppVersion(): string {
+  const p = runtimePlatform();
+  if (p === 'android') return 'Android';
+  if (p === 'web' || p === 'browser') return 'Macintosh';
+  if (p === 'macos' || p === 'mac' || p === 'darwin') return 'Macintosh';
+  if (p === 'windows' || p === 'win32') return 'Windows';
+  if (p === 'linux') return 'Linux';
+  return 'iOS';
+}
+
+function callNumericHostFunction(name: string): number | null {
+  const fn = (globalThis as any)[name];
+  if (typeof fn !== 'function') return null;
+  try {
+    const value = Number(fn());
+    return Number.isFinite(value) && value > 0 ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+function approximateDeviceMemory(totalBytes: number | null): number {
+  if (totalBytes == null) return 4;
+  const gib = totalBytes / (1024 * 1024 * 1024);
+  const buckets = [0.25, 0.5, 1, 2, 4, 8];
+  let selected = buckets[0];
+  for (const bucket of buckets) {
+    if (gib >= bucket) {
+      selected = bucket;
+    }
+  }
+  return selected;
+}
+
+function readOnlineStatus(): boolean {
+  const g = globalThis as any;
+  if (typeof g.__exactGetOnlineStatus === 'function') {
+    try {
+      return g.__exactGetOnlineStatus() !== false;
+    } catch {
+      return true;
+    }
+  }
+  if (typeof g.__exactGetNetworkInterfaces !== 'function') {
+    return true;
+  }
+  try {
+    const interfaces = g.__exactGetNetworkInterfaces();
+    if (!interfaces || typeof interfaces !== 'object') {
+      return true;
+    }
+    for (const entries of Object.values(interfaces)) {
+      if (!Array.isArray(entries)) continue;
+      for (const entry of entries) {
+        if (hasUsableNetworkAddress(entry)) {
+          return true;
+        }
+      }
+    }
+    return false;
+  } catch {
+    return true;
+  }
+}
+
+function hasUsableNetworkAddress(entry: unknown): boolean {
+  if (!entry || typeof entry !== 'object') return false;
+  const record = entry as { address?: unknown; internal?: unknown };
+  if (record.internal === true || typeof record.address !== 'string') {
+    return false;
+  }
+  return record.address.length > 0 &&
+    record.address !== '0.0.0.0' &&
+    record.address !== '::';
+}
+
+/**
+ * Navigator provides information about the runtime environment.
+ */
+export class Navigator {
+  readonly __exactNavigator = true;
+
+  private _locks: LockManager | null = null;
+  private _storage: StorageManager | null = null;
+  private _clipboard: Clipboard | null = null;
+  private _geolocation: Geolocation | null = null;
+  /**
+   * User agent string identifying the runtime.
+   * Format: "Exact/{version} ({platform}; {engine})"
+   */
+  get userAgent(): string {
+    return USER_AGENT;
+  }
+
+  /**
+   * Vendor string (always "Exact" for this runtime).
+   */
+  get vendor(): string {
+    return 'Exact';
+  }
+
+  /**
+   * Vendor sub-version (empty string).
+   */
+  get vendorSub(): string {
+    return '';
+  }
+
+  /**
+   * Product name (always "Exact").
+   */
+  get product(): string {
+    return 'Exact';
+  }
+
+  /**
+   * Product sub-version (empty string).
+   */
+  get productSub(): string {
+    return '';
+  }
+
+  /**
+   * App name for compatibility (always "Netscape" per spec).
+   */
+  get appName(): string {
+    return 'Netscape';
+  }
+
+  /**
+   * App code name for compatibility.
+   */
+  get appCodeName(): string {
+    return 'Mozilla';
+  }
+
+  /**
+   * App version string.
+   */
+  get appVersion(): string {
+    return `5.0 (${platformLabelForAppVersion()})`;
+  }
+
+  /**
+   * Platform identifier.
+   * Returns "iPhone", "Android", "MacIntel", etc. depending on the runtime platform.
+   */
+  get platform(): string {
+    return platformLabelForNavigator();
+  }
+
+  /**
+   * Primary language preference.
+   * Returns the device's preferred language via native bridge if available.
+   */
+  get language(): string {
+    const exactLocale = getExactLocaleSnapshot();
+    if (exactLocale.tag.length > 0) {
+      return exactLocale.tag;
+    }
+
+    const g = globalThis as any;
+    if (typeof g.__exactLocale === 'string' && g.__exactLocale) {
+      return g.__exactLocale;
+    }
+    if (typeof g.__exactLanguage === 'string' && g.__exactLanguage) {
+      return g.__exactLanguage;
+    }
+    return 'en-US';
+  }
+
+  /**
+   * Array of preferred languages.
+   */
+  get languages(): readonly string[] {
+    const exactLocale = getExactLocaleSnapshot();
+    if (exactLocale.tags.length > 0) {
+      return exactLocale.tags;
+    }
+
+    const lang = this.language;
+    const base = lang.includes('-') ? lang.split('-')[0] : lang;
+    if (base !== lang) {
+      return Object.freeze([lang, base]);
+    }
+    return Object.freeze([lang]);
+  }
+
+  /**
+   * Whether the device is online.
+   */
+  get onLine(): boolean {
+    // @ref LLP 0008#os-info - Android navigator online status uses native network interface data.
+    return readOnlineStatus();
+  }
+
+  /**
+   * Number of logical processors available.
+   */
+  get hardwareConcurrency(): number {
+    // @ref LLP 0008#os-info - Android navigator device hints use native sysconf/sysinfo values.
+    const nativeCount = callNumericHostFunction('__exactGetCpuCount');
+    return nativeCount == null ? 4 : Math.max(1, Math.floor(nativeCount));
+  }
+
+  /**
+   * Maximum touch points supported by the device.
+   */
+  get maxTouchPoints(): number {
+    // Mobile devices support multi-touch
+    return 5;
+  }
+
+  /**
+   * Whether cookies are enabled.
+   * Always returns true in Exact (we support cookies in fetch).
+   */
+  get cookieEnabled(): boolean {
+    return true;
+  }
+
+  /**
+   * Whether Java is enabled (always false).
+   */
+  javaEnabled(): boolean {
+    return false;
+  }
+
+  /**
+   * Device memory in GB (approximate).
+   * Note: This is a hint, not exact value.
+   */
+  get deviceMemory(): number {
+    // @ref LLP 0008#os-info - Android navigator device hints use native sysconf/sysinfo values.
+    return approximateDeviceMemory(callNumericHostFunction('__exactGetTotalMem'));
+  }
+
+  /**
+   * PDF viewer support (always false in native app).
+   */
+  get pdfViewerEnabled(): boolean {
+    return false;
+  }
+
+  /**
+   * Web driver status (always false).
+   */
+  get webdriver(): boolean {
+    return false;
+  }
+
+  /**
+   * Clipboard API for reading and writing clipboard data.
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/Navigator/clipboard
+   */
+  get clipboard(): Clipboard {
+    if (!this._clipboard) {
+      this._clipboard = new Clipboard();
+    }
+    return this._clipboard;
+  }
+
+  /**
+   * Geolocation API installed from the runtime location backend.
+   */
+  get geolocation(): Geolocation {
+    if (!this._geolocation) {
+      this._geolocation = getGeolocation();
+    }
+    return this._geolocation;
+  }
+
+  /**
+   * Web Locks API for coordinating concurrent access.
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/Navigator/locks
+   */
+  get locks(): LockManager {
+    if (!this._locks) {
+      this._locks = new LockManager();
+    }
+    return this._locks;
+  }
+
+  /**
+   * Storage manager for quota and persistence info.
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/Navigator/storage
+   */
+  get storage(): StorageManager {
+    if (!this._storage) {
+      this._storage = new StorageManager();
+    }
+    return this._storage;
+  }
+
+  get [Symbol.toStringTag](): string {
+    return 'Navigator';
+  }
+}
+
+// Singleton navigator instance
+let _navigator: Navigator | null = null;
+
+export function getNavigator(): Navigator {
+  if (!_navigator) {
+    _navigator = new Navigator();
+  }
+  return _navigator;
+}
+
+export const navigator = getNavigator();
+
+export default Navigator;

package/src/navigator/index.ts

@@ -0,0 +1 @@
+export { Navigator, navigator, getNavigator } from './Navigator';