@octane-xplat/media 0.0.1 → 0.10.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Alec Larson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -1,3 +1,55 @@
-# @octane-xplat/media
+# `@octane-xplat/media`
 
-Version 0.0.1 is a reservation stub so the automated release can publish this package name. It has no supported API. Use a later release for the implementation.
+```sh
+pnpm add @octane-xplat/media
+```
+
+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`.
+
+```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
+`'granted' | 'denied' | 'unsupported'`.
+
+```tsx
+import { useState } from 'octane'
+import { Button, Image } from '@octane-xplat/ui'
+import { media } from '@octane-xplat/media'
+
+export function PhotoPicker() {
+	const [preview, setPreview] = useState<string | null>(null)
+	async function pickPhoto() {
+		if ((await media.ensure('photos')) !== 'granted') return
+		const photo = await media.pickImage()
+		if (photo) setPreview(photo.dataUrl)
+	}
+	return (
+		<>
+			<Button onPress={pickPhoto}>Choose photo</Button>
+			{preview && <Image src={preview} alt="Selected photo" />}
+		</>
+	)
+}
+```
+
+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).
+Exercised by the harness `Services` screen and
+[`CameraDemo`](../demos/src/CameraDemo.tsrx).

package/package.json

@@ -1,19 +1,71 @@
 {
   "name": "@octane-xplat/media",
-  "version": "0.0.1",
+  "version": "0.10.0",
   "description": "Image picking and OS camera capture for Octane xplat — matching web + NativeScript implementations",
+  "keywords": [
+    "android",
+    "camera",
+    "cross-platform",
+    "image-picker",
+    "ios",
+    "media",
+    "nativescript",
+    "octane",
+    "photo",
+    "web",
+    "xplat"
+  ],
+  "homepage": "https://github.com/octane-xplat/octane-xplat/tree/main/packages/media",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/octane-xplat/octane-xplat.git",
+    "url": "https://github.com/octane-xplat/octane-xplat",
     "directory": "packages/media"
   },
-  "homepage": "https://github.com/octane-xplat/octane-xplat/tree/main/packages/media",
-  "main": "./index.js",
-  "types": "./index.d.ts",
   "files": [
-    "README.md",
-    "index.js",
-    "index.d.ts"
-  ]
-}
+    "src"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "macos": "./src/index.macos.ts",
+      "default": "./src/index.ts"
+    },
+    "./*": "./src/*"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@nativescript/camera": "7.0.0",
+    "@nativescript/imagepicker": "5.0.0"
+  },
+  "devDependencies": {
+    "@nativescript-community/octane": "0.2.4",
+    "@nativescript/core": "9.1.2",
+    "@nativescript/types": "9.0.0",
+    "octane": "0.6.3"
+  },
+  "peerDependencies": {
+    "@nativescript-community/octane": ">=0.2.1 <1",
+    "@nativescript/core": ">=9.1.0 <10",
+    "octane": ">=0.6.3 <1"
+  },
+  "peerDependenciesMeta": {
+    "@nativescript-community/octane": {
+      "optional": true
+    },
+    "@nativescript/core": {
+      "optional": true
+    }
+  },
+  "nativescript": {
+    "platforms": {
+      "android": "9.1.0",
+      "ios": "9.1.0"
+    }
+  },
+  "scripts": {
+    "test": "node --test tests/*.test.mjs"
+  }
+}

package/src/index.macos.ts

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

package/src/index.ts

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

package/src/media.macos.ts

@@ -0,0 +1,18 @@
+// Media — AppKit host leaf. No picker or capture flow is wired on the
+// desktop dev host.
+import type { MediaImpl } from './types'
+
+export const media: MediaImpl = {
+	async ensure() {
+		return 'unsupported'
+	},
+	async pickImage() {
+		return null
+	},
+	async pickImages() {
+		return []
+	},
+	async capturePhoto() {
+		return null
+	},
+}

package/src/media.ts

@@ -0,0 +1,197 @@
+// 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).
+import { isAvailable as isCameraAvailable, takePicture } from '@nativescript/camera'
+
+import { create as createImagePicker } from '@nativescript/imagepicker'
+// Ambient const enum — verbatimModuleSyntax forbids value access; Image = 1.
+import type { ImagePickerMediaType } from '@nativescript/imagepicker'
+import { Application, File, ImageSource, knownFolders, path } from '@nativescript/core'
+import type {
+	CapturePhotoOptions,
+	MediaImpl,
+	MediaPermissionKind,
+	PermissionResult,
+	PickedImage,
+} from './types'
+
+async function ensurePhotos(): Promise<PermissionResult> {
+	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'
+			: 'denied'
+	} catch {
+		return 'denied'
+	}
+}
+
+let cameraRequestCode = 7717
+
+// Request camera access through the platform primitives directly rather than
+// @nativescript/camera's requestCameraPermissions(): it delegates to
+// @nativescript-community/perms, and the bundler may resolve a perms major
+// whose return shape the plugin's status mapper can't read (3.x Status
+// string vs the 2.x `[status, bool]` array) — a granted permission then maps
+// to 'denied'. The direct paths can't drift with that dependency.
+async function ensureCamera(): Promise<PermissionResult> {
+	try {
+		if (!isCameraAvailable()) {
+			return 'unsupported'
+		}
+
+		if (Application.ios) {
+			const av = (globalThis as any).AVCaptureDevice
+			const video = (globalThis as any).AVMediaTypeVideo
+			// 0=notDetermined 1=restricted 2=denied 3=authorized
+			const status = av?.authorizationStatusForMediaType?.(video)
+			if (status === 3) {
+				return 'granted'
+			}
+
+			if (status === 1 || status === 2) {
+				return 'denied'
+			}
+
+			return await new Promise<PermissionResult>((resolve) => {
+				av.requestAccessForMediaTypeCompletionHandler(video, (granted: boolean) =>
+					resolve(granted ? 'granted' : 'denied'),
+				)
+			})
+		}
+
+		const perm = 'android.permission.CAMERA'
+		const activity = Application.android.foregroundActivity ?? Application.android.startActivity
+
+		if (
+			activity?.checkSelfPermission?.(perm) === android.content.pm.PackageManager.PERMISSION_GRANTED
+		) {
+			return 'granted'
+		}
+
+		if (!activity) {
+			return 'denied'
+		}
+
+		return await new Promise<PermissionResult>((resolve) => {
+			const requestCode = cameraRequestCode++
+			const onResult = (args: any) => {
+				if (args.requestCode !== requestCode) {
+					return
+				}
+
+				Application.android.off(Application.android.activityRequestPermissionsEvent, onResult)
+
+				resolve(
+					args.grantResults?.[0] === android.content.pm.PackageManager.PERMISSION_GRANTED
+						? 'granted'
+						: 'denied',
+				)
+			}
+
+			Application.android.on(Application.android.activityRequestPermissionsEvent, onResult)
+
+			activity.requestPermissions([perm], requestCode)
+		})
+	} catch (e) {
+		console.log('[media] ensureCamera error: ' + (e as Error)?.message)
+		return 'denied'
+	}
+}
+
+async function persistImage(source: ImageSource, name: string): Promise<PickedImage> {
+	const filename = `octane-image-${Date.now()}-${Math.random().toString(36).slice(2)}.jpg`
+	const uri = path.join(knownFolders.temp().path, filename)
+	try {
+		const saved = await source.saveToFileAsync(uri, 'jpeg', 85)
+		if (!saved) {
+			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}` }
+	} catch (error) {
+		// This operation owns this generated path, including a partial save.
+		try {
+			File.fromPath(uri).removeSync()
+		} catch {}
+
+		throw error
+	}
+}
+
+async function pickSelections(mode: 'single' | 'multiple'): Promise<PickedImage[]> {
+	const picker = createImagePicker({ mode, mediaType: 1 as ImagePickerMediaType })
+	const permission = (await picker.authorize()) as { authorized?: boolean } | boolean
+	if (
+		!(permission === true || (typeof permission === 'object' && permission.authorized === true))
+	) {
+		return []
+	}
+
+	const selections = await picker.present()
+	const refs: PickedImage[] = []
+	try {
+		for (const selection of selections) {
+			const source = await ImageSource.fromAsset(selection.asset)
+			const name = selection.originalFilename || selection.filename || 'image.jpg'
+			refs.push(await persistImage(source, name))
+		}
+
+		return refs
+	} catch (error) {
+		for (const ref of refs) {
+			try {
+				File.fromPath(ref.uri).removeSync()
+			} catch {}
+		}
+
+		throw error
+	}
+}
+
+export const media: MediaImpl = {
+	/** Opens the native image picker; returns null when canceled. */
+	async pickImage(): Promise<PickedImage | null> {
+		const [image] = await pickSelections('single')
+		return image ?? null
+	},
+	/** Opens the native image picker in multiple-selection mode. */
+	pickImages() {
+		return pickSelections('multiple')
+	},
+	/** Presents the OS camera UI; null when canceled, denied, or unsupported. */
+	async capturePhoto(options?: CapturePhotoOptions): Promise<PickedImage | null> {
+		if ((await ensureCamera()) !== 'granted') {
+			return null
+		}
+
+		try {
+			const asset = await takePicture({
+				width: options?.width,
+				height: options?.height,
+				keepAspectRatio: options?.keepAspectRatio,
+				saveToGallery: options?.saveToGallery ?? false,
+				cameraFacing: options?.cameraFacing,
+			})
+
+			const source = await ImageSource.fromAsset(asset)
+			return await persistImage(source, `octane-capture-${Date.now()}.jpg`)
+		} catch {
+			return null
+		}
+	},
+	async ensure(kind: MediaPermissionKind): Promise<PermissionResult> {
+		return kind === 'photos' ? ensurePhotos() : ensureCamera()
+	},
+}
+
+// Register the permission owners this leaf provides so
+// @octane-xplat/platform's `permissions.ensure(kind)` can reach them without
+// a dependency edge — the generic seam reports 'unsupported' when the leaf
+// is not installed.
+const permissionOwners = ((globalThis as any).__xplatPermissionOwners ??= {})
+permissionOwners.camera = () => ensureCamera()
+permissionOwners.photos = () => ensurePhotos()

package/src/media.web.ts

@@ -0,0 +1,122 @@
+// 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.
+import type {
+	CapturePhotoOptions,
+	MediaImpl,
+	MediaPermissionKind,
+	PermissionResult,
+	PickedImage,
+} from './types'
+
+function selectFiles(multiple: boolean, capture?: 'user' | 'environment'): Promise<File[]> {
+	return new Promise((resolve) => {
+		const input = document.createElement('input')
+		input.type = 'file'
+		input.accept = 'image/*'
+		input.multiple = multiple
+		if (capture) {
+			input.capture = capture
+		}
+
+		input.onchange = () => resolve(Array.from(input.files ?? []))
+		input.oncancel = () => resolve([])
+		input.click()
+	})
+}
+
+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'))
+			}
+		}
+
+		reader.onerror = () => reject(reader.error ?? new Error('Could not read the selected image'))
+
+		reader.readAsDataURL(file)
+	})
+}
+
+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]! })
+		}
+
+		return refs
+	} catch (error) {
+		for (const ref of refs) {
+			URL.revokeObjectURL(ref.uri)
+		}
+
+		throw error
+	}
+}
+
+async function pickFiles(multiple: boolean): Promise<PickedImage[]> {
+	return imageRefs(await selectFiles(multiple))
+}
+
+export const media: MediaImpl = {
+	/** Opens the browser image picker; returns null when selection is canceled. */
+	async pickImage(): Promise<PickedImage | null> {
+		const [image] = await pickFiles(false)
+		return image ?? null
+	},
+	/** Opens the browser image picker with multiple selection enabled. */
+	pickImages() {
+		return pickFiles(true)
+	},
+	/**
+	 * Requests a camera shot via `<input type="file" capture>`. Mobile browsers
+	 * open the camera UI; desktop browsers fall back to the file picker —
+	 * there is no headless still-capture API without a rendered viewfinder.
+	 * `width`/`height`/`keepAspectRatio`/`saveToGallery` have no web meaning
+	 * and are ignored.
+	 */
+	async capturePhoto(options?: CapturePhotoOptions): Promise<PickedImage | null> {
+		const facing = options?.cameraFacing === 'front' ? 'user' : 'environment'
+		const [file] = await selectFiles(false, facing)
+		if (!file) {
+			return null
+		}
+
+		const [image] = await imageRefs([file])
+		return image ?? 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'
+		}
+	},
+}
+
+// See media.ts — registers the kinds this leaf owns for the platform
+// permissions dispatcher.
+const permissionOwners = ((globalThis as any).__xplatPermissionOwners ??= {})
+permissionOwners.camera = () => media.ensure('camera')
+permissionOwners.photos = () => media.ensure('photos')

package/src/types.ts

@@ -0,0 +1,57 @@
+/** 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 displayable URI and an upload data URL.
+ * Native URIs point to temporary JPEG files; delete them when the preview is
+ * no longer needed.
+ */
+export interface PickedImage extends FileRef {
+	dataUrl: string
+}
+
+/**
+ * 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. 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.
+	 */
+	capturePhoto(options?: CapturePhotoOptions): Promise<PickedImage | null>
+	ensure(kind: MediaPermissionKind): Promise<PermissionResult>
+}

package/index.d.ts

@@ -1 +0,0 @@
-export {}

package/index.js

@@ -1,2 +0,0 @@
-// Reservation stub; implementation will arrive in a later release.
-module.exports = {}