From 86c3862b6053a757814ffae6a6aa56d088e61a37 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?John=20Molakvo=C3=A6?=
 <14975046+skjnldsv@users.noreply.github.com>
Date: Wed, 7 Oct 2026 10:41:39 +0200
Subject: [PATCH 1/6] feat(viewer): name the element that shows a file, to
 render it elsewhere
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The preview of a file link (the files reference widget, in Talk, Text and
the like) used to render the viewer handler's component inline, found
through OCA.Viewer.availableHandlers. Handlers are custom elements now,
and the registry is not something a page should dig through, so
getViewer().elementFor(file) names the element of the handler that would
open the file, defined and ready to render, without loading the viewer.

`embedded` on ViewerProps tells the handler it is shown inline, which the
old widget said with `isEmbedded` and `active`. A hint not to take over the
page: videos and sounds wait to be played, and editing is better left to
the viewer.

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: John Molakvoæ <14975046+skjnldsv@users.noreply.github.com>
---
 README.md                         | 31 +++++++++++++++++++++++-
 __tests__/component/media.spec.ts | 20 ++++++++++++++++
 __tests__/viewerService.spec.ts   | 39 ++++++++++++++++++++++++++++++-
 lib/components/Audios.vue         |  2 +-
 lib/components/Videos.vue         |  2 +-
 lib/viewer.ts                     | 34 +++++++++++++++++++++++++++
 6 files changed, 124 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 4bf42e8..0911cf7 100644
--- a/README.md
+++ b/README.md
@@ -522,6 +522,35 @@ opens on it. The view chosen is kept until the viewer closes.
 `compare()` when viewer is already open compares the new files in it. Their
 elements are mounted again, as for every file opened.
 
+### 🖼️ Show a file outside the viewer
+
+To show a file where it is mentioned, as the preview of a file link in a chat
+or a document, ask the viewer which element shows it and render that element
+yourself:
+
+```ts
+import { getViewer } from '@nextcloud/viewer'
+
+const tagName = await getViewer().elementFor(file)
+if (tagName !== undefined) {
+	const element = document.createElement(tagName)
+	Object.assign(element, { file, files: [file], maxWidth: 600, maxHeight: 400, embedded: true })
+	element.addEventListener('loaded', () => { /* shown */ })
+	element.addEventListener('errored', () => { /* fall back to a plain link */ })
+	container.append(element)
+}
+```
+
+It names the element of the handler the viewer would open the file with, once
+that element is defined (a handler with `onInit()` is initialized first), and
+nothing when no handler takes the file or the user cannot read it. The element
+takes the props and emits the events of any handler (`ViewerProps`,
+`ViewerEmits`). Nothing of the viewer itself is loaded for it.
+
+Set `embedded` so the handler knows it is shown inline: videos and sounds then
+wait to be played rather than starting on their own. Editing is usually better
+left to the viewer: offer a way to open the file there with `getViewer().open()`.
+
 ### 🕰️ Nextcloud 35 and older
 
 The library is made for Nextcloud 36, whose server ships a copy of it. Older
@@ -561,7 +590,7 @@ instead, and the viewer works with `@nextcloud/files` nodes rather than the
 | `OCA.Viewer.close()`                              | `getViewer().close()`                                          |
 | `OCA.Viewer.mimetypes.includes(node.mime)`        | `canView(node)`                                                |
 | `OCA.Viewer.mimetypesCompare.includes(node.mime)` | `canView(node)`                                                |
-| `OCA.Viewer.availableHandlers`                    | `getHandlers()`, or `canView(node)` to test one file           |
+| `OCA.Viewer.availableHandlers`                    | `getHandlers()`, `canView(node)` to test one file, `getViewer().elementFor(node)` to render it |
 | `OCA.Viewer.registerHandler({ component })`       | `registerHandler({ tagName })`, see above                      |
 | `canCompare: true` on a handler                   | `canCompare: (nodes) => true`, and `canCompare(node)` to decide whether to offer it |
 | `\OCP\Util::addScript` for the registration        | `\OCP\Util::addInitScript`                                      |
diff --git a/__tests__/component/media.spec.ts b/__tests__/component/media.spec.ts
index 204be8d..9ed0fa7 100644
--- a/__tests__/component/media.spec.ts
+++ b/__tests__/component/media.spec.ts
@@ -555,6 +555,26 @@ describe('the keyboard, once the media is on screen', () => {
 	})
 })
 
+// Shown inline, as the preview of a link in a chat, the media would start
+// playing in the middle of the page
+describe.each([
+	['video', 'clip.mp4', 'video/mp4'],
+	['sound', 'song.mp3', 'audio/mpeg'],
+] as const)('a %s', (kind, basename, mime) => {
+	const component = kind === 'video' ? Videos : Audios
+
+	it.each([
+		['plays on its own in the viewer', false, true],
+		['waits to be played when shown inline', true, false],
+	])('%s', async (_name, embedded, autoplay) => {
+		const file = makeFile({ basename, mime })
+		const wrapper = mount(component, { props: makeProps({ file, files: [file], embedded }) })
+		await flushPromises()
+
+		expect((wrapper.find(kind === 'video' ? 'video' : 'audio').element as HTMLMediaElement).autoplay).toBe(autoplay)
+	})
+})
+
 describe('a video that has played to the end', () => {
 	// What a user puts beside a film to show before and after it plays:
 	// a picture of the same name in the same folder
diff --git a/__tests__/viewerService.spec.ts b/__tests__/viewerService.spec.ts
index 1b21eb0..b8aac18 100644
--- a/__tests__/viewerService.spec.ts
+++ b/__tests__/viewerService.spec.ts
@@ -4,10 +4,12 @@
  */
 import type ViewerVue from '../lib/views/Viewer.vue'
 
+import { Permission } from '@nextcloud/files'
 import { describe, expect, it, vi } from 'vitest'
+import { registerHandler } from '../lib/handlers.ts'
 import { registerImplementation, scope } from '../lib/scope.ts'
 import { getViewer, Viewer } from '../lib/viewer.ts'
-import { makeFile } from './factories.ts'
+import { makeFile, makeHandler } from './factories.ts'
 
 type Mounted = InstanceType<typeof ViewerVue>
 
@@ -146,3 +148,38 @@ describe('the synchronous methods', () => {
 		expect(mounted.setEditing).toHaveBeenCalledWith(true)
 	})
 })
+
+describe('elementFor()', () => {
+	let count = 0
+	const tag = () => `oca-viewer-embed-${++count}`
+
+	// A file link's preview shows the file where the link is, without the
+	// modal, and must not pull the whole viewer in for it
+	it('names the element of the handler that takes the file, without loading the viewer', async () => {
+		const load = offerImplementation(makeMounted())
+		const tagName = tag()
+		registerHandler(makeHandler({ id: tagName, tagName, enabled: (nodes) => nodes.every((node) => node.mime === 'image/jpeg') }))
+
+		expect(await getViewer().elementFor(makeFile({ mime: 'image/jpeg' }))).toBe(tagName)
+		expect(load).not.toHaveBeenCalled()
+	})
+
+	it('has the element defined first, by the handler\'s onInit', async () => {
+		const tagName = tag()
+		const onInit = vi.fn(async () => {
+			customElements.define(tagName, class extends HTMLElement {})
+		})
+		registerHandler(makeHandler({ id: tagName, tagName, enabled: () => true, onInit }))
+
+		expect(await getViewer().elementFor(makeFile())).toBe(tagName)
+		expect(customElements.get(tagName)).toBeDefined()
+	})
+
+	it('names nothing for a file no handler takes, or one the user cannot read', async () => {
+		const tagName = tag()
+		registerHandler(makeHandler({ id: tagName, tagName, enabled: (nodes) => nodes.every((node) => node.mime === 'image/jpeg') }))
+
+		expect(await getViewer().elementFor(makeFile({ mime: 'video/mp4' }))).toBeUndefined()
+		expect(await getViewer().elementFor(makeFile({ mime: 'image/jpeg', permissions: Permission.NONE }))).toBeUndefined()
+	})
+})
diff --git a/lib/components/Audios.vue b/lib/components/Audios.vue
index 19c2921..03e6948 100644
--- a/lib/components/Audios.vue
+++ b/lib/components/Audios.vue
@@ -10,7 +10,7 @@
 			<audio-skin class="viewer-media" tabindex="-1">
 				<audio
 					ref="audio"
-					:autoplay="true"
+					:autoplay="!embedded"
 					:src="src"
 					preload="metadata"
 					@error.capture.prevent.stop="onFail"
diff --git a/lib/components/Videos.vue b/lib/components/Videos.vue
index d764b9d..4ab608f 100644
--- a/lib/components/Videos.vue
+++ b/lib/components/Videos.vue
@@ -16,7 +16,7 @@
 				}">
 				<video
 					ref="video"
-					:autoplay="true"
+					:autoplay="!embedded"
 					:playsinline="true"
 					:poster="poster"
 					:src="src"
diff --git a/lib/viewer.ts b/lib/viewer.ts
index f303046..0e92f3c 100644
--- a/lib/viewer.ts
+++ b/lib/viewer.ts
@@ -7,7 +7,10 @@ import type { IFile, IFolder, IView } from '@nextcloud/files'
 import type { ViewerEventMap, ViewerSession } from './session.ts'
 import type ViewerVue from './views/Viewer.vue'
 
+import { canView } from './handlers.ts'
+import { getHandlerForFile } from './helpers/handlerHelper.ts'
 import { loadImplementation, scope } from './scope.ts'
+import { initHandlerElement } from './utils/customElements.ts'
 
 /**
  * List of props provided to your custom component.
@@ -80,6 +83,14 @@ export interface ViewerProps {
 	 * `files`, the older one, to its `file` (see `IHandler.canShowDifferences`).
 	 */
 	comparison?: ComparisonView
+
+	/**
+	 * Whether the file is shown inline, outside the viewer, as the preview of a
+	 * link to it (see `getViewer().elementFor()`). A hint that handlers should
+	 * not take over the page, for example by autoplaying. Editing is usually
+	 * better left to the viewer, which the caller can open on the file.
+	 */
+	embedded?: boolean
 }
 
 /**
@@ -331,6 +342,29 @@ export class Viewer extends EventTarget implements ViewerAPI {
 	removeEventListener(type: string, listener: EventListenerOrEventListenerObject | null, options?: boolean | EventListenerOptions): void {
 		super.removeEventListener(type, listener, options)
 	}
+
+	/**
+	 * The element that shows a file, to render it outside the viewer, as the
+	 * preview of a file link in a chat or a document does.
+	 *
+	 * Resolves with the tag name of the custom element of the handler the
+	 * viewer would open the file with, once that element is defined (see
+	 * `IHandler.onInit`), or with nothing when no handler takes the file. The
+	 * element takes the props every handler does (`ViewerProps`), and says it
+	 * has loaded or failed with the same events. Loads nothing of the viewer
+	 * itself.
+	 *
+	 * @param file - The file to show
+	 */
+	async elementFor(file: IFile): Promise<string | undefined> {
+		// The one the viewer opens it with, for a file it can show at all
+		const handler = canView(file) ? getHandlerForFile(file) : undefined
+		if (handler === undefined) {
+			return undefined
+		}
+		await initHandlerElement(handler)
+		return handler.tagName
+	}
 }
 
 /**

From d4f1848cc74de5a08a83d2cad1cd9ce533d5d613 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?John=20Molakvo=C3=A6?=
 <14975046+skjnldsv@users.noreply.github.com>
Date: Wed, 21 Oct 2026 11:40:51 +0200
Subject: [PATCH 2/6] fix(handlers): define the default elements when first
 needed
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

elementFor() named the elements of the images, video, audio and sheet
music handlers before anything defined them: only the viewer did, as it
mounted. They are defined from onInit now, like any handler's.

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: John Molakvoæ <14975046+skjnldsv@users.noreply.github.com>
---
 __tests__/defaultHandlers.spec.ts | 35 +++++++++++++++++++++++++++++++
 lib/models/audios.ts              |  3 +++
 lib/models/images.ts              |  3 +++
 lib/models/sheetmusic.ts          |  3 +++
 lib/models/videos.ts              |  3 +++
 5 files changed, 47 insertions(+)
 create mode 100644 __tests__/defaultHandlers.spec.ts

diff --git a/__tests__/defaultHandlers.spec.ts b/__tests__/defaultHandlers.spec.ts
new file mode 100644
index 0000000..9a72dab
--- /dev/null
+++ b/__tests__/defaultHandlers.spec.ts
@@ -0,0 +1,35 @@
+/*!
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+import { beforeEach, describe, expect, it } from 'vitest'
+import { getHandlers } from '../lib/handlers.ts'
+import { registerAudioHandler } from '../lib/models/audios.ts'
+import { registerImageHandler } from '../lib/models/images.ts'
+import { registerSheetmusicHandler } from '../lib/models/sheetmusic.ts'
+import { registerVideoHandler } from '../lib/models/videos.ts'
+import { getViewer } from '../lib/viewer.ts'
+import { makeFile } from './factories.ts'
+
+// Each test starts on an empty registry
+beforeEach(() => {
+	registerAudioHandler()
+	registerVideoHandler()
+	registerImageHandler()
+	registerSheetmusicHandler()
+})
+
+// <nc-viewer-file> shows them outside the viewer, which defined their
+// elements only as it mounted
+describe('the default handlers', () => {
+	it.each(['images', 'videos', 'audios', 'sheetmusic'])('%s define their element when first needed', (id) => {
+		expect(getHandlers().get(id)?.onInit).toBeTypeOf('function')
+	})
+
+	it('have their element defined before it is named', async () => {
+		expect(customElements.get('oca-viewer-image')).toBeUndefined()
+
+		expect(await getViewer().elementFor(makeFile({ mime: 'image/jpeg' }))).toBe('oca-viewer-image')
+		expect(customElements.get('oca-viewer-image')).toBeDefined()
+	})
+})
diff --git a/lib/models/audios.ts b/lib/models/audios.ts
index b5a3aa5..6038383 100644
--- a/lib/models/audios.ts
+++ b/lib/models/audios.ts
@@ -47,6 +47,9 @@ export async function registerAudioCustomElement(): Promise<void> {
 export function registerAudioHandler() {
 	registerHandler({
 		id: 'audios',
+		// Defined when first needed: by the viewer as it mounts, or by a
+		// <nc-viewer-file> showing one of these files outside of it
+		onInit: registerAudioCustomElement,
 		displayName: t('Audio player'),
 		tagName,
 		supportsEndToEndEncryption: true,
diff --git a/lib/models/images.ts b/lib/models/images.ts
index c064368..6d276bf 100644
--- a/lib/models/images.ts
+++ b/lib/models/images.ts
@@ -131,6 +131,9 @@ export function registerImageHandler() {
 
 	registerHandler({
 		id: 'images',
+		// Defined when first needed: by the viewer as it mounts, or by a
+		// <nc-viewer-file> showing one of these files outside of it
+		onInit: registerImageCustomElement,
 		displayName: t('Images'),
 		tagName,
 		// With video and audio: a folder of photos and films pages through
diff --git a/lib/models/sheetmusic.ts b/lib/models/sheetmusic.ts
index a2de70a..0301fd9 100644
--- a/lib/models/sheetmusic.ts
+++ b/lib/models/sheetmusic.ts
@@ -46,6 +46,9 @@ export async function registerSheetmusicCustomElement(): Promise<void> {
 export function registerSheetmusicHandler() {
 	registerHandler({
 		id: 'sheetmusic',
+		// Defined when first needed: by the viewer as it mounts, or by a
+		// <nc-viewer-file> showing one of these files outside of it
+		onInit: registerSheetmusicCustomElement,
 		displayName: t('Sheet music'),
 		tagName,
 
diff --git a/lib/models/videos.ts b/lib/models/videos.ts
index ea4f9c1..6e542c2 100644
--- a/lib/models/videos.ts
+++ b/lib/models/videos.ts
@@ -44,6 +44,9 @@ export async function registerVideoCustomElement(): Promise<void> {
 export function registerVideoHandler() {
 	registerHandler({
 		id: 'videos',
+		// Defined when first needed: by the viewer as it mounts, or by a
+		// <nc-viewer-file> showing one of these files outside of it
+		onInit: registerVideoCustomElement,
 		displayName: t('Video player'),
 		tagName,
 		supportsEndToEndEncryption: true,

From 97d4d2722b2c701d158f22f599455bb89477a1fb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?John=20Molakvo=C3=A6?=
 <14975046+skjnldsv@users.noreply.github.com>
Date: Wed, 21 Oct 2026 11:40:52 +0200
Subject: [PATCH 3/6] fix(audios): keep the player to the width it is given
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

It had a width of its own, wider than a file shown outside the viewer.

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: John Molakvoæ <14975046+skjnldsv@users.noreply.github.com>
---
 lib/components/Audios.vue | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lib/components/Audios.vue b/lib/components/Audios.vue
index 03e6948..83264fc 100644
--- a/lib/components/Audios.vue
+++ b/lib/components/Audios.vue
@@ -7,7 +7,7 @@
 	<!-- eslint-disable vue/no-unused-refs -- the player ref is consumed by useVideojsAdapter, the audio one by useMediaPlayer, via useTemplateRef -->
 	<media-i18n :lang="playerLanguage">
 		<audio-player ref="player">
-			<audio-skin class="viewer-media" tabindex="-1">
+			<audio-skin class="viewer-media" tabindex="-1" :style="{ maxWidth: maxWidth > 0 ? `${maxWidth}px` : undefined }">
 				<audio
 					ref="audio"
 					:autoplay="!embedded"

From 52ac863209458812a2ae3d6b04643a9ca5528e76 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?John=20Molakvo=C3=A6?=
 <14975046+skjnldsv@users.noreply.github.com>
Date: Wed, 21 Oct 2026 11:40:53 +0200
Subject: [PATCH 4/6] feat(viewer): show a file anywhere with <nc-viewer-file>
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Give it a file and a size: it shows the file with the handler the viewer
would use, fitted to its box, its blurhash while it loads, and a strip
naming it with a menu to open it in the viewer or download it. A video
waits behind its poster until played. When nothing can show the file,
or it fails to, it says so and offers the download, or shows what the
page put inside it. Its view is only fetched once one is on the page.

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: John Molakvoæ <14975046+skjnldsv@users.noreply.github.com>
---
 README.md                              |  41 ++-
 __tests__/component/viewerFile.spec.ts | 223 +++++++++++
 __tests__/viewerFileElement.spec.ts    |  71 ++++
 e2e/embeds.spec.ts                     |  63 ++++
 lib/components/ViewerFile.vue          | 488 +++++++++++++++++++++++++
 lib/elements/mountViewerFile.ts        |  41 +++
 lib/elements/viewerFile.ts             |  99 +++++
 lib/index.ts                           |   6 +
 playground/App.vue                     |  45 +++
 playground/style.css                   |   8 +
 playground/vite.config.ts              |   2 +-
 11 files changed, 1066 insertions(+), 21 deletions(-)
 create mode 100644 __tests__/component/viewerFile.spec.ts
 create mode 100644 __tests__/viewerFileElement.spec.ts
 create mode 100644 e2e/embeds.spec.ts
 create mode 100644 lib/components/ViewerFile.vue
 create mode 100644 lib/elements/mountViewerFile.ts
 create mode 100644 lib/elements/viewerFile.ts

diff --git a/README.md b/README.md
index 0911cf7..ba87198 100644
--- a/README.md
+++ b/README.md
@@ -525,31 +525,32 @@ elements are mounted again, as for every file opened.
 ### 🖼️ Show a file outside the viewer
 
 To show a file where it is mentioned, as the preview of a file link in a chat
-or a document, ask the viewer which element shows it and render that element
-yourself:
+or a document, put a `<nc-viewer-file>` there, give it the file and a size:
 
-```ts
-import { getViewer } from '@nextcloud/viewer'
+```vue
+<nc-viewer-file :file.prop="file" style="width: 280px; height: 180px" />
+```
 
-const tagName = await getViewer().elementFor(file)
-if (tagName !== undefined) {
-	const element = document.createElement(tagName)
-	Object.assign(element, { file, files: [file], maxWidth: 600, maxHeight: 400, embedded: true })
-	element.addEventListener('loaded', () => { /* shown */ })
-	element.addEventListener('errored', () => { /* fall back to a plain link */ })
-	container.append(element)
-}
+```ts
+const element = document.createElement('nc-viewer-file')
+element.file = file
+container.append(element)
 ```
 
-It names the element of the handler the viewer would open the file with, once
-that element is defined (a handler with `onInit()` is initialized first), and
-nothing when no handler takes the file or the user cannot read it. The element
-takes the props and emits the events of any handler (`ViewerProps`,
-`ViewerEmits`). Nothing of the viewer itself is loaded for it.
+It shows the file with the handler the viewer would open it with, fitted to
+its box, and loads nothing of the viewer itself. While the file loads it
+shows its blurhash where the server has one. Over the file, a strip names it
+and offers to open it in the viewer or to download it, on hover, focus or a
+tap. A video waits behind its poster until played, and a sound waits too.
+
+When nothing can show the file, or it fails to, it says so and offers the
+download where the share allows it. Put something inside the element, such as
+a link of your own, to show that instead. It dispatches `loaded` and
+`errored`, as a handler does.
 
-Set `embedded` so the handler knows it is shown inline: videos and sounds then
-wait to be played rather than starting on their own. Editing is usually better
-left to the viewer: offer a way to open the file there with `getViewer().open()`.
+To render the handler's element yourself, `getViewer().elementFor(file)`
+names it, once it is defined, or nothing when no handler takes the file.
+Give it the props of any handler (`ViewerProps`), with `embedded: true`.
 
 ### 🕰️ Nextcloud 35 and older
 
diff --git a/__tests__/component/viewerFile.spec.ts b/__tests__/component/viewerFile.spec.ts
new file mode 100644
index 0000000..c08a11f
--- /dev/null
+++ b/__tests__/component/viewerFile.spec.ts
@@ -0,0 +1,223 @@
+/*!
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+import type { IFile } from '@nextcloud/files'
+
+import { flushPromises, mount } from '@vue/test-utils'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+// What the viewer answers: the element that shows a file, and opening it
+const viewer = vi.hoisted(() => ({ elementFor: vi.fn(), open: vi.fn() }))
+vi.mock('../../lib/viewer.ts', () => ({ getViewer: () => viewer }))
+
+const { default: ViewerFile } = await import('../../lib/components/ViewerFile.vue')
+const { makeFile } = await import('../factories.ts')
+
+// A handler's element, keeping what it is given to read it back
+class ShownElement extends HTMLElement {
+	file?: IFile
+	files?: IFile[]
+	embedded?: boolean
+	shown?: boolean
+	maxWidth?: number
+}
+customElements.define('oca-viewer-embedded', ShownElement)
+
+afterEach(() => {
+	viewer.elementFor.mockReset()
+	viewer.open.mockReset()
+	document.body.innerHTML = ''
+})
+
+/**
+ * Show a file as `<nc-viewer-file>` does.
+ *
+ * @param file - The file
+ * @param tagName - The element the viewer names for it, none if nothing shows it
+ * @param fallback - What the page put inside the element
+ */
+async function show(file: IFile, tagName?: string, fallback: Node[] = []) {
+	viewer.elementFor.mockResolvedValue(tagName)
+	const host = document.createElement('div')
+	const wrapper = mount(ViewerFile, { props: { file, host, fallback }, attachTo: document.body })
+	await flushPromises()
+	const element = wrapper.find('oca-viewer-embedded').exists()
+		? wrapper.find('oca-viewer-embedded').element as ShownElement
+		: undefined
+	return { wrapper, host, element }
+}
+
+describe('a file shown where it is mentioned', () => {
+	it('is shown by the element of its handler, inline', async () => {
+		const file = makeFile({ basename: 'beach.jpg' })
+		const { element } = await show(file, 'oca-viewer-embedded')
+
+		expect(viewer.elementFor).toHaveBeenCalledWith(file)
+		expect(element!.file?.source).toBe(file.source)
+		expect(element!.files?.map((shown) => shown.source)).toEqual([file.source])
+		// Videos and sounds wait to be played
+		expect(element!.embedded).toBe(true)
+		expect(element!.shown).toBe(false)
+	})
+
+	it('is said to have loaded once its handler has', async () => {
+		const { wrapper, host, element } = await show(makeFile({ basename: 'beach.jpg' }), 'oca-viewer-embedded')
+		const loaded = vi.fn()
+		host.addEventListener('loaded', loaded)
+		expect(wrapper.find('.viewer-file__bar').exists()).toBe(false)
+
+		element!.dispatchEvent(new CustomEvent('loaded'))
+		await flushPromises()
+
+		expect(loaded).toHaveBeenCalledOnce()
+		expect(element!.shown).toBe(true)
+		expect(wrapper.find('.viewer-file__name').text()).toBe('beach.jpg')
+	})
+
+	it('opens in the viewer from its menu', async () => {
+		const file = makeFile({ basename: 'beach.jpg' })
+		const { wrapper, element } = await show(file, 'oca-viewer-embedded')
+		element!.dispatchEvent(new CustomEvent('loaded'))
+		await flushPromises()
+
+		await wrapper.find('.viewer-file__actions button').trigger('click')
+		await flushPromises()
+		const open = wrapper.findAllComponents({ name: 'NcActionButton' }).find((action) => action.text().includes('Open in the viewer'))
+		await open!.vm.$emit('click')
+
+		expect(viewer.open).toHaveBeenCalledOnce()
+		const [files, shown] = viewer.open.mock.calls[0]!
+		expect(files.map((opened: IFile) => opened.source)).toEqual([file.source])
+		expect(shown.source).toBe(file.source)
+	})
+})
+
+// The handler's whole player over a small box is a lot: a video waits behind
+// its poster and one play button until played
+describe('a video shown where it is mentioned', () => {
+	/**
+	 * Show a video, its handler's element holding a video with that poster.
+	 *
+	 * @param poster - The poster, none for a video without
+	 */
+	async function showVideo(poster?: string) {
+		const shown = await show(makeFile({ basename: 'trailer.webm', mime: 'video/webm' }), 'oca-viewer-embedded')
+		const video = document.createElement('video')
+		if (poster) {
+			video.poster = poster
+		}
+		video.play = vi.fn(async () => {})
+		shown.element!.append(video)
+		shown.element!.dispatchEvent(new CustomEvent('loaded'))
+		await flushPromises()
+		return { ...shown, video }
+	}
+
+	it('waits behind its poster', async () => {
+		const { wrapper } = await showVideo('https://cloud.example.com/poster.jpg')
+		const cover = wrapper.find('.viewer-file__cover')
+
+		expect(cover.attributes('aria-label')).toBe('Play')
+		expect(cover.attributes('style')).toContain('poster.jpg')
+	})
+
+	it('plays, and leaves its player to it, once the cover is clicked', async () => {
+		const { wrapper, video } = await showVideo()
+
+		await wrapper.find('.viewer-file__cover').trigger('click')
+
+		expect(video.play).toHaveBeenCalledOnce()
+		expect(wrapper.find('.viewer-file__cover').exists()).toBe(false)
+	})
+
+	it('is no cover over a picture', async () => {
+		const { wrapper, element } = await show(makeFile({ basename: 'beach.jpg' }), 'oca-viewer-embedded')
+		element!.dispatchEvent(new CustomEvent('loaded'))
+		await flushPromises()
+
+		expect(wrapper.find('.viewer-file__cover').exists()).toBe(false)
+	})
+})
+
+describe('a file nothing shows', () => {
+	it('says so, with its name, its size and the download', async () => {
+		const { wrapper } = await show(makeFile({ basename: 'report.zip', mime: 'application/zip', size: 4404019 }))
+
+		expect(wrapper.find('.viewer-file__type').text()).toBe('ZIP')
+		expect(wrapper.find('.viewer-file__card-name').text()).toBe('report.zip')
+		expect(wrapper.find('.viewer-file__card-meta').text()).toBe('4.2 MB · No preview available')
+		expect(wrapper.find('button[aria-label="Download"]').exists()).toBe(true)
+	})
+
+	it('offers no download where its share forbids it', async () => {
+		const file = makeFile({ basename: 'report.zip', mime: 'application/zip', attributes: { 'hide-download': true } })
+		const { wrapper } = await show(file)
+
+		expect(wrapper.find('.viewer-file__card').exists()).toBe(true)
+		expect(wrapper.find('button[aria-label="Download"]').exists()).toBe(false)
+	})
+
+	it('shows what the page put inside instead', async () => {
+		const link = document.createElement('a')
+		link.textContent = 'report.zip'
+		const { wrapper } = await show(makeFile({ basename: 'report.zip', mime: 'application/zip' }), undefined, [link])
+
+		expect(wrapper.find('.viewer-file__card').exists()).toBe(false)
+		expect(wrapper.find('.viewer-file__fallback').element.contains(link)).toBe(true)
+	})
+
+	it('says so as well when its handler fails to show it', async () => {
+		const { wrapper, host, element } = await show(makeFile({ basename: 'beach.jpg' }), 'oca-viewer-embedded')
+		const errored = vi.fn()
+		host.addEventListener('errored', errored)
+
+		element!.dispatchEvent(new CustomEvent('errored', { detail: [new Error('broken')] }))
+		await flushPromises()
+
+		expect(errored).toHaveBeenCalledOnce()
+		expect(wrapper.find('.viewer-file__card-name').text()).toBe('beach.jpg')
+	})
+})
+
+describe('another file given', () => {
+	it('is asked for, and a late answer for the one before is dropped', async () => {
+		let answerFirst!: (tag: string | undefined) => void
+		viewer.elementFor.mockReturnValueOnce(new Promise((resolve) => {
+			answerFirst = resolve
+		}))
+		const host = document.createElement('div')
+		const first = makeFile({ basename: 'first.jpg' })
+		const wrapper = mount(ViewerFile, { props: { file: first, host, fallback: [] } })
+
+		viewer.elementFor.mockResolvedValueOnce(undefined)
+		await wrapper.setProps({ file: makeFile({ basename: 'second.zip', mime: 'application/zip' }) })
+		await flushPromises()
+		answerFirst('oca-viewer-embedded')
+		await flushPromises()
+
+		expect(wrapper.find('oca-viewer-embedded').exists()).toBe(false)
+		expect(wrapper.find('.viewer-file__card-name').text()).toBe('second.zip')
+	})
+})
+
+// Touch has no hover: a tap on the file shows its name and menu
+describe('a tap on the file', () => {
+	it('shows its strip, and the next one hides it', async () => {
+		const { wrapper } = await show(makeFile({ basename: 'beach.jpg' }), 'oca-viewer-embedded')
+		const root = wrapper.find('.viewer-file')
+
+		await root.trigger('pointerdown', { pointerType: 'touch' })
+		expect(root.classes()).toContain('viewer-file--active')
+		await root.trigger('pointerdown', { pointerType: 'touch' })
+		expect(root.classes()).not.toContain('viewer-file--active')
+	})
+
+	it('is not a mouse click', async () => {
+		const { wrapper } = await show(makeFile({ basename: 'beach.jpg' }), 'oca-viewer-embedded')
+		const root = wrapper.find('.viewer-file')
+
+		await root.trigger('pointerdown', { pointerType: 'mouse' })
+		expect(root.classes()).not.toContain('viewer-file--active')
+	})
+})
diff --git a/__tests__/viewerFileElement.spec.ts b/__tests__/viewerFileElement.spec.ts
new file mode 100644
index 0000000..beaa648
--- /dev/null
+++ b/__tests__/viewerFileElement.spec.ts
@@ -0,0 +1,71 @@
+/*!
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+import { flushPromises } from '@vue/test-utils'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+// The view, which the element only fetches once it is on the page
+const view = vi.hoisted(() => ({ update: vi.fn(), unmount: vi.fn() }))
+const mountViewerFile = vi.hoisted(() => vi.fn(async () => view))
+vi.mock('../lib/elements/mountViewerFile.ts', () => ({ mountViewerFile }))
+
+const { defineViewerFileElement } = await import('../lib/elements/viewerFile.ts')
+const { makeFile } = await import('./factories.ts')
+defineViewerFileElement()
+
+afterEach(() => {
+	document.body.innerHTML = ''
+	vi.clearAllMocks()
+})
+
+describe('<nc-viewer-file>', () => {
+	it('fetches nothing until it is on the page', () => {
+		document.createElement('nc-viewer-file').file = makeFile()
+		expect(mountViewerFile).not.toHaveBeenCalled()
+	})
+
+	it('shows its file, and the next one it is given', async () => {
+		const element = document.createElement('nc-viewer-file')
+		const first = makeFile({ basename: 'first.jpg' })
+		element.file = first
+		document.body.append(element)
+		await flushPromises()
+		expect(mountViewerFile).toHaveBeenCalledWith(element, first, [])
+
+		const second = makeFile({ basename: 'second.jpg' })
+		element.file = second
+		expect(view.update).toHaveBeenLastCalledWith(second)
+	})
+
+	// Shown when nothing can show the file
+	it('keeps what the page put inside for its view', async () => {
+		const element = document.createElement('nc-viewer-file')
+		const link = document.createElement('a')
+		const text = document.createTextNode(' and more')
+		element.append(link, text)
+		document.body.append(element)
+		await flushPromises()
+
+		expect(mountViewerFile).toHaveBeenCalledWith(element, undefined, [link, text])
+		expect(element.contains(link)).toBe(false)
+	})
+
+	it('takes its view down once off the page', async () => {
+		const element = document.createElement('nc-viewer-file')
+		document.body.append(element)
+		await flushPromises()
+
+		element.remove()
+		expect(view.unmount).toHaveBeenCalledOnce()
+	})
+
+	it('drops a view that arrives once it is off the page already', async () => {
+		const element = document.createElement('nc-viewer-file')
+		document.body.append(element)
+		element.remove()
+		await flushPromises()
+
+		expect(view.unmount).toHaveBeenCalledOnce()
+	})
+})
diff --git a/e2e/embeds.spec.ts b/e2e/embeds.spec.ts
new file mode 100644
index 0000000..d974875
--- /dev/null
+++ b/e2e/embeds.spec.ts
@@ -0,0 +1,63 @@
+/*!
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+import { expect, test } from '@playwright/test'
+import { ViewerPage } from './support/viewer.ts'
+
+// Files shown where they are mentioned, as the preview of a link in a chat
+test.describe('<nc-viewer-file>', () => {
+	test.beforeEach(async ({ page }) => {
+		await page.goto('/?embeds')
+	})
+
+	test('shows a picture, and names it under the pointer', async ({ page }) => {
+		const element = page.locator('nc-viewer-file').nth(0)
+		await element.scrollIntoViewIfNeeded()
+		await expect(element.locator('oca-viewer-image img')).toBeVisible()
+		const bar = element.locator('.viewer-file__bar')
+		await expect(bar).toHaveCSS('opacity', '0')
+
+		await element.hover()
+		await expect(bar).toHaveCSS('opacity', '1')
+		await expect(bar).toContainText('photo.jpg')
+	})
+
+	test('opens it in the viewer from its menu', async ({ page }) => {
+		const element = page.locator('nc-viewer-file').nth(0)
+		await element.scrollIntoViewIfNeeded()
+		await expect(element.locator('oca-viewer-image img')).toBeVisible()
+		await element.hover()
+		await element.locator('.viewer-file__actions button').first().click()
+		await page.getByRole('menuitem', { name: 'Open in the viewer' }).click()
+
+		const viewer = new ViewerPage(page)
+		await viewer.waitForOpen()
+		expect(await viewer.currentName()).toBe('photo.jpg')
+	})
+
+	test('keeps a video behind one play button until played', async ({ page }) => {
+		const element = page.locator('nc-viewer-file').nth(1)
+		await element.scrollIntoViewIfNeeded()
+		const cover = element.getByRole('button', { name: 'Play' }).and(element.locator('.viewer-file__cover'))
+		await expect(cover).toBeVisible()
+
+		await cover.click()
+		await expect(cover).toHaveCount(0)
+	})
+
+	test('says when nothing can show a file, and offers it to download', async ({ page }) => {
+		const card = page.locator('.viewer-file__card')
+		await card.scrollIntoViewIfNeeded()
+		await expect(card).toContainText('report.zip')
+		await expect(card).toContainText('No preview available')
+		await expect(card.getByRole('button', { name: 'Download' })).toBeVisible()
+	})
+
+	test('shows what the page put inside instead, when it put something', async ({ page }) => {
+		const own = page.locator('.playground__embed--own')
+		await own.scrollIntoViewIfNeeded()
+		await expect(own.getByRole('link', { name: 'report.zip' })).toBeVisible()
+		await expect(own.locator('.viewer-file__card')).toHaveCount(0)
+	})
+})
diff --git a/lib/components/ViewerFile.vue b/lib/components/ViewerFile.vue
new file mode 100644
index 0000000..9a737b9
--- /dev/null
+++ b/lib/components/ViewerFile.vue
@@ -0,0 +1,488 @@
+<!--
+  - SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+  - SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
+<template>
+	<div
+		ref="root"
+		class="viewer-file"
+		:class="{
+			'viewer-file--active': active || menuOpen,
+			'viewer-file--said': status === 'none' || status === 'failed',
+		}"
+		@pointerdown="onPointerDown">
+		<template v-if="file">
+			<!-- Nothing can show it, or it failed to -->
+			<template v-if="status === 'none' || status === 'failed'">
+				<div v-if="fallback.length > 0" ref="fallbackHolder" class="viewer-file__fallback" />
+				<div v-else class="viewer-file__card">
+					<span class="viewer-file__type" aria-hidden="true">{{ extension }}</span>
+					<span class="viewer-file__about">
+						<span class="viewer-file__card-name">{{ file.displayname }}</span>
+						<span class="viewer-file__card-meta">{{ meta }}</span>
+					</span>
+					<NcButton
+						v-if="downloadable"
+						class="viewer-file__download"
+						variant="secondary"
+						:aria-label="t('Download')"
+						:title="t('Download')"
+						@click="download">
+						<template #icon>
+							<DownloadIcon :size="20" />
+						</template>
+					</NcButton>
+				</div>
+			</template>
+
+			<template v-else>
+				<!-- The handlers are custom elements: they observe hyphenated
+				     attributes, so camelCase bindings are lost whenever the element
+				     is patched before it upgrades. -->
+				<!-- eslint-disable vue/attribute-hyphenation -->
+				<div class="viewer-file__handler">
+					<component
+						:is="tagName"
+						v-if="tagName"
+						v-show="status === 'shown'"
+						ref="handlerElement"
+						:file="file"
+						:files="[file]"
+						:max-width="width"
+						:max-height="height"
+						:is-sidebar-shown="false"
+						:editing="false"
+						:embedded="true"
+						:shown="status === 'shown'"
+						@loaded="onLoaded"
+						@errored="onErrored" />
+				</div>
+				<!-- eslint-enable vue/attribute-hyphenation -->
+
+				<span v-if="status === 'loading'" class="viewer-file__loading">
+					<!-- The picture's colours, blurred, at the size it will take -->
+					<span
+						v-if="placeholder"
+						class="viewer-file__placeholder"
+						:style="{ width: `${placeholder.width}px`, height: `${placeholder.height}px` }">
+						<NcBlurHash :hash="placeholder.hash" />
+					</span>
+					<NcLoadingIcon appearance="light" :size="28" />
+				</span>
+
+				<!-- A video waits behind its poster and one play button until
+				     played, rather than its whole player over a small box -->
+				<button
+					v-if="status === 'shown' && poster !== undefined && !started"
+					type="button"
+					class="viewer-file__cover"
+					:style="poster ? { backgroundImage: `url(${JSON.stringify(poster)})` } : undefined"
+					:aria-label="t('Play')"
+					@click="play">
+					<span class="viewer-file__play">
+						<PlayIcon :size="32" />
+					</span>
+				</button>
+
+				<div v-if="status === 'shown'" class="viewer-file__bar">
+					<span class="viewer-file__name">{{ file.displayname }}</span>
+					<NcActions
+						v-model:open="menuOpen"
+						class="viewer-file__actions"
+						placement="bottom-end"
+						variant="tertiary-no-background"
+						:aria-label="t('Actions')">
+						<NcActionButton closeAfterClick @click="openInViewer">
+							<template #icon>
+								<FullscreenIcon :size="20" />
+							</template>
+							{{ t('Open in the viewer') }}
+						</NcActionButton>
+						<NcActionButton v-if="downloadable" closeAfterClick @click="download">
+							<template #icon>
+								<DownloadIcon :size="20" />
+							</template>
+							{{ t('Download') }}
+						</NcActionButton>
+					</NcActions>
+				</div>
+			</template>
+		</template>
+	</div>
+</template>
+
+<script setup lang="ts">
+import type { IFile } from '@nextcloud/files'
+
+import { formatFileSize } from '@nextcloud/files'
+import { computed, nextTick, onBeforeUnmount, onMounted, ref, useTemplateRef, watch } from 'vue'
+import NcActionButton from '@nextcloud/vue/components/NcActionButton'
+import NcActions from '@nextcloud/vue/components/NcActions'
+import NcBlurHash from '@nextcloud/vue/components/NcBlurHash'
+import NcButton from '@nextcloud/vue/components/NcButton'
+import NcLoadingIcon from '@nextcloud/vue/components/NcLoadingIcon'
+import DownloadIcon from 'vue-material-design-icons/Download.vue'
+import FullscreenIcon from 'vue-material-design-icons/Fullscreen.vue'
+import PlayIcon from 'vue-material-design-icons/Play.vue'
+import { logger } from '../services/logger.ts'
+import { canDownload } from '../utils/canDownload.ts'
+import { emittedValue } from '../utils/handlerEvents.ts'
+import { t } from '../utils/l10n.ts'
+import { blurhash, fitInto, photoSize } from '../utils/photoMetadata.ts'
+import { getViewer } from '../viewer.ts'
+
+const props = defineProps<{
+	/** The file to show */
+	file?: IFile
+	/** The `<nc-viewer-file>` this is the view of, which tells the page */
+	host: HTMLElement
+	/** What the page put inside the element, shown when nothing can show the file */
+	fallback: Node[]
+}>()
+
+/**
+ * Where the file is at: its handler being found or it loading, shown,
+ * failed, or no handler taking it at all
+ */
+const status = ref<'loading' | 'shown' | 'failed' | 'none'>('loading')
+const tagName = ref<string>()
+
+// Which file the handler was asked for, so a late answer for one replaced
+// meanwhile is dropped
+let asked: IFile | undefined
+watch(() => props.file, async (file) => {
+	asked = file
+	tagName.value = undefined
+	status.value = 'loading'
+	if (file === undefined) {
+		return
+	}
+	try {
+		const found = await getViewer().elementFor(file)
+		if (asked !== file) {
+			return
+		}
+		tagName.value = found
+		status.value = found === undefined ? 'none' : 'loading'
+	} catch (error) {
+		logger.error('Could not find what shows the file', { file, error })
+		if (asked === file) {
+			status.value = 'failed'
+		}
+	}
+}, { immediate: true })
+
+// The space the element was given, which the file is fitted into
+const root = useTemplateRef<HTMLElement>('root')
+const width = ref(0)
+const height = ref(0)
+const resizeObserver = new ResizeObserver(([entry]) => {
+	width.value = Math.floor(entry!.contentRect.width)
+	height.value = Math.floor(entry!.contentRect.height)
+})
+onMounted(() => resizeObserver.observe(root.value!))
+onBeforeUnmount(() => resizeObserver.disconnect())
+
+const placeholder = computed(() => {
+	const file = props.file
+	const hash = file && blurhash(file)
+	const size = file && photoSize(file)
+	if (hash === undefined || size === undefined || width.value === 0) {
+		return undefined
+	}
+	return { hash, ...fitInto(size, width.value, height.value) }
+})
+
+const handlerElement = useTemplateRef<HTMLElement>('handlerElement')
+// The video's poster, `''` for one without, nothing for a file that is no video
+const poster = ref<string>()
+// Whether the video was played, which its whole player is left to from then on
+const started = ref(false)
+watch(() => props.file, () => {
+	poster.value = undefined
+	started.value = false
+})
+
+/**
+ * Play the video behind the cover, and leave it to its player.
+ */
+function play() {
+	started.value = true
+	void handlerElement.value?.querySelector('video')?.play()
+}
+
+/**
+ * The handler's element has shown the file.
+ */
+function onLoaded() {
+	poster.value = handlerElement.value?.querySelector('video')?.poster
+	status.value = 'shown'
+	props.host.dispatchEvent(new CustomEvent('loaded'))
+}
+
+/**
+ * The handler's element could not show the file.
+ *
+ * @param reported - What it emitted
+ */
+function onErrored(reported: unknown) {
+	const error = emittedValue(reported)
+	logger.error('Could not show the file', { file: props.file, error })
+	status.value = 'failed'
+	props.host.dispatchEvent(new CustomEvent('errored', { detail: error }))
+}
+
+// What the page put inside the element, moved into the view when it is shown
+const fallbackHolder = useTemplateRef<HTMLElement>('fallbackHolder')
+watch(status, async () => {
+	await nextTick()
+	fallbackHolder.value?.append(...props.fallback)
+})
+
+const downloadable = computed(() => props.file !== undefined && canDownload(props.file))
+const extension = computed(() => (props.file?.extension ?? '').replace(/^\./, '').toUpperCase().slice(0, 4))
+const meta = computed(() => {
+	const size = props.file?.size
+	const parts = size === undefined ? [] : [formatFileSize(size)]
+	return [...parts, t('No preview available')].join(' · ')
+})
+
+/**
+ * Download the file through the browser.
+ */
+function download() {
+	if (props.file === undefined) {
+		return
+	}
+	const link = document.createElement('a')
+	link.href = props.file.encodedSource
+	link.download = props.file.basename
+	document.body.append(link)
+	link.click()
+	link.remove()
+}
+
+/**
+ * Open the file in the viewer, for the full screen and everything it offers.
+ */
+function openInViewer() {
+	if (props.file !== undefined) {
+		void getViewer().open([props.file], props.file)
+	}
+}
+
+// The strip shows on hover and focus. Touch has neither: a tap on the file
+// shows it, and the next one hides it
+const active = ref(false)
+const menuOpen = ref(false)
+
+/**
+ * A tap on the file, rather than on its strip, shows or hides the strip.
+ *
+ * @param event - The pointer going down
+ */
+function onPointerDown(event: PointerEvent) {
+	if (event.pointerType === 'touch' && !(event.target as Element).closest('.viewer-file__bar')) {
+		active.value = !active.value
+	}
+}
+</script>
+
+<style lang="scss">
+// Sized by the page, as any block
+nc-viewer-file {
+	display: block;
+	position: relative;
+	overflow: hidden;
+	border-radius: var(--border-radius-container, var(--border-radius-large));
+}
+</style>
+
+<style scoped lang="scss">
+.viewer-file {
+	position: absolute;
+	inset: 0;
+	// Nothing in it draws over the page
+	isolation: isolate;
+	display: flex;
+	align-items: center;
+	justify-content: center;
+	background-color: #111;
+
+	// The handler's own layers, the viewer's z-index of its players included,
+	// stay under the strip and the cover
+	&__handler {
+		position: absolute;
+		inset: 0;
+		z-index: 0;
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		isolation: isolate;
+	}
+
+	&__cover,
+	&__bar {
+		z-index: 1;
+	}
+
+	&__loading,
+	&__placeholder {
+		position: relative;
+		display: flex;
+		align-items: center;
+		justify-content: center;
+	}
+
+	&__loading {
+		position: absolute;
+		inset: 0;
+
+		.loading-icon {
+			position: absolute;
+		}
+	}
+
+	&__placeholder canvas {
+		display: block;
+		width: 100%;
+		height: 100%;
+	}
+
+	// The name and the menu, out of the way of a player's controls at the
+	// bottom, and out of sight until wanted
+	&__bar {
+		position: absolute;
+		inset: 0 0 auto 0;
+		display: flex;
+		align-items: center;
+		gap: var(--default-grid-baseline);
+		padding-block: var(--default-grid-baseline);
+		padding-inline: calc(3 * var(--default-grid-baseline)) var(--default-grid-baseline);
+		background: linear-gradient(rgba(0, 0, 0, .65), rgba(0, 0, 0, 0));
+		color: #ffffff;
+		font-weight: bold;
+		opacity: 0;
+		transition: opacity var(--animation-quick, 100ms);
+
+		// On the dark strip whatever the theme
+		--color-main-text: #ffffff;
+	}
+
+	&--active &__bar,
+	&:focus-within &__bar {
+		opacity: 1;
+	}
+
+	@media (hover: hover) {
+		&:hover &__bar {
+			opacity: 1;
+		}
+	}
+
+	// Over the player, the size of the box, until the video is played
+	&__cover {
+		position: absolute;
+		inset: 0;
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		margin: 0;
+		padding: 0;
+		border: 0;
+		border-radius: 0;
+		background: #111 center / contain no-repeat;
+		cursor: pointer;
+	}
+
+	&__play {
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		width: 56px;
+		height: 56px;
+		border-radius: 50%;
+		background-color: rgba(0, 0, 0, .55);
+		color: #ffffff;
+	}
+
+	&__cover:hover &__play,
+	&__cover:focus-visible &__play {
+		background-color: rgba(0, 0, 0, .75);
+	}
+
+	&__name {
+		flex: 1;
+		overflow: hidden;
+		text-overflow: ellipsis;
+		white-space: nowrap;
+	}
+
+	// Nothing to show: no dark box, what the page put inside the element or
+	// what the file is and the download, in a line
+	&--said {
+		background-color: transparent;
+	}
+
+	&__fallback {
+		position: absolute;
+		inset: 0;
+	}
+
+	&__card {
+		box-sizing: border-box;
+		width: 100%;
+		background-color: var(--color-main-background);
+		color: var(--color-main-text);
+		display: flex;
+		align-items: center;
+		gap: calc(3 * var(--default-grid-baseline));
+		padding: calc(2 * var(--default-grid-baseline)) calc(3 * var(--default-grid-baseline));
+		border: 1px solid var(--color-border);
+		border-radius: var(--border-radius-container, var(--border-radius-large));
+	}
+
+	&__type {
+		display: flex;
+		flex: none;
+		align-items: center;
+		justify-content: center;
+		width: 40px;
+		height: 40px;
+		border-radius: var(--border-radius-element, var(--border-radius));
+		background-color: var(--color-primary-element-light);
+		color: var(--color-primary-element-light-text);
+		font-size: 11px;
+		font-weight: bold;
+	}
+
+	&__about {
+		display: flex;
+		flex: 1;
+		flex-direction: column;
+		min-width: 0;
+	}
+
+	&__card-name {
+		color: var(--color-primary-element);
+		overflow: hidden;
+		text-overflow: ellipsis;
+		white-space: nowrap;
+	}
+
+	&__card-name {
+		font-weight: bold;
+	}
+
+	&__download {
+		flex: none;
+		border-radius: 50% !important;
+	}
+
+	&__card-meta {
+		color: var(--color-text-maxcontrast);
+		font-size: var(--font-size-small, 13px);
+	}
+}
+</style>
diff --git a/lib/elements/mountViewerFile.ts b/lib/elements/mountViewerFile.ts
new file mode 100644
index 0000000..20ef7c9
--- /dev/null
+++ b/lib/elements/mountViewerFile.ts
@@ -0,0 +1,41 @@
+/*!
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+import type { IFile } from '@nextcloud/files'
+import type { ViewerFileView } from './viewerFile.ts'
+
+import { createApp, h, markRaw, shallowRef } from 'vue'
+import ViewerFile from '../components/ViewerFile.vue'
+import { loadTranslations } from '../utils/l10n.ts'
+
+/**
+ * Mount the view of a `<nc-viewer-file>` inside it, once the strings it
+ * shows can be translated.
+ *
+ * @param host - The element
+ * @param file - The file to show
+ * @param fallback - What the page put inside the element, shown when nothing can show the file
+ */
+export async function mountViewerFile(host: HTMLElement, file: IFile | undefined, fallback: Node[]): Promise<ViewerFileView> {
+	await loadTranslations()
+	const shown = shallowRef(file && markRaw(file))
+	const container = document.createElement('div')
+	container.className = 'nc-viewer-file__root'
+	host.append(container)
+
+	const app = createApp({
+		render: () => h(ViewerFile, { file: shown.value, host, fallback }),
+	})
+	app.mount(container)
+
+	return {
+		update(next) {
+			shown.value = next && markRaw(next)
+		},
+		unmount() {
+			app.unmount()
+			container.remove()
+		},
+	}
+}
diff --git a/lib/elements/viewerFile.ts b/lib/elements/viewerFile.ts
new file mode 100644
index 0000000..ab9683b
--- /dev/null
+++ b/lib/elements/viewerFile.ts
@@ -0,0 +1,99 @@
+/*!
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+import type { IFile } from '@nextcloud/files'
+
+import { defineCustomElementOnce } from '../utils/customElements.ts'
+
+/** The element that shows a file where it is mentioned, outside the viewer */
+export const VIEWER_FILE_TAG = 'nc-viewer-file'
+
+/** What the view of the element is driven by, once it is loaded */
+export interface ViewerFileView {
+	/** Show another file */
+	update(file: IFile | undefined): void
+	/** Take the view down */
+	unmount(): void
+}
+
+/**
+ * `<nc-viewer-file>`: shows a file, as the viewer would, wherever it is put.
+ *
+ * Set its `file` property and size it with CSS. It finds the handler that
+ * shows the file and renders its element inside, sized to its own box, with a
+ * strip naming the file and offering to open it in the viewer or download it.
+ * When nothing can show the file, or it fails to, it says so with a card
+ * offering the download, or shows what the page put inside it instead. It
+ * dispatches `loaded` and `errored` as handlers do.
+ *
+ * A plain element rather than a Vue one: it is defined on every page the
+ * library is on, and only fetches its view once one is actually connected.
+ */
+export class ViewerFileElement extends HTMLElement {
+	#file: IFile | undefined
+	#fallback: Node[] | undefined
+	#view: ViewerFileView | undefined
+	#mounting = false
+
+	/** The file shown */
+	get file(): IFile | undefined {
+		return this.#file
+	}
+
+	set file(file: IFile | undefined) {
+		this.#file = file
+		this.#view?.update(file)
+	}
+
+	connectedCallback(): void {
+		// What the page put inside: shown when nothing can show the file
+		if (this.#fallback === undefined) {
+			// Copied first: removing them empties the live list as it is read
+			this.#fallback = Array.from(this.childNodes)
+			for (const node of this.#fallback) {
+				this.removeChild(node)
+			}
+		}
+		void this.#mount()
+	}
+
+	disconnectedCallback(): void {
+		this.#view?.unmount()
+		this.#view = undefined
+	}
+
+	async #mount(): Promise<void> {
+		if (this.#view !== undefined || this.#mounting) {
+			return
+		}
+		this.#mounting = true
+		try {
+			const { mountViewerFile } = await import('./mountViewerFile.ts')
+			const view = await mountViewerFile(this, this.#file, this.#fallback ?? [])
+			// Taken off the page meanwhile
+			if (!this.isConnected) {
+				view.unmount()
+				return
+			}
+			// The file it was given meanwhile
+			view.update(this.#file)
+			this.#view = view
+		} finally {
+			this.#mounting = false
+		}
+	}
+}
+
+/**
+ * Define `<nc-viewer-file>`, once for every copy of the library on the page.
+ */
+export function defineViewerFileElement(): void {
+	defineCustomElementOnce(VIEWER_FILE_TAG, ViewerFileElement)
+}
+
+declare global {
+	interface HTMLElementTagNameMap {
+		'nc-viewer-file': ViewerFileElement
+	}
+}
diff --git a/lib/index.ts b/lib/index.ts
index 24c8ce7..ad5d74a 100644
--- a/lib/index.ts
+++ b/lib/index.ts
@@ -2,6 +2,7 @@
  * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
  * SPDX-License-Identifier: AGPL-3.0-or-later
  */
+import { defineViewerFileElement } from './elements/viewerFile.ts'
 import { registerImplementation } from './scope.ts'
 import { loadTranslations } from './utils/l10n.ts'
 import { getViewer } from './viewer.ts'
@@ -26,8 +27,13 @@ registerImplementation({
 // It is an empty shell until the viewer is mounted.
 getViewer()
 
+// <nc-viewer-file>, for a page to show a file where it is mentioned. Its view
+// is only fetched once one is on the page
+defineViewerFileElement()
+
 export { canCompare, canView, getHandlers, registerHandler } from './handlers.ts'
 export type { IHandler } from './handlers.ts'
+export type { ViewerFileElement } from './elements/viewerFile.ts'
 export { getViewer, Viewer } from './viewer.ts'
 export type { CompareOptions, ComparisonView, ViewerAPI, ViewerBeforeDownloadDetail, ViewerEmits, ViewerOptions, ViewerProps } from './viewer.ts'
 export type { ViewerEventMap, ViewerSession } from './session.ts'
diff --git a/playground/App.vue b/playground/App.vue
index 7da61b9..5d1c055 100644
--- a/playground/App.vue
+++ b/playground/App.vue
@@ -163,6 +163,22 @@ const compared = flags.get('compare')?.split(',').map((name) => nodes.find((node
 if (compared?.length === 2 && compared[0] && compared[1]) {
 	getViewer().compare(compared[0], compared[1], { view: flags.get('view') === 'differences' ? 'differences' : 'side-by-side' })
 }
+
+// Files shown where they are mentioned, as the preview of a link in a chat:
+// `?embeds`. A file nothing shows, to see what is said instead, once with
+// the card the element makes and once with what the page puts inside
+const withEmbeds = flags.has('embeds')
+const report = new File({
+	source: `${window.location.origin}${DAV}/report.zip`,
+	root: '/files/playground',
+	mime: 'application/zip',
+	owner: 'playground',
+	size: 4404019,
+	permissions: Permission.READ,
+})
+const embeds = withEmbeds
+	? ['photo.jpg', 'trailer.webm', 'audio.mp3'].map((name) => nodes.find((node) => node.basename === name)!).concat(report)
+	: []
 </script>
 
 <template>
@@ -180,10 +196,39 @@ if (compared?.length === 2 && compared[0] && compared[1]) {
 				</button>
 			</li>
 		</ul>
+
+		<section v-if="withEmbeds" class="playground__embeds">
+			<h2>Shown where they are mentioned</h2>
+			<!-- eslint-disable vue/no-undef-components -- the custom element the library defines -->
+			<nc-viewer-file
+				v-for="node in embeds"
+				:key="node.source"
+				:file.prop="node"
+				class="playground__embed" />
+			<nc-viewer-file :file.prop="report" class="playground__embed playground__embed--own">
+				<a :href="report.source">{{ report.displayname }}</a>
+			</nc-viewer-file>
+			<!-- eslint-enable vue/no-undef-components -->
+		</section>
 	</main>
 </template>
 
 <style scoped>
+.playground__embeds {
+	display: grid;
+	grid-template-columns: repeat(auto-fill, 280px);
+	gap: 1rem;
+}
+
+.playground__embeds h2 {
+	grid-column: 1 / -1;
+}
+
+.playground__embed {
+	width: 280px;
+	height: 180px;
+}
+
 .playground {
 	max-inline-size: 40rem;
 	margin: 0 auto;
diff --git a/playground/style.css b/playground/style.css
index e3e0d2a..44ca125 100644
--- a/playground/style.css
+++ b/playground/style.css
@@ -16,3 +16,11 @@ body {
 .nc-select__dropdown.vs__dropdown-menu {
 	--vs-dropdown-z-index: 9999;
 }
+
+/* What the server's core/css/styles.scss resets on every page, which the
+ * menus of @nextcloud/vue count on */
+ul {
+	margin: 0;
+	padding: 0;
+	list-style: none;
+}
diff --git a/playground/vite.config.ts b/playground/vite.config.ts
index e5b8123..9214733 100644
--- a/playground/vite.config.ts
+++ b/playground/vite.config.ts
@@ -8,7 +8,7 @@ import { isVideojsElement } from '../build/videojsElements.ts'
 
 export default defineConfig({
 	root: import.meta.dirname,
-	plugins: [vue({ template: { compilerOptions: { isCustomElement: isVideojsElement } } })],
+	plugins: [vue({ template: { compilerOptions: { isCustomElement: (tag) => isVideojsElement(tag) || tag === 'nc-viewer-file' } } })],
 	define: {
 		// No bundled translations while serving the playground
 		__TRANSLATIONS__: '[]',

From 5abc34d6fb109477cf315282be6e198c5433f783 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?John=20Molakvo=C3=A6?=
 <14975046+skjnldsv@users.noreply.github.com>
Date: Wed, 21 Oct 2026 11:51:11 +0200
Subject: [PATCH 5/6] docs: say what a handler shown embedded is expected to do
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Read-only to start and not taking over the page, with any switch to
editing inline left to the handler, as Text has.

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: John Molakvoæ <14975046+skjnldsv@users.noreply.github.com>
---
 README.md     | 1 +
 lib/viewer.ts | 9 +++++----
 2 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index ba87198..620a49e 100644
--- a/README.md
+++ b/README.md
@@ -242,6 +242,7 @@ const src = computed(() => props.file.encodedSource)
 | `localSource`    | `string`  | An object URL to show instead of the file, e.g. right after an edit. Optional |
 | `turns`          | `number`  | Quarter turns the viewer asks you to show the file rotated by. Optional |
 | `comparison`     | `'side-by-side' \| 'differences'` | How the viewer compares `files`, see [comparing two files](#comparing-two-files). Optional |
+| `embedded`       | `boolean` | Shown inline by a `<nc-viewer-file>`, outside the viewer: start read-only, no autoplay. You may offer your own switch to editing there. Optional |
 
 `ViewerEmits` lets you emit:
 
diff --git a/lib/viewer.ts b/lib/viewer.ts
index 0e92f3c..a27c84b 100644
--- a/lib/viewer.ts
+++ b/lib/viewer.ts
@@ -85,10 +85,11 @@ export interface ViewerProps {
 	comparison?: ComparisonView
 
 	/**
-	 * Whether the file is shown inline, outside the viewer, as the preview of a
-	 * link to it (see `getViewer().elementFor()`). A hint that handlers should
-	 * not take over the page, for example by autoplaying. Editing is usually
-	 * better left to the viewer, which the caller can open on the file.
+	 * Whether the file is shown inline, outside the viewer, by a
+	 * `<nc-viewer-file>` as the preview of a link to it. Start read-only and
+	 * do not take over the page: no autoplay, no focus taken. A handler may
+	 * offer its own way to switch to editing inline, as Text does; the full
+	 * viewer, editing included, is one click away from the element's menu.
 	 */
 	embedded?: boolean
 }

From 32d13590baa26b433f44e9827fab6f369235a806 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?John=20Molakvo=C3=A6?=
 <14975046+skjnldsv@users.noreply.github.com>
Date: Wed, 21 Oct 2026 11:57:24 +0200
Subject: [PATCH 6/6] build: make room in the entry for <nc-viewer-file>
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

It is defined on every page, and the default handlers now define their
elements when first needed: 0.8 kB gzipped. Its view stays lazy, and
the check now says so.

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: John Molakvoæ <14975046+skjnldsv@users.noreply.github.com>
---
 build/check-bundle-size.mjs | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/build/check-bundle-size.mjs b/build/check-bundle-size.mjs
index 6457f82..21e7952 100644
--- a/build/check-bundle-size.mjs
+++ b/build/check-bundle-size.mjs
@@ -22,11 +22,15 @@ import { gzipSync } from 'node:zlib'
  * in it.
  */
 
-/** What the entry may cost, gzipped, before anyone has opened a file */
-const BUDGET_GZIP = 10 * 1024
+/**
+ * What the entry may cost, gzipped, before anyone has opened a file. Raised
+ * from 10 kB for <nc-viewer-file>, defined on every page, and the default
+ * handlers defining their elements when first needed
+ */
+const BUDGET_GZIP = 11 * 1024
 
 /** Chunks that must only ever be reached through a dynamic import */
-const MUST_BE_LAZY = ['mount', 'Images', 'Videos', 'Audios', 'ImageEditor', 'usePlyrPlayer', 'translations']
+const MUST_BE_LAZY = ['mount', 'mountViewerFile', 'Images', 'Videos', 'Audios', 'ImageEditor', 'usePlyrPlayer', 'translations']
 
 /**
  * Packages a page must not pay for unless it opens something needing them.