expo-tiddlywiki-filesystem-android-external-storage 2.2.12 → 2.2.13

package/build/index.js

@@ -18,8 +18,8 @@ let _module;
 function getNativeModule() {
     if (_module)
         return _module;
-    if (Platform.OS !== 'android') {
-        throw new Error('ExternalStorage native module is only available on Android');
+    if (Platform.OS !== 'android' && Platform.OS !== 'ios') {
+        throw new Error('ExternalStorage native module is only available on Android and iOS');
     }
     // eslint-disable-next-line @typescript-eslint/no-require-imports
     const { requireNativeModule } = require('expo-modules-core');

package/build/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAExC,IAAI,OAA2C,CAAC;AAEhD;;;;GAIG;AACH,SAAS,eAAe;IACtB,IAAI,OAAO;QAAE,OAAO,OAAO,CAAC;IAC5B,IAAI,QAAQ,CAAC,EAAE,KAAK,SAAS,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CAAC,4DAA4D,CAAC,CAAC;IAChF,CAAC;IACD,iEAAiE;IACjE,MAAM,EAAE,mBAAmB,EAAE,GAAG,OAAO,CAAC,mBAAmB,CAAsE,CAAC;IAClI,OAAO,GAAG,mBAAmB,CAAC,iBAAiB,CAAC,CAAC;IACjD,OAAO,OAAO,CAAC;AACjB,CAAC;AAsLD,MAAM,CAAC,MAAM,eAAe,GAA2B,IAAI,KAAK,CAAC,EAA4B,EAAE;IAC7F,GAAG,CAAC,OAAO,EAAE,QAAQ;QACnB,MAAM,GAAG,GAAG,eAAe,EAAE,CAAC;QAC9B,OAAQ,GAAmD,CAAC,QAAQ,CAAC,CAAC;IACxE,CAAC;CACF,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,SAAiB;IAC3C,IAAI,SAAS,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QACpC,OAAO,SAAS,CAAC,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAC3C,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC","sourcesContent":["/**\n * TypeScript bindings for the ExternalStorage native module.\n *\n * This module uses raw java.io.File on Android to bypass Expo FileSystem's\n * directory whitelist. It allows reading/writing to shared external storage\n * when MANAGE_EXTERNAL_STORAGE permission is granted.\n *\n * All path arguments are plain filesystem paths (e.g. \"/storage/emulated/0/Documents/TidGi/\").\n * Do NOT pass file:// URIs — strip the scheme before calling.\n */\nimport { Platform } from 'react-native';\n\nlet _module: IExternalStorageModule | undefined;\n\n/**\n * Lazily load the native module. Wrapped in a function so that the app does NOT\n * crash at import time if the native module is missing (e.g. on iOS or when the\n * binary was built without it).\n */\nfunction getNativeModule(): IExternalStorageModule {\n  if (_module) return _module;\n  if (Platform.OS !== 'android') {\n    throw new Error('ExternalStorage native module is only available on Android');\n  }\n  // eslint-disable-next-line @typescript-eslint/no-require-imports\n  const { requireNativeModule } = require('expo-modules-core') as { requireNativeModule: (name: string) => IExternalStorageModule };\n  _module = requireNativeModule('ExternalStorage');\n  return _module;\n}\n\ninterface FileInfo {\n  exists: boolean;\n  isDirectory: boolean;\n  size: number;\n  /** Milliseconds since epoch */\n  modificationTime: number;\n}\n\ninterface BatchWriteResult {\n  writtenCount: number;\n}\n\ninterface HttpPostToFileResult {\n  statusCode: number;\n  headers: Record<string, string>;\n  bytesWritten: number;\n}\n\ninterface DownloadFileResumableResult {\n  statusCode: number;\n  /** Final size of the file on disk after download */\n  totalBytes: number;\n  /** true if the download resumed from a partial file (HTTP 206) */\n  resumed: boolean;\n}\n\ninterface ExtractTarResult {\n  filesExtracted: number;\n}\n\ninterface ReadFileChunkResult {\n  /** Base64-encoded chunk data */\n  data: string;\n  bytesRead: number;\n}\n\ninterface IExternalStorageModule {\n  exists(path: string): Promise<boolean>;\n  getInfo(path: string): Promise<FileInfo>;\n\n  mkdir(path: string): Promise<void>;\n  readDir(path: string): Promise<string[]>;\n  /** Recursively list all files under a directory, returning relative paths. Skips .git etc. */\n  readDirRecursive(path: string): Promise<string[]>;\n  rmdir(path: string): Promise<void>;\n\n  readFileUtf8(path: string): Promise<string>;\n  readFileBase64(path: string): Promise<string>;\n  writeFileUtf8(path: string, content: string): Promise<void>;\n  writeFileBase64(path: string, base64Content: string): Promise<void>;\n  /**\n   * Append a Base64-encoded chunk to a file, optionally truncating first.\n   *\n   * Designed for streaming large writes from JS in bounded-memory chunks\n   * (e.g. 512 KB each) so the JVM never allocates the full file content,\n   * avoiding OOM on 50+ MB git pack files.\n   *\n   * @param truncateFirst Pass `true` for the first chunk to create/truncate\n   *                      the file, then `false` for subsequent chunks.\n   */\n  appendFileBase64(path: string, base64Content: string, truncateFirst: boolean): Promise<void>;\n  writeFilesBase64(paths: string[], base64Contents: string[]): Promise<BatchWriteResult>;\n  deleteFile(path: string): Promise<void>;\n\n  isExternalStorageWritable(): Promise<boolean>;\n  getExternalStorageDirectory(): Promise<string>;\n  /** Android 11+ (API 30): check if MANAGE_EXTERNAL_STORAGE is granted. Pre-30 returns true. */\n  isExternalStorageManager(): Promise<boolean>;\n\n  /**\n   * HTTP POST with the response body streamed directly to a file on disk,\n   * **never buffering the full response in JVM/Hermes heap**.\n   *\n   * Designed for git-upload-pack which can return 100+ MB packfiles.\n   *\n   * @param url         Target URL\n   * @param headers     HTTP headers as `{ key: value }`\n   * @param bodyBase64  Request body encoded as Base64 (binary git protocol data)\n   * @param destPath    Plain filesystem path to write the response body to\n   * @param contentType MIME type for the request body\n   */\n  httpPostToFile(\n    url: string,\n    headers: Record<string, string>,\n    bodyBase64: string,\n    destPath: string,\n    contentType: string,\n  ): Promise<HttpPostToFileResult>;\n\n  /**\n   * Read a chunk of a file starting at `offset` for up to `length` bytes.\n   * Returns Base64-encoded data and actual bytes read.\n   *\n   * Use this to stream a large file into JS in bounded-memory chunks.\n   */\n  readFileChunk(path: string, offset: number, length: number): Promise<ReadFileChunkResult>;\n\n  /**\n   * Download a file via HTTP GET with resumable download support.\n   *\n   * If `destPath` already exists on disk (from a previous interrupted download),\n   * sends `Range: bytes=<existingSize>-` to resume. The server must respond\n   * with 206 Partial Content for resume to work; otherwise the file is\n   * overwritten from scratch (200 response).\n   *\n   * @param url       Target URL\n   * @param headers   Extra HTTP headers (e.g. Authorization, ETag)\n   * @param destPath  Plain filesystem path for the downloaded file\n   */\n  downloadFileResumable(\n    url: string,\n    headers: Record<string, string>,\n    destPath: string,\n  ): Promise<DownloadFileResumableResult>;\n\n  /**\n   * Extract an uncompressed tar archive to a destination directory.\n   * Uses a native tar parser — no third-party dependency.\n   * Supports POSIX ustar and GNU long-name extensions.\n   * Validates paths to prevent directory traversal attacks.\n   *\n   * @param tarPath  Path to the .tar file\n   * @param destDir  Destination directory (created if needed)\n   */\n  extractTar(tarPath: string, destDir: string): Promise<ExtractTarResult>;\n\n  /**\n   * Parse a batch of TiddlyWiki tiddler files entirely in native Kotlin.\n   *\n   * This is the critical performance optimization for initial wiki loading:\n   * a single bridge call processes 100+ files in parallel, returning a\n   * ready-to-inject JSON array string. Eliminates per-file bridge round-trips.\n   *\n   * Supports .tid, .json, and .meta files. Applies skinny logic:\n   * - System tiddlers ($:/) → always full text\n   * - Plugins (application/json + plugin-type) → always full text\n   * - Module tiddlers (module-type) → always full text\n   * - Small tiddlers (< 10KB body) → full text\n   * - Large user tiddlers → skinny (_is_skinny: \"yes\", text omitted)\n   *\n   * @param filePaths     Array of absolute filesystem paths\n   * @param quickLoadMode If true, all tiddlers returned as skinny\n   * @returns JSON string: serialized array of tiddler field objects\n   */\n  batchParseTidFiles(filePaths: string[], quickLoadMode: boolean): Promise<string>;\n\n  /**\n   * Lightweight native git status using direct git-index parsing.\n   *\n   * Parses `.git/index` to get tracked files and their stat-cache entries,\n   * then compares against the working directory using file size and mtime.\n   * Orders of magnitude faster than isomorphic-git's `statusMatrix` because:\n   * - No JS↔Native bridge round-trips per file\n   * - Uses stat-cache (size+mtime) instead of SHA-1 re-hashing\n   * - Parallel file walking in Java\n   *\n   * @param gitRootDir The root directory of the git repository (parent of .git/)\n   * @returns JSON string: `[{\"path\":\"tiddlers/foo.tid\",\"type\":\"add\"|\"modify\"|\"delete\"}, ...]`\n   */\n  gitStatus(gitRootDir: string): Promise<string>;\n\n  /**\n   * Debug function returning diagnostic info about the git repository state.\n   * @returns JSON string with root/gitDir/index existence and git dir children\n   */\n  gitStatusDebug(gitRootDir: string): Promise<string>;\n\n  /**\n   * Build `.git/index` natively by reading the HEAD tree from pack files,\n   * stat'ing all files on disk, and writing a v2 index file.\n   *\n   * This is used after archive clone where TidGi Desktop's tar export\n   * doesn't include `.git/index`.\n   *\n   * @param gitRootDir The root directory of the git repository (parent of .git/)\n   * @returns JSON string: `{\"ok\":true,\"entries\":N,\"indexSize\":M}` or `{\"ok\":false,\"error\":\"...\"}`\n   */\n  buildGitIndex(gitRootDir: string): Promise<string>;\n}\n\nexport const ExternalStorage: IExternalStorageModule = new Proxy({} as IExternalStorageModule, {\n  get(_target, property) {\n    const mod = getNativeModule();\n    return (mod as unknown as Record<string | symbol, unknown>)[property];\n  },\n});\n\n/**\n * Strip file:// prefix from a URI to produce a plain filesystem path.\n * Safe to call on paths that are already plain.\n */\nexport function toPlainPath(uriOrPath: string): string {\n  if (uriOrPath.startsWith('file://')) {\n    return uriOrPath.slice('file://'.length);\n  }\n  return uriOrPath;\n}\n\nexport type { BatchWriteResult, DownloadFileResumableResult, ExtractTarResult, FileInfo, HttpPostToFileResult, IExternalStorageModule, ReadFileChunkResult };\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAExC,IAAI,OAA2C,CAAC;AAEhD;;;;GAIG;AACH,SAAS,eAAe;IACtB,IAAI,OAAO;QAAE,OAAO,OAAO,CAAC;IAC5B,IAAI,QAAQ,CAAC,EAAE,KAAK,SAAS,IAAI,QAAQ,CAAC,EAAE,KAAK,KAAK,EAAE,CAAC;QACvD,MAAM,IAAI,KAAK,CAAC,oEAAoE,CAAC,CAAC;IACxF,CAAC;IACD,iEAAiE;IACjE,MAAM,EAAE,mBAAmB,EAAE,GAAG,OAAO,CAAC,mBAAmB,CAAsE,CAAC;IAClI,OAAO,GAAG,mBAAmB,CAAC,iBAAiB,CAAC,CAAC;IACjD,OAAO,OAAO,CAAC;AACjB,CAAC;AAsLD,MAAM,CAAC,MAAM,eAAe,GAA2B,IAAI,KAAK,CAAC,EAA4B,EAAE;IAC7F,GAAG,CAAC,OAAO,EAAE,QAAQ;QACnB,MAAM,GAAG,GAAG,eAAe,EAAE,CAAC;QAC9B,OAAQ,GAAmD,CAAC,QAAQ,CAAC,CAAC;IACxE,CAAC;CACF,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,SAAiB;IAC3C,IAAI,SAAS,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QACpC,OAAO,SAAS,CAAC,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAC3C,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC","sourcesContent":["/**\n * TypeScript bindings for the ExternalStorage native module.\n *\n * This module uses raw java.io.File on Android to bypass Expo FileSystem's\n * directory whitelist. It allows reading/writing to shared external storage\n * when MANAGE_EXTERNAL_STORAGE permission is granted.\n *\n * All path arguments are plain filesystem paths (e.g. \"/storage/emulated/0/Documents/TidGi/\").\n * Do NOT pass file:// URIs — strip the scheme before calling.\n */\nimport { Platform } from 'react-native';\n\nlet _module: IExternalStorageModule | undefined;\n\n/**\n * Lazily load the native module. Wrapped in a function so that the app does NOT\n * crash at import time if the native module is missing (e.g. on iOS or when the\n * binary was built without it).\n */\nfunction getNativeModule(): IExternalStorageModule {\n  if (_module) return _module;\n  if (Platform.OS !== 'android' && Platform.OS !== 'ios') {\n    throw new Error('ExternalStorage native module is only available on Android and iOS');\n  }\n  // eslint-disable-next-line @typescript-eslint/no-require-imports\n  const { requireNativeModule } = require('expo-modules-core') as { requireNativeModule: (name: string) => IExternalStorageModule };\n  _module = requireNativeModule('ExternalStorage');\n  return _module;\n}\n\ninterface FileInfo {\n  exists: boolean;\n  isDirectory: boolean;\n  size: number;\n  /** Milliseconds since epoch */\n  modificationTime: number;\n}\n\ninterface BatchWriteResult {\n  writtenCount: number;\n}\n\ninterface HttpPostToFileResult {\n  statusCode: number;\n  headers: Record<string, string>;\n  bytesWritten: number;\n}\n\ninterface DownloadFileResumableResult {\n  statusCode: number;\n  /** Final size of the file on disk after download */\n  totalBytes: number;\n  /** true if the download resumed from a partial file (HTTP 206) */\n  resumed: boolean;\n}\n\ninterface ExtractTarResult {\n  filesExtracted: number;\n}\n\ninterface ReadFileChunkResult {\n  /** Base64-encoded chunk data */\n  data: string;\n  bytesRead: number;\n}\n\ninterface IExternalStorageModule {\n  exists(path: string): Promise<boolean>;\n  getInfo(path: string): Promise<FileInfo>;\n\n  mkdir(path: string): Promise<void>;\n  readDir(path: string): Promise<string[]>;\n  /** Recursively list all files under a directory, returning relative paths. Skips .git etc. */\n  readDirRecursive(path: string): Promise<string[]>;\n  rmdir(path: string): Promise<void>;\n\n  readFileUtf8(path: string): Promise<string>;\n  readFileBase64(path: string): Promise<string>;\n  writeFileUtf8(path: string, content: string): Promise<void>;\n  writeFileBase64(path: string, base64Content: string): Promise<void>;\n  /**\n   * Append a Base64-encoded chunk to a file, optionally truncating first.\n   *\n   * Designed for streaming large writes from JS in bounded-memory chunks\n   * (e.g. 512 KB each) so the JVM never allocates the full file content,\n   * avoiding OOM on 50+ MB git pack files.\n   *\n   * @param truncateFirst Pass `true` for the first chunk to create/truncate\n   *                      the file, then `false` for subsequent chunks.\n   */\n  appendFileBase64(path: string, base64Content: string, truncateFirst: boolean): Promise<void>;\n  writeFilesBase64(paths: string[], base64Contents: string[]): Promise<BatchWriteResult>;\n  deleteFile(path: string): Promise<void>;\n\n  isExternalStorageWritable(): Promise<boolean>;\n  getExternalStorageDirectory(): Promise<string>;\n  /** Android 11+ (API 30): check if MANAGE_EXTERNAL_STORAGE is granted. Pre-30 returns true. */\n  isExternalStorageManager(): Promise<boolean>;\n\n  /**\n   * HTTP POST with the response body streamed directly to a file on disk,\n   * **never buffering the full response in JVM/Hermes heap**.\n   *\n   * Designed for git-upload-pack which can return 100+ MB packfiles.\n   *\n   * @param url         Target URL\n   * @param headers     HTTP headers as `{ key: value }`\n   * @param bodyBase64  Request body encoded as Base64 (binary git protocol data)\n   * @param destPath    Plain filesystem path to write the response body to\n   * @param contentType MIME type for the request body\n   */\n  httpPostToFile(\n    url: string,\n    headers: Record<string, string>,\n    bodyBase64: string,\n    destPath: string,\n    contentType: string,\n  ): Promise<HttpPostToFileResult>;\n\n  /**\n   * Read a chunk of a file starting at `offset` for up to `length` bytes.\n   * Returns Base64-encoded data and actual bytes read.\n   *\n   * Use this to stream a large file into JS in bounded-memory chunks.\n   */\n  readFileChunk(path: string, offset: number, length: number): Promise<ReadFileChunkResult>;\n\n  /**\n   * Download a file via HTTP GET with resumable download support.\n   *\n   * If `destPath` already exists on disk (from a previous interrupted download),\n   * sends `Range: bytes=<existingSize>-` to resume. The server must respond\n   * with 206 Partial Content for resume to work; otherwise the file is\n   * overwritten from scratch (200 response).\n   *\n   * @param url       Target URL\n   * @param headers   Extra HTTP headers (e.g. Authorization, ETag)\n   * @param destPath  Plain filesystem path for the downloaded file\n   */\n  downloadFileResumable(\n    url: string,\n    headers: Record<string, string>,\n    destPath: string,\n  ): Promise<DownloadFileResumableResult>;\n\n  /**\n   * Extract an uncompressed tar archive to a destination directory.\n   * Uses a native tar parser — no third-party dependency.\n   * Supports POSIX ustar and GNU long-name extensions.\n   * Validates paths to prevent directory traversal attacks.\n   *\n   * @param tarPath  Path to the .tar file\n   * @param destDir  Destination directory (created if needed)\n   */\n  extractTar(tarPath: string, destDir: string): Promise<ExtractTarResult>;\n\n  /**\n   * Parse a batch of TiddlyWiki tiddler files entirely in native Kotlin.\n   *\n   * This is the critical performance optimization for initial wiki loading:\n   * a single bridge call processes 100+ files in parallel, returning a\n   * ready-to-inject JSON array string. Eliminates per-file bridge round-trips.\n   *\n   * Supports .tid, .json, and .meta files. Applies skinny logic:\n   * - System tiddlers ($:/) → always full text\n   * - Plugins (application/json + plugin-type) → always full text\n   * - Module tiddlers (module-type) → always full text\n   * - Small tiddlers (< 10KB body) → full text\n   * - Large user tiddlers → skinny (_is_skinny: \"yes\", text omitted)\n   *\n   * @param filePaths     Array of absolute filesystem paths\n   * @param quickLoadMode If true, all tiddlers returned as skinny\n   * @returns JSON string: serialized array of tiddler field objects\n   */\n  batchParseTidFiles(filePaths: string[], quickLoadMode: boolean): Promise<string>;\n\n  /**\n   * Lightweight native git status using direct git-index parsing.\n   *\n   * Parses `.git/index` to get tracked files and their stat-cache entries,\n   * then compares against the working directory using file size and mtime.\n   * Orders of magnitude faster than isomorphic-git's `statusMatrix` because:\n   * - No JS↔Native bridge round-trips per file\n   * - Uses stat-cache (size+mtime) instead of SHA-1 re-hashing\n   * - Parallel file walking in Java\n   *\n   * @param gitRootDir The root directory of the git repository (parent of .git/)\n   * @returns JSON string: `[{\"path\":\"tiddlers/foo.tid\",\"type\":\"add\"|\"modify\"|\"delete\"}, ...]`\n   */\n  gitStatus(gitRootDir: string): Promise<string>;\n\n  /**\n   * Debug function returning diagnostic info about the git repository state.\n   * @returns JSON string with root/gitDir/index existence and git dir children\n   */\n  gitStatusDebug(gitRootDir: string): Promise<string>;\n\n  /**\n   * Build `.git/index` natively by reading the HEAD tree from pack files,\n   * stat'ing all files on disk, and writing a v2 index file.\n   *\n   * This is used after archive clone where TidGi Desktop's tar export\n   * doesn't include `.git/index`.\n   *\n   * @param gitRootDir The root directory of the git repository (parent of .git/)\n   * @returns JSON string: `{\"ok\":true,\"entries\":N,\"indexSize\":M}` or `{\"ok\":false,\"error\":\"...\"}`\n   */\n  buildGitIndex(gitRootDir: string): Promise<string>;\n}\n\nexport const ExternalStorage: IExternalStorageModule = new Proxy({} as IExternalStorageModule, {\n  get(_target, property) {\n    const mod = getNativeModule();\n    return (mod as unknown as Record<string | symbol, unknown>)[property];\n  },\n});\n\n/**\n * Strip file:// prefix from a URI to produce a plain filesystem path.\n * Safe to call on paths that are already plain.\n */\nexport function toPlainPath(uriOrPath: string): string {\n  if (uriOrPath.startsWith('file://')) {\n    return uriOrPath.slice('file://'.length);\n  }\n  return uriOrPath;\n}\n\nexport type { BatchWriteResult, DownloadFileResumableResult, ExtractTarResult, FileInfo, HttpPostToFileResult, IExternalStorageModule, ReadFileChunkResult };\n"]}

package/expo-module.config.json

@@ -1,6 +1,9 @@
 {
-  "platforms": ["android"],
+  "platforms": ["android", "ios"],
   "android": {
     "modules": ["expo.modules.externalstorage.ExternalStorageModule"]
+  },
+  "ios": {
+    "modules": ["ExternalStorageModule"]
   }
 }

package/ios/ExternalStorageModule.swift

@@ -0,0 +1,359 @@
+import ExpoModulesCore
+import Foundation
+
+/// iOS implementation of the ExternalStorage native module.
+/// Provides filesystem operations, TiddlyWiki batch parsing,
+/// git status/index building, tar extraction, and streaming HTTP.
+///
+/// All path arguments are plain filesystem paths — NOT file:// URIs.
+public class ExternalStorageModule: Module {
+  public func definition() -> ModuleDefinition {
+    Name("ExternalStorage")
+
+    // ─── Basic queries ─────────────────────────────────────────────
+
+    AsyncFunction("exists") { (path: String) -> Bool in
+      FileManager.default.fileExists(atPath: path)
+    }
+
+    AsyncFunction("getInfo") { (path: String) -> [String: Any] in
+      let fm = FileManager.default
+      guard fm.fileExists(atPath: path) else {
+        return ["exists": false, "isDirectory": false, "size": 0, "modificationTime": 0]
+      }
+      let attrs = try fm.attributesOfItem(atPath: path)
+      let isDir = (attrs[.type] as? FileAttributeType) == .typeDirectory
+      let size = (attrs[.size] as? UInt64) ?? 0
+      let mtime = (attrs[.modificationDate] as? Date)?.timeIntervalSince1970 ?? 0
+      return [
+        "exists": true,
+        "isDirectory": isDir,
+        "size": size,
+        "modificationTime": Int(mtime * 1000),
+      ]
+    }
+
+    // ─── Directory operations ──────────────────────────────────────
+
+    AsyncFunction("mkdir") { (path: String) in
+      try FileManager.default.createDirectory(
+        atPath: path,
+        withIntermediateDirectories: true,
+        attributes: nil
+      )
+    }
+
+    AsyncFunction("readDir") { (path: String) -> [String] in
+      let fm = FileManager.default
+      guard fm.fileExists(atPath: path) else {
+        throw NSError(domain: "ENOENT", code: 2, userInfo: [NSLocalizedDescriptionKey: "Directory does not exist: \(path)"])
+      }
+      return try fm.contentsOfDirectory(atPath: path)
+    }
+
+    AsyncFunction("readDirRecursive") { (path: String) -> [String] in
+      Self.readDirRecursive(root: path)
+    }
+
+    AsyncFunction("rmdir") { (path: String) in
+      let fm = FileManager.default
+      if fm.fileExists(atPath: path) {
+        try fm.removeItem(atPath: path)
+      }
+    }
+
+    // ─── File read/write ───────────────────────────────────────────
+
+    AsyncFunction("readFileUtf8") { (path: String) -> String in
+      guard FileManager.default.fileExists(atPath: path) else {
+        throw NSError(domain: "ENOENT", code: 2, userInfo: [NSLocalizedDescriptionKey: "File does not exist: \(path)"])
+      }
+      return try String(contentsOfFile: path, encoding: .utf8)
+    }
+
+    AsyncFunction("readFileBase64") { (path: String) -> String in
+      guard FileManager.default.fileExists(atPath: path) else {
+        throw NSError(domain: "ENOENT", code: 2, userInfo: [NSLocalizedDescriptionKey: "File does not exist: \(path)"])
+      }
+      let data = try Data(contentsOf: URL(fileURLWithPath: path))
+      return data.base64EncodedString()
+    }
+
+    AsyncFunction("writeFileUtf8") { (path: String, content: String) in
+      let url = URL(fileURLWithPath: path)
+      try FileManager.default.createDirectory(
+        at: url.deletingLastPathComponent(),
+        withIntermediateDirectories: true,
+        attributes: nil
+      )
+      try content.write(toFile: path, atomically: true, encoding: .utf8)
+    }
+
+    AsyncFunction("writeFileBase64") { (path: String, base64Content: String) in
+      guard let data = Data(base64Encoded: base64Content) else {
+        throw NSError(domain: "InvalidBase64", code: 1, userInfo: nil)
+      }
+      let url = URL(fileURLWithPath: path)
+      try FileManager.default.createDirectory(
+        at: url.deletingLastPathComponent(),
+        withIntermediateDirectories: true,
+        attributes: nil
+      )
+      try data.write(to: url)
+    }
+
+    AsyncFunction("appendFileBase64") { (path: String, base64Content: String, truncateFirst: Bool) in
+      guard let data = Data(base64Encoded: base64Content) else {
+        throw NSError(domain: "InvalidBase64", code: 1, userInfo: nil)
+      }
+      let url = URL(fileURLWithPath: path)
+      if truncateFirst {
+        try FileManager.default.createDirectory(
+          at: url.deletingLastPathComponent(),
+          withIntermediateDirectories: true,
+          attributes: nil
+        )
+        try data.write(to: url)
+      } else {
+        let handle = try FileHandle(forWritingTo: url)
+        defer { handle.closeFile() }
+        handle.seekToEndOfFile()
+        handle.write(data)
+      }
+    }
+
+    AsyncFunction("writeFilesBase64") { (paths: [String], base64Contents: [String]) -> [String: Int] in
+      guard paths.count == base64Contents.count else {
+        throw NSError(domain: "InvalidArgs", code: 1, userInfo: [NSLocalizedDescriptionKey: "paths and contents must have same length"])
+      }
+      var written = 0
+      for (path, b64) in zip(paths, base64Contents) {
+        guard let data = Data(base64Encoded: b64) else { continue }
+        let url = URL(fileURLWithPath: path)
+        try FileManager.default.createDirectory(
+          at: url.deletingLastPathComponent(),
+          withIntermediateDirectories: true,
+          attributes: nil
+        )
+        try data.write(to: url)
+        written += 1
+      }
+      return ["writtenCount": written]
+    }
+
+    AsyncFunction("deleteFile") { (path: String) in
+      let fm = FileManager.default
+      if fm.fileExists(atPath: path) {
+        try fm.removeItem(atPath: path)
+      }
+    }
+
+    // ─── Storage queries (iOS equivalents) ─────────────────────────
+
+    AsyncFunction("isExternalStorageWritable") { () -> Bool in
+      // iOS always has writable app sandbox
+      true
+    }
+
+    AsyncFunction("getExternalStorageDirectory") { () -> String in
+      // Return the Documents directory
+      NSSearchPathForDirectoriesInDomains(.documentDirectory, .userDomainMask, true).first ?? ""
+    }
+
+    AsyncFunction("isExternalStorageManager") { () -> Bool in
+      // iOS doesn't have this concept — always true within sandbox
+      true
+    }
+
+    // ─── Streaming HTTP operations ─────────────────────────────────
+
+    AsyncFunction("httpPostToFile") { (url: String, headersMap: [String: String], bodyBase64: String, destPath: String, contentType: String) -> [String: Any] in
+      try await Self.httpPostToFile(
+        url: url,
+        headers: headersMap,
+        bodyBase64: bodyBase64,
+        destPath: destPath,
+        contentType: contentType
+      )
+    }
+
+    AsyncFunction("downloadFileResumable") { (url: String, headersMap: [String: String], destPath: String) -> [String: Any] in
+      try await Self.downloadFileResumable(url: url, headers: headersMap, destPath: destPath)
+    }
+
+    // ─── Chunked file reading ──────────────────────────────────────
+
+    AsyncFunction("readFileChunk") { (path: String, offset: Int, length: Int) -> [String: Any] in
+      guard FileManager.default.fileExists(atPath: path) else {
+        throw NSError(domain: "ENOENT", code: 2, userInfo: nil)
+      }
+      let handle = try FileHandle(forReadingFrom: URL(fileURLWithPath: path))
+      defer { handle.closeFile() }
+      handle.seek(toFileOffset: UInt64(offset))
+      let data = handle.readData(ofLength: length)
+      return [
+        "data": data.base64EncodedString(),
+        "bytesRead": data.count,
+      ]
+    }
+
+    // ─── Tar extraction ────────────────────────────────────────────
+
+    AsyncFunction("extractTar") { (tarPath: String, destDir: String) -> [String: Int] in
+      let count = try TarExtractor.extract(tarPath: tarPath, destDir: destDir)
+      return ["filesExtracted": count]
+    }
+
+    // ─── TiddlyWiki batch parsing ──────────────────────────────────
+
+    AsyncFunction("batchParseTidFiles") { (filePaths: [String], quickLoadMode: Bool) -> String in
+      TiddlerParser.batchParse(filePaths: filePaths, quickLoadMode: quickLoadMode)
+    }
+
+    // ─── Git operations ────────────────────────────────────────────
+
+    AsyncFunction("gitStatus") { (gitRootDir: String) -> String in
+      try GitHelper.gitStatus(rootDir: gitRootDir)
+    }
+
+    AsyncFunction("gitStatusDebug") { (gitRootDir: String) -> String in
+      try GitHelper.gitStatusDebug(rootDir: gitRootDir)
+    }
+
+    AsyncFunction("buildGitIndex") { (gitRootDir: String) -> String in
+      try GitHelper.buildGitIndex(rootDir: gitRootDir)
+    }
+  }
+
+  // ─── Static helpers ──────────────────────────────────────────────
+
+  private static let skipDirs: Set<String> = [".git", "node_modules", ".DS_Store", "output"]
+
+  static func readDirRecursive(root: String) -> [String] {
+    var results = [String]()
+    walkDir(base: root, prefix: "", results: &results)
+    return results
+  }
+
+  private static func walkDir(base: String, prefix: String, results: inout [String]) {
+    let fm = FileManager.default
+    guard let children = try? fm.contentsOfDirectory(atPath: base) else { return }
+    for child in children {
+      if skipDirs.contains(child) { continue }
+      let fullPath = (base as NSString).appendingPathComponent(child)
+      let relPath = prefix.isEmpty ? child : "\(prefix)/\(child)"
+      var isDir: ObjCBool = false
+      if fm.fileExists(atPath: fullPath, isDirectory: &isDir), isDir.boolValue {
+        walkDir(base: fullPath, prefix: relPath, results: &results)
+      } else {
+        results.append(relPath)
+      }
+    }
+  }
+
+  // ─── Streaming HTTP helpers ──────────────────────────────────────
+
+  private static func httpPostToFile(
+    url: String,
+    headers: [String: String],
+    bodyBase64: String,
+    destPath: String,
+    contentType: String
+  ) async throws -> [String: Any] {
+    guard let requestUrl = URL(string: url) else {
+      throw NSError(domain: "InvalidURL", code: 1, userInfo: nil)
+    }
+    guard let bodyData = Data(base64Encoded: bodyBase64) else {
+      throw NSError(domain: "InvalidBase64", code: 1, userInfo: nil)
+    }
+
+    let destUrl = URL(fileURLWithPath: destPath)
+    try FileManager.default.createDirectory(
+      at: destUrl.deletingLastPathComponent(),
+      withIntermediateDirectories: true,
+      attributes: nil
+    )
+
+    var request = URLRequest(url: requestUrl)
+    request.httpMethod = "POST"
+    request.setValue(contentType, forHTTPHeaderField: "Content-Type")
+    for (key, value) in headers {
+      request.setValue(value, forHTTPHeaderField: key)
+    }
+    request.httpBody = bodyData
+    request.timeoutInterval = 300  // 5 min read timeout
+
+    let (data, response) = try await URLSession.shared.data(for: request)
+    let httpResponse = response as? HTTPURLResponse
+    let statusCode = httpResponse?.statusCode ?? 0
+    let responseHeaders = (httpResponse?.allHeaderFields as? [String: String]) ?? [:]
+
+    // Write response to file
+    try data.write(to: destUrl)
+
+    return [
+      "statusCode": statusCode,
+      "headers": responseHeaders,
+      "bytesWritten": data.count,
+    ]
+  }
+
+  private static func downloadFileResumable(
+    url: String,
+    headers: [String: String],
+    destPath: String
+  ) async throws -> [String: Any] {
+    guard let requestUrl = URL(string: url) else {
+      throw NSError(domain: "InvalidURL", code: 1, userInfo: nil)
+    }
+
+    let destUrl = URL(fileURLWithPath: destPath)
+    try FileManager.default.createDirectory(
+      at: destUrl.deletingLastPathComponent(),
+      withIntermediateDirectories: true,
+      attributes: nil
+    )
+
+    var request = URLRequest(url: requestUrl)
+    request.httpMethod = "GET"
+    for (key, value) in headers {
+      request.setValue(value, forHTTPHeaderField: key)
+    }
+    request.timeoutInterval = 600  // 10 min
+
+    // Check existing file for resume
+    var existingSize: UInt64 = 0
+    if FileManager.default.fileExists(atPath: destPath) {
+      let attrs = try FileManager.default.attributesOfItem(atPath: destPath)
+      existingSize = (attrs[.size] as? UInt64) ?? 0
+      if existingSize > 0 {
+        request.setValue("bytes=\(existingSize)-", forHTTPHeaderField: "Range")
+      }
+    }
+
+    let (data, response) = try await URLSession.shared.data(for: request)
+    let httpResponse = response as? HTTPURLResponse
+    let statusCode = httpResponse?.statusCode ?? 0
+    let resumed = statusCode == 206
+
+    if resumed {
+      // Append to existing file
+      let handle = try FileHandle(forWritingTo: destUrl)
+      defer { handle.closeFile() }
+      handle.seekToEndOfFile()
+      handle.write(data)
+    } else {
+      // Overwrite
+      try data.write(to: destUrl)
+    }
+
+    let finalAttrs = try FileManager.default.attributesOfItem(atPath: destPath)
+    let totalBytes = (finalAttrs[.size] as? UInt64) ?? 0
+
+    return [
+      "statusCode": statusCode,
+      "totalBytes": totalBytes,
+      "resumed": resumed,
+    ]
+  }
+}