@glass-sdk/file-picker

pickFiles({ multiple?: boolean }) opens the platform's file chooser and returns:

• { status: 'picked', files: [{ name, bytes: Uint8Array }] }
• { status: 'cancelled' }
• { status: 'failed', code, message }

Codes: unsupported, busy, too-large, invalid-request, incompatible-host, unauthorized, io. User cancellation never throws. Only one selection may be active. There is no human-interaction timeout. Browser support requires HTMLInputElement.showPicker and the file-input cancel event; server-side calls return unsupported. No private browsing APIs or focus-based cancellation guesses are used.

Selection is limited to 32 files, 16 MiB combined. Bytes are read into memory; this is not a streaming or persistent-access API. Native adapters bound reads before serializing base64. The public adapter validates the wire response and returns original bytes. Names are display names, never filesystem authority. Applications decide how to decode, inspect, or upload data.

Wire request: { version: 1, multiple: boolean }. Native responses use version 1, the same statuses, and { name, base64 } for picked files. Unsupported versions fail; they are never translated. Desktop uses an origin-checked Electron IPC receiver. Mobile uses a registered Capacitor plugin. Web uses the browser file input. No public implementation-registration or consumer extension mechanism is included.

Platform implementation ownership:

• src/: public API, wire validation, browser implementation.
• native/desktop/: Electron dialog and bounded file reads.
• native/ios/: UIDocumentPicker and bounded security-scoped reads.
• native/android/: Storage Access Framework and bounded background reads.

A future capability should own its contract and adapters in its package. Only actual used integrations belong in host registration and CLI assembly; this package does not define a speculative general plugin system.