expo-tiddlywiki-filesystem-android-external-storage 2.0.2

package/app.plugin.js

@@ -0,0 +1,25 @@
+const { withAndroidManifest } = require('@expo/config-plugins');
+
+const withExternalStoragePermission = (config) => {
+  return withAndroidManifest(config, async (config) => {
+    const androidManifest = config.modResults;
+    
+    if (!androidManifest.manifest['uses-permission']) {
+      androidManifest.manifest['uses-permission'] = [];
+    }
+
+    // Add MANAGE_EXTERNAL_STORAGE permission
+    if (!androidManifest.manifest['uses-permission'].find(p => p.$['android:name'] === 'android.permission.MANAGE_EXTERNAL_STORAGE')) {
+      androidManifest.manifest['uses-permission'].push({
+        $: {
+          'android:name': 'android.permission.MANAGE_EXTERNAL_STORAGE',
+          // Optionally add tools:ignore="ScopedStorage" if needed but usually standard permission is enough
+        },
+      });
+    }
+
+    return config;
+  });
+};
+
+module.exports = withExternalStoragePermission;

package/build/index.d.ts

@@ -0,0 +1,130 @@
+interface FileInfo {
+    exists: boolean;
+    isDirectory: boolean;
+    size: number;
+    /** Milliseconds since epoch */
+    modificationTime: number;
+}
+interface BatchWriteResult {
+    writtenCount: number;
+}
+interface HttpPostToFileResult {
+    statusCode: number;
+    headers: Record<string, string>;
+    bytesWritten: number;
+}
+interface DownloadFileResumableResult {
+    statusCode: number;
+    /** Final size of the file on disk after download */
+    totalBytes: number;
+    /** true if the download resumed from a partial file (HTTP 206) */
+    resumed: boolean;
+}
+interface ExtractTarResult {
+    filesExtracted: number;
+}
+interface ReadFileChunkResult {
+    /** Base64-encoded chunk data */
+    data: string;
+    bytesRead: number;
+}
+interface IExternalStorageModule {
+    exists(path: string): Promise<boolean>;
+    getInfo(path: string): Promise<FileInfo>;
+    mkdir(path: string): Promise<void>;
+    readDir(path: string): Promise<string[]>;
+    /** Recursively list all files under a directory, returning relative paths. Skips .git etc. */
+    readDirRecursive(path: string): Promise<string[]>;
+    rmdir(path: string): Promise<void>;
+    readFileUtf8(path: string): Promise<string>;
+    readFileBase64(path: string): Promise<string>;
+    writeFileUtf8(path: string, content: string): Promise<void>;
+    writeFileBase64(path: string, base64Content: string): Promise<void>;
+    /**
+     * Append a Base64-encoded chunk to a file, optionally truncating first.
+     *
+     * Designed for streaming large writes from JS in bounded-memory chunks
+     * (e.g. 512 KB each) so the JVM never allocates the full file content,
+     * avoiding OOM on 50+ MB git pack files.
+     *
+     * @param truncateFirst Pass `true` for the first chunk to create/truncate
+     *                      the file, then `false` for subsequent chunks.
+     */
+    appendFileBase64(path: string, base64Content: string, truncateFirst: boolean): Promise<void>;
+    writeFilesBase64(paths: string[], base64Contents: string[]): Promise<BatchWriteResult>;
+    deleteFile(path: string): Promise<void>;
+    isExternalStorageWritable(): Promise<boolean>;
+    getExternalStorageDirectory(): Promise<string>;
+    /** Android 11+ (API 30): check if MANAGE_EXTERNAL_STORAGE is granted. Pre-30 returns true. */
+    isExternalStorageManager(): Promise<boolean>;
+    /**
+     * HTTP POST with the response body streamed directly to a file on disk,
+     * **never buffering the full response in JVM/Hermes heap**.
+     *
+     * Designed for git-upload-pack which can return 100+ MB packfiles.
+     *
+     * @param url         Target URL
+     * @param headers     HTTP headers as `{ key: value }`
+     * @param bodyBase64  Request body encoded as Base64 (binary git protocol data)
+     * @param destPath    Plain filesystem path to write the response body to
+     * @param contentType MIME type for the request body
+     */
+    httpPostToFile(url: string, headers: Record<string, string>, bodyBase64: string, destPath: string, contentType: string): Promise<HttpPostToFileResult>;
+    /**
+     * Read a chunk of a file starting at `offset` for up to `length` bytes.
+     * Returns Base64-encoded data and actual bytes read.
+     *
+     * Use this to stream a large file into JS in bounded-memory chunks.
+     */
+    readFileChunk(path: string, offset: number, length: number): Promise<ReadFileChunkResult>;
+    /**
+     * Download a file via HTTP GET with resumable download support.
+     *
+     * If `destPath` already exists on disk (from a previous interrupted download),
+     * sends `Range: bytes=<existingSize>-` to resume. The server must respond
+     * with 206 Partial Content for resume to work; otherwise the file is
+     * overwritten from scratch (200 response).
+     *
+     * @param url       Target URL
+     * @param headers   Extra HTTP headers (e.g. Authorization, ETag)
+     * @param destPath  Plain filesystem path for the downloaded file
+     */
+    downloadFileResumable(url: string, headers: Record<string, string>, destPath: string): Promise<DownloadFileResumableResult>;
+    /**
+     * Extract an uncompressed tar archive to a destination directory.
+     * Uses a native tar parser — no third-party dependency.
+     * Supports POSIX ustar and GNU long-name extensions.
+     * Validates paths to prevent directory traversal attacks.
+     *
+     * @param tarPath  Path to the .tar file
+     * @param destDir  Destination directory (created if needed)
+     */
+    extractTar(tarPath: string, destDir: string): Promise<ExtractTarResult>;
+    /**
+     * Parse a batch of TiddlyWiki tiddler files entirely in native Kotlin.
+     *
+     * This is the critical performance optimization for initial wiki loading:
+     * a single bridge call processes 100+ files in parallel, returning a
+     * ready-to-inject JSON array string. Eliminates per-file bridge round-trips.
+     *
+     * Supports .tid, .json, and .meta files. Applies skinny logic:
+     * - System tiddlers ($:/) → always full text
+     * - Plugins (application/json + plugin-type) → always full text
+     * - Module tiddlers (module-type) → always full text
+     * - Small tiddlers (< 10KB body) → full text
+     * - Large user tiddlers → skinny (_is_skinny: "yes", text omitted)
+     *
+     * @param filePaths     Array of absolute filesystem paths
+     * @param quickLoadMode If true, all tiddlers returned as skinny
+     * @returns JSON string: serialized array of tiddler field objects
+     */
+    batchParseTidFiles(filePaths: string[], quickLoadMode: boolean): Promise<string>;
+}
+export declare const ExternalStorage: IExternalStorageModule;
+/**
+ * Strip file:// prefix from a URI to produce a plain filesystem path.
+ * Safe to call on paths that are already plain.
+ */
+export declare function toPlainPath(uriOrPath: string): string;
+export type { BatchWriteResult, DownloadFileResumableResult, ExtractTarResult, FileInfo, HttpPostToFileResult, IExternalStorageModule, ReadFileChunkResult };
+//# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/build/index.js

@@ -0,0 +1,45 @@
+/**
+ * TypeScript bindings for the ExternalStorage native module.
+ *
+ * This module uses raw java.io.File on Android to bypass Expo FileSystem's
+ * directory whitelist. It allows reading/writing to shared external storage
+ * when MANAGE_EXTERNAL_STORAGE permission is granted.
+ *
+ * All path arguments are plain filesystem paths (e.g. "/storage/emulated/0/Documents/TidGi/").
+ * Do NOT pass file:// URIs — strip the scheme before calling.
+ */
+import { Platform } from 'react-native';
+let _module;
+/**
+ * Lazily load the native module. Wrapped in a function so that the app does NOT
+ * crash at import time if the native module is missing (e.g. on iOS or when the
+ * binary was built without it).
+ */
+function getNativeModule() {
+    if (_module)
+        return _module;
+    if (Platform.OS !== 'android') {
+        throw new Error('ExternalStorage native module is only available on Android');
+    }
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { requireNativeModule } = require('expo-modules-core');
+    _module = requireNativeModule('ExternalStorage');
+    return _module;
+}
+export const ExternalStorage = new Proxy({}, {
+    get(_target, property) {
+        const mod = getNativeModule();
+        return mod[property];
+    },
+});
+/**
+ * Strip file:// prefix from a URI to produce a plain filesystem path.
+ * Safe to call on paths that are already plain.
+ */
+export function toPlainPath(uriOrPath) {
+    if (uriOrPath.startsWith('file://')) {
+        return uriOrPath.slice('file://'.length);
+    }
+    return uriOrPath;
+}
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +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;AAqJD,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\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

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

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "expo-tiddlywiki-filesystem-android-external-storage",
+  "version": "2.0.2",
+  "description": "Expo native module for TidGi-Mobile: external storage I/O + TiddlyWiki .tid/.meta/.json batch parsing in Kotlin",
+  "main": "build/index.js",
+  "types": "build/index.d.ts",
+  "plugin": "app.plugin.js",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "expo-module clean",
+    "lint": "expo-module lint",
+    "test": "expo-module test",
+    "prepare": "tsc -p tsconfig.json"
+  },
+  "keywords": [
+    "react-native",
+    "expo",
+    "filesystem",
+    "android",
+    "external-storage"
+  ],
+  "author": "TidGi Mobile Team",
+  "license": "MIT",
+  "peerDependencies": {
+    "expo": "*",
+    "react": "*",
+    "react-native": "*"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.0",
+    "@types/react-native": "^0.73.0",
+    "expo": "^50.0.0",
+    "expo-module-scripts": "^3.0.0",
+    "expo-modules-core": "^1.11.0",
+    "react": "^18.2.0",
+    "react-native": "^0.73.0",
+    "typescript": "^5.0.0"
+  },
+  "files": [
+    "build",
+    "android",
+    "expo-module.config.json",
+    "src",
+    "plugin.js",
+    "app.plugin.js"
+  ],
+  "dependencies": {
+    "@expo/config-plugins": "^54.0.4"
+  }
+}

package/plugin.js

@@ -0,0 +1,25 @@
+const { withAndroidManifest } = require('@expo/config-plugins');
+
+const withExternalStoragePermission = (config) => {
+  return withAndroidManifest(config, async (config) => {
+    const androidManifest = config.modResults;
+    
+    if (!androidManifest.manifest['uses-permission']) {
+      androidManifest.manifest['uses-permission'] = [];
+    }
+
+    // Add MANAGE_EXTERNAL_STORAGE permission
+    if (!androidManifest.manifest['uses-permission'].find(p => p.$['android:name'] === 'android.permission.MANAGE_EXTERNAL_STORAGE')) {
+      androidManifest.manifest['uses-permission'].push({
+        $: {
+          'android:name': 'android.permission.MANAGE_EXTERNAL_STORAGE',
+          // Optionally add tools:ignore="ScopedStorage" if needed but usually standard permission is enough
+        },
+      });
+    }
+
+    return config;
+  });
+};
+
+module.exports = withExternalStoragePermission;

package/src/index.ts

@@ -0,0 +1,196 @@
+/**
+ * TypeScript bindings for the ExternalStorage native module.
+ *
+ * This module uses raw java.io.File on Android to bypass Expo FileSystem's
+ * directory whitelist. It allows reading/writing to shared external storage
+ * when MANAGE_EXTERNAL_STORAGE permission is granted.
+ *
+ * All path arguments are plain filesystem paths (e.g. "/storage/emulated/0/Documents/TidGi/").
+ * Do NOT pass file:// URIs — strip the scheme before calling.
+ */
+import { Platform } from 'react-native';
+
+let _module: IExternalStorageModule | undefined;
+
+/**
+ * Lazily load the native module. Wrapped in a function so that the app does NOT
+ * crash at import time if the native module is missing (e.g. on iOS or when the
+ * binary was built without it).
+ */
+function getNativeModule(): IExternalStorageModule {
+  if (_module) return _module;
+  if (Platform.OS !== 'android') {
+    throw new Error('ExternalStorage native module is only available on Android');
+  }
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const { requireNativeModule } = require('expo-modules-core') as { requireNativeModule: (name: string) => IExternalStorageModule };
+  _module = requireNativeModule('ExternalStorage');
+  return _module;
+}
+
+interface FileInfo {
+  exists: boolean;
+  isDirectory: boolean;
+  size: number;
+  /** Milliseconds since epoch */
+  modificationTime: number;
+}
+
+interface BatchWriteResult {
+  writtenCount: number;
+}
+
+interface HttpPostToFileResult {
+  statusCode: number;
+  headers: Record<string, string>;
+  bytesWritten: number;
+}
+
+interface DownloadFileResumableResult {
+  statusCode: number;
+  /** Final size of the file on disk after download */
+  totalBytes: number;
+  /** true if the download resumed from a partial file (HTTP 206) */
+  resumed: boolean;
+}
+
+interface ExtractTarResult {
+  filesExtracted: number;
+}
+
+interface ReadFileChunkResult {
+  /** Base64-encoded chunk data */
+  data: string;
+  bytesRead: number;
+}
+
+interface IExternalStorageModule {
+  exists(path: string): Promise<boolean>;
+  getInfo(path: string): Promise<FileInfo>;
+
+  mkdir(path: string): Promise<void>;
+  readDir(path: string): Promise<string[]>;
+  /** Recursively list all files under a directory, returning relative paths. Skips .git etc. */
+  readDirRecursive(path: string): Promise<string[]>;
+  rmdir(path: string): Promise<void>;
+
+  readFileUtf8(path: string): Promise<string>;
+  readFileBase64(path: string): Promise<string>;
+  writeFileUtf8(path: string, content: string): Promise<void>;
+  writeFileBase64(path: string, base64Content: string): Promise<void>;
+  /**
+   * Append a Base64-encoded chunk to a file, optionally truncating first.
+   *
+   * Designed for streaming large writes from JS in bounded-memory chunks
+   * (e.g. 512 KB each) so the JVM never allocates the full file content,
+   * avoiding OOM on 50+ MB git pack files.
+   *
+   * @param truncateFirst Pass `true` for the first chunk to create/truncate
+   *                      the file, then `false` for subsequent chunks.
+   */
+  appendFileBase64(path: string, base64Content: string, truncateFirst: boolean): Promise<void>;
+  writeFilesBase64(paths: string[], base64Contents: string[]): Promise<BatchWriteResult>;
+  deleteFile(path: string): Promise<void>;
+
+  isExternalStorageWritable(): Promise<boolean>;
+  getExternalStorageDirectory(): Promise<string>;
+  /** Android 11+ (API 30): check if MANAGE_EXTERNAL_STORAGE is granted. Pre-30 returns true. */
+  isExternalStorageManager(): Promise<boolean>;
+
+  /**
+   * HTTP POST with the response body streamed directly to a file on disk,
+   * **never buffering the full response in JVM/Hermes heap**.
+   *
+   * Designed for git-upload-pack which can return 100+ MB packfiles.
+   *
+   * @param url         Target URL
+   * @param headers     HTTP headers as `{ key: value }`
+   * @param bodyBase64  Request body encoded as Base64 (binary git protocol data)
+   * @param destPath    Plain filesystem path to write the response body to
+   * @param contentType MIME type for the request body
+   */
+  httpPostToFile(
+    url: string,
+    headers: Record<string, string>,
+    bodyBase64: string,
+    destPath: string,
+    contentType: string,
+  ): Promise<HttpPostToFileResult>;
+
+  /**
+   * Read a chunk of a file starting at `offset` for up to `length` bytes.
+   * Returns Base64-encoded data and actual bytes read.
+   *
+   * Use this to stream a large file into JS in bounded-memory chunks.
+   */
+  readFileChunk(path: string, offset: number, length: number): Promise<ReadFileChunkResult>;
+
+  /**
+   * Download a file via HTTP GET with resumable download support.
+   *
+   * If `destPath` already exists on disk (from a previous interrupted download),
+   * sends `Range: bytes=<existingSize>-` to resume. The server must respond
+   * with 206 Partial Content for resume to work; otherwise the file is
+   * overwritten from scratch (200 response).
+   *
+   * @param url       Target URL
+   * @param headers   Extra HTTP headers (e.g. Authorization, ETag)
+   * @param destPath  Plain filesystem path for the downloaded file
+   */
+  downloadFileResumable(
+    url: string,
+    headers: Record<string, string>,
+    destPath: string,
+  ): Promise<DownloadFileResumableResult>;
+
+  /**
+   * Extract an uncompressed tar archive to a destination directory.
+   * Uses a native tar parser — no third-party dependency.
+   * Supports POSIX ustar and GNU long-name extensions.
+   * Validates paths to prevent directory traversal attacks.
+   *
+   * @param tarPath  Path to the .tar file
+   * @param destDir  Destination directory (created if needed)
+   */
+  extractTar(tarPath: string, destDir: string): Promise<ExtractTarResult>;
+
+  /**
+   * Parse a batch of TiddlyWiki tiddler files entirely in native Kotlin.
+   *
+   * This is the critical performance optimization for initial wiki loading:
+   * a single bridge call processes 100+ files in parallel, returning a
+   * ready-to-inject JSON array string. Eliminates per-file bridge round-trips.
+   *
+   * Supports .tid, .json, and .meta files. Applies skinny logic:
+   * - System tiddlers ($:/) → always full text
+   * - Plugins (application/json + plugin-type) → always full text
+   * - Module tiddlers (module-type) → always full text
+   * - Small tiddlers (< 10KB body) → full text
+   * - Large user tiddlers → skinny (_is_skinny: "yes", text omitted)
+   *
+   * @param filePaths     Array of absolute filesystem paths
+   * @param quickLoadMode If true, all tiddlers returned as skinny
+   * @returns JSON string: serialized array of tiddler field objects
+   */
+  batchParseTidFiles(filePaths: string[], quickLoadMode: boolean): Promise<string>;
+}
+
+export const ExternalStorage: IExternalStorageModule = new Proxy({} as IExternalStorageModule, {
+  get(_target, property) {
+    const mod = getNativeModule();
+    return (mod as unknown as Record<string | symbol, unknown>)[property];
+  },
+});
+
+/**
+ * Strip file:// prefix from a URI to produce a plain filesystem path.
+ * Safe to call on paths that are already plain.
+ */
+export function toPlainPath(uriOrPath: string): string {
+  if (uriOrPath.startsWith('file://')) {
+    return uriOrPath.slice('file://'.length);
+  }
+  return uriOrPath;
+}
+
+export type { BatchWriteResult, DownloadFileResumableResult, ExtractTarResult, FileInfo, HttpPostToFileResult, IExternalStorageModule, ReadFileChunkResult };