@bagelink/vue 1.15.668 → 1.17.2

package/src/assets.test.ts

@@ -0,0 +1,123 @@
+// @vitest-environment happy-dom
+import { describe, expect, it, vi } from 'vitest'
+import { createAssetClient, ASSET_CLIENT_KEY, useAssetDelivery, type AssetDelivery, type AssetTransport } from './assets'
+import { mount } from '@vue/test-utils'
+import { defineComponent, nextTick } from 'vue'
+
+const delivery = (version_id = 'v1'): AssetDelivery => ({
+	url: 'https://delivery.example/private',
+	expires_at: new Date(Date.now() + 60_000).toISOString(),
+	version_id,
+})
+
+function setup() {
+	const resolve = vi.fn<AssetTransport['resolve']>(async references => references.map(() => delivery()))
+	const upload = vi.fn<AssetTransport['upload']>(async () => ({ asset_id: 'a', version_id: 'v1' }))
+	return { resolve, upload, client: createAssetClient({ resolve, upload }) }
+}
+
+describe('asset client', () => {
+	it('keeps the displayed URL while refreshing, but clears immediately on session change', async () => {
+		vi.useFakeTimers()
+		const { client, resolve } = setup()
+		let finish!: (value: AssetDelivery[]) => void
+		let state!: ReturnType<typeof useAssetDelivery>
+		const component = mount(defineComponent({
+			setup() { state = useAssetDelivery(() => ({ asset_id: 'a' })); return () => null },
+		}), { global: { provide: { [ASSET_CLIENT_KEY as symbol]: client } } })
+		try {
+			await vi.advanceTimersByTimeAsync(0)
+			expect(state.url.value).toBe(delivery().url)
+			resolve.mockImplementationOnce(() => new Promise(done => { finish = done }))
+			await vi.advanceTimersByTimeAsync(48_000)
+			expect(resolve).toHaveBeenCalledTimes(2)
+			expect(state.url.value).toBe(delivery().url)
+			client.clearSession()
+			expect(state.url.value).toBeUndefined()
+			finish([delivery()])
+			await nextTick()
+			expect(state.url.value).toBeUndefined()
+		} finally {
+			component.unmount()
+			vi.useRealTimers()
+		}
+	})
+
+	it('deduplicates in-flight requests without sharing subscriber cancellation', async () => {
+		const { client, resolve } = setup()
+		let finish!: (value: AssetDelivery[]) => void
+		resolve.mockImplementationOnce(() => new Promise(done => { finish = done }))
+		const controller = new AbortController()
+		const first = client.resolve({ asset_id: 'a' }, controller.signal)
+		const rejected = expect(first).rejects.toMatchObject({ name: 'AbortError' })
+		await Promise.resolve()
+		const second = client.resolve({ asset_id: 'a', representation: 'original' })
+		controller.abort()
+		await rejected
+		expect(resolve.mock.calls[0]![1].aborted).toBe(false)
+		finish([delivery()])
+		await expect(second).resolves.toMatchObject({ version_id: 'v1' })
+		expect(resolve).toHaveBeenCalledTimes(1)
+	})
+
+	it('aborts unused requests and starts fresh after a session change', async () => {
+		const { client, resolve } = setup()
+		resolve.mockImplementationOnce(() => new Promise(() => {}))
+		const first = client.resolve({ asset_id: 'a' })
+		const rejected = expect(first).rejects.toMatchObject({ name: 'AbortError' })
+		await Promise.resolve()
+		client.clearSession()
+		await rejected
+		expect(resolve.mock.calls[0]![1].aborted).toBe(true)
+		await expect(client.resolve({ asset_id: 'a' })).resolves.toMatchObject({ version_id: 'v1' })
+		expect(resolve).toHaveBeenCalledTimes(2)
+	})
+
+	it('batches same-turn resolutions and preserves pins', async () => {
+		const { client, resolve } = setup()
+		await Promise.all([client.resolve({ asset_id: 'a', version_id: 'v1' }), client.resolve({ asset_id: 'b' })])
+		expect(resolve).toHaveBeenCalledTimes(1)
+		expect(resolve.mock.calls[0]![0][0]).toEqual({ asset_id: 'a', version_id: 'v1' })
+	})
+
+	it('does not cache grants between calls', async () => {
+		const { client, resolve } = setup()
+		await client.resolve({ asset_id: 'a' })
+		await client.resolve({ asset_id: 'a' })
+		expect(resolve).toHaveBeenCalledTimes(2)
+	})
+
+	it('rejects expired grants and mismatched pinned versions', async () => {
+		const { client, resolve } = setup()
+		await expect(client.resolve({ asset_id: 'a', version_id: 'v2' })).rejects.toThrow('Invalid asset delivery')
+		resolve.mockResolvedValueOnce([{ ...delivery(), expires_at: '2000-01-01T00:00:00Z' }])
+		await expect(client.resolve({ asset_id: 'a' })).rejects.toThrow('Invalid asset delivery')
+	})
+
+	it('cancels queued requests on session change', async () => {
+		const { client, resolve } = setup()
+		const request = client.resolve({ asset_id: 'a' })
+		client.clearSession()
+		await expect(request).rejects.toMatchObject({ name: 'AbortError' })
+		expect(resolve).not.toHaveBeenCalled()
+	})
+
+	it('rejects stale in-flight results even if transport ignores abort', async () => {
+		const { client, resolve } = setup()
+		let finish!: (value: AssetDelivery[]) => void
+		resolve.mockImplementationOnce(() => new Promise(done => { finish = done }))
+		const request = client.resolve({ asset_id: 'a' })
+		await Promise.resolve()
+		client.clearSession()
+		finish([delivery()])
+		await expect(request).rejects.toMatchObject({ name: 'AbortError' })
+	})
+
+	it('does not dispatch already-cancelled requests', async () => {
+		const { client, resolve } = setup()
+		const controller = new AbortController()
+		controller.abort()
+		await expect(client.resolve({ asset_id: 'a' }, controller.signal)).rejects.toMatchObject({ name: 'AbortError' })
+		expect(resolve).not.toHaveBeenCalled()
+	})
+})

package/src/assets.ts

@@ -0,0 +1,245 @@
+import { inject, onScopeDispose, ref, toValue, watch, type InjectionKey, type MaybeRefOrGetter } from 'vue'
+
+/** Persist this reference, never an AssetDelivery. Version pins are immutable. */
+export interface AssetReference {
+	asset_id: string
+	version_id?: string
+}
+
+export interface AssetDelivery {
+	url: string
+	expires_at: string
+	version_id: string
+}
+
+export type AssetPurpose = 'original' | 'preview' | 'thumbnail' | 'website' | 'social'
+
+export interface AssetDeliveryRequest extends AssetReference {
+	/** Backend-approved preset, e.g. an image preview; never arbitrary transforms. */
+	representation?: AssetPurpose
+}
+
+/** A separate facade: generated SDK namespaces remain unchanged. */
+export interface AssetTransport {
+	/** Return deliveries in request order; adapt the SDK's `{items}` envelope here. */
+	resolve(references: readonly AssetDeliveryRequest[], signal: AbortSignal): Promise<AssetDelivery[]>
+	upload(file: File, signal: AbortSignal): Promise<AssetReference>
+}
+
+interface Pending {
+	reference: AssetDeliveryRequest
+	signal?: AbortSignal
+	resolve: (delivery: AssetDelivery) => void
+	reject: (reason: unknown) => void
+}
+
+const abortError = () => new DOMException('Asset request cancelled', 'AbortError')
+
+/** App/session scoped, with no persistent storage or delivery cache. */
+export function createAssetClient(transport: AssetTransport) {
+	const revision = ref(0)
+	const controllers = new Set<AbortController>()
+	let pending: Pending[] = []
+	let scheduled = false
+	const inFlight = new Map<string, { controller: AbortController; promise: Promise<AssetDelivery>; users: number }>()
+
+	async function flush() {
+		scheduled = false
+		const batch = pending
+		pending = []
+		const active = batch.filter(item => !item.signal?.aborted)
+		for (const item of batch) if (item.signal?.aborted) item.reject(abortError())
+		if (!active.length) return
+		const controller = new AbortController()
+		controllers.add(controller)
+		const cancelIfUnused = () => {
+			for (const item of active) if (item.signal?.aborted) item.reject(abortError())
+			if (active.every(item => item.signal?.aborted)) controller.abort()
+		}
+		const rejectAborted = () => {
+			for (const item of active) item.reject(abortError())
+		}
+		controller.signal.addEventListener('abort', rejectAborted, { once: true })
+		for (const item of active) item.signal?.addEventListener('abort', cancelIfUnused)
+		try {
+			const deliveries = await transport.resolve(active.map(item => item.reference), controller.signal)
+			if (controller.signal.aborted) throw abortError()
+			if (deliveries.length !== active.length) throw new Error('Incomplete asset delivery batch')
+			active.forEach((item, index) => {
+				const delivery = deliveries[index]!
+				if (item.signal?.aborted) item.reject(abortError())
+				else if (!Number.isFinite(Date.parse(delivery.expires_at))
+					|| Date.parse(delivery.expires_at) <= Date.now()
+					|| !/^https?:\/\//.test(delivery.url)
+					|| !delivery.version_id
+					|| (item.reference.version_id && item.reference.version_id !== delivery.version_id)) {
+					item.reject(new Error('Invalid asset delivery'))
+				} else item.resolve(delivery)
+			})
+		} catch (error) {
+			for (const item of active) item.reject(error)
+		} finally {
+			controllers.delete(controller)
+			controller.signal.removeEventListener('abort', rejectAborted)
+			for (const item of active) item.signal?.removeEventListener('abort', cancelIfUnused)
+		}
+	}
+
+	return {
+		revision,
+		resolve(reference: AssetDeliveryRequest, signal?: AbortSignal): Promise<AssetDelivery> {
+			if (signal?.aborted) return Promise.reject(abortError())
+			const key = JSON.stringify([reference.asset_id, reference.version_id ?? null, reference.representation ?? 'original'])
+			let entry = inFlight.get(key)
+			if (!entry) {
+				const controller = new AbortController()
+				const promise = new Promise<AssetDelivery>((resolve, reject) => {
+					pending.push({ reference: { ...reference }, signal: controller.signal, resolve, reject })
+					if (!scheduled) { scheduled = true; queueMicrotask(() => { void flush() }) }
+				})
+				entry = { controller, promise, users: 0 }
+				inFlight.set(key, entry)
+				const current = entry
+				void promise.then(() => {
+					if (inFlight.get(key) === current) inFlight.delete(key)
+				}, () => {
+					if (inFlight.get(key) === current) inFlight.delete(key)
+				})
+			}
+			const shared = entry
+			shared.users++
+			return new Promise((resolve, reject) => {
+				let settled = false
+				const finish = () => {
+					if (settled) return false
+					settled = true
+					signal?.removeEventListener('abort', abort)
+					shared.users--
+					if (!shared.users) {
+						if (inFlight.get(key) === shared) inFlight.delete(key)
+						shared.controller.abort()
+					}
+					return true
+				}
+				const abort = () => { if (finish()) reject(abortError()) }
+				signal?.addEventListener('abort', abort, { once: true })
+				void shared.promise.then(value => { if (finish()) resolve(value) }, error => { if (finish()) reject(error) })
+			})
+		},
+		async upload(file: File, signal?: AbortSignal): Promise<AssetReference> {
+			const controller = new AbortController()
+			const abort = () => controller.abort()
+			signal?.addEventListener('abort', abort, { once: true })
+			controllers.add(controller)
+			try {
+				if (signal?.aborted) controller.abort()
+				if (controller.signal.aborted) throw abortError()
+				const reference = await transport.upload(file, controller.signal)
+				if (controller.signal.aborted) throw abortError()
+				return { asset_id: reference.asset_id, version_id: reference.version_id }
+			} finally {
+				controllers.delete(controller)
+				signal?.removeEventListener('abort', abort)
+			}
+		},
+		/** Call synchronously before logout/tenant/account transitions. */
+		clearSession() {
+			inFlight.clear()
+			for (const controller of controllers) controller.abort()
+			for (const item of pending) item.reject(abortError())
+			pending = []
+			revision.value++
+		},
+	}
+}
+
+export type AssetClient = ReturnType<typeof createAssetClient>
+export const ASSET_CLIENT_KEY: InjectionKey<AssetClient> = Symbol('bagel:assets')
+
+/** Opt-in upload state; original bytes are handed unchanged to the transport. */
+export function useAssetUpload() {
+	const client = inject(ASSET_CLIENT_KEY, undefined)
+	const uploading = ref(false)
+	const reference = ref<AssetReference>()
+	let controller: AbortController | undefined
+	let generation = 0
+	function cancel() {
+		generation++
+		controller?.abort()
+		uploading.value = false
+		reference.value = undefined
+	}
+	async function upload(file: File): Promise<AssetReference> {
+		cancel()
+		if (!client) throw new Error('Asset client is not configured')
+		const current = generation
+		controller = new AbortController()
+		uploading.value = true
+		try {
+			const result = await client.upload(file, controller.signal)
+			if (current !== generation) throw abortError()
+			reference.value = result
+			return result
+		} finally {
+			if (current === generation) uploading.value = false
+		}
+	}
+	const stop = client ? watch(client.revision, cancel, { flush: 'sync' }) : undefined
+	onScopeDispose(() => { cancel(); stop?.() })
+	return { upload, cancel, uploading, reference }
+}
+
+/** Private resolution stays inside display primitives, not persisted domain data. */
+export function useAssetDelivery(source: MaybeRefOrGetter<AssetDeliveryRequest | undefined>) {
+	const client = inject(ASSET_CLIENT_KEY, undefined)
+	const url = ref<string>()
+	const error = ref(false)
+	let controller: AbortController | undefined
+	let timer: ReturnType<typeof setTimeout> | undefined
+	let generation = 0
+	let retried = false
+	let invalidated = false
+
+	function cancel(keepUrl = false) {
+		generation++
+		controller?.abort()
+		clearTimeout(timer)
+		if (!keepUrl) url.value = undefined
+	}
+	async function load(refresh = false) {
+		cancel(refresh)
+		error.value = false
+		if (invalidated) return
+		const reference = toValue(source)
+		if (!reference) return
+		if (!client) { error.value = true; return }
+		const current = generation
+		controller = new AbortController()
+		try {
+			const delivery = await client.resolve(reference, controller.signal)
+			if (current !== generation) return
+			url.value = delivery.url
+			const remaining = Date.parse(delivery.expires_at) - Date.now()
+			timer = setTimeout(() => { void load(true) }, Math.min(2_147_483_647, Math.max(1, remaining * 0.8)))
+		} catch {
+			if (current === generation) { error.value = true; url.value = undefined }
+		}
+	}
+	function onError() {
+		if (retried) { cancel(); error.value = true; return }
+		retried = true
+		void load()
+	}
+	watch(() => [toValue(source)?.asset_id, toValue(source)?.version_id, toValue(source)?.representation], () => {
+		retried = false
+		invalidated = false
+		void load()
+	}, { immediate: true })
+	// Never automatically reauthorize old references under a different session.
+	const stop = client ? watch(client.revision, () => {
+		invalidated = true
+		cancel()
+	}, { flush: 'sync' }) : undefined
+	onScopeDispose(() => { cancel(); stop?.() })
+	return { url, error, onError }
+}

package/src/components/Image.vue

@@ -1,10 +1,16 @@
 <script setup lang="ts">
 defineOptions({ name: 'BglImage', inheritAttrs: false })
 import { Skeleton, normalizeDimension, Icon, useImageSrc } from '../index'
+import type { AssetDeliveryRequest, AssetPurpose } from '../assets'
 import { Comment, computed, ref, useSlots, watch, type StyleValue, type VNode } from 'vue'
 
 interface ImageProps {
-	src?: string
+	src?: string | AssetDeliveryRequest
+	/** Stable asset UUID; requires an injected asset client. */
+	assetId?: string
+	versionId?: string
+	/** Server preset; width/height below control layout only. */
+	purpose?: AssetPurpose
 	pathKey?: string
 	alt?: string
 	width?: string | number
@@ -25,10 +31,17 @@ interface ImageProps {
 
 const props = defineProps<ImageProps>()
 
-const { imageSrc, loadingError } = useImageSrc(() => props.src ?? props.pathKey ?? props.modelValue)
+const { imageSrc, loadingError, onError } = useImageSrc(() => props.assetId
+	? { asset_id: props.assetId, version_id: props.versionId, representation: props.purpose }
+	: typeof props.src === 'object'
+		? { ...props.src, representation: props.purpose ?? props.src.representation }
+		: props.src ?? props.pathKey ?? props.modelValue)
 const imageLoaded = ref(false)
 
-watch(imageSrc, () => {
+watch(imageSrc, value => {
+	if (!value) imageLoaded.value = false
+})
+watch(() => [props.assetId, props.versionId, props.purpose, props.src, props.pathKey, props.modelValue], () => {
 	imageLoaded.value = false
 })
 
@@ -101,6 +114,7 @@ const imgFit = computed(() => props.fit ?? 'cover')
 			:class="[frameHasHeight ? 'absolute-fill' : 'bgl-image-frame-img--flow', { 'opacity-0': !imageLoaded }]"
 			:style="{ objectFit: imgFit, mixBlendMode: blend } as StyleValue"
 			@load="onImageLoad"
+			@error="onError"
 		>
 		<Skeleton v-if="!imageLoaded && !loadingError" class="absolute-fill" />
 		<div v-else-if="loadingError && !gradientCss" class="flex-center absolute-fill error-image">
@@ -120,6 +134,7 @@ const imgFit = computed(() => props.fit ?? 'cover')
 			:height="normalizeDimension(height)"
 				:class="{ 'opacity-0': !imageLoaded }"
 				@load="onImageLoad"
+				@error="onError"
 		>
 		<Skeleton
 				v-if="!imageLoaded && !loadingError"
@@ -144,6 +159,7 @@ const imgFit = computed(() => props.fit ?? 'cover')
 			:class="{ 'opacity-0': !imageLoaded }"
 			:style="{ objectFit: imgFit }"
 			@load="onImageLoad"
+			@error="onError"
 		>
 		<div v-if="loadingError" class="flex-center absolute-fill error-image">
 			<Icon name="broken_image" />

package/src/components/form/inputs/Upload/AssetUploadInput.vue

@@ -0,0 +1,67 @@
+<script setup lang="ts">
+import { computed, onScopeDispose, ref } from 'vue'
+import { Btn, Image, Card, Loading } from '../../../../index'
+import { useAssetUpload, type AssetReference } from '../../../../assets'
+import { useFileUpload } from './useFileUpload'
+import { useFileDropzone } from '../../../file-drop/useFileDropzone'
+import type { UploadInputProps } from '../../../../types/BagelForm'
+
+const props = defineProps<UploadInputProps>()
+const emit = defineEmits<{
+	'update:modelValue': [value: AssetReference | AssetReference[] | undefined]
+	addFileStart: []
+}>()
+const { upload, uploading, cancel } = useAssetUpload()
+const failure = ref('')
+const values = computed<AssetReference[]>(() => [props.modelValue].flat().filter(
+	(value): value is AssetReference => !!value && typeof value === 'object' && 'asset_id' in value,
+))
+const disabled = computed(() => props.disabled || props.readonly || uploading.value)
+function output(items: AssetReference[]) {
+	emit('update:modelValue', props.multiple ? items : items[0])
+}
+const { browse, addFile, fileQueue } = useFileUpload({
+	multiple: props.multiple, accept: props.accept, capture: props.capture,
+	onFileQueued: async queued => {
+		if (disabled.value) {
+			for (const item of queued) if (item.url) URL.revokeObjectURL(item.url)
+			fileQueue.value = []
+			return
+		}
+		failure.value = ''
+		emit('addFileStart')
+		const next = props.multiple ? [...values.value] : []
+		try {
+			for (const item of props.multiple ? queued : queued.slice(0, 1)) {
+				next.push(await upload(item.file))
+				output([...next])
+			}
+		} catch (error) {
+			if (!(error instanceof DOMException && error.name === 'AbortError')) failure.value = 'Upload failed. Please try again.'
+		} finally {
+			for (const item of queued) if (item.url) URL.revokeObjectURL(item.url)
+			fileQueue.value = []
+		}
+	},
+})
+const { handlers } = useFileDropzone({ disabled, onDrop: files => addFile(files) })
+onScopeDispose(() => {
+	for (const item of fileQueue.value) if (item.url) URL.revokeObjectURL(item.url)
+})
+</script>
+
+<template>
+	<Card outline class="flex column gap-1 p-1" v-on="handlers">
+		<label v-if="label">{{ label }}</label>
+		<div v-for="(value, index) in values" :key="`${value.asset_id}:${value.version_id}`" class="flex gap-1 align-items-center">
+			<Image v-if="accept?.startsWith('image/')" :src="value" width="80" height="80" />
+			<span class="ellipsis-1">{{ value.asset_id }}</span>
+			<Btn v-if="!readonly" flat icon="close" :disabled="disabled" aria-label="Remove attachment"
+				@click="output(values.filter((_, i) => i !== index))" />
+		</div>
+		<Loading v-if="uploading" />
+		<Btn v-if="!readonly" :disabled="disabled" icon="upload" :value="btnPlaceholder || 'Upload file'" @click="browse()" />
+		<Btn v-if="uploading" flat value="Cancel" @click="cancel" />
+		<p v-if="failure || error" role="alert">{{ failure || error }}</p>
+	</Card>
+</template>

package/src/components/form/inputs/Upload/UploadInput.vue

@@ -5,6 +5,7 @@ import { watch, computed, ref, useSlots } from 'vue'
 import { useFileDropzone } from '../../../file-drop/useFileDropzone'
 import { useFileUpload } from './useFileUpload'
 import { useBagelInputShell } from '../bagelInputShell'
+import AssetUploadInput from './AssetUploadInput.vue'
 
 const props = withDefaults(defineProps<UploadInputProps>(), {
 	height: '215px',
@@ -32,7 +33,7 @@ const {
 	pk,
 } = useFileUpload({
 	disabled: props.disabled,
-	dirPath: props.dirPath,
+	dirPath: props.assetMode ? undefined : props.dirPath,
 	multiple: props.multiple,
 	accept: props.accept,
 	capture: props.capture,
@@ -121,7 +122,10 @@ function fileName(pathKey: string) {
 </script>
 
 <template>
+	<AssetUploadInput v-if="assetMode" v-bind="props"
+		@update:model-value="emit('update:modelValue', $event)" @add-file-start="emit('addFileStart')" />
 	<div
+		v-else
 		class="bagel-input" :class="[shellClass, { 'has-error': !!error, 'has-value': hasValue }]"
 		:style="shellStyle" :data-field="name || id"
 	>

package/src/components/lightbox/AssetPreview.vue

@@ -0,0 +1,16 @@
+<script setup lang="ts">
+import { useAssetDelivery, type AssetReference } from '../../assets'
+import { Btn, Image } from '../../index'
+const props = defineProps<{ asset: AssetReference, type: string, name?: string }>()
+const { url, error, onError } = useAssetDelivery(() => props.asset)
+</script>
+
+<template>
+	<div class="flex column gap-1">
+		<Image v-if="type === 'image'" :src="asset" />
+		<video v-else-if="type === 'video' && url" :src="url" controls @error="onError" />
+		<iframe v-else-if="type === 'pdf' && url" :src="url" :title="name || 'PDF preview'" referrerpolicy="no-referrer" />
+		<Btn v-if="url" :href="url" target="_blank" rel="noopener noreferrer" value="Open / download" />
+		<p v-if="error" role="alert">File preview unavailable.</p>
+	</div>
+</template>

package/src/components/lightbox/Lightbox.vue

@@ -4,6 +4,7 @@ import type { LightboxItem } from './lightbox.types'
 import { BglVideo, Btn, Icon, Zoomer, Image, normalizeURL, Swiper, downloadFile, useEscapeKey } from '../../index'
 import { computed, nextTick, ref, watch } from 'vue'
 import LightboxImage from './LightboxImage.vue'
+import AssetPreview from './AssetPreview.vue'
 
 const isOpen = ref(false)
 const dialogRef = ref<HTMLDialogElement | null>(null)
@@ -29,7 +30,10 @@ function open(item: LightboxItem, groupItems?: LightboxItem[]) {
 			&& groupItem.src === item.src
 		const hasPathMatch = item.pathKey !== undefined && item.pathKey !== null && item.pathKey !== ''
 			&& groupItem.pathKey === item.pathKey
-		return hasSrcMatch || hasPathMatch
+		const hasAssetMatch = item.asset && groupItem.asset
+			&& item.asset.asset_id === groupItem.asset.asset_id
+			&& item.asset.version_id === groupItem.asset.version_id
+		return hasSrcMatch || hasPathMatch || hasAssetMatch
 	})
 	if (currentIndex.value === -1) currentIndex.value = 0
 	zoom.value = 1
@@ -98,9 +102,10 @@ defineExpose({ open, close })
 						<Zoomer v-if="item.type === 'image'" v-model:zoom="zoom" :disabled="!item?.enableZoom"
 							:mouse-wheel-to-zoom="false" :double-click-to-zoom="true" :max-scale="5" :min-scale="1"
 							:aspect-ratio="0" :limit-translation="true" @click.stop>
-							<LightboxImage :src="item?.src" />
+							<LightboxImage :src="item?.asset ?? item?.src ?? item?.pathKey" />
 						</Zoomer>
 
+						<AssetPreview v-else-if="item.asset" :asset="item.asset" :type="item.type" :name="item.name" />
 						<BglVideo v-else-if="item?.type === 'video' && item?.src" :src="item?.src" autoplay controls
 							class="lightbox-video" />
 
@@ -143,7 +148,7 @@ defineExpose({ open, close })
 
 			<div v-if="group && group.length > 1" class="lightbox-thumbnails" @click.stop>
 				<template v-for="(item, index) in group" :key="index">
-					<Image v-if="item.type === 'image'" class="thumbnail" :src="item.src" alt=""
+					<Image v-if="item.type === 'image'" class="thumbnail" :src="item.asset ?? item.src ?? item.pathKey" alt=""
 						:class="{ active: currentIndex === index }" @click.stop="selectItem(index)" />
 					<Icon v-else class="thumbnail thumbnail-icon" icon="description"
 						:class="{ active: currentIndex === index }" @click.stop="selectItem(index)" />

package/src/components/lightbox/LightboxImage.vue

@@ -4,11 +4,12 @@
 // so the natural dimensions drive layout — <Image>'s framed mode renders an
 // absolute-fill img that collapses the zoomer to 0×0.
 import { useImageSrc } from '../../index'
+import type { AssetReference } from '../../assets'
 
-const props = defineProps<{ src?: string }>()
-const { imageSrc } = useImageSrc(() => props.src)
+const props = defineProps<{ src?: string | AssetReference }>()
+const { imageSrc, onError } = useImageSrc(() => props.src)
 </script>
 
 <template>
-	<img :draggable="false" :src="imageSrc" alt="Preview" class="lightbox-image">
+	<img :draggable="false" :src="imageSrc" alt="Preview" class="lightbox-image" @error="onError">
 </template>

package/src/components/lightbox/index.ts

@@ -1,8 +1,9 @@
 import type { App, Directive, DirectiveBinding, Plugin } from 'vue'
+import { ASSET_CLIENT_KEY, type AssetClient } from '../../assets'
 
 import type { LightboxItem } from './lightbox.types'
 import { IMAGE_FORMATS_REGEXP, pathKeyToURL, VIDEO_FORMATS_REGEXP } from '../../index'
-import { createApp } from 'vue'
+import { createApp, inject } from 'vue'
 import Lightbox from './Lightbox.vue'
 
 type OpenFunction = (item: LightboxItem, groupItems?: LightboxItem[]) => void
@@ -36,7 +37,9 @@ const lightboxDirective: Directive = {
 function groupHandler(item: LightboxItem) {
 	if (item.group) {
 		if (!groups[item.group]) { groups[item.group] = [] }
-		const currentIndex = groups[item.group].findIndex(i => i.src === item.src)
+		const currentIndex = groups[item.group].findIndex(i => item.asset
+			? i.asset?.asset_id === item.asset.asset_id && i.asset?.version_id === item.asset.version_id
+			: i.src === item.src)
 		if (currentIndex === -1) { groups[item.group].push(item) }
 	}
 }
@@ -44,7 +47,7 @@ function groupHandler(item: LightboxItem) {
 function openClickHandler(e: MouseEvent, el: HTMLElement, binding: DirectiveBinding) {
 	e.stopPropagation()
 	const item = bindingToItem(binding, el)
-	const lightboxInstance = getLightboxInstance()
+	const lightboxInstance = getLightboxInstance(binding)
 	if (!lightboxInstance || !lightboxInstance.open) { return }
 	const open = lightboxInstance.open as OpenFunction
 	const group = item && item.group ? groups[item.group] : undefined
@@ -52,6 +55,9 @@ function openClickHandler(e: MouseEvent, el: HTMLElement, binding: DirectiveBind
 }
 
 function bindingToItem(binding: DirectiveBinding, el: HTMLElement): LightboxItem {
+	if (binding.value?.asset) {
+		return { ...binding.value, src: undefined, pathKey: undefined, type: binding.value.type || 'image', name: binding.value.name || '' }
+	}
 	let { group, src, type, name, thumbnail, enableZoom, openFile, download, pathKey } = binding.value || {}
 	src = pathKeyToURL(src || pathKey) || binding.value || el.getAttribute('src') || ''
 	type = type || determineFileType(src)
@@ -82,10 +88,25 @@ function determineFileType(url: any): string {
 	return extension ?? 'unknown'
 }
 
+const instances = new WeakMap<App, InstanceType<typeof Lightbox>>()
 let lightboxInstance: InstanceType<typeof Lightbox> | undefined
 
-function getLightboxInstance(): InstanceType<typeof Lightbox> | undefined {
+function getLightboxInstance(binding: DirectiveBinding): InstanceType<typeof Lightbox> | undefined {
 	if (typeof document === 'undefined') { return undefined }
+	const owner = binding.instance?.$?.appContext.app
+	if (owner) {
+		const existing = instances.get(owner)
+		if (existing) return existing
+		const element = document.createElement('div')
+		document.body.prepend(element)
+		const child = createApp(Lightbox)
+		const client = owner.runWithContext(() => injectAssetClient())
+		if (client) child.provide(ASSET_CLIENT_KEY, client)
+		const instance = child.mount(element) as InstanceType<typeof Lightbox>
+		instances.set(owner, instance)
+		owner.onUnmount(() => { child.unmount(); element.remove(); instances.delete(owner) })
+		return instance
+	}
 	if (!lightboxInstance) {
 		const lightboxEl = document.createElement('div')
 		document.body.prepend(lightboxEl)
@@ -95,6 +116,10 @@ function getLightboxInstance(): InstanceType<typeof Lightbox> | undefined {
 	return lightboxInstance
 }
 
+function injectAssetClient(): AssetClient | undefined {
+	return inject(ASSET_CLIENT_KEY, undefined)
+}
+
 const lightboxPlugin: Plugin = {
 	install(app: App) {
 		app.directive('lightbox', lightboxDirective)