feat(handlers): add onInit() to define a handler's element when it is needed

Same shape as the files sidebar tabs: the viewer calls onInit() the first
time it needs the element, and renders it once the promise resolved and
the tag is defined. The view and what it imports stay out of the
registration script that runs on every page.

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: John Molakvoæ <14975046+skjnldsv@users.noreply.github.com>

Author: skjnldsv

README.md

@@ -87,30 +87,34 @@ element is mounted again for every file, which is why `onMounted` is enough here
 
 #### 3. Register it
 
-This script turns the component into a custom element and tells the viewer which
-files it takes:
+This script tells the viewer which files it takes, and how to define the element
+that shows them:
 
 ```ts
 // src/init-viewer.ts
 import { t } from '@nextcloud/l10n'
 import { registerHandler } from '@nextcloud/viewer'
-import { defineCustomElement } from 'vue'
-import NoteView from './views/NoteView.vue'
 
 const tagname = 'myapp-note-view'
 
-if (!window.customElements.get(tagname)) {
-	window.customElements.define(tagname, defineCustomElement(NoteView, { shadowRoot: false }))
-}
-
 registerHandler({
 	id: 'myapp-notes',
 	displayName: t('myapp', 'Notes'),
 	tagname,
 	enabled: (nodes) => nodes.every((node) => node.mime === 'application/x-myapp-note'),
+	// Only called the first time a note is opened
+	onInit: async () => {
+		const { defineCustomElement } = await import('vue')
+		const { default: NoteView } = await import('./views/NoteView.vue')
+		window.customElements.define(tagname, defineCustomElement(NoteView, { shadowRoot: false }))
+	},
 })
 ```
 
+`onInit()` keeps your view out of this script. The viewer calls it the first
+time it needs the element, and renders the element once the promise has resolved
+and the tag is defined.
+
 Add it as an entry of your build, next to your other ones:
 
 ```js
@@ -122,9 +126,9 @@ export default createAppConfig({
 })
 ```
 
-It lands in `js/myapp-init-viewer.mjs`. This script runs on every page, so keep
-it small: if your view pulls in something heavy, have the element render a small
-wrapper that loads the real view with `defineAsyncComponent`.
+It lands in `js/myapp-init-viewer.mjs`. This script runs on every page, which is
+why the view itself is only imported in `onInit()`: the script stays a few lines however
+much the view imports.
 
 #### 4. Load it on every page
 
@@ -309,6 +313,11 @@ registerHandler({
 })
 ```
 
+Defining the element up front puts the view in the script that registers the
+handler, and that script runs on every page. To keep it out, leave the
+definition to `onInit()`, as the [tutorial](#3-register-it) does: the viewer
+calls it the first time it needs the element.
+
 The full handler shape (see the `IHandler` interface):
 
 | Field           | Type                                  | Required | Description                                                        |
@@ -322,6 +331,7 @@ The full handler shape (see the `IHandler` interface):
 | `preload`       | `(node: File) => Promise<void>`       | no       | Preload data for neighbouring files                                |
 | `theme`         | `'dark' \| 'light' \| 'default'`      | no       | Viewer modal theme                                                 |
 | `supportsEndToEndEncryption` | `boolean`                | no       | Whether the handler supports end-to-end encrypted files            |
+| `onInit`        | `() => Promise<void>`                 | no       | Defines the element for `tagname`, called the first time it is needed |
 
 Gotchas:
 

__tests__/component/Viewer.spec.ts

@@ -722,3 +722,76 @@ describe('opening over a viewer that is still open', () => {
 		expect(onClose).toHaveBeenCalledOnce()
 	})
 })
+
+describe('a handler that defines its element in onInit()', () => {
+	let count = 0
+
+	/**
+	 * A handler whose onInit() defines its element, under a tag no other test uses.
+	 *
+	 * @param before - What onInit() waits for before defining it
+	 */
+	function lazyHandler(before: () => Promise<void> = async () => {}) {
+		const tagname = `oca-viewer-lazy-${++count}`
+		const onInit = vi.fn(async () => {
+			await before()
+			customElements.define(tagname, class extends HTMLElement {})
+		})
+		return makeHandler({ id: tagname, tagname, enabled: () => true, onInit })
+	}
+
+	it('renders the element only once onInit() has defined it', async () => {
+		let resolve!: () => void
+		const handler = lazyHandler(() => new Promise((r) => {
+			resolve = r
+		}))
+		const { vm, renderedTags } = mountViewer([handler])
+		const file = makeFile()
+		await vm.open([file], file)
+		await flushPromises()
+
+		// Rendered before it is defined, it would get its bindings as
+		// attributes and lose them on upgrade
+		expect(renderedTags()).not.toContain(handler.tagname)
+		expect(customElements.get(handler.tagname)).toBeUndefined()
+
+		resolve()
+		await flushPromises()
+
+		expect(customElements.get(handler.tagname)).toBeDefined()
+		expect(renderedTags()).toContain(handler.tagname)
+	})
+
+	it('calls onInit() once however many files open with it', async () => {
+		const handler = lazyHandler()
+		const { vm, renderedTags } = mountViewer([handler])
+		const first = makeFile({ basename: 'first.txt' })
+		const second = makeFile({ basename: 'second.txt' })
+		await vm.open([first, second], first)
+		await flushPromises()
+		await vm.open([first, second], second)
+		await flushPromises()
+
+		expect(handler.onInit).toHaveBeenCalledOnce()
+		expect(renderedTags()).toContain(handler.tagname)
+	})
+
+	it('shows the error when onInit() fails, and tries again on the next open', async () => {
+		const handler = lazyHandler()
+		vi.mocked(handler.onInit!).mockRejectedValueOnce(new Error('Failed to fetch dynamically imported module'))
+		const { vm, errorText, renderedTags } = mountViewer([handler])
+		const file = makeFile()
+		await vm.open([file], file)
+		await flushPromises()
+
+		expect(errorText()).toBe('Failed to fetch dynamically imported module')
+		expect(renderedTags()).not.toContain(handler.tagname)
+
+		vm.close()
+		await vm.open([file], file)
+		await flushPromises()
+
+		expect(handler.onInit).toHaveBeenCalledTimes(2)
+		expect(renderedTags()).toContain(handler.tagname)
+	})
+})

__tests__/registerHandler.spec.ts

@@ -40,3 +40,13 @@ describe('registering a handler whose id is taken', () => {
 		expect(warn).not.toHaveBeenCalled()
 	})
 })
+
+describe('a handler that defines its element in onInit()', () => {
+	it('is refused when onInit is not a function', () => {
+		expect(() => registerHandler(makeHandler({
+			id: 'not-an-init',
+			tagname: 'oca-viewer-not-an-init',
+			onInit: 'later' as never,
+		}))).toThrow('Handler onInit must be a function if provided')
+	})
+})

lib/handlers.ts

@@ -62,6 +62,18 @@ export interface IHandler {
 	 */
 	preload?: (node: IFile) => Promise<void>
 
+	/**
+	 * Called the first time the viewer needs the element, to define it
+	 * (`customElements.define()` with `tagname`).
+	 *
+	 * The viewer waits for the returned promise and for the element to be
+	 * defined (`customElements.whenDefined()`) before rendering it, so the
+	 * view and everything it imports stay out of the registration script
+	 * that runs on every page. Leave it out when the element is already
+	 * defined by the time the viewer opens.
+	 */
+	onInit?: () => Promise<void>
+
 	/**
 	 * Viewer modal theme (one of 'dark', 'light', 'default')
 	 */
@@ -303,6 +315,10 @@ function validateHandler(handler: IHandler): void {
 		throw new Error('Handler preload must be a function if provided')
 	}
 
+	if (handler.onInit && typeof handler.onInit !== 'function') {
+		throw new Error('Handler onInit must be a function if provided')
+	}
+
 	if (handler.theme && !['dark', 'light', 'default'].includes(handler.theme)) {
 		throw new Error("Handler theme must be one of 'dark', 'light', 'default' if provided")
 	}

lib/utils/customElements.ts

@@ -2,6 +2,8 @@
  * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
  * SPDX-License-Identifier: AGPL-3.0-or-later
  */
+import type { IHandler } from '../handlers.ts'
+
 import { logger } from '../services/logger.ts'
 
 /**
@@ -23,3 +25,29 @@ export function defineCustomElementOnce(tagname: string, constructor: CustomElem
 
 	window.customElements.define(tagname, constructor)
 }
+
+/** The handlers being initialized, by tag, so each one is initialized once however often it is asked for */
+const initializing = new Map<string, Promise<void>>()
+
+/**
+ * Make sure a handler's element is defined, initializing the handler first if it has to.
+ *
+ * Resolves at once for an element that is defined already, or for a
+ * handler without `onInit()`, which defines its element itself. An
+ * `onInit()` that fails is forgotten, so the next open tries again.
+ *
+ * @param handler - The handler whose element is about to be rendered
+ */
+export function initHandlerElement(handler: IHandler): Promise<void> {
+	if (handler.onInit === undefined || window.customElements.get(handler.tagname) !== undefined) {
+		return Promise.resolve()
+	}
+
+	let pending = initializing.get(handler.tagname)
+	if (pending === undefined) {
+		pending = handler.onInit().then(() => window.customElements.whenDefined(handler.tagname)).then(() => undefined)
+		initializing.set(handler.tagname, pending)
+		pending.catch(() => initializing.delete(handler.tagname))
+	}
+	return pending
+}

lib/views/Viewer.vue

@@ -145,7 +145,7 @@
 			<!-- eslint-disable vue/attribute-hyphenation -->
 			<component
 				:is="currentHandler?.tagname"
-				v-if="currentFile"
+				v-if="currentFile && elementReady(currentHandler)"
 				:file="currentFile"
 				:files="[]"
 				:is-sidebar-shown="isSidebarShown"
@@ -156,7 +156,7 @@
 				@errored="onError" />
 			<component
 				:is="comparisonHandler?.tagname"
-				v-if="comparisonFile"
+				v-if="comparisonFile && elementReady(comparisonHandler)"
 				:file="comparisonFile"
 				:files="[]"
 				:is-sidebar-shown="isSidebarShown"
@@ -170,7 +170,7 @@
 		<!-- Single file view -->
 		<component
 			:is="currentHandler?.tagname"
-			v-else-if="currentFile"
+			v-else-if="currentFile && elementReady(currentHandler)"
 			v-show="!loading && !errorString"
 			:key="`${currentFile.fileid}-${reloadKey}`"
 			ref="handlerElement"
@@ -245,6 +245,7 @@ import { getHandlerForFile } from '../helpers/handlerHelper.ts'
 import { fetchFolderContent } from '../services/dav.ts'
 import { logger } from '../services/logger.ts'
 import { canDownload } from '../utils/canDownload.ts'
+import { initHandlerElement } from '../utils/customElements.ts'
 import { restoreTitle, setViewerTitle } from '../utils/documentTitle.ts'
 import { emittedValue, toError } from '../utils/handlerEvents.ts'
 import { t } from '../utils/l10n.ts'
@@ -353,6 +354,41 @@ const canOpenSidebar = computed(() => currentOptions.value.enableSidebar !== fal
 // Comparison context (compare API)
 const comparisonFile = ref<IFile>()
 const comparisonHandler = ref<IHandler>()
+
+// Tags whose element a handler's onInit() has defined. The registry itself
+// is not reactive, so this is what tells the template it may render them.
+const loadedTags = ref(new Set<string>())
+
+/**
+ * Whether a handler's element can be rendered yet.
+ *
+ * Rendered before its tag is defined, the element gets its bindings as
+ * attributes and loses them when it upgrades, so one that comes from
+ * `onInit()` waits for it.
+ *
+ * @param handler - The handler about to be rendered
+ */
+function elementReady(handler?: IHandler): boolean {
+	return handler !== undefined
+		&& (handler.onInit === undefined || loadedTags.value.has(handler.tagname) || window.customElements.get(handler.tagname) !== undefined)
+}
+
+watch([currentHandler, comparisonHandler], (handlers) => {
+	for (const handler of handlers) {
+		if (handler === undefined || elementReady(handler)) {
+			continue
+		}
+		initHandlerElement(handler).then(() => {
+			loadedTags.value = new Set([...loadedTags.value, handler.tagname])
+		}, (error: unknown) => {
+			logger.error('Could not initialize a handler', { handler: handler.id, error })
+			onError(error)
+		})
+	}
+// Synchronous: closing and reopening with the same handler in one tick is a
+// change a deferred watcher would not see, and the retry after a failed
+// load would never happen
+}, { immediate: true, flush: 'sync' })
 const isComparing = computed(() => !!comparisonFile.value)
 
 // Files actions rendered in the viewer menu (download, delete, …), linked to