feat: add browser environment compatibility support

- Remove Node.js-specific imports from module level
- Use dynamic imports with isNode() environment checks
- Wrap all file system operations in conditional blocks
- Add fallback values for browser environments
- Ensure code works in both Node.js and browser contexts

This change enables Brainy to run in browser environments without
requiring Node.js polyfills, making it truly universal.

Co-Authored-By: dpsifr <noreply@dpsifr.com>

src/utils/version.ts

@@ -2,32 +2,89 @@
  * Version utilities for Brainy
  */
 
-import { readFileSync } from 'node:fs'
-import { join, dirname } from 'node:path'
-import { fileURLToPath } from 'node:url'
+import { isNode } from './environment.js'
 
-// Get package.json path relative to this file
-const __filename = fileURLToPath(import.meta.url)
-const __dirname = dirname(__filename)
-const packageJsonPath = join(__dirname, '../../package.json')
+// Default version - this should be replaced at build time
+const DEFAULT_VERSION = '3.5.1'
 
 let cachedVersion: string | null = null
+let versionPromise: Promise<string> | null = null
+
+/**
+ * Load version from package.json in Node.js environment
+ */
+async function loadVersionFromPackageJson(): Promise<string> {
+  if (!isNode()) {
+    return DEFAULT_VERSION
+  }
+
+  try {
+    // Dynamic imports for Node.js modules - modern approach
+    const [{ readFileSync }, { join, dirname }, { fileURLToPath }] = await Promise.all([
+      import('node:fs'),
+      import('node:path'),
+      import('node:url')
+    ])
+
+    const __filename = fileURLToPath(import.meta.url)
+    const __dirname = dirname(__filename)
+    const packageJsonPath = join(__dirname, '../../package.json')
+
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8'))
+    return packageJson.version || DEFAULT_VERSION
+  } catch (error) {
+    // Silently fall back to default version
+    return DEFAULT_VERSION
+  }
+}
 
 /**
  * Get the current Brainy package version
+ * In Node.js, attempts to read from package.json
+ * In browser, returns the default version
  * @returns The current version string
  */
 export function getBrainyVersion(): string {
-  if (!cachedVersion) {
-    try {
-      const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8'))
-      cachedVersion = packageJson.version
-    } catch {
-      // Fallback version if package.json can't be read
-      cachedVersion = '2.7.1'
-    }
+  if (cachedVersion) {
+    return cachedVersion
   }
-  return cachedVersion!
+
+  // In browser or if we need immediate response, return default
+  if (!isNode()) {
+    cachedVersion = DEFAULT_VERSION
+    return cachedVersion
+  }
+
+  // For Node.js, try to load synchronously first time
+  // This is a compromise for backward compatibility
+  if (!versionPromise) {
+    versionPromise = loadVersionFromPackageJson()
+    versionPromise.then(version => {
+      cachedVersion = version
+    })
+  }
+
+  // Return default while loading
+  return cachedVersion || DEFAULT_VERSION
+}
+
+/**
+ * Get the current Brainy package version asynchronously
+ * Guaranteed to attempt loading from package.json in Node.js
+ * @returns Promise resolving to the current version string
+ */
+export async function getBrainyVersionAsync(): Promise<string> {
+  if (cachedVersion) {
+    return cachedVersion
+  }
+
+  if (!versionPromise) {
+    versionPromise = loadVersionFromPackageJson()
+  }
+
+  const version = await versionPromise
+  cachedVersion = version
+  return version
 }
 
 /**