@octane-xplat/files 0.10.0 → 0.11.0

package/README.md

@@ -46,3 +46,40 @@ if (file) {
 	}
 }
 ```
+
+## Binary reads, writes, and export
+
+`files.readBytes(ref, { maxBytes?, signal? })` reads the full contents as a
+`Uint8Array`. It works on `content://` picks (read through Android's
+`ContentResolver`), iOS picker copies, sandbox files, and web object URLs.
+`maxBytes` rejects oversized files mid-read instead of loading them, and
+`signal` aborts the read with an `AbortError`.
+
+```ts
+const bytes = await files.readBytes(file, { maxBytes: 10 * 1024 * 1024 })
+```
+
+`files.writeBytes(name, bytes)` mirrors `writeText`: on native it writes into
+the app sandbox (Documents) and returns a `FileRef`; on web it starts a
+browser download. `name` must be a bare file name — paths like `../x` or
+`a/b` are rejected, and `writeText` enforces the same rule.
+
+`files.export(name, bytes, { mimeType? })` asks the user where to save the
+data and resolves `saved`, `cancelled`, or `unavailable`. `saved` means the
+platform committed the bytes — Android flushes them through
+`ContentResolver` to the picked document, iOS completes the export-as-copy
+flow, and web closes a File System Access writable. Browsers without
+`showSaveFilePicker` and the AppKit leaf report `unavailable`; a share-sheet
+presentation never counts as `saved`. Only one export can run at a time — a
+concurrent call rejects with an `ExportBusyError` rather than stealing the
+open picker's result.
+
+```ts
+const result = await files.export('report.pdf', pdfBytes, { mimeType: 'application/pdf' })
+if (result === 'cancelled') console.log('user dismissed')
+```
+
+Picked refs are only guaranteed readable within the picking session. Android
+`content://` grants are not persisted by the picker, and iOS import-mode
+copies live in a temp folder — copy what you need with `writeBytes`, and
+call `files.release(ref)` when done.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octane-xplat/files",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Native + web file pick and read/write for Octane xplat — matching web + NativeScript implementations",
   "keywords": [
     "android",
@@ -42,13 +42,13 @@
   },
   "dependencies": {
     "@nativescript-community/ui-document-picker": "1.1.29",
-    "@octane-xplat/platform": "0.10.0"
+    "@octane-xplat/platform": "0.11.0"
   },
   "devDependencies": {
     "@nativescript-community/octane": "0.2.4",
     "@nativescript/core": "9.1.2",
     "@nativescript/types": "9.0.0",
-    "@octane-xplat/ui": "0.10.0",
+    "@octane-xplat/ui": "0.11.0",
     "octane": "0.6.3"
   },
   "peerDependencies": {

package/src/file-bytes.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'vitest'
+import { assertSafeFileName, concatBytes, exactBuffer, throwIfAborted } from './file-bytes'
+
+describe('assertSafeFileName', () => {
+	it('accepts plain file names', () => {
+		for (const name of ['a.txt', 'report 1.pdf', 'x.y.z.bin', 'résumé.md']) {
+			expect(() => assertSafeFileName(name)).not.toThrow()
+		}
+	})
+
+	it('rejects empty, dot, and traversal names', () => {
+		for (const name of ['', '.', '..', '../x', 'a/b', 'a\\b', '..\\x', 'a\0b']) {
+			expect(() => assertSafeFileName(name)).toThrow(/Unsafe file name/)
+		}
+	})
+})
+
+describe('throwIfAborted', () => {
+	it('passes for live or absent signals', () => {
+		expect(() => throwIfAborted(undefined)).not.toThrow()
+		const controller = new AbortController()
+		expect(() => throwIfAborted(controller.signal)).not.toThrow()
+	})
+
+	it('throws AbortError for aborted signals', () => {
+		const controller = new AbortController()
+		controller.abort()
+		expect(() => throwIfAborted(controller.signal)).toThrowError(
+			expect.objectContaining({ name: 'AbortError' }),
+		)
+	})
+})
+
+describe('concatBytes / exactBuffer', () => {
+	it('concatenates chunks in order', () => {
+		const joined = concatBytes(
+			[new Uint8Array([1, 2]), new Uint8Array([3]), new Uint8Array([4, 5])],
+			5,
+		)
+
+		expect([...joined]).toEqual([1, 2, 3, 4, 5])
+	})
+
+	it('returns the buffer only when the view covers it', () => {
+		const buffer = new Uint8Array([9, 8, 7, 6]).buffer
+		expect(exactBuffer(new Uint8Array(buffer))).toBe(buffer)
+
+		const windowed = new Uint8Array(buffer, 1, 2)
+		const exact = exactBuffer(windowed)
+		expect(exact.byteLength).toBe(2)
+		expect([...new Uint8Array(exact)]).toEqual([8, 7])
+	})
+})

package/src/file-bytes.ts

@@ -0,0 +1,68 @@
+/**
+ * Shared helpers for the binary file primitives (readBytes/writeBytes/export).
+ * DOM-free so the native leaf can use it too.
+ */
+
+/** File names used for sandbox writes and export temp files must be bare
+ *  names, not paths — a `/`, `\`, or `..` segment escapes the sandbox. */
+export function assertSafeFileName(name: string): void {
+	if (
+		typeof name !== 'string' ||
+		name.length === 0 ||
+		name === '.' ||
+		name === '..' ||
+		name.includes('/') ||
+		name.includes('\\') ||
+		name.includes('\0')
+	) {
+		throw new Error(`Unsafe file name: ${JSON.stringify(name)}`)
+	}
+}
+
+export function fileTooLarge(name: string, maxBytes: number): Error {
+	return new Error(`${name}: file exceeds the ${maxBytes}-byte limit`)
+}
+
+/** Named rejection for a second `files.export` while one is in flight. */
+export function exportBusy(): Error {
+	const error = new Error('files.export: an export is already in progress')
+	error.name = 'ExportBusyError'
+	return error
+}
+
+export function throwIfAborted(signal: AbortSignal | undefined): void {
+	if (!signal?.aborted) {
+		return
+	}
+
+	const thrower = (signal as { throwIfAborted?: () => void }).throwIfAborted
+	if (typeof thrower === 'function') {
+		thrower.call(signal)
+	}
+
+	const error = new Error('The operation was aborted')
+	error.name = 'AbortError'
+	throw error
+}
+
+/** Concatenate Uint8Array chunks into one exact-length array. */
+export function concatBytes(chunks: Uint8Array[], total: number): Uint8Array {
+	const out = new Uint8Array(total)
+	let offset = 0
+	for (const chunk of chunks) {
+		out.set(chunk, offset)
+		offset += chunk.byteLength
+	}
+
+	return out
+}
+
+/** Return an ArrayBuffer covering exactly this view's byte range — native
+ *  marshallers treat the argument as the whole buffer. */
+export function exactBuffer(bytes: Uint8Array): ArrayBuffer {
+	if (bytes.byteOffset === 0 && bytes.byteLength === bytes.buffer.byteLength) {
+		return bytes.buffer as ArrayBuffer
+	}
+
+	return bytes.slice().buffer as ArrayBuffer
+}

package/src/files.bridge.test.ts

@@ -0,0 +1,342 @@
+// Native-leaf bridge tests. The @nativescript/* module imports and the
+// iOS/Android global APIs are replaced with faithful mock shapes (same call
+// surfaces the runtime marshals) so the leaf's failure, concurrency, and
+// cleanup paths are exercised in node — not a substitute for native smoke.
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+const bridge = vi.hoisted(() => ({
+	application: { android: undefined as any },
+	listeners: new Map<string, Set<(arg: any) => void>>(),
+	resolver: null as any,
+	activity: null as any,
+	visibleVC: null as any,
+	keyWindow: true,
+	writeAtomic: true,
+	removedPaths: [] as string[],
+	channelWrites: [] as any[],
+	presented: [] as any[],
+}))
+
+vi.mock('@nativescript-community/ui-document-picker', () => ({
+	openFilePicker: vi.fn(async () => ({ files: [] })),
+}))
+
+vi.mock('@nativescript/core', () => ({
+	Application: bridge.application,
+	File: {
+		fromPath: (p: string) => ({
+			removeSync: () => {
+				bridge.removedPaths.push(p)
+			},
+			readText: async () => '',
+		}),
+	},
+	knownFolders: {
+		documents: () => ({ path: '/docs' }),
+		temp: () => ({ path: '/tmp' }),
+	},
+	path: {
+		join: (...parts: string[]) => parts.join('/'),
+	},
+	Utils: {
+		ios: {
+			getVisibleViewController: (root: any) => (root ? bridge.visibleVC : null),
+		},
+	},
+}))
+
+// Explicit .ts specifier: the web resolve chain would otherwise pick
+// files.web.ts; this suite covers the shared iOS/Android leaf.
+import { files } from './files.ts'
+import { files as macosFiles } from './files.macos'
+
+function stubAndroid() {
+	bridge.resolver = { openOutputStream: vi.fn(() => ({ close: vi.fn() })) }
+	bridge.activity = {
+		getContentResolver: () => bridge.resolver,
+		startActivityForResult: vi.fn(),
+	}
+
+	bridge.application.android = {
+		activityResultEvent: 'activityResult',
+		foregroundActivity: bridge.activity,
+		startActivity: bridge.activity,
+		on(event: string, cb: (arg: any) => void) {
+			if (!bridge.listeners.has(event)) {
+				bridge.listeners.set(event, new Set())
+			}
+
+			bridge.listeners.get(event)!.add(cb)
+		},
+		off(event: string, cb: (arg: any) => void) {
+			bridge.listeners.get(event)?.delete(cb)
+		},
+	}
+}
+
+function emitResult(arg: any) {
+	for (const cb of Array.from(bridge.listeners.get('activityResult') ?? [])) {
+		cb(arg)
+	}
+}
+
+function okResult(uri = 'content://dest/doc.bin') {
+	return {
+		requestCode: 1241,
+		resultCode: -1,
+		intent: { getData: () => ({ toString: () => uri }) },
+	}
+}
+
+let lastPicker: any
+
+beforeEach(() => {
+	bridge.listeners.clear()
+	bridge.removedPaths = []
+	bridge.channelWrites = []
+	bridge.presented = []
+	bridge.keyWindow = true
+	bridge.writeAtomic = true
+	bridge.resolver = null
+	bridge.activity = null
+	lastPicker = null
+
+	bridge.visibleVC = {
+		presentViewControllerAnimatedCompletion: vi.fn((controller: any) => {
+			bridge.presented.push(controller)
+		}),
+	}
+
+	vi.stubGlobal('android', {
+		content: {
+			Intent: class {
+				static ACTION_CREATE_DOCUMENT = 'android.intent.action.CREATE_DOCUMENT'
+				static CATEGORY_OPENABLE = 'android.intent.category.OPENABLE'
+				static EXTRA_TITLE = 'android.intent.extra.TITLE'
+				static FLAG_GRANT_READ_URI_PERMISSION = 1
+				static FLAG_GRANT_WRITE_URI_PERMISSION = 2
+				action: any
+				extras = new Map()
+				constructor(action: any) {
+					this.action = action
+				}
+				addCategory() {}
+				setType() {}
+				putExtra(key: any, value: any) {
+					this.extras.set(key, value)
+				}
+				addFlags() {}
+			},
+		},
+		app: { Activity: { RESULT_OK: -1 } },
+		net: { Uri: { parse: (s: string) => ({ toString: () => s }) } },
+	})
+
+	vi.stubGlobal('java', {
+		io: {
+			FileOutputStream: class {},
+			FileInputStream: class {},
+			ByteArrayOutputStream: class {
+				data: number[] = []
+				write(chunk: any, _off: number, count: number) {
+					for (let i = 0; i < count; i++) {
+						this.data.push(chunk[i])
+					}
+				}
+				size() {
+					return this.data.length
+				}
+				toByteArray() {
+					return this.data
+				}
+			},
+			BufferedReader: class {},
+			InputStreamReader: class {},
+		},
+		nio: {
+			channels: {
+				Channels: {
+					newChannel: (out: any) => ({
+						write: (buf: ArrayBuffer) => {
+							bridge.channelWrites.push({ out, buf })
+							return buf.byteLength
+						},
+					}),
+				},
+			},
+		},
+	})
+
+	vi.stubGlobal('NSData', {
+		dataWithBytesLength: (view: Uint8Array, length: number) => ({
+			view,
+			length,
+			writeToFileAtomically: vi.fn(() => bridge.writeAtomic),
+		}),
+	})
+
+	vi.stubGlobal('NSURL', { fileURLWithPath: (p: string) => ({ path: p }) })
+	vi.stubGlobal('UIApplication', {
+		sharedApplication: {
+			get keyWindow() {
+				return bridge.keyWindow ? { rootViewController: {} } : null
+			},
+			windows: { count: 0 },
+		},
+	})
+
+	vi.stubGlobal('UIDocumentPickerViewController', {
+		alloc: () => ({
+			initForExportingURLsAsCopy: (urls: any, asCopy: boolean) => {
+				lastPicker = { urls, asCopy, delegate: null, shouldShowFileExtensions: false }
+				return lastPicker
+			},
+		}),
+	})
+
+	vi.stubGlobal('UIDocumentPickerDelegate', {})
+	vi.stubGlobal(
+		'NSObject',
+		class {
+			static new(this: any) {
+				return new this()
+			}
+		},
+	)
+})
+
+afterEach(() => {
+	bridge.application.android = undefined
+	vi.unstubAllGlobals()
+	vi.restoreAllMocks()
+})
+
+describe('files.writeBytes (ios bridge)', () => {
+	it('rejects when the atomic write reports failure instead of returning a dead ref', async () => {
+		bridge.writeAtomic = false
+		await expect(files.writeBytes('a.bin', new Uint8Array([1]))).rejects.toThrow(
+			/Failed to write file/,
+		)
+	})
+
+	it('returns a sandbox ref after a confirmed write', async () => {
+		const ref = await files.writeBytes('a.bin', new Uint8Array([1, 2]))
+		expect(ref).toEqual({ name: 'a.bin', uri: '/docs/a.bin' })
+	})
+})
+
+describe('files.export (android bridge)', () => {
+	beforeEach(stubAndroid)
+
+	it('flushes bytes to the picked URI and resolves saved', async () => {
+		const pending = files.export('out.bin', new Uint8Array([7, 8]))
+		expect(bridge.activity.startActivityForResult).toHaveBeenCalledTimes(1)
+		emitResult(okResult())
+		expect(await pending).toBe('saved')
+		expect(bridge.resolver.openOutputStream).toHaveBeenCalledTimes(1)
+		expect(bridge.channelWrites).toHaveLength(1)
+		expect(bridge.listeners.get('activityResult')?.size ?? 0).toBe(0)
+	})
+
+	it('resolves cancelled on a non-OK result and drops the listener', async () => {
+		const pending = files.export('out.bin', new Uint8Array([1]))
+		emitResult({ requestCode: 1241, resultCode: 0, intent: null })
+		expect(await pending).toBe('cancelled')
+		expect(bridge.resolver.openOutputStream).not.toHaveBeenCalled()
+		expect(bridge.listeners.get('activityResult')?.size ?? 0).toBe(0)
+	})
+
+	it('rejects a concurrent export with ExportBusyError and recovers after settle', async () => {
+		const first = files.export('a.bin', new Uint8Array([1]))
+		await expect(files.export('b.bin', new Uint8Array([2]))).rejects.toThrowError(
+			expect.objectContaining({ name: 'ExportBusyError' }),
+		)
+
+		expect(bridge.activity.startActivityForResult).toHaveBeenCalledTimes(1)
+
+		emitResult(okResult())
+		expect(await first).toBe('saved')
+
+		const third = files.export('c.bin', new Uint8Array([3]))
+		emitResult(okResult())
+		expect(await third).toBe('saved')
+	})
+
+	it('rejects when the destination stream cannot open and cleans up', async () => {
+		bridge.resolver.openOutputStream.mockReturnValue(null)
+		const pending = files.export('out.bin', new Uint8Array([1]))
+		emitResult(okResult())
+		await expect(pending).rejects.toThrow(/Unable to open destination/)
+		expect(bridge.listeners.get('activityResult')?.size ?? 0).toBe(0)
+
+		// Guard released — a follow-up export is not stuck busy.
+		bridge.resolver.openOutputStream.mockReturnValue({ close: vi.fn() })
+		const next = files.export('next.bin', new Uint8Array([1]))
+		emitResult(okResult())
+		expect(await next).toBe('saved')
+	})
+
+	it('rejects when the activity cannot be started and removes the listener', async () => {
+		bridge.activity.startActivityForResult.mockImplementation(() => {
+			throw new Error('no activity to handle intent')
+		})
+
+		await expect(files.export('out.bin', new Uint8Array([1]))).rejects.toThrow(/no activity/)
+		expect(bridge.listeners.get('activityResult')?.size ?? 0).toBe(0)
+	})
+})
+
+describe('files.export (ios bridge)', () => {
+	it('stages a temp copy, presents export-as-copy, and resolves saved with cleanup', async () => {
+		const pending = files.export('out.bin', new Uint8Array([9]))
+		expect(bridge.presented).toHaveLength(1)
+		expect(lastPicker.asCopy).toBe(true)
+		expect(lastPicker.delegate).toBeTruthy()
+
+		lastPicker.delegate.documentPickerDidPickDocumentAtURL(lastPicker, { path: '/dest' })
+		expect(await pending).toBe('saved')
+		expect(bridge.removedPaths).toEqual(['/tmp/out.bin'])
+		expect(lastPicker.delegate).toBeNull()
+	})
+
+	it('resolves cancelled on dismissal and removes the temp copy', async () => {
+		const pending = files.export('out.bin', new Uint8Array([9]))
+		lastPicker.delegate.documentPickerWasCancelled(lastPicker)
+		expect(await pending).toBe('cancelled')
+		expect(bridge.removedPaths).toEqual(['/tmp/out.bin'])
+	})
+
+	it('rejects when the temp write fails instead of hanging', async () => {
+		bridge.writeAtomic = false
+		await expect(files.export('out.bin', new Uint8Array([1]))).rejects.toThrow(
+			/Failed to stage export file/,
+		)
+
+		expect(bridge.presented).toHaveLength(0)
+	})
+
+	it('rejects when no view controller can present instead of hanging', async () => {
+		bridge.keyWindow = false
+		await expect(files.export('out.bin', new Uint8Array([1]))).rejects.toThrow(
+			/No visible view controller/,
+		)
+
+		expect(bridge.removedPaths).toEqual(['/tmp/out.bin'])
+	})
+
+	it('rejects a concurrent export with ExportBusyError', async () => {
+		const first = files.export('a.bin', new Uint8Array([1]))
+		await expect(files.export('b.bin', new Uint8Array([2]))).rejects.toThrowError(
+			expect.objectContaining({ name: 'ExportBusyError' }),
+		)
+
+		lastPicker.delegate.documentPickerDidPickDocumentsAtURLs(lastPicker, { count: 1 })
+		expect(await first).toBe('saved')
+	})
+})
+
+describe('files.export (macos leaf)', () => {
+	it('reports unavailable instead of throwing', async () => {
+		expect(await macosFiles.export('a.bin', new Uint8Array([1]))).toBe('unavailable')
+	})
+})

package/src/files.macos.ts

@@ -1,5 +1,11 @@
 // Files — AppKit host leaf.
-import type { FileRef } from './types'
+import type {
+	FileExportOptions,
+	FileExportResult,
+	FileReadBytesOptions,
+	FileRef,
+	Files,
+} from './types'
 
 function openPanel(accept = '*/*', multiple = false): FileRef[] | null {
 	const appKit = globalThis as any
@@ -42,7 +48,7 @@ function openPanel(accept = '*/*', multiple = false): FileRef[] | null {
 	}))
 }
 
-export const files = {
+export const files: Files = {
 	async pick(accept = '*/*'): Promise<FileRef | null> {
 		return openPanel(accept)?.[0] ?? null
 	},
@@ -52,8 +58,23 @@ export const files = {
 	async readText(_file: FileRef): Promise<string> {
 		throw new Error('unsupported: AppKit file access is not wired')
 	},
+	async readBytes(_file: FileRef, _opts?: FileReadBytesOptions): Promise<Uint8Array> {
+		throw new Error('unsupported: AppKit file access is not wired')
+	},
 	async writeText(_name: string, _text: string): Promise<FileRef> {
 		throw new Error('unsupported: the AppKit host does not provide a save panel')
 	},
+	async writeBytes(_name: string, _bytes: Uint8Array): Promise<FileRef> {
+		throw new Error('unsupported: the AppKit host does not provide a save panel')
+	},
+	// FileExportResult names this leaf as the 'unavailable' case — the AppKit
+	// host offers no save panel, so report it instead of throwing.
+	async export(
+		_name: string,
+		_bytes: Uint8Array,
+		_opts?: FileExportOptions,
+	): Promise<FileExportResult> {
+		return 'unavailable'
+	},
 	release(_file: FileRef): void {},
 }

package/src/files.ts

@@ -2,10 +2,26 @@
 // are still used for writes; picked Android SAF references may be content://
 // URIs and must be read through ContentResolver.
 import { openFilePicker } from '@nativescript-community/ui-document-picker'
-import { Application, File, knownFolders, path } from '@nativescript/core'
-import type { FileRef } from './types'
+import { Application, File, knownFolders, path, Utils } from '@nativescript/core'
+import {
+	assertSafeFileName,
+	exactBuffer,
+	exportBusy,
+	fileTooLarge,
+	throwIfAborted,
+} from './file-bytes'
+
+import type {
+	FileExportOptions,
+	FileExportResult,
+	FileReadBytesOptions,
+	FileRef,
+	Files,
+} from './types'
 
 const docs = () => knownFolders.documents()
+const READ_CHUNK = 64 * 1024
+const ANDROID_EXPORT_REQUEST_CODE = 1241
 
 function pickerTypes(accept: string): { extensions: string[]; mimeTypes: string[] } {
 	const values = accept
@@ -106,12 +122,270 @@ async function pickFiles(
 	}))
 }
 
-export const files = {
-	/** Opens the platform document picker and returns selected opaque URIs. */
+// openInputStream accepts content:// and file:// schemes; bare paths go
+// through FileInputStream. Returns null when the resolver cannot open the URI.
+function openAndroidInput(uri: string): any {
+	const activity = Application.android?.foregroundActivity ?? Application.android?.startActivity
+	if (uri.startsWith('content://') || uri.startsWith('file://')) {
+		return activity?.getContentResolver()?.openInputStream(android.net.Uri.parse(uri))
+	}
+
+	return new java.io.FileInputStream(uri)
+}
+
+function readAndroidBytes(uri: string, opts?: FileReadBytesOptions): Uint8Array {
+	const input = openAndroidInput(uri)
+	if (!input) {
+		throw new Error(`Unable to open picked file: ${uri}`)
+	}
+
+	const out = new java.io.ByteArrayOutputStream()
+	const chunk = Array.create('byte', READ_CHUNK)
+	try {
+		let count: number
+		while ((count = input.read(chunk)) !== -1) {
+			throwIfAborted(opts?.signal)
+			out.write(chunk, 0, count)
+			if (opts?.maxBytes != null && out.size() > opts.maxBytes) {
+				throw fileTooLarge(uri, opts.maxBytes)
+			}
+		}
+	} finally {
+		input.close()
+	}
+
+	// ArrayBuffer.from is an NS Android runtime builtin that takes a
+	// java.nio.ByteBuffer — wrap the byte[] rather than marshalling per byte.
+	return new Uint8Array((ArrayBuffer as any).from(java.nio.ByteBuffer.wrap(out.toByteArray())))
+}
+
+// Picked iOS refs come from the picker's Import mode, so they are app-owned
+// copies — no security-scoped access needed. Single-pick URIs keep their
+// percent-encoding, so fall back to a decoded path when the literal misses.
+function iosFilePath(uri: string): string {
+	let p = uri.startsWith('file://') ? uri.slice('file://'.length) : uri
+	if (NSFileManager.defaultManager.fileExistsAtPath(p)) {
+		return p
+	}
+
+	try {
+		const decoded = decodeURIComponent(p)
+		if (decoded !== p && NSFileManager.defaultManager.fileExistsAtPath(decoded)) {
+			return decoded
+		}
+	} catch {}
+
+	return p
+}
+
+function readIosBytes(uri: string, opts?: FileReadBytesOptions): Uint8Array {
+	const p = iosFilePath(uri)
+	const handle = NSFileHandle.fileHandleForReadingAtPath(p)
+	if (!handle) {
+		throw new Error(`Unable to open picked file: ${uri}`)
+	}
+
+	const out = NSMutableData.new()
+	try {
+		while (true) {
+			throwIfAborted(opts?.signal)
+			const data = handle.readDataOfLength(READ_CHUNK)
+			if (!data || data.length === 0) {
+				break
+			}
+
+			out.appendData(data)
+			if (opts?.maxBytes != null && out.length > opts.maxBytes) {
+				throw fileTooLarge(uri, opts.maxBytes)
+			}
+		}
+	} finally {
+		handle.closeFile()
+	}
+
+	return new Uint8Array(interop.bufferFromData(out))
+}
+
+// ContentResolver.openOutputStream accepts content:// and file:// URIs; bare
+// paths go through FileOutputStream. The WritableByteChannel adapter writes
+// the full buffer per the OutputStream contract — no chunked short writes.
+function writeAndroidBytes(uri: string, bytes: Uint8Array): void {
+	const activity = Application.android?.foregroundActivity ?? Application.android?.startActivity
+	const out: java.io.OutputStream =
+		uri.startsWith('content://') || uri.startsWith('file://')
+			? activity?.getContentResolver()?.openOutputStream(android.net.Uri.parse(uri))
+			: new java.io.FileOutputStream(uri)
+
+	if (!out) {
+		throw new Error(`Unable to open destination: ${uri}`)
+	}
+
+	try {
+		java.nio.channels.Channels.newChannel(out).write(exactBuffer(bytes) as any)
+	} finally {
+		out.close()
+	}
+}
+
+function androidExport(
+	name: string,
+	bytes: Uint8Array,
+	opts?: FileExportOptions,
+): Promise<FileExportResult> {
+	const activity = Application.android?.foregroundActivity ?? Application.android?.startActivity
+	if (!activity) {
+		return Promise.resolve('unavailable')
+	}
+
+	const Intent = android.content.Intent
+	const intent = new Intent(Intent.ACTION_CREATE_DOCUMENT)
+	intent.addCategory(Intent.CATEGORY_OPENABLE)
+	intent.setType(opts?.mimeType ?? '*/*')
+	intent.putExtra(Intent.EXTRA_TITLE, name)
+	intent.addFlags(Intent.FLAG_GRANT_WRITE_URI_PERMISSION | Intent.FLAG_GRANT_READ_URI_PERMISSION)
+
+	return new Promise<FileExportResult>((resolve, reject) => {
+		const onEvent = (event: any) => {
+			if (event.requestCode !== ANDROID_EXPORT_REQUEST_CODE) {
+				return
+			}
+
+			Application.android.off(Application.android.activityResultEvent, onEvent)
+			const uri = event.intent?.getData?.()
+			if (event.resultCode !== android.app.Activity.RESULT_OK || !uri) {
+				resolve('cancelled')
+				return
+			}
+
+			try {
+				writeAndroidBytes(uri.toString(), bytes)
+				resolve('saved')
+			} catch (error) {
+				reject(error)
+			}
+		}
+
+		Application.android.on(Application.android.activityResultEvent, onEvent)
+		try {
+			activity.startActivityForResult(intent, ANDROID_EXPORT_REQUEST_CODE)
+		} catch (error) {
+			Application.android.off(Application.android.activityResultEvent, onEvent)
+			reject(error)
+		}
+	})
+}
+
+// One export UI at a time: Android listeners share the activity-result event,
+// and the iOS picker delegate below is kept alive in this slot (the
+// controller's `delegate` property is weak). A second concurrent export would
+// corrupt the first, so `files.export` fails fast instead.
+let activeExport: { delegate?: any; controller?: any } | null = null
+
+// Per-call delegate — defined lazily because NSObject and the picker symbols
+// only exist on iOS, while this module also loads on Android.
+let IosExportDelegate: any = null
+
+function iosExportDelegateClass(): any {
+	if (IosExportDelegate) {
+		return IosExportDelegate
+	}
+
+	IosExportDelegate = class extends NSObject {
+		static ObjCProtocols = [UIDocumentPickerDelegate]
+		finish: ((saved: boolean) => void) | null = null
+
+		documentPickerDidPickDocumentAtURL(controller: any, _url: any): void {
+			this.settle(controller, true)
+		}
+		documentPickerDidPickDocumentsAtURLs(controller: any, urls: any): void {
+			this.settle(controller, urls.count > 0)
+		}
+		documentPickerWasCancelled(controller: any): void {
+			this.settle(controller, false)
+		}
+		private settle(controller: any, saved: boolean): void {
+			const finish = this.finish
+			this.finish = null
+			controller.delegate = null
+			finish?.(saved)
+		}
+	}
+
+	return IosExportDelegate
+}
+
+function iosVisibleViewController(): any {
+	const app = UIApplication.sharedApplication
+	const keyWindow = app.keyWindow || (app.windows.count > 0 && app.windows[0])
+	// Utils.ios is only populated on iOS — typed as an empty bag elsewhere.
+	const getVisible = (Utils.ios as any)?.getVisibleViewController
+	return keyWindow && typeof getVisible === 'function'
+		? getVisible(keyWindow.rootViewController)
+		: null
+}
+
+// Own export picker rather than the upstream plugin's saveFile: that helper
+// runs an async promise executor (a failed temp write or a missing visible
+// controller leaves the promise unsettled) and holds the picker delegate in
+// one weak module slot, so overlapping calls drop the earlier request.
+async function iosExport(
+	name: string,
+	bytes: Uint8Array,
+	slot: { delegate?: any; controller?: any },
+): Promise<FileExportResult> {
+	const tempPath = path.join(knownFolders.temp().path, name)
+	const staged = NSData.dataWithBytesLength(bytes as any, bytes.byteLength).writeToFileAtomically(
+		tempPath,
+		true,
+	)
+
+	const removeTemp = () => {
+		try {
+			File.fromPath(tempPath).removeSync()
+		} catch {}
+	}
+
+	if (!staged) {
+		throw new Error(`Failed to stage export file: ${name}`)
+	}
+
+	const visibleVC = iosVisibleViewController()
+	if (!visibleVC) {
+		removeTemp()
+		throw new Error('No visible view controller to present the export picker')
+	}
+
+	return new Promise<FileExportResult>((resolve, reject) => {
+		try {
+			const controller = UIDocumentPickerViewController.alloc().initForExportingURLsAsCopy(
+				[NSURL.fileURLWithPath(tempPath)] as any,
+				true,
+			)
+
+			const delegate = iosExportDelegateClass().new()
+			// `saved` only after the system commits the export-as-copy to the
+			// chosen destination; dismissal settles as 'cancelled'.
+			delegate.finish = (saved: boolean) => {
+				removeTemp()
+				resolve(saved ? 'saved' : 'cancelled')
+			}
+
+			slot.delegate = delegate
+			slot.controller = controller
+			controller.delegate = delegate
+			controller.shouldShowFileExtensions = true
+			visibleVC.presentViewControllerAnimatedCompletion(controller, true, null)
+		} catch (error) {
+			removeTemp()
+			reject(error)
+		}
+	})
+}
+
+export const files: Files = {
 	async pickMultiple(accept = '*/*', opts?: { startingFolder?: string }): Promise<FileRef[]> {
 		return pickFiles(accept, true, opts)
 	},
-	/** Opens the platform document picker and returns its first opaque URI. */
 	async pick(accept = '*/*', opts?: { startingFolder?: string }): Promise<FileRef | null> {
 		return (await pickFiles(accept, false, opts))[0] ?? null
 	},
@@ -120,14 +394,63 @@ export const files = {
 			return readContentUri(ref.uri)
 		}
 
-		return File.fromPath(ref.uri).readText()
+		return File.fromPath(Application.android ? ref.uri : iosFilePath(ref.uri)).readText()
+	},
+	async readBytes(ref: FileRef, opts?: FileReadBytesOptions): Promise<Uint8Array> {
+		throwIfAborted(opts?.signal)
+		return Application.android ? readAndroidBytes(ref.uri, opts) : readIosBytes(ref.uri, opts)
 	},
 	async writeText(name: string, text: string): Promise<FileRef> {
+		assertSafeFileName(name)
 		const p = path.join(docs().path, name)
 		const f = File.fromPath(p)
 		f.writeTextSync(text)
 		return { name, uri: p }
 	},
+	async writeBytes(name: string, bytes: Uint8Array): Promise<FileRef> {
+		assertSafeFileName(name)
+		const p = path.join(docs().path, name)
+		if (Application.android) {
+			writeAndroidBytes(p, bytes)
+		} else {
+			// FileSystemAccess.writeBufferSync drops the writeToFileAtomically
+			// result and swallows errors without an onError callback, so a
+			// failed write would resolve with a ref to a missing file. Check
+			// the BOOL — it is the platform's overwrite confirmation.
+			const written = NSData.dataWithBytesLength(
+				bytes as any,
+				bytes.byteLength,
+			).writeToFileAtomically(p, true)
+
+			if (!written) {
+				throw new Error(`Failed to write file: ${p}`)
+			}
+		}
+
+		return { name, uri: p }
+	},
+	async export(
+		name: string,
+		bytes: Uint8Array,
+		opts?: FileExportOptions,
+	): Promise<FileExportResult> {
+		assertSafeFileName(name)
+		if (activeExport) {
+			throw exportBusy()
+		}
+
+		const slot: { delegate?: any; controller?: any } = {}
+		activeExport = slot
+		try {
+			return Application.android
+				? await androidExport(name, bytes, opts)
+				: await iosExport(name, bytes, slot)
+		} finally {
+			if (activeExport === slot) {
+				activeExport = null
+			}
+		}
+	},
 	release(ref: FileRef): void {
 		const cachePrefix = knownFolders.temp().path + '/'
 		if (!ref.uri.startsWith(cachePrefix)) {

package/src/files.web.test.ts

@@ -0,0 +1,117 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { files } from './files.web'
+
+beforeEach(() => {
+	let counter = 0
+	vi.stubGlobal('URL', {
+		...URL,
+		createObjectURL: (_blob: Blob) => `blob:mock/${counter++}`,
+		revokeObjectURL: vi.fn(),
+	})
+})
+
+afterEach(() => {
+	vi.unstubAllGlobals()
+	vi.restoreAllMocks()
+	delete (window as any).showSaveFilePicker
+})
+
+describe('files.writeBytes (web)', () => {
+	it('starts a download and returns a readable ref', async () => {
+		const ref = await files.writeBytes('report.bin', new Uint8Array([1, 2, 3, 255]))
+		expect(ref.name).toBe('report.bin')
+		expect(ref.uri).toMatch(/^blob:/)
+
+		const back = await files.readBytes(ref)
+		expect([...back]).toEqual([1, 2, 3, 255])
+	})
+
+	it('rejects path-traversal names', async () => {
+		await expect(files.writeBytes('../escape.bin', new Uint8Array(1))).rejects.toThrow(
+			/Unsafe file name/,
+		)
+	})
+})
+
+describe('files.readBytes (web)', () => {
+	it('enforces maxBytes without returning truncated data', async () => {
+		const ref = await files.writeBytes('big.bin', new Uint8Array(1024))
+		await expect(files.readBytes(ref, { maxBytes: 512 })).rejects.toThrow(/exceeds/)
+	})
+
+	it('rejects on an aborted signal', async () => {
+		const ref = await files.writeBytes('a.bin', new Uint8Array([1]))
+		const controller = new AbortController()
+		controller.abort()
+		await expect(files.readBytes(ref, { signal: controller.signal })).rejects.toThrowError(
+			expect.objectContaining({ name: 'AbortError' }),
+		)
+	})
+
+	it('rejects when the signal aborts during blob.arrayBuffer()', async () => {
+		const controller = new AbortController()
+		vi.spyOn(Blob.prototype, 'arrayBuffer').mockImplementation(async () => {
+			controller.abort()
+			return new Uint8Array([1]).buffer
+		})
+
+		const ref = await files.writeBytes('a.bin', new Uint8Array([1]))
+		await expect(files.readBytes(ref, { signal: controller.signal })).rejects.toThrowError(
+			expect.objectContaining({ name: 'AbortError' }),
+		)
+	})
+
+	it('reads foreign URLs through fetch with the cap applied', async () => {
+		const body = new Uint8Array([1, 2, 3, 4])
+		vi.stubGlobal(
+			'fetch',
+			vi.fn(async () => new Response(body)),
+		)
+
+		const back = await files.readBytes({ name: 'remote.bin', uri: 'https://x/remote.bin' })
+		expect([...back]).toEqual([1, 2, 3, 4])
+		expect(fetch).toHaveBeenCalledWith('https://x/remote.bin', { signal: undefined })
+
+		await expect(
+			files.readBytes({ name: 'remote.bin', uri: 'https://x/remote.bin' }, { maxBytes: 2 }),
+		).rejects.toThrow(/exceeds/)
+	})
+
+	it('revokes the object URL on release', async () => {
+		const ref = await files.writeBytes('gone.bin', new Uint8Array([1]))
+		files.release(ref)
+		expect(URL.revokeObjectURL).toHaveBeenCalledWith(ref.uri)
+	})
+})
+
+describe('files.export (web)', () => {
+	it('returns unavailable without the File System Access API', async () => {
+		expect(await files.export('a.bin', new Uint8Array([1]))).toBe('unavailable')
+	})
+
+	it('writes bytes through a save picker and reports saved', async () => {
+		const write = vi.fn()
+		const close = vi.fn(async () => {})
+		const showSaveFilePicker = vi.fn(async () => ({
+			createWritable: async () => ({ write, close }),
+		}))
+
+		;(window as any).showSaveFilePicker = showSaveFilePicker
+
+		const result = await files.export('dump.bin', new Uint8Array([7, 8]))
+		expect(result).toBe('saved')
+		expect(write).toHaveBeenCalledWith(new Uint8Array([7, 8]))
+		expect(close).toHaveBeenCalled()
+	})
+
+	it('maps picker dismissal to cancelled', async () => {
+		const showSaveFilePicker = vi.fn(async () => {
+			throw new DOMException('dismissed', 'AbortError')
+		})
+
+		;(window as any).showSaveFilePicker = showSaveFilePicker
+
+		expect(await files.export('dump.bin', new Uint8Array([7]))).toBe('cancelled')
+	})
+})

package/src/files.web.ts

@@ -1,7 +1,31 @@
 // Files — web leaf. Desktop webview hosts own real pickers and file:// refs;
 // outside a host this uses opaque object URLs and browser downloads.
 import { desktopHost } from '@octane-xplat/platform/host/web'
-import type { FileRef } from './types'
+import {
+	assertSafeFileName,
+	concatBytes,
+	exactBuffer,
+	fileTooLarge,
+	throwIfAborted,
+} from './file-bytes'
+
+import type {
+	FileExportOptions,
+	FileExportResult,
+	FileReadBytesOptions,
+	FileRef,
+	Files,
+} from './types'
+
+// Object URLs this leaf minted, keyed by URL, so readBytes returns exact bytes
+// without a fetch round-trip and release can drop the backing Blob.
+const objectBlobs = new Map<string, Blob>()
+
+function mintObjectUrl(blob: Blob): string {
+	const uri = URL.createObjectURL(blob)
+	objectBlobs.set(uri, blob)
+	return uri
+}
 
 function chooseFiles(accept: string, multiple: boolean): Promise<FileRef[]> {
 	return new Promise((resolve) => {
@@ -12,7 +36,7 @@ function chooseFiles(accept: string, multiple: boolean): Promise<FileRef[]> {
 		input.onchange = () => {
 			const refs: FileRef[] = []
 			for (const file of Array.from(input.files ?? [])) {
-				refs.push({ name: file.name, uri: URL.createObjectURL(file) })
+				refs.push({ name: file.name, uri: mintObjectUrl(file) })
 			}
 
 			resolve(refs)
@@ -23,7 +47,53 @@ function chooseFiles(accept: string, multiple: boolean): Promise<FileRef[]> {
 	})
 }
 
-export const files = {
+// Capped stream read: stop as soon as the cap is exceeded instead of
+// materializing the whole response.
+async function fetchBytes(uri: string, opts?: FileReadBytesOptions): Promise<Uint8Array> {
+	const response = await fetch(uri, { signal: opts?.signal })
+	if (!response.ok) {
+		throw new Error(`Unable to read file: ${uri}`)
+	}
+
+	if (opts?.maxBytes == null) {
+		return new Uint8Array(await response.arrayBuffer())
+	}
+
+	const reader = response.body?.getReader()
+	if (!reader) {
+		const bytes = new Uint8Array(await response.arrayBuffer())
+		if (bytes.byteLength > opts.maxBytes) {
+			throw fileTooLarge(uri, opts.maxBytes)
+		}
+
+		return bytes
+	}
+
+	const chunks: Uint8Array[] = []
+	let total = 0
+	try {
+		while (true) {
+			const { done, value } = await reader.read()
+			if (done) {
+				break
+			}
+
+			total += value.byteLength
+			if (total > opts.maxBytes) {
+				await reader.cancel().catch(() => {})
+				throw fileTooLarge(uri, opts.maxBytes)
+			}
+
+			chunks.push(value)
+		}
+	} finally {
+		reader.releaseLock()
+	}
+
+	return concatBytes(chunks, total)
+}
+
+export const files: Files = {
 	async pickMultiple(accept = '*/*', _opts?: { startingFolder?: string }): Promise<FileRef[]> {
 		return chooseFiles(accept, true)
 	},
@@ -48,8 +118,26 @@ export const files = {
 
 		return (await fetch(ref.uri)).text()
 	},
+	async readBytes(ref: FileRef, opts?: FileReadBytesOptions): Promise<Uint8Array> {
+		throwIfAborted(opts?.signal)
+		const blob = objectBlobs.get(ref.uri)
+		if (blob) {
+			if (opts?.maxBytes != null && blob.size > opts.maxBytes) {
+				throw fileTooLarge(ref.uri, opts.maxBytes)
+			}
+
+			const bytes = new Uint8Array(await blob.arrayBuffer())
+			throwIfAborted(opts?.signal)
+			return bytes
+		}
+
+		// Host file:// refs need a host binary read, which the desktop service
+		// contract does not provide; other URLs go through fetch.
+		return fetchBytes(ref.uri, opts)
+	},
 	/** Desktop hosts write the selected path; plain web starts a download. */
 	async writeText(name: string, text: string): Promise<FileRef> {
+		assertSafeFileName(name)
 		const host = desktopHost()
 		if (host && (await host.supports('files', 'writeText'))) {
 			const file = await host.files.writeText(name, text)
@@ -60,15 +148,56 @@ export const files = {
 			return file
 		}
 
-		const uri = URL.createObjectURL(new Blob([text], { type: 'text/plain' }))
+		const uri = mintObjectUrl(new Blob([text], { type: 'text/plain' }))
+		const a = document.createElement('a')
+		a.href = uri
+		a.download = name
+		a.click()
+		return { name, uri }
+	},
+	/** The desktop host contract is text-only, so bytes always download. */
+	async writeBytes(name: string, bytes: Uint8Array): Promise<FileRef> {
+		assertSafeFileName(name)
+		const uri = mintObjectUrl(new Blob([exactBuffer(bytes)], { type: 'application/octet-stream' }))
 		const a = document.createElement('a')
 		a.href = uri
 		a.download = name
 		a.click()
 		return { name, uri }
 	},
+	async export(
+		name: string,
+		bytes: Uint8Array,
+		opts?: FileExportOptions,
+	): Promise<FileExportResult> {
+		assertSafeFileName(name)
+		const picker = (window as any).showSaveFilePicker as ((opts: any) => Promise<any>) | undefined
+
+		if (typeof picker !== 'function') {
+			return 'unavailable'
+		}
+
+		const extension = name.includes('.') ? `.${name.split('.').pop()}` : null
+		const types =
+			opts?.mimeType && extension ? [{ accept: { [opts.mimeType]: [extension] } }] : undefined
+
+		try {
+			const handle = await picker.call(window, { suggestedName: name, types })
+			const writable = await handle.createWritable()
+			await writable.write(bytes)
+			await writable.close()
+			return 'saved'
+		} catch (error) {
+			if ((error as DOMException)?.name === 'AbortError') {
+				return 'cancelled'
+			}
+
+			throw error
+		}
+	},
 	release(ref: FileRef): void {
 		if (ref.uri.startsWith('blob:')) {
+			objectBlobs.delete(ref.uri)
 			URL.revokeObjectURL(ref.uri)
 		}
 	},

package/src/types.ts

@@ -2,8 +2,71 @@ export interface FileRef {
 	name: string
 	/**
 	 * Opaque reference: blob/object URL on web, filesystem path on native.
-	 * `files.writeText()` downloads on web and writes where implemented.
-	 * Picked mobile files may use `content://` URIs.
+	 * `files.writeText()`/`files.writeBytes()` download on web and write the
+	 * app sandbox on native. Picked Android files may use `content://` URIs.
 	 */
 	uri: string
 }
+
+export interface FilePickOptions {
+	startingFolder?: string
+}
+
+export interface FileReadBytesOptions {
+	/**
+	 * Reject with a too-large error once the file exceeds this many bytes.
+	 * Enforced while reading, so oversized sources are never fully loaded.
+	 */
+	maxBytes?: number
+	/** Abort an in-progress read. Rejects with an `AbortError`. */
+	signal?: AbortSignal
+}
+
+export interface FileExportOptions {
+	/**
+	 * MIME type hint for the destination — the Android SAF action type and the
+	 * web save picker's accept filter. Ignored on iOS.
+	 */
+	mimeType?: string
+}
+
+/**
+ * `saved`: the platform committed the bytes to the chosen destination —
+ * bytes flushed through `ContentResolver` on Android, the export-as-copy
+ * picker's destination commit on iOS, or a closed `FileSystemWritableFileStream`
+ * on web. `cancelled`: the user dismissed the destination UI. `unavailable`:
+ * the platform offers no qualified export surface (browser without the
+ * File System Access API, the AppKit leaf).
+ */
+export type FileExportResult = 'saved' | 'cancelled' | 'unavailable'
+
+/** Shared contract every platform leaf implements. */
+export interface Files {
+	/** Opens the platform document picker and returns its first opaque URI. */
+	pick(accept?: string, opts?: FilePickOptions): Promise<FileRef | null>
+	/** Opens the platform document picker and returns selected opaque URIs. */
+	pickMultiple(accept?: string, opts?: FilePickOptions): Promise<FileRef[]>
+	readText(ref: FileRef): Promise<string>
+	/**
+	 * Reads the full binary content of a picked or sandbox-written ref.
+	 * Android `content://` refs are read through `ContentResolver`; iOS picker
+	 * refs are app-owned import copies; web reads the backing `Blob` directly
+	 * or fetches foreign URLs.
+	 */
+	readBytes(ref: FileRef, opts?: FileReadBytesOptions): Promise<Uint8Array>
+	writeText(name: string, text: string): Promise<FileRef>
+	/**
+	 * Writes bytes inside the app sandbox (native) or starts a browser
+	 * download (web) and returns a ref suitable for `readBytes`/`release`.
+	 */
+	writeBytes(name: string, bytes: Uint8Array): Promise<FileRef>
+	/**
+	 * User-directed export to a destination the user picks: the Android SAF
+	 * create action, iOS export-as-copy picker, web `showSaveFilePicker`.
+	 * Only one export can be in flight — a concurrent call rejects with an
+	 * `ExportBusyError`.
+	 */
+	export(name: string, bytes: Uint8Array, opts?: FileExportOptions): Promise<FileExportResult>
+	/** Free the ref's backing resource (revoke object URLs, delete temp copies). */
+	release(ref: FileRef): void
+}

package/types/index.d.ts

@@ -12,4 +12,11 @@ export type {
 } from '../src/props.js'
 
 export { files } from '../src/files.js'
-export type { FileRef } from '../src/types.js'
+export type {
+	FileExportOptions,
+	FileExportResult,
+	FilePickOptions,
+	FileReadBytesOptions,
+	FileRef,
+	Files,
+} from '../src/types.js'

package/types/index.macos.d.ts

@@ -11,4 +11,11 @@ export type {
 } from '../src/props.js'
 
 export { files } from '../src/files.macos.js'
-export type { FileRef } from '../src/types.js'
+export type {
+	FileExportOptions,
+	FileExportResult,
+	FilePickOptions,
+	FileReadBytesOptions,
+	FileRef,
+	Files,
+} from '../src/types.js'