Content.image
luastra/contentContent.image(handle: string, metadata: ImageMetadata): Image
Creates a typed image reference from an opaque protected or host-local preview handle and bounded media metadata. The handle remains provider-neutral and cannot contain a URL, path, raw bytes, or bucket name.
Before you use it
Add luastra/content to this module's dependencies in luastra.json, then import it with require("luastra/content"). Declare content.pick for browser selection and content.upload for transfer. Upload requires a server-created intent from an authenticated declared backend function. Application code must never construct a provider URL, file path, data URL, blob URL, bucket path, or upload handle.
How it fits
Image construction and decoders are synchronous. Selection, release, upload, and cancellation return request IDs and complete through application/app resolve; progress enters application/app handle as content_progress.
When to use it
Use Content.image after a generated backend result or admitted picker returns a content: or preview: handle with validated metadata. Pass the result directly to UI.Image and refresh it after onError when appropriate.
Parameters
| Parameter | Type / values | Description |
|---|---|---|
| handle | string | Opaque content: or preview: handle returned by a trusted boundary. |
| metadata | ImageMetadata | Bounded media type, bytes, pixel dimensions, orientation, and optional placeholder color. |
Returns
Image — a typed image reference admitted from the project manifest.
What happens next
A bounded image lifecycle that keeps local files and provider credentials outside Luau while reusing UI.Image.
Failures and fixes
Cancellation, malformed or expired handles, unsupported media types, excessive bytes or dimensions, offline transfer, authorization denial, and decode failure remain explicit branches. Release previews, request fresh display grants after UI.Image.onError, and never persist or log upload/content handles.
Availability
Private source foundation after 0.5.0-alpha; browser PNG/JPEG selection and upload are automated, while camera and native picker certification remain later evidence gates.
Focused example
local Content = require("luastra/content")
local cover = Content.image(result.source, {
mediaType = result.mediaType,
bytes = result.bytes,
width = result.width,
height = result.height,
})