@octane-xplat/media 0.14.0 → 0.15.0

package/README.md

@@ -1,55 +1,97 @@
 # `@octane-xplat/media`
 
 ```sh
-pnpm add @octane-xplat/media
+pnpm add @octane-xplat/media @octane-xplat/files
 ```
 
 Still-image picking and OS camera capture for Octane xplat apps. iOS runs
 `@nativescript/imagepicker` + `@nativescript/camera`, Android the same
 plugins over its photo picker/camera intent; web uses `<input
 type="file">` (with the `capture` attribute for camera shots, which mobile
-browsers route to the camera app); the macOS AppKit dev host reports
-`unsupported`.
+browsers route to the camera app). macOS AppKit uses the normal file picker
+for existing images and an app-owned Capture/Cancel sheet for still photos.
+Photos-library browsing and gallery saving remain unsupported.
 
 ```ts
 import { media } from '@octane-xplat/media'
 
-await media.ensure('photos')
 const image = await media.pickImage() // null when the user cancels
 const shot = await media.capturePhoto()
 ```
 
-Every method returns a `PickedImage` — `FileRef` (`name`, opaque `uri`)
-plus a `dataUrl` you can hand straight to `Image src`. Cancellation
-resolves `null` (or `[]` for `pickImages`), so check the result rather
-than catching. `ensure('camera' | 'photos')` resolves
+Every method returns a `PickedImage` — a `FileRef` (`name`, opaque `uri`)
+you can hand straight to `Image src`, or to `files.readBytes()` for an
+upload body. Cancellation resolves `null` (or `[]` for `pickImages`), so
+check the result rather than catching. `ensure('camera' | 'photos')` resolves
 `'granted' | 'denied' | 'unsupported'`.
 
 ```tsx
 import { useState } from 'octane'
 import { Button, Image } from '@octane-xplat/ui'
 import { media } from '@octane-xplat/media'
+import type { PickedImage } from '@octane-xplat/media'
+import { files } from '@octane-xplat/files'
 
 export function PhotoPicker() {
-	const [preview, setPreview] = useState<string | null>(null)
+	const [preview, setPreview] = useState<PickedImage | null>(null)
 	async function pickPhoto() {
-		if ((await media.ensure('photos')) !== 'granted') return
 		const photo = await media.pickImage()
-		if (photo) setPreview(photo.dataUrl)
+		if (!photo) return
+		// The ref is a file handle — keep it alive while it displays; release
+		// the previous pick once the new one is showing.
+		const previous = preview
+		setPreview(photo)
+		if (previous) files.release(previous)
 	}
 	return (
 		<>
-			<Button onPress={pickPhoto}>Choose photo</Button>
-			{preview && <Image src={preview} alt="Selected photo" />}
+			<Button clickAction={pickPhoto}>Choose photo</Button>
+			{preview && <Image src={preview.uri} alt="Selected photo" />}
 		</>
 	)
 }
 ```
 
+On macOS, call the picker directly from a button. It reads only the selected
+files, keeps their pixel dimensions and aspect ratio, and returns an app-owned
+temporary JPEG ref. Install `@octane-xplat/files` and release that JPEG after
+preview/upload use — the ref is dead once released.
+Failed conversion or writing rejects and cleans outputs from that selection.
+Real macOS panel selection is a separate runtime qualification gate.
+
+```ts
+import { media } from '@octane-xplat/media'
+import { files } from '@octane-xplat/files'
+
+const images = await media.pickImages() // [] on cancel
+try {
+	console.log(images.map((image) => image.uri))
+} finally {
+	for (const image of images) files.release(image)
+}
+```
+
 For a live preview surface instead of one-shot capture, use
 [`@octane-xplat/camera`](../camera/README.md)'s `CameraView`.
 
 Guide: [Using device features](../../docs/platform/platform-services.md);
-per-target availability: [platform notes](../../docs/notes/platform-notes.md).
+per-target availability: [platform notes](../../.agents/docs/notes/platform-notes.md).
 Exercised by the harness `Services` screen and
 [`CameraDemo`](../demos/src/CameraDemo.tsrx).
+
+On AppKit, invoke capture from a user action. The first Capture press authorizes
+and starts the camera preview; the next takes the photo. Cancel or failure keeps
+a null result. Add `NSCameraUsageDescription` to your macOS package's Info.plist.
+The still-photo flow requests no microphone permission and rejects gallery saving
+before permission or UI. Actual camera capture on AppKit remains unqualified;
+deterministic sheet and lifecycle checks use an injected camera backend.
+
+```ts
+import { media } from '@octane-xplat/media'
+
+export async function onCapturePress() {
+	return media.capturePhoto({ width: 800, height: 600, saveToGallery: false })
+}
+```
+
+[AppKit setup and ownership example](../../docs/platform/platform-services.md#appkit-still-photos).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octane-xplat/media",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Image picking and OS camera capture for Octane xplat — matching web + NativeScript implementations",
   "keywords": [
     "android",
@@ -23,28 +23,47 @@
     "directory": "packages/media"
   },
   "files": [
-    "src"
+    "src",
+    "types",
+    "!src/**/*.test.*",
+    "!src/**/*.spec.*"
   ],
   "type": "module",
   "exports": {
     ".": {
-      "macos": "./src/index.macos.ts",
+      "macos": {
+        "types": "./types/generated/index.macos.d.ts",
+        "default": "./src/index.macos.ts"
+      },
+      "types": "./types/generated/index.d.ts",
       "default": "./src/index.ts"
     },
-    "./*": "./src/*"
+    "./*": {
+      "types": "./types/generated/*.d.ts",
+      "default": "./src/*"
+    },
+    "./*.ts": {
+      "types": "./types/generated/*.d.ts",
+      "default": "./src/*.ts"
+    }
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
     "@nativescript/camera": "7.0.0",
-    "@nativescript/imagepicker": "5.0.0"
+    "@nativescript/imagepicker": "5.0.0",
+    "@octane-xplat/camera": "0.15.0",
+    "@octane-xplat/platform": "0.15.0"
   },
   "devDependencies": {
-    "@nativescript-community/octane": "0.2.4",
+    "@nativescript-community/octane": "0.2.5",
     "@nativescript/core": "9.1.3",
     "@nativescript/types": "9.1.4",
-    "octane": "0.11.0"
+    "@tsrx/typescript-plugin": "0.4.11",
+    "octane": "0.11.0",
+    "tsrx-typegen": "0.3.0",
+    "typescript": "5.9.3"
   },
   "peerDependencies": {
     "@nativescript-community/octane": ">=0.2.1 <1",
@@ -66,6 +85,10 @@
     }
   },
   "scripts": {
-    "test": "node --test tests/*.test.mjs"
+    "test": "node --test tests/*.test.mjs",
+    "test:packed": "node tests/packed-consumer.mjs",
+    "test:macos-runtime": "node tests/macos-runtime.mjs",
+    "typegen": "tsrx-typegen --project tsconfig.types.json",
+    "pack:check": "tsrx-typegen --pack-check"
   }
 }

package/src/media.macos.ts

@@ -1,18 +1,127 @@
-// Media — AppKit host leaf. No picker or capture flow is wired on the
-// desktop dev host.
-import type { MediaImpl } from './types'
+// Media — AppKit file selection. Photos-library browsing is not requested.
+import type { MediaImpl, PickedImage } from './types'
+import { capturePhoto, ensureCamera } from './photo-capture.macos'
+
+// __xplatTemporaryFiles is a registry shared with @octane-xplat/files: app
+// registers only the temp outputs it minted, and files.release deletes them.
+function temporaryImages(): Set<string> {
+	return ((globalThis as any).__xplatTemporaryFiles ??= new Set<string>())
+}
+
+function removeOutput(uri: string): void {
+	const manager = (globalThis as any).NSFileManager.defaultManager
+	if (manager.fileExistsAtPath(uri) && !manager.removeItemAtPathError(uri, null)) {
+		throw new Error(`Could not remove temporary image: ${uri}`)
+	}
+
+	temporaryImages().delete(uri)
+}
+
+function persistSelection(url: any, outputs: string[]): PickedImage {
+	const host = globalThis as any
+	const scoped = url.startAccessingSecurityScopedResource()
+	try {
+		const data = host.NSData.dataWithContentsOfURL(url)
+		const bitmap = data && host.NSBitmapImageRep.imageRepWithData(data)
+		if (!bitmap || !(bitmap.pixelsWide > 0 && bitmap.pixelsHigh > 0)) {
+			throw new Error('Could not decode the selected image')
+		}
+
+		// Encode the original pixel dimensions, without point-size or screen-scale resizing.
+		const jpeg = bitmap.representationUsingTypeProperties(host.NSBitmapImageFileTypeJPEG ?? 3, {
+			[host.NSImageCompressionFactor]: 0.85,
+		})
+
+		if (!jpeg || !Number(jpeg.length)) {
+			throw new Error('Could not convert the selected image to JPEG')
+		}
+
+		const manager = host.NSFileManager.defaultManager
+		const filename = `octane-image-${host.NSUUID.UUID().UUIDString}.jpg`
+		const uri = String(manager.temporaryDirectory.URLByAppendingPathComponent(filename).path)
+		if (manager.fileExistsAtPath(uri)) {
+			throw new Error('Temporary image path already exists')
+		}
+
+		// Track ownership before writing, including a partially written output.
+		outputs.push(uri)
+		temporaryImages().add(uri)
+		if (!jpeg.writeToFileAtomically(uri, true)) {
+			throw new Error('Could not save the image to temporary storage')
+		}
+
+		// Read back the app-owned file before relinquishing access to the source.
+		const readable = host.NSData.dataWithContentsOfFile(uri)
+		if (!readable?.isEqualToData(jpeg)) {
+			throw new Error('Could not read the saved temporary image')
+		}
+
+		return {
+			name: String(url.lastPathComponent ?? 'image.jpg'),
+			uri,
+		}
+	} finally {
+		if (scoped) {
+			url.stopAccessingSecurityScopedResource()
+		}
+	}
+}
+
+function pickSelections(multiple: boolean): PickedImage[] {
+	const host = globalThis as any
+	if (!host.NSOpenPanel?.openPanel) {
+		throw new Error('AppKit NSOpenPanel is unavailable in this macOS host')
+	}
+
+	const panel = host.NSOpenPanel.openPanel()
+	panel.canChooseFiles = true
+	panel.canChooseDirectories = false
+	panel.allowsMultipleSelection = multiple
+	panel.allowedFileTypes = host.NSBitmapImageRep.imageTypes
+	if (panel.runModal() !== (host.NSModalResponseOK ?? 1)) {
+		return []
+	}
+
+	const outputs: string[] = []
+	try {
+		const refs: PickedImage[] = []
+		if (multiple) {
+			const selected = panel.URLs
+			for (let index = 0; index < Number(selected?.count ?? 0); index++) {
+				refs.push(persistSelection(selected.objectAtIndex(index), outputs))
+			}
+		} else if (panel.URL) {
+			refs.push(persistSelection(panel.URL, outputs))
+		}
+
+		return refs
+	} catch (error) {
+		const failures: unknown[] = []
+		for (const uri of outputs) {
+			try {
+				removeOutput(uri)
+			} catch (cleanupError) {
+				failures.push(cleanupError)
+			}
+		}
+
+		if (failures.length) {
+			throw new AggregateError([error, ...failures], 'Image selection and temporary cleanup failed')
+		}
+
+		throw error
+	}
+}
 
 export const media: MediaImpl = {
-	async ensure() {
-		return 'unsupported'
+	async ensure(kind) {
+		return kind === 'camera' ? ensureCamera() : 'unsupported'
 	},
 	async pickImage() {
-		return null
+		return pickSelections(false)[0] ?? null
 	},
 	async pickImages() {
-		return []
-	},
-	async capturePhoto() {
-		return null
+		return pickSelections(true)
 	},
+	capturePhoto,
 }

package/src/media.ts

@@ -1,7 +1,8 @@
-// Media picking + camera capture — store a temporary JPEG for NativeScript
-// Image and return a data URL for APIs that persist image payloads. Camera
-// capture is stills only: @nativescript/camera presents the OS capture UI
-// (UIImagePickerController on iOS, ACTION_IMAGE_CAPTURE on Android).
+// Media picking + camera capture — returns a temporary-JPEG file ref (the
+// same FileRef `files.readBytes`/`files.release` consume; upload paths read
+// the file, never an inline data URL). Camera capture is stills only:
+// @nativescript/camera presents the OS capture UI (UIImagePickerController
+// on iOS, ACTION_IMAGE_CAPTURE on Android).
 import { isAvailable as isCameraAvailable, takePicture } from '@nativescript/camera'
 
 import { create as createImagePicker } from '@nativescript/imagepicker'
@@ -16,9 +17,18 @@ import type {
 	PickedImage,
 } from './types'
 
+import { android } from '@octane-xplat/platform/android'
+
 async function ensurePhotos(): Promise<PermissionResult> {
+	let picker
+	try {
+		picker = createImagePicker({ mode: 'single', mediaType: 1 as ImagePickerMediaType })
+	} catch {
+		// Plugin missing or unusable — capability absence, not user denial.
+		return 'unsupported'
+	}
+
 	try {
-		const picker = createImagePicker({ mode: 'single', mediaType: 1 as ImagePickerMediaType })
 		const permission = (await picker.authorize()) as { authorized?: boolean } | boolean
 		return permission === true || (typeof permission === 'object' && permission.authorized === true)
 			? 'granted'
@@ -55,6 +65,11 @@ async function ensureCamera(): Promise<PermissionResult> {
 				return 'denied'
 			}
 
+			// Framework unlinked or metadata missing — nothing can be granted.
+			if (typeof av?.requestAccessForMediaTypeCompletionHandler !== 'function') {
+				return 'unsupported'
+			}
+
 			return await new Promise<PermissionResult>((resolve) => {
 				av.requestAccessForMediaTypeCompletionHandler(video, (granted: boolean) =>
 					resolve(granted ? 'granted' : 'denied'),
@@ -77,12 +92,13 @@ async function ensureCamera(): Promise<PermissionResult> {
 
 		return await new Promise<PermissionResult>((resolve) => {
 			const requestCode = cameraRequestCode++
+			const event = Application.android.activityRequestPermissionsEvent
 			const onResult = (args: any) => {
 				if (args.requestCode !== requestCode) {
 					return
 				}
 
-				Application.android.off(Application.android.activityRequestPermissionsEvent, onResult)
+				Application.android.off(event, onResult)
 
 				resolve(
 					args.grantResults?.[0] === android.content.pm.PackageManager.PERMISSION_GRANTED
@@ -91,9 +107,15 @@ async function ensureCamera(): Promise<PermissionResult> {
 				)
 			}
 
-			Application.android.on(Application.android.activityRequestPermissionsEvent, onResult)
-
-			activity.requestPermissions([perm], requestCode)
+			Application.android.on(event, onResult)
+			try {
+				activity.requestPermissions([perm], requestCode)
+			} catch {
+				// A finishing activity rejects the request synchronously —
+				// do not leak the global listener.
+				Application.android.off(event, onResult)
+				resolve('denied')
+			}
 		})
 	} catch (e) {
 		console.log('[media] ensureCamera error: ' + (e as Error)?.message)
@@ -110,8 +132,7 @@ async function persistImage(source: ImageSource, name: string): Promise<PickedIm
 			throw new Error('Could not save the image to temporary storage')
 		}
 
-		const base64 = await source.toBase64StringAsync('jpeg', 85)
-		return { name, uri, dataUrl: `data:image/jpeg;base64,${base64}` }
+		return { name, uri }
 	} catch (error) {
 		// This operation owns this generated path, including a partial save.
 		try {

package/src/media.web.ts

@@ -1,5 +1,6 @@
-// Media picking — web leaf. Keep an object URL for previews and a data URL for
-// APIs that persist image payloads. The file input supports multiple photos.
+// Media picking — web leaf. The picked File gets a blob: object URL — a file
+// handle that previews via `Image.src` and uploads via `files.readBytes`;
+// no inline data URL is produced. The file input supports multiple photos.
 import type {
 	CapturePhotoOptions,
 	MediaImpl,
@@ -18,37 +19,43 @@ function selectFiles(multiple: boolean, capture?: 'user' | 'environment'): Promi
 			input.capture = capture
 		}
 
-		input.onchange = () => resolve(Array.from(input.files ?? []))
-		input.oncancel = () => resolve([])
-		input.click()
-	})
-}
+		let settled = false
+		const settle = (files: File[]) => {
+			if (settled) {
+				return
+			}
 
-function readDataUrl(file: File): Promise<string> {
-	return new Promise((resolve, reject) => {
-		const reader = new FileReader()
-		reader.onload = () => {
-			if (typeof reader.result === 'string') {
-				resolve(reader.result)
-			} else {
-				reject(new Error('Could not read the selected image'))
+			settled = true
+			input.onchange = null
+			input.oncancel = null
+			if (typeof window !== 'undefined') {
+				window.removeEventListener('focus', onFocus)
 			}
+
+			resolve(files)
 		}
 
-		reader.onerror = () => reject(reader.error ?? new Error('Could not read the selected image'))
+		// Browsers without input.oncancel still return focus to the page when
+		// the picker dismisses — wait a beat for a trailing change event.
+		const onFocus = () => {
+			setTimeout(() => settle(Array.from(input.files ?? [])), 350)
+		}
 
-		reader.readAsDataURL(file)
+		input.onchange = () => settle(Array.from(input.files ?? []))
+		input.oncancel = () => settle([])
+		if (typeof window !== 'undefined') {
+			window.addEventListener('focus', onFocus)
+		}
+
+		input.click()
 	})
 }
 
 async function imageRefs(selected: File[]): Promise<PickedImage[]> {
-	// Finish every fallible read before allocating preview URLs. A failed batch
-	// cannot return its successful siblings, so those need no retained previews.
-	const dataUrls = await Promise.all(selected.map(readDataUrl))
 	const refs: PickedImage[] = []
 	try {
-		for (const [index, file] of selected.entries()) {
-			refs.push({ name: file.name, uri: URL.createObjectURL(file), dataUrl: dataUrls[index]! })
+		for (const file of selected) {
+			refs.push({ name: file.name, uri: URL.createObjectURL(file) })
 		}
 
 		return refs
@@ -89,29 +96,23 @@ export const media: MediaImpl = {
 			return null
 		}
 
-		const [image] = await imageRefs([file])
-		return image ?? null
+		// Non-cancel failures resolve null on every leaf — a shared caller
+		// never has to catch a read or persistence failure here.
+		try {
+			const [image] = await imageRefs([file])
+			return image ?? null
+		} catch {
+			return null
+		}
 	},
 	async ensure(kind: MediaPermissionKind): Promise<PermissionResult> {
 		if (kind === 'photos') {
 			return typeof document !== 'undefined' ? 'granted' : 'unsupported'
 		}
 
-		if (!navigator.permissions?.query) {
-			return 'unsupported'
-		}
-
-		try {
-			const status = await navigator.permissions.query({ name: 'camera' as PermissionName })
-			if (status.state === 'granted') {
-				return 'granted'
-			}
-
-			return status.state === 'denied' ? 'denied' : 'unsupported'
-		} catch {
-			// Some browsers expose Permissions API but reject the camera descriptor.
-			return 'unsupported'
-		}
+		// The file-input capture path needs no camera permission — report the
+		// capability the leaf actually delivers, like the photos branch.
+		return typeof document !== 'undefined' ? 'granted' : 'unsupported'
 	},
 }
 

package/src/photo-capture.macos.ts

@@ -0,0 +1,113 @@
+import type { CapturePhotoOptions, PermissionResult, PickedImage } from './types'
+
+interface PhotoSheet {
+	permissionStatus(): string
+	presentReply(options: CapturePhotoOptions, reply: (result: string | null) => void): void
+	dispose(): void
+	discard(uri: string): void
+}
+
+declare const XplatPhotoCaptureSheet: { alloc(): { init(): PhotoSheet } }
+
+let active: PhotoSheet | undefined
+
+/** Query only. Still-photo authorization belongs to the sheet's Capture action. */
+export async function ensureCamera(): Promise<PermissionResult> {
+	if (typeof XplatPhotoCaptureSheet === 'undefined') {
+		return 'unsupported'
+	}
+
+	const sheet = XplatPhotoCaptureSheet.alloc().init()
+	try {
+		const status = String(sheet.permissionStatus())
+		return status === 'granted'
+			? 'granted'
+			: status === 'denied' || status === 'restricted'
+				? 'denied'
+				: 'unsupported'
+	} finally {
+		sheet.dispose()
+	}
+}
+
+/** Call from a user action. The sheet owns its preview until it settles. */
+export async function capturePhoto(options: CapturePhotoOptions = {}): Promise<PickedImage | null> {
+	if (options.saveToGallery) {
+		throw new Error('unsupported: saveToGallery is unavailable for macOS still-photo capture')
+	}
+
+	if (active || typeof XplatPhotoCaptureSheet === 'undefined') {
+		return null
+	}
+
+	const sheet = XplatPhotoCaptureSheet.alloc().init()
+	active = sheet
+	return new Promise((resolve) => {
+		let settled = false
+		let deliveredUri: string | undefined
+		const finish = (message: string | null) => {
+			let image: PickedImage | null = null
+			try {
+				if (message) {
+					const value = JSON.parse(message) as Partial<PickedImage> & { dataUrl?: unknown }
+					if (typeof value.name === 'string' && typeof value.uri === 'string') {
+						// The sheet's reply may still carry a dataUrl payload; the
+						// public ref is only the file handle.
+						image = { name: value.name, uri: value.uri }
+					}
+				}
+			} catch {
+				// A malformed host result must not replace the current selection.
+			}
+
+			if (settled) {
+				if (image && image.uri !== deliveredUri) {
+					sheet.discard(image.uri)
+				}
+
+				return
+			}
+
+			settled = true
+			deliveredUri = image?.uri
+			if (image) {
+				// Shared with the AppKit file picker and files.release; never register
+				// a user-owned original or a rejected/late capture result. Only the
+				// host's own captures belong in the deletable registry — mirror the
+				// sheet's tempDir + octane-capture- guard on the reply's uri. The
+				// bridge does not expose standardizedFileURL, so compare against
+				// the same unstandardized temporaryDirectory the sheet writes to.
+				const manager = (globalThis as any).NSFileManager?.defaultManager
+				const tempDir = String(manager?.temporaryDirectory?.path ?? '')
+				const name = image.uri.slice(image.uri.lastIndexOf('/') + 1)
+				if (
+					tempDir !== '' &&
+					name.startsWith('octane-capture-') &&
+					image.uri === `${tempDir.replace(/\/+$/, '')}/${name}`
+				) {
+					const state = globalThis as typeof globalThis & {
+						__xplatTemporaryFiles?: Set<string>
+					}
+
+					;(state.__xplatTemporaryFiles ??= new Set<string>()).add(image.uri)
+				}
+			}
+
+			try {
+				sheet.dispose()
+			} finally {
+				if (active === sheet) {
+					active = undefined
+				}
+
+				resolve(image)
+			}
+		}
+
+		try {
+			sheet.presentReply(options, finish)
+		} catch {
+			finish(null)
+		}
+	})
+}

package/src/types.ts

@@ -19,13 +19,11 @@ export interface FileRef {
 }
 
 /**
- * Result of `media.pickImage()`: a displayable URI and an upload data URL.
- * Native URIs point to temporary JPEG files; delete them when the preview is
- * no longer needed.
+ * Result of `media.pickImage()`: a file ref usable directly as `Image.src`
+ * and with `files.readBytes()` for upload. Native URIs point to temporary
+ * JPEG files; `files.release()` them when the preview is no longer needed.
  */
-export interface PickedImage extends FileRef {
-	dataUrl: string
-}
+export type PickedImage = FileRef
 
 /**
  * Options for `media.capturePhoto()`. Sizes are device-independent pixels;
@@ -47,10 +45,12 @@ export interface MediaImpl {
 	pickImage(): Promise<PickedImage | null>
 	pickImages(): Promise<PickedImage[]>
 	/**
-	 * Still-image capture through the OS camera UI. Resolves null when the
-	 * shot is canceled, permission is denied, or no camera exists — call
-	 * `ensure('camera')` first to tell those apart. Video capture is not part
-	 * of the contract: no maintained NativeScript substrate exists.
+	 * Still-image capture through the OS camera UI (app-owned sheet on AppKit). Resolves null when the
+	 * shot is canceled, permission is denied, no camera exists, or the result cannot be
+	 * read or persisted — call
+	 * `ensure('camera')` from a user action to check permission separately.
+	 * AppKit rejects saveToGallery:true before permission or UI; it never writes
+	 * to Photos or requests microphone access. Use @octane-xplat/camera for movies.
 	 */
 	capturePhoto(options?: CapturePhotoOptions): Promise<PickedImage | null>
 	ensure(kind: MediaPermissionKind): Promise<PermissionResult>

package/types/generated/.tsrx-typegen-manifest.json

@@ -0,0 +1,12 @@
+{
+  "version": 1,
+  "files": [
+    "index.d.ts",
+    "index.macos.d.ts",
+    "media.d.ts",
+    "media.macos.d.ts",
+    "media.web.d.ts",
+    "photo-capture.macos.d.ts",
+    "types.d.ts"
+  ]
+}

package/types/generated/index.d.ts

@@ -0,0 +1,2 @@
+export * from './types.js';
+export { media } from './media.js';

package/types/generated/index.macos.d.ts

@@ -0,0 +1,2 @@
+export * from './types.js';
+export { media } from './media.macos.js';

package/types/generated/media.d.ts

@@ -0,0 +1,2 @@
+import type { MediaImpl } from './types.js';
+export declare const media: MediaImpl;

package/types/generated/media.macos.d.ts

@@ -0,0 +1,2 @@
+import type { MediaImpl } from './types.js';
+export declare const media: MediaImpl;

package/types/generated/media.web.d.ts

@@ -0,0 +1,2 @@
+import type { MediaImpl } from './types.js';
+export declare const media: MediaImpl;

package/types/generated/photo-capture.macos.d.ts

@@ -0,0 +1,5 @@
+import type { CapturePhotoOptions, PermissionResult, PickedImage } from './types.js';
+/** Query only. Still-photo authorization belongs to the sheet's Capture action. */
+export declare function ensureCamera(): Promise<PermissionResult>;
+/** Call from a user action. The sheet owns its preview until it settles. */
+export declare function capturePhoto(options?: CapturePhotoOptions): Promise<PickedImage | null>;

package/types/generated/types.d.ts

@@ -0,0 +1,51 @@
+/** Optional capability — never throws for absence (docs/platform/platform-services.md). */
+export interface Capability<T> {
+    supported: boolean;
+    ensure(): Promise<'granted' | 'denied' | 'unsupported'>;
+    /** usable iff supported && ensured */
+    impl: T | null;
+}
+export type PermissionResult = 'granted' | 'denied' | 'unsupported';
+export type MediaPermissionKind = 'camera' | 'photos';
+export interface FileRef {
+    name: string;
+    /**
+     * Opaque reference: blob/object URL on web, filesystem path on native.
+     */
+    uri: string;
+}
+/**
+ * Result of `media.pickImage()`: a file ref usable directly as `Image.src`
+ * and with `files.readBytes()` for upload. Native URIs point to temporary
+ * JPEG files; `files.release()` them when the preview is no longer needed.
+ */
+export type PickedImage = FileRef;
+/**
+ * Options for `media.capturePhoto()`. Sizes are device-independent pixels;
+ * the delivered image may be larger on high-density screens and may differ
+ * from the request when `keepAspectRatio` applies.
+ */
+export interface CapturePhotoOptions {
+    width?: number;
+    height?: number;
+    /** Preserve the sensor aspect ratio when resizing to width/height. Default true. */
+    keepAspectRatio?: boolean;
+    /** Also write the shot to the OS photo library. Default false. */
+    saveToGallery?: boolean;
+    /** Preferred lens. Default 'rear'; Android devices may ignore the hint. */
+    cameraFacing?: 'front' | 'rear';
+}
+export interface MediaImpl {
+    pickImage(): Promise<PickedImage | null>;
+    pickImages(): Promise<PickedImage[]>;
+    /**
+     * Still-image capture through the OS camera UI (app-owned sheet on AppKit). Resolves null when the
+     * shot is canceled, permission is denied, no camera exists, or the result cannot be
+     * read or persisted — call
+     * `ensure('camera')` from a user action to check permission separately.
+     * AppKit rejects saveToGallery:true before permission or UI; it never writes
+     * to Photos or requests microphone access. Use @octane-xplat/camera for movies.
+     */
+    capturePhoto(options?: CapturePhotoOptions): Promise<PickedImage | null>;
+    ensure(kind: MediaPermissionKind): Promise<PermissionResult>;
+}