From d9cdf03442fb41b5f71683ae140ba88ce37d69bc Mon Sep 17 00:00:00 2001
From: Lee Kelleher <leekelleher@users.noreply.github.com>
Date: Fri, 24 Oct 2025 09:29:22 +0100
Subject: [PATCH] Preview: Allows changing the preview environment inside the
 preview app, and other UX changes that enhance the experience (#20598)

* Preview Device: refactored config

Fixed "flip" icon style.

Removed "shadow" as unnecessary.

Renamed "className" to "wrapperClass" to be descriptive.

* Preview element CSS refinement

* Preview element: load in private extensions

* Added "Preview Environments" preview-app

Made `unique`, `culture` and `segment` observable in the context.

* Aligned preview-app design

with `hidden` attribute and design consistency.

* Created "Preview" package

* Relocated "Preview Apps" and Context to the new package

* Deprecated `UmbDocumentPreviewRepository` (for v19)

as the methods have moved to `UmbPreviewRepository`.

* Removed Preview Sessions event listeners

* Changed localization from "End" to "Exit"

* chore: consumes context only when needed

* feat: uses the UmbPreviewRepository instead

* feat: adds localization to errors and ensures the function does not randomly throw

* feat: prevents creating a new repository for every click

* feat: prevents potential memory leak by adding a signal to the events added to each iframe update

* feat: adds a custom interface to prevent typescript errors

* feat: ensures new string states are checked properly

* docs: adds comment to avoid confusion

* feat: sets up scaling once per iframe load rather than on each update

* fix: ensures that you can go back to the default segment again

* feat: closes popovers when clicking on the iframe (losing blur) and if selecting an item (expect for devices)

---------

Co-authored-by: Jacob Overgaard <752371+iOvergaard@users.noreply.github.com>
---
 src/Umbraco.Web.UI.Client/package-lock.json   |   7 +
 src/Umbraco.Web.UI.Client/package.json        |   1 +
 .../src/apps/preview/index.ts                 |   1 +
 .../src/apps/preview/preview.element.ts       |  76 +++++---
 .../src/assets/lang/en.ts                     |   4 +-
 .../preview/document-preview.repository.ts    |  13 ++
 .../workspace/document-workspace.context.ts   |   4 +-
 .../src/packages/preview/context/index.ts     |   2 +
 .../preview/context/preview.context-token.ts  |   4 +
 .../preview/context}/preview.context.ts       | 150 ++++++++++------
 .../src/packages/preview/index.ts             |   2 +
 .../src/packages/preview/manifests.ts         |   4 +
 .../src/packages/preview/package.json         |   8 +
 .../preview/preview-apps}/manifests.ts        |  15 +-
 .../preview-apps}/preview-culture.element.ts  |  59 +++++-
 .../preview-apps}/preview-device.element.ts   |  91 +++++++---
 .../preview-environments.element.ts           | 170 ++++++++++++++++++
 .../preview-apps}/preview-exit.element.ts     |   4 +-
 .../preview-open-website.element.ts           |   4 +-
 .../preview-apps}/preview-segment.element.ts  |  66 +++++--
 .../packages/preview/preview-apps/types.ts    |   6 +
 .../src/packages/preview/repository/index.ts  |   1 +
 .../preview/repository/preview.repository.ts  |  74 ++++++++
 .../src/packages/preview/umbraco-package.ts   |   9 +
 .../src/packages/preview/vite.config.ts       |  12 ++
 src/Umbraco.Web.UI.Client/tsconfig.json       |   1 +
 26 files changed, 649 insertions(+), 139 deletions(-)
 create mode 100644 src/Umbraco.Web.UI.Client/src/apps/preview/index.ts
 create mode 100644 src/Umbraco.Web.UI.Client/src/packages/preview/context/index.ts
 create mode 100644 src/Umbraco.Web.UI.Client/src/packages/preview/context/preview.context-token.ts
 rename src/Umbraco.Web.UI.Client/src/{apps/preview => packages/preview/context}/preview.context.ts (65%)
 create mode 100644 src/Umbraco.Web.UI.Client/src/packages/preview/index.ts
 create mode 100644 src/Umbraco.Web.UI.Client/src/packages/preview/manifests.ts
 create mode 100644 src/Umbraco.Web.UI.Client/src/packages/preview/package.json
 rename src/Umbraco.Web.UI.Client/src/{apps/preview/apps => packages/preview/preview-apps}/manifests.ts (76%)
 rename src/Umbraco.Web.UI.Client/src/{apps/preview/apps => packages/preview/preview-apps}/preview-culture.element.ts (66%)
 rename src/Umbraco.Web.UI.Client/src/{apps/preview/apps => packages/preview/preview-apps}/preview-device.element.ts (57%)
 create mode 100644 src/Umbraco.Web.UI.Client/src/packages/preview/preview-apps/preview-environments.element.ts
 rename src/Umbraco.Web.UI.Client/src/{apps/preview/apps => packages/preview/preview-apps}/preview-exit.element.ts (91%)
 rename src/Umbraco.Web.UI.Client/src/{apps/preview/apps => packages/preview/preview-apps}/preview-open-website.element.ts (91%)
 rename src/Umbraco.Web.UI.Client/src/{apps/preview/apps => packages/preview/preview-apps}/preview-segment.element.ts (62%)
 create mode 100644 src/Umbraco.Web.UI.Client/src/packages/preview/preview-apps/types.ts
 create mode 100644 src/Umbraco.Web.UI.Client/src/packages/preview/repository/index.ts
 create mode 100644 src/Umbraco.Web.UI.Client/src/packages/preview/repository/preview.repository.ts
 create mode 100644 src/Umbraco.Web.UI.Client/src/packages/preview/umbraco-package.ts
 create mode 100644 src/Umbraco.Web.UI.Client/src/packages/preview/vite.config.ts

diff --git a/src/Umbraco.Web.UI.Client/package-lock.json b/src/Umbraco.Web.UI.Client/package-lock.json
index 9c08dfb59f..74589de99c 100644
--- a/src/Umbraco.Web.UI.Client/package-lock.json
+++ b/src/Umbraco.Web.UI.Client/package-lock.json
@@ -3638,6 +3638,10 @@
 			"resolved": "src/packages/performance-profiling",
 			"link": true
 		},
+		"node_modules/@umbraco-backoffice/preview": {
+			"resolved": "src/packages/preview",
+			"link": true
+		},
 		"node_modules/@umbraco-backoffice/property-editors": {
 			"resolved": "src/packages/property-editors",
 			"link": true
@@ -17084,6 +17088,9 @@
 		"src/packages/performance-profiling": {
 			"name": "@umbraco-backoffice/performance-profiling"
 		},
+		"src/packages/preview": {
+			"name": "@umbraco-backoffice/preview"
+		},
 		"src/packages/property-editors": {
 			"name": "@umbraco-backoffice/property-editors"
 		},
diff --git a/src/Umbraco.Web.UI.Client/package.json b/src/Umbraco.Web.UI.Client/package.json
index b22f6f4e74..f91e42d9ba 100644
--- a/src/Umbraco.Web.UI.Client/package.json
+++ b/src/Umbraco.Web.UI.Client/package.json
@@ -85,6 +85,7 @@
 		"./picker-input": "./dist-cms/packages/core/picker-input/index.js",
 		"./picker-data-source": "./dist-cms/packages/core/picker-data-source/index.js",
 		"./picker": "./dist-cms/packages/core/picker/index.js",
+		"./preview": "./dist-cms/packages/preview/index.js",
 		"./property-action": "./dist-cms/packages/core/property-action/index.js",
 		"./property-editor-data-source": "./dist-cms/packages/core/property-editor-data-source/index.js",
 		"./property-editor": "./dist-cms/packages/core/property-editor/index.js",
diff --git a/src/Umbraco.Web.UI.Client/src/apps/preview/index.ts b/src/Umbraco.Web.UI.Client/src/apps/preview/index.ts
new file mode 100644
index 0000000000..d90c7995f9
--- /dev/null
+++ b/src/Umbraco.Web.UI.Client/src/apps/preview/index.ts
@@ -0,0 +1 @@
+export * from './preview.element.js';
diff --git a/src/Umbraco.Web.UI.Client/src/apps/preview/preview.element.ts b/src/Umbraco.Web.UI.Client/src/apps/preview/preview.element.ts
index b2d0db0da7..e9bce3c441 100644
--- a/src/Umbraco.Web.UI.Client/src/apps/preview/preview.element.ts
+++ b/src/Umbraco.Web.UI.Client/src/apps/preview/preview.element.ts
@@ -1,8 +1,14 @@
-import { manifests as previewApps } from './apps/manifests.js';
-import { UmbPreviewContext } from './preview.context.js';
 import { css, customElement, html, nothing, state, when } from '@umbraco-cms/backoffice/external/lit';
-import { umbExtensionsRegistry } from '@umbraco-cms/backoffice/extension-registry';
+import {
+	umbExtensionsRegistry,
+	UmbBackofficeEntryPointExtensionInitializer,
+} from '@umbraco-cms/backoffice/extension-registry';
 import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element';
+import { UmbPreviewContext } from '@umbraco-cms/backoffice/preview';
+import { UmbServerExtensionRegistrator } from '@umbraco-cms/backoffice/extension-api';
+import { UMB_AUTH_CONTEXT } from '@umbraco-cms/backoffice/auth';
+
+const CORE_PACKAGES = [import('../../packages/preview/umbraco-package.js')];
 
 /**
  * @element umb-preview
@@ -11,23 +17,40 @@ import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element';
 export class UmbPreviewElement extends UmbLitElement {
 	#context = new UmbPreviewContext(this);
 
-	constructor() {
-		super();
-
-		if (previewApps?.length) {
-			umbExtensionsRegistry.registerMany(previewApps);
-		}
-
-		this.observe(this.#context.iframeReady, (iframeReady) => (this._iframeReady = iframeReady));
-		this.observe(this.#context.previewUrl, (previewUrl) => (this._previewUrl = previewUrl));
-	}
-
 	@state()
 	private _iframeReady?: boolean;
 
 	@state()
 	private _previewUrl?: string;
 
+	constructor() {
+		super();
+
+		new UmbBackofficeEntryPointExtensionInitializer(this, umbExtensionsRegistry);
+
+		this.observe(this.#context.iframeReady, (iframeReady) => (this._iframeReady = iframeReady));
+		this.observe(this.#context.previewUrl, (previewUrl) => (this._previewUrl = previewUrl));
+	}
+
+	override async firstUpdated() {
+		await this.#extensionsAfterAuth();
+
+		// Extensions are loaded in parallel and don't need to block the preview frame
+		CORE_PACKAGES.forEach(async (packageImport) => {
+			const { extensions } = await packageImport;
+			umbExtensionsRegistry.registerMany(extensions);
+		});
+	}
+
+	async #extensionsAfterAuth() {
+		const authContext = await this.getContext(UMB_AUTH_CONTEXT, { preventTimeout: true });
+		if (!authContext) {
+			throw new Error('UmbPreviewElement requires the UMB_AUTH_CONTEXT to be set.');
+		}
+		await this.observe(authContext.isAuthorized).asPromise();
+		await new UmbServerExtensionRegistrator(this, umbExtensionsRegistry).registerPrivateExtensions();
+	}
+
 	#onIFrameLoad(event: Event & { target: HTMLIFrameElement }) {
 		this.#context.iframeLoaded(event.target);
 	}
@@ -36,7 +59,7 @@ export class UmbPreviewElement extends UmbLitElement {
 		if (!this._previewUrl) return nothing;
 		return html`
 			${when(!this._iframeReady, () => html`<div id="loading"><uui-loader-circle></uui-loader-circle></div>`)}
-			<div id="wrapper">
+			<div id="wrapper" class="fullsize">
 				<div id="container">
 					<iframe
 						src=${this._previewUrl}
@@ -47,9 +70,9 @@ export class UmbPreviewElement extends UmbLitElement {
 			</div>
 			<div id="menu">
 				<h4>Preview Mode</h4>
-				<uui-button-group>
-					<umb-extension-slot id="apps" type="previewApp"></umb-extension-slot>
-				</uui-button-group>
+				<div id="apps">
+					<umb-extension-slot type="previewApp"></umb-extension-slot>
+				</div>
 			</div>
 		`;
 	}
@@ -62,10 +85,7 @@ export class UmbPreviewElement extends UmbLitElement {
 				align-items: center;
 
 				position: absolute;
-				top: 0;
-				left: 0;
-				right: 0;
-				bottom: 0;
+				inset: 0;
 
 				padding-bottom: 40px;
 			}
@@ -82,7 +102,9 @@ export class UmbPreviewElement extends UmbLitElement {
 				bottom: 0;
 
 				font-size: 6rem;
-				backdrop-filter: blur(5px);
+				backdrop-filter: blur(var(--uui-size-1, 3px));
+
+				z-index: 1;
 			}
 
 			#wrapper {
@@ -97,7 +119,7 @@ export class UmbPreviewElement extends UmbLitElement {
 				overflow: hidden;
 			}
 
-			#wrapper.shadow {
+			#wrapper:not(.fullsize) {
 				margin: 10px auto;
 				background-color: white;
 				border-radius: 3px;
@@ -123,6 +145,8 @@ export class UmbPreviewElement extends UmbLitElement {
 				left: 0;
 				right: 0;
 
+				z-index: 1;
+
 				background-color: var(--uui-color-header-surface);
 				height: 40px;
 
@@ -136,7 +160,9 @@ export class UmbPreviewElement extends UmbLitElement {
 				padding: 0 15px;
 			}
 
-			#menu > uui-button-group {
+			#apps {
+				display: inline-flex;
+				align-items: stretch;
 				height: 100%;
 			}
 
diff --git a/src/Umbraco.Web.UI.Client/src/assets/lang/en.ts b/src/Umbraco.Web.UI.Client/src/assets/lang/en.ts
index 810d9dbb4d..1d70a6ab6d 100644
--- a/src/Umbraco.Web.UI.Client/src/assets/lang/en.ts
+++ b/src/Umbraco.Web.UI.Client/src/assets/lang/en.ts
@@ -2737,8 +2737,8 @@ export default {
 			'You can edit and delete Document Blueprints from the "Document Blueprints" tree in the Settings section. Expand the Document Type which the Document Blueprint is based on and click it to edit or delete it.',
 	},
 	preview: {
-		endLabel: 'End',
-		endTitle: 'End preview mode',
+		endLabel: 'Exit',
+		endTitle: 'Exit preview mode',
 		openWebsiteLabel: 'Preview website',
 		openWebsiteTitle: 'Open website in preview mode',
 		returnToPreviewHeadline: 'Preview website?',
diff --git a/src/Umbraco.Web.UI.Client/src/packages/documents/documents/repository/preview/document-preview.repository.ts b/src/Umbraco.Web.UI.Client/src/packages/documents/documents/repository/preview/document-preview.repository.ts
index d216290d39..abf31e6867 100644
--- a/src/Umbraco.Web.UI.Client/src/packages/documents/documents/repository/preview/document-preview.repository.ts
+++ b/src/Umbraco.Web.UI.Client/src/packages/documents/documents/repository/preview/document-preview.repository.ts
@@ -5,6 +5,7 @@ import { UmbRepositoryBase } from '@umbraco-cms/backoffice/repository';
 import type { DocumentUrlInfoModel } from '@umbraco-cms/backoffice/external/backend-api';
 import type { UmbControllerHost } from '@umbraco-cms/backoffice/controller-api';
 
+/** @deprecated This has been deprecated, please use `UmbPreviewRepository` instead. To be removed in Umbraco 19. [LK] */
 export class UmbDocumentPreviewRepository extends UmbRepositoryBase {
 	constructor(host: UmbControllerHost) {
 		super(host);
@@ -24,6 +25,12 @@ export class UmbDocumentPreviewRepository extends UmbRepositoryBase {
 		culture?: string,
 		segment?: string,
 	): Promise<DocumentUrlInfoModel> {
+		new UmbDeprecation({
+			removeInVersion: '19.0.0',
+			deprecated: '`UmbDocumentPreviewRepository.getPreviewUrl()`',
+			solution: 'Use `UmbPreviewRepository.getPreviewUrl()` instead',
+		}).warn();
+
 		const { data, error } = await tryExecute(
 			this,
 			DocumentService.getDocumentByIdPreviewUrl({
@@ -62,6 +69,12 @@ export class UmbDocumentPreviewRepository extends UmbRepositoryBase {
 	 * @memberof UmbDocumentPreviewRepository
 	 */
 	async exit(): Promise<void> {
+		new UmbDeprecation({
+			removeInVersion: '19.0.0',
+			deprecated: '`UmbDocumentPreviewRepository.exit()`',
+			solution: 'Use `UmbPreviewRepository.exit()` instead',
+		}).warn();
+
 		await tryExecute(this, PreviewService.deletePreview(), { disableNotifications: true });
 		return;
 	}
diff --git a/src/Umbraco.Web.UI.Client/src/packages/documents/documents/workspace/document-workspace.context.ts b/src/Umbraco.Web.UI.Client/src/packages/documents/documents/workspace/document-workspace.context.ts
index 0d199d874c..50d45001ff 100644
--- a/src/Umbraco.Web.UI.Client/src/packages/documents/documents/workspace/document-workspace.context.ts
+++ b/src/Umbraco.Web.UI.Client/src/packages/documents/documents/workspace/document-workspace.context.ts
@@ -14,7 +14,6 @@ import {
 	UMB_USER_PERMISSION_DOCUMENT_CREATE,
 	UMB_USER_PERMISSION_DOCUMENT_UPDATE,
 } from '../constants.js';
-import { UmbDocumentPreviewRepository } from '../repository/preview/index.js';
 import { UmbDocumentValidationRepository } from '../repository/validation/index.js';
 import { UMB_DOCUMENT_CONFIGURATION_CONTEXT } from '../index.js';
 import { UMB_DOCUMENT_DETAIL_MODEL_VARIANT_SCAFFOLD, UMB_DOCUMENT_WORKSPACE_ALIAS } from './constants.js';
@@ -41,6 +40,7 @@ import type { UmbEntityModel } from '@umbraco-cms/backoffice/entity';
 import type { UmbVariantPropertyGuardRule } from '@umbraco-cms/backoffice/property';
 import { UMB_ACTION_EVENT_CONTEXT } from '@umbraco-cms/backoffice/action';
 import { UmbLocalizationController } from '@umbraco-cms/backoffice/localization-api';
+import { UmbPreviewRepository } from '@umbraco-cms/backoffice/preview';
 
 type ContentModel = UmbDocumentDetailModel;
 type ContentTypeModel = UmbDocumentTypeDetailModel;
@@ -337,7 +337,7 @@ export class UmbDocumentWorkspaceContext
 		}
 
 		// Get the preview URL from the server.
-		const previewRepository = new UmbDocumentPreviewRepository(this);
+		const previewRepository = new UmbPreviewRepository(this);
 		const previewUrlData = await previewRepository.getPreviewUrl(
 			unique,
 			urlProviderAlias,
diff --git a/src/Umbraco.Web.UI.Client/src/packages/preview/context/index.ts b/src/Umbraco.Web.UI.Client/src/packages/preview/context/index.ts
new file mode 100644
index 0000000000..6e256cf2a7
--- /dev/null
+++ b/src/Umbraco.Web.UI.Client/src/packages/preview/context/index.ts
@@ -0,0 +1,2 @@
+export * from './preview.context.js';
+export * from './preview.context-token.js';
diff --git a/src/Umbraco.Web.UI.Client/src/packages/preview/context/preview.context-token.ts b/src/Umbraco.Web.UI.Client/src/packages/preview/context/preview.context-token.ts
new file mode 100644
index 0000000000..1010ffeefc
--- /dev/null
+++ b/src/Umbraco.Web.UI.Client/src/packages/preview/context/preview.context-token.ts
@@ -0,0 +1,4 @@
+import type { UmbPreviewContext } from './preview.context.js';
+import { UmbContextToken } from '@umbraco-cms/backoffice/context-api';
+
+export const UMB_PREVIEW_CONTEXT = new UmbContextToken<UmbPreviewContext>('UmbPreviewContext');
diff --git a/src/Umbraco.Web.UI.Client/src/apps/preview/preview.context.ts b/src/Umbraco.Web.UI.Client/src/packages/preview/context/preview.context.ts
similarity index 65%
rename from src/Umbraco.Web.UI.Client/src/apps/preview/preview.context.ts
rename to src/Umbraco.Web.UI.Client/src/packages/preview/context/preview.context.ts
index f3f13c9fde..de4b0267c7 100644
--- a/src/Umbraco.Web.UI.Client/src/apps/preview/preview.context.ts
+++ b/src/Umbraco.Web.UI.Client/src/packages/preview/context/preview.context.ts
@@ -1,10 +1,8 @@
-import { tryExecute } from '@umbraco-cms/backoffice/resources';
-import { DocumentService } from '@umbraco-cms/backoffice/external/backend-api';
+import { UmbPreviewRepository } from '../repository/index.js';
+import { UMB_PREVIEW_CONTEXT } from './preview.context-token.js';
 import { HubConnectionBuilder } from '@umbraco-cms/backoffice/external/signalr';
 import { UmbBooleanState, UmbStringState } from '@umbraco-cms/backoffice/observable-api';
 import { UmbContextBase } from '@umbraco-cms/backoffice/class-api';
-import { UmbContextToken } from '@umbraco-cms/backoffice/context-api';
-import { UmbDocumentPreviewRepository } from '@umbraco-cms/backoffice/document';
 import { UmbLocalizationController } from '@umbraco-cms/backoffice/localization-api';
 import { UMB_NOTIFICATION_CONTEXT } from '@umbraco-cms/backoffice/notification';
 import { UMB_SERVER_CONTEXT } from '@umbraco-cms/backoffice/server';
@@ -12,11 +10,11 @@ import type { HubConnection } from '@umbraco-cms/backoffice/external/signalr';
 import type { UmbControllerHost } from '@umbraco-cms/backoffice/controller-api';
 
 interface UmbPreviewIframeArgs {
-	className?: string;
 	culture?: string;
 	height?: string;
 	segment?: string;
 	width?: string;
+	wrapperClass?: string;
 }
 
 interface UmbPreviewUrlArgs {
@@ -28,11 +26,18 @@ interface UmbPreviewUrlArgs {
 }
 
 export class UmbPreviewContext extends UmbContextBase {
-	#unique?: string | null;
-	#culture?: string | null;
-	#segment?: string | null;
-	#serverUrl: string = '';
 	#connection?: HubConnection;
+	#currentArgs: UmbPreviewIframeArgs = {};
+	#notificationContext?: typeof UMB_NOTIFICATION_CONTEXT.TYPE;
+	#resizeController?: AbortController;
+	#serverUrl: string = '';
+
+	#previewRepository = new UmbPreviewRepository(this);
+
+	#localize = new UmbLocalizationController(this);
+
+	#culture = new UmbStringState(undefined);
+	public readonly culture = this.#culture.asObservable();
 
 	#iframeReady = new UmbBooleanState(false);
 	public readonly iframeReady = this.#iframeReady.asObservable();
@@ -40,27 +45,31 @@ export class UmbPreviewContext extends UmbContextBase {
 	#previewUrl = new UmbStringState(undefined);
 	public readonly previewUrl = this.#previewUrl.asObservable();
 
-	#documentPreviewRepository = new UmbDocumentPreviewRepository(this);
+	#segment = new UmbStringState(undefined);
+	public readonly segment = this.#segment.asObservable();
 
-	#notificationContext?: typeof UMB_NOTIFICATION_CONTEXT.TYPE;
-	#localize = new UmbLocalizationController(this);
+	#unique = new UmbStringState(undefined);
+	public readonly unique = this.#unique.asObservable();
 
 	constructor(host: UmbControllerHost) {
 		super(host, UMB_PREVIEW_CONTEXT);
 
-		this.consumeContext(UMB_SERVER_CONTEXT, (instance) => {
+		this.consumeContext(UMB_SERVER_CONTEXT, (serverContext) => {
 			const params = new URLSearchParams(window.location.search);
 
-			this.#unique = params.get('id');
-			this.#culture = params.get('culture');
-			this.#segment = params.get('segment');
-
-			if (!this.#unique) {
+			if (!params.has('id')) {
 				console.error('No unique ID found in query string.');
 				return;
 			}
 
-			const serverUrl = instance?.getServerUrl();
+			this.#unique.setValue(params.get('id') ?? undefined);
+			this.#culture.setValue(params.get('culture') ?? undefined);
+			this.#segment.setValue(params.get('segment') ?? undefined);
+
+			this.#currentArgs.culture = this.#culture.getValue();
+			this.#currentArgs.segment = this.#segment.getValue();
+
+			const serverUrl = serverContext?.getServerUrl();
 
 			if (!serverUrl) {
 				console.error('No server URL found in context');
@@ -74,11 +83,24 @@ export class UmbPreviewContext extends UmbContextBase {
 			this.#initHubConnection(serverUrl);
 		});
 
-		this.consumeContext(UMB_NOTIFICATION_CONTEXT, (instance) => {
-			this.#notificationContext = instance;
+		this.consumeContext(UMB_NOTIFICATION_CONTEXT, (notificationContext) => {
+			this.#notificationContext = notificationContext;
 		});
 	}
 
+	override hostDisconnected() {
+		super.hostDisconnected();
+
+		// Clean up event listeners
+		this.#resizeController?.abort();
+
+		// Clean up SignalR connection
+		if (this.#connection) {
+			this.#connection.stop();
+			this.#connection = undefined;
+		}
+	}
+
 	async #initHubConnection(serverUrl: string) {
 		const previewHubUrl = `${serverUrl}/umbraco/PreviewHub`;
 
@@ -91,7 +113,7 @@ export class UmbPreviewContext extends UmbContextBase {
 		this.#connection = new HubConnectionBuilder().withUrl(previewHubUrl).build();
 
 		this.#connection.on('refreshed', (payload) => {
-			if (payload === this.#unique) {
+			if (payload === this.#unique.getValue()) {
 				this.#setPreviewUrl({ rnd: Math.random() });
 			}
 		});
@@ -119,13 +141,11 @@ export class UmbPreviewContext extends UmbContextBase {
 	}
 
 	async #getPublishedUrl(): Promise<string | null> {
-		if (!this.#unique) return null;
+		const unique = this.#unique.getValue();
+		if (!unique) return null;
 
-		// NOTE: We should be reusing `UmbDocumentUrlRepository` here, but the preview app doesn't register the `itemStore` extensions, so can't resolve/consume `UMB_DOCUMENT_URL_STORE_CONTEXT`. [LK]
-		const { data } = await tryExecute(this, DocumentService.getDocumentUrls({ query: { id: [this.#unique] } }));
-
-		if (!data?.length) return null;
-		const urlInfo = this.#culture ? data[0].urlInfos.find((x) => x.culture === this.#culture) : data[0].urlInfos[0];
+		const culture = this.#culture.getValue();
+		const urlInfo = await this.#previewRepository.getPublishedUrl(unique, culture);
 
 		if (!urlInfo?.url) return null;
 		return urlInfo.url.startsWith('/') ? `${this.#serverUrl}${urlInfo.url}` : urlInfo.url;
@@ -133,7 +153,7 @@ export class UmbPreviewContext extends UmbContextBase {
 
 	#setPreviewUrl(args?: UmbPreviewUrlArgs) {
 		const host = args?.serverUrl || this.#serverUrl;
-		const unique = args?.unique || this.#unique;
+		const unique = args?.unique || this.#unique.getValue();
 
 		if (!unique) {
 			throw new Error('No unique ID found in query string.');
@@ -142,8 +162,8 @@ export class UmbPreviewContext extends UmbContextBase {
 		const url = new URL(unique, host);
 		const params = new URLSearchParams(url.search);
 
-		const culture = args?.culture || this.#culture;
-		const segment = args?.segment || this.#segment;
+		const culture = args && 'culture' in args ? args.culture : this.#culture.getValue();
+		const segment = args && 'segment' in args ? args.segment : this.#segment.getValue();
 
 		const cultureParam = 'culture';
 		const rndParam = 'rnd';
@@ -151,8 +171,10 @@ export class UmbPreviewContext extends UmbContextBase {
 
 		if (culture) {
 			params.set(cultureParam, culture);
+			this.#culture.setValue(culture);
 		} else {
 			params.delete(cultureParam);
+			this.#culture.setValue(undefined);
 		}
 
 		if (args?.rnd) {
@@ -163,8 +185,10 @@ export class UmbPreviewContext extends UmbContextBase {
 
 		if (segment) {
 			params.set(segmentParam, segment);
+			this.#segment.setValue(segment);
 		} else {
 			params.delete(segmentParam);
+			this.#segment.setValue(undefined);
 		}
 
 		const previewUrl = new URL(`${url.pathname}?${params.toString()}`, host);
@@ -174,7 +198,7 @@ export class UmbPreviewContext extends UmbContextBase {
 	}
 
 	async exitPreview() {
-		await this.#documentPreviewRepository.exit();
+		await this.#previewRepository.exit();
 
 		if (this.#connection) {
 			await this.#connection.stop();
@@ -193,6 +217,35 @@ export class UmbPreviewContext extends UmbContextBase {
 	iframeLoaded(iframe: HTMLIFrameElement) {
 		if (!iframe) return;
 		this.#iframeReady.setValue(true);
+		this.#setupScaling();
+	}
+
+	#setupScaling() {
+		// Clean up old event listeners before adding new ones
+		this.#resizeController?.abort();
+		this.#resizeController = new AbortController();
+		const signal = this.#resizeController.signal;
+
+		const wrapper = this.getIFrameWrapper();
+		if (!wrapper) return;
+
+		const scaleIFrame = () => {
+			if (wrapper.className === 'fullsize') {
+				wrapper.style.transform = '';
+			} else {
+				const wScale = document.body.offsetWidth / (wrapper.offsetWidth + 30);
+				const hScale = document.body.offsetHeight / (wrapper.offsetHeight + 30);
+				const scale = Math.min(wScale, hScale, 1);
+				wrapper.style.transform = `scale(${scale})`;
+			}
+		};
+
+		// Set up listeners once per iframe load
+		window.addEventListener('resize', scaleIFrame, { signal });
+		wrapper.addEventListener('transitionend', scaleIFrame, { signal });
+
+		// Initial scale
+		scaleIFrame();
 	}
 
 	getIFrameWrapper(): HTMLElement | undefined {
@@ -216,41 +269,32 @@ export class UmbPreviewContext extends UmbContextBase {
 		document.location.reload();
 	}
 
-	#currentArgs: UmbPreviewIframeArgs = {};
 	async updateIFrame(args?: UmbPreviewIframeArgs) {
 		const mergedArgs = { ...this.#currentArgs, ...args };
 
 		const wrapper = this.getIFrameWrapper();
 		if (!wrapper) return;
 
-		const scaleIFrame = () => {
-			if (wrapper.className === 'fullsize') {
-				wrapper.style.transform = '';
-			} else {
-				const wScale = document.body.offsetWidth / (wrapper.offsetWidth + 30);
-				const hScale = document.body.offsetHeight / (wrapper.offsetHeight + 30);
-				const scale = Math.min(wScale, hScale, 1); // get the lowest ratio, but not higher than 1
-				wrapper.style.transform = `scale(${scale})`;
-			}
-		};
+		// Check if URL will change (culture or segment changed)
+		const urlWillChange =
+			(args?.culture !== undefined && mergedArgs.culture !== this.#currentArgs.culture) ||
+			(args?.segment !== undefined && mergedArgs.segment !== this.#currentArgs.segment);
 
-		window.addEventListener('resize', scaleIFrame);
-		wrapper.addEventListener('transitionend', scaleIFrame);
-
-		this.#iframeReady.setValue(false);
+		// Only show loading spinner if iframe will reload
+		if (urlWillChange) {
+			this.#iframeReady.setValue(false);
+		}
 
 		const params = new URLSearchParams(window.location.search);
 
+		params.delete('culture');
 		if (mergedArgs.culture) {
 			params.set('culture', mergedArgs.culture);
-		} else {
-			params.delete('culture');
 		}
 
+		params.delete('segment');
 		if (mergedArgs.segment) {
 			params.set('segment', mergedArgs.segment);
-		} else {
-			params.delete('segment');
 		}
 
 		const newRelativePathQuery = window.location.pathname + '?' + params.toString();
@@ -260,10 +304,8 @@ export class UmbPreviewContext extends UmbContextBase {
 
 		this.#setPreviewUrl({ culture: mergedArgs.culture, segment: mergedArgs.segment });
 
-		if (mergedArgs.className) wrapper.className = mergedArgs.className;
+		if (mergedArgs.wrapperClass) wrapper.className = mergedArgs.wrapperClass;
 		if (mergedArgs.height) wrapper.style.height = mergedArgs.height;
 		if (mergedArgs.width) wrapper.style.width = mergedArgs.width;
 	}
 }
-
-export const UMB_PREVIEW_CONTEXT = new UmbContextToken<UmbPreviewContext>('UmbPreviewContext');
diff --git a/src/Umbraco.Web.UI.Client/src/packages/preview/index.ts b/src/Umbraco.Web.UI.Client/src/packages/preview/index.ts
new file mode 100644
index 0000000000..b8e135f982
--- /dev/null
+++ b/src/Umbraco.Web.UI.Client/src/packages/preview/index.ts
@@ -0,0 +1,2 @@
+export * from './context/index.js';
+export * from './repository/index.js';
diff --git a/src/Umbraco.Web.UI.Client/src/packages/preview/manifests.ts b/src/Umbraco.Web.UI.Client/src/packages/preview/manifests.ts
new file mode 100644
index 0000000000..5a50cd3e0c
--- /dev/null
+++ b/src/Umbraco.Web.UI.Client/src/packages/preview/manifests.ts
@@ -0,0 +1,4 @@
+import { manifests as previewApps } from './preview-apps/manifests.js';
+import type { UmbExtensionManifestKind } from '@umbraco-cms/backoffice/extension-registry';
+
+export const manifests: Array<UmbExtensionManifest | UmbExtensionManifestKind> = [...previewApps];
diff --git a/src/Umbraco.Web.UI.Client/src/packages/preview/package.json b/src/Umbraco.Web.UI.Client/src/packages/preview/package.json
new file mode 100644
index 0000000000..1949079ee4
--- /dev/null
+++ b/src/Umbraco.Web.UI.Client/src/packages/preview/package.json
@@ -0,0 +1,8 @@
+{
+	"name": "@umbraco-backoffice/preview",
+	"private": true,
+	"type": "module",
+	"scripts": {
+		"build": "vite build"
+	}
+}
diff --git a/src/Umbraco.Web.UI.Client/src/apps/preview/apps/manifests.ts b/src/Umbraco.Web.UI.Client/src/packages/preview/preview-apps/manifests.ts
similarity index 76%
rename from src/Umbraco.Web.UI.Client/src/apps/preview/apps/manifests.ts
rename to src/Umbraco.Web.UI.Client/src/packages/preview/preview-apps/manifests.ts
index b9c2126a96..9f84f0659b 100644
--- a/src/Umbraco.Web.UI.Client/src/apps/preview/apps/manifests.ts
+++ b/src/Umbraco.Web.UI.Client/src/packages/preview/preview-apps/manifests.ts
@@ -1,6 +1,4 @@
-import type { ManifestPreviewAppProvider } from '@umbraco-cms/backoffice/extension-registry';
-
-export const manifests: Array<ManifestPreviewAppProvider> = [
+export const manifests: Array<UmbExtensionManifest> = [
 	{
 		type: 'previewApp',
 		alias: 'Umb.PreviewApps.Device',
@@ -13,14 +11,21 @@ export const manifests: Array<ManifestPreviewAppProvider> = [
 		alias: 'Umb.PreviewApps.Culture',
 		name: 'Preview: Culture Switcher',
 		element: () => import('./preview-culture.element.js'),
-		weight: 300,
+		weight: 310,
 	},
 	{
 		type: 'previewApp',
 		alias: 'Umb.PreviewApps.Segment',
 		name: 'Preview: Segment Switcher',
 		element: () => import('./preview-segment.element.js'),
-		weight: 290,
+		weight: 300,
+	},
+	{
+		type: 'previewApp',
+		alias: 'Umb.PreviewApps.Environments',
+		name: 'Preview: Environments Menu',
+		element: () => import('./preview-environments.element.js'),
+		weight: 210,
 	},
 	{
 		type: 'previewApp',
diff --git a/src/Umbraco.Web.UI.Client/src/apps/preview/apps/preview-culture.element.ts b/src/Umbraco.Web.UI.Client/src/packages/preview/preview-apps/preview-culture.element.ts
similarity index 66%
rename from src/Umbraco.Web.UI.Client/src/apps/preview/apps/preview-culture.element.ts
rename to src/Umbraco.Web.UI.Client/src/packages/preview/preview-apps/preview-culture.element.ts
index 3fd66910ed..fd7f9fa756 100644
--- a/src/Umbraco.Web.UI.Client/src/apps/preview/apps/preview-culture.element.ts
+++ b/src/Umbraco.Web.UI.Client/src/packages/preview/preview-apps/preview-culture.element.ts
@@ -1,25 +1,39 @@
-import { UMB_PREVIEW_CONTEXT } from '../preview.context.js';
-import { css, customElement, html, nothing, repeat, state } from '@umbraco-cms/backoffice/external/lit';
+import { UMB_PREVIEW_CONTEXT } from '../context/preview.context-token.js';
+import type { UmbPopoverToggleEvent } from './types.js';
+import { css, customElement, html, nothing, query, repeat, state } from '@umbraco-cms/backoffice/external/lit';
 import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element';
 import { UmbLanguageCollectionRepository } from '@umbraco-cms/backoffice/language';
 import type { UmbLanguageDetailModel } from '@umbraco-cms/backoffice/language';
+import type { UUIPopoverContainerElement } from '@umbraco-cms/backoffice/external/uui';
 
 @customElement('umb-preview-culture')
 export class UmbPreviewCultureElement extends UmbLitElement {
 	#languageRepository = new UmbLanguageCollectionRepository(this);
 
+	@query('#cultures-popover')
+	private _popoverElement?: UUIPopoverContainerElement;
+
 	@state()
 	private _culture?: UmbLanguageDetailModel;
 
 	@state()
 	private _cultures: Array<UmbLanguageDetailModel> = [];
 
-	override connectedCallback() {
-		super.connectedCallback();
-		this.#getCultures();
+	@state()
+	private _popoverOpen = false;
+
+	constructor() {
+		super();
+		this.addEventListener('blur', this.#onBlur, true); // Use capture phase to catch blur events
 	}
 
-	async #getCultures() {
+	override connectedCallback() {
+		super.connectedCallback();
+		this.hidden = true;
+		this.#loadCultures();
+	}
+
+	async #loadCultures() {
 		const { data: langauges } = await this.#languageRepository.requestCollection({ skip: 0, take: 100 });
 		this._cultures = langauges?.items ?? [];
 
@@ -29,6 +43,8 @@ export class UmbPreviewCultureElement extends UmbLitElement {
 		if (culture && culture !== this._culture?.unique) {
 			this._culture = this._cultures.find((c) => c.unique === culture);
 		}
+
+		this.hidden = !this._cultures.length;
 	}
 
 	async #onClick(culture: UmbLanguageDetailModel) {
@@ -37,8 +53,20 @@ export class UmbPreviewCultureElement extends UmbLitElement {
 
 		const previewContext = await this.getContext(UMB_PREVIEW_CONTEXT);
 		previewContext?.updateIFrame({ culture: culture.unique });
+
+		this._popoverElement?.hidePopover();
 	}
 
+	#onPopoverToggle(event: UmbPopoverToggleEvent) {
+		this._popoverOpen = event.newState === 'open';
+	}
+
+	#onBlur = () => {
+		if (this._popoverOpen) {
+			this._popoverElement?.hidePopover();
+		}
+	};
+
 	override render() {
 		if (this._cultures.length <= 1) return nothing;
 		return html`
@@ -47,8 +75,9 @@ export class UmbPreviewCultureElement extends UmbLitElement {
 					<uui-icon name="icon-globe"></uui-icon>
 					<span>${this._culture?.name ?? this.localize.term('treeHeaders_languages')}</span>
 				</div>
+				<uui-symbol-expand slot="extra" id="expand-symbol" .open=${this._popoverOpen}></uui-symbol-expand>
 			</uui-button>
-			<uui-popover-container id="cultures-popover" placement="top-end">
+			<uui-popover-container id="cultures-popover" placement="top-end" @toggle=${this.#onPopoverToggle}>
 				<umb-popover-layout>
 					${repeat(
 						this._cultures,
@@ -75,12 +104,26 @@ export class UmbPreviewCultureElement extends UmbLitElement {
 				--uui-button-font-weight: 400;
 				--uui-button-padding-left-factor: 3;
 				--uui-button-padding-right-factor: 3;
+				--uui-menu-item-flat-structure: 1;
+			}
+
+			:host([hidden]) {
+				display: none;
+			}
+
+			#expand-symbol {
+				transform: rotate(-90deg);
+				margin-left: var(--uui-size-space-3, 9px);
+
+				&[open] {
+					transform: rotate(0deg);
+				}
 			}
 
 			uui-button > div {
 				display: flex;
 				align-items: center;
-				gap: 5px;
+				gap: var(--uui-size-2, 6px);
 			}
 
 			umb-popover-layout {
diff --git a/src/Umbraco.Web.UI.Client/src/apps/preview/apps/preview-device.element.ts b/src/Umbraco.Web.UI.Client/src/packages/preview/preview-apps/preview-device.element.ts
similarity index 57%
rename from src/Umbraco.Web.UI.Client/src/apps/preview/apps/preview-device.element.ts
rename to src/Umbraco.Web.UI.Client/src/packages/preview/preview-apps/preview-device.element.ts
index 92cb0412b1..bb0a24baf1 100644
--- a/src/Umbraco.Web.UI.Client/src/apps/preview/apps/preview-device.element.ts
+++ b/src/Umbraco.Web.UI.Client/src/packages/preview/preview-apps/preview-device.element.ts
@@ -1,65 +1,66 @@
-import { UMB_PREVIEW_CONTEXT } from '../preview.context.js';
-import { css, customElement, html, property, repeat } from '@umbraco-cms/backoffice/external/lit';
+import { UMB_PREVIEW_CONTEXT } from '../context/preview.context-token.js';
+import type { UmbPopoverToggleEvent } from './types.js';
+import { css, customElement, html, ifDefined, property, query, repeat, state } from '@umbraco-cms/backoffice/external/lit';
 import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element';
+import type { UUIPopoverContainerElement } from '@umbraco-cms/backoffice/external/uui';
 
 export interface UmbPreviewDevice {
 	alias: string;
 	label: string;
-	css: string;
 	icon: string;
+	iconClass?: string;
 	dimensions: { height: string; width: string };
 }
 
 @customElement('umb-preview-device')
 export class UmbPreviewDeviceElement extends UmbLitElement {
+	@query('#devices-popover')
+	private _popoverElement?: UUIPopoverContainerElement;
+
+	// TODO: [LK] Eventually, convert these devices to be an  extension point.
 	#devices: Array<UmbPreviewDevice> = [
 		{
 			alias: 'fullsize',
 			label: 'Fit browser',
-			css: 'fullsize',
 			icon: 'icon-application-window-alt',
 			dimensions: { height: '100%', width: '100%' },
 		},
 		{
 			alias: 'desktop',
 			label: 'Desktop',
-			css: 'desktop shadow',
 			icon: 'icon-display',
 			dimensions: { height: '1080px', width: '1920px' },
 		},
 		{
 			alias: 'laptop',
 			label: 'Laptop',
-			css: 'laptop shadow',
 			icon: 'icon-laptop',
 			dimensions: { height: '768px', width: '1366px' },
 		},
 		{
 			alias: 'ipad-portrait',
 			label: 'Tablet portrait',
-			css: 'ipad-portrait shadow',
 			icon: 'icon-ipad',
 			dimensions: { height: '929px', width: '769px' },
 		},
 		{
 			alias: 'ipad-landscape',
 			label: 'Tablet landscape',
-			css: 'ipad-landscape shadow flip',
 			icon: 'icon-ipad',
+			iconClass: 'flip',
 			dimensions: { height: '675px', width: '1024px' },
 		},
 		{
 			alias: 'smartphone-portrait',
 			label: 'Smartphone portrait',
-			css: 'smartphone-portrait shadow',
 			icon: 'icon-iphone',
 			dimensions: { height: '640px', width: '360px' },
 		},
 		{
 			alias: 'smartphone-landscape',
 			label: 'Smartphone landscape',
-			css: 'smartphone-landscape shadow flip',
 			icon: 'icon-iphone',
+			iconClass: 'flip',
 			dimensions: { height: '360px', width: '640px' },
 		},
 	];
@@ -67,44 +68,68 @@ export class UmbPreviewDeviceElement extends UmbLitElement {
 	@property({ attribute: false, type: Object })
 	device = this.#devices[0];
 
-	override connectedCallback() {
-		super.connectedCallback();
-		this.#changeDevice(this.device);
+	@state()
+	private _popoverOpen = false;
+
+	constructor() {
+		super();
+		this.addEventListener('blur', this.#onBlur, true); // Use capture phase to catch blur events
 	}
 
-	async #changeDevice(device: UmbPreviewDevice) {
+	override connectedCallback() {
+		super.connectedCallback();
+		this.hidden = true;
+		this.#loadDevices();
+	}
+
+	async #loadDevices() {
+		// TODO: [LK] Eventually, load devices from extension points.
+		this.hidden = false;
+	}
+
+	async #onClick(device: UmbPreviewDevice) {
 		if (device === this.device) return;
 
 		this.device = device;
 
 		const previewContext = await this.getContext(UMB_PREVIEW_CONTEXT);
 
-		previewContext?.updateIFrame({
-			className: device.css,
+		await previewContext?.updateIFrame({
+			wrapperClass: device.alias,
 			height: device.dimensions.height,
 			width: device.dimensions.width,
 		});
+
+		// Don't close popover for device selector - users often want to quickly test multiple devices
 	}
 
+	#onPopoverToggle(event: UmbPopoverToggleEvent) {
+		this._popoverOpen = event.newState === 'open';
+	}
+
+	#onBlur = () => {
+		if (this._popoverOpen) {
+			this._popoverElement?.hidePopover();
+		}
+	};
+
 	override render() {
 		return html`
 			<uui-button look="primary" popovertarget="devices-popover">
 				<div>
-					<uui-icon name=${this.device.icon} class=${this.device.css.includes('flip') ? 'flip' : ''}></uui-icon>
+					<uui-icon name=${this.device.icon} class=${ifDefined(this.device.iconClass)}></uui-icon>
 					<span>${this.device.label}</span>
 				</div>
+				<uui-symbol-expand slot="extra" id="expand-symbol" .open=${this._popoverOpen}></uui-symbol-expand>
 			</uui-button>
-			<uui-popover-container id="devices-popover" placement="top-end">
+			<uui-popover-container id="devices-popover" placement="top-end" @toggle=${this.#onPopoverToggle}>
 				<umb-popover-layout>
 					${repeat(
 						this.#devices,
 						(item) => item.alias,
 						(item) => html`
-							<uui-menu-item
-								label=${item.label}
-								?active=${item === this.device}
-								@click=${() => this.#changeDevice(item)}>
-								<uui-icon slot="icon" name=${item.icon} class=${item.css.includes('flip') ? 'flip' : ''}></uui-icon>
+							<uui-menu-item label=${item.label} ?active=${item === this.device} @click=${() => this.#onClick(item)}>
+								<uui-icon slot="icon" name=${item.icon} class=${ifDefined(item.iconClass)}></uui-icon>
 							</uui-menu-item>
 						`,
 					)}
@@ -121,12 +146,30 @@ export class UmbPreviewDeviceElement extends UmbLitElement {
 				--uui-button-font-weight: 400;
 				--uui-button-padding-left-factor: 3;
 				--uui-button-padding-right-factor: 3;
+				--uui-menu-item-flat-structure: 1;
+			}
+
+			:host([hidden]) {
+				display: none;
+			}
+
+			#expand-symbol {
+				transform: rotate(-90deg);
+				margin-left: var(--uui-size-space-3, 9px);
+
+				&[open] {
+					transform: rotate(0deg);
+				}
 			}
 
 			uui-button > div {
 				display: flex;
 				align-items: center;
-				gap: 5px;
+				gap: var(--uui-size-2, 6px);
+			}
+
+			uui-icon.flip {
+				transform: rotate(90deg);
 			}
 
 			umb-popover-layout {
diff --git a/src/Umbraco.Web.UI.Client/src/packages/preview/preview-apps/preview-environments.element.ts b/src/Umbraco.Web.UI.Client/src/packages/preview/preview-apps/preview-environments.element.ts
new file mode 100644
index 0000000000..8b0bf0452a
--- /dev/null
+++ b/src/Umbraco.Web.UI.Client/src/packages/preview/preview-apps/preview-environments.element.ts
@@ -0,0 +1,170 @@
+import { UmbPreviewRepository } from '../repository/preview.repository.js';
+import { UMB_PREVIEW_CONTEXT } from '../context/preview.context-token.js';
+import { css, customElement, html, nothing, repeat, state } from '@umbraco-cms/backoffice/external/lit';
+import { umbExtensionsRegistry } from '@umbraco-cms/backoffice/extension-registry';
+import { umbPeekError } from '@umbraco-cms/backoffice/notification';
+import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element';
+import type { UmbPopoverToggleEvent } from './types.js';
+
+type UmbPreviewEnvironmentItem = {
+	alias: string;
+	label: string;
+	icon: string;
+	urlProviderAlias?: string;
+};
+
+@customElement('umb-preview-environments')
+export class UmbPreviewEnvironmentsElement extends UmbLitElement {
+	#fallbackIcon = 'icon-multiple-windows';
+
+	@state()
+	private _culture?: string;
+
+	@state()
+	private _items: Array<UmbPreviewEnvironmentItem> = [];
+
+	@state()
+	private _popoverOpen = false;
+
+	@state()
+	private _segment?: string;
+
+	@state()
+	private _unique?: string;
+
+	#previewRepository = new UmbPreviewRepository(this);
+
+	constructor() {
+		super();
+
+		this.consumeContext(UMB_PREVIEW_CONTEXT, (context) => {
+			this.observe(context?.unique, (unique) => (this._unique = unique), '_observeUnique');
+			this.observe(context?.culture, (culture) => (this._culture = culture), '_observeCulture');
+			this.observe(context?.segment, (segment) => (this._segment = segment), '_observeSegment');
+		});
+	}
+
+	override connectedCallback() {
+		super.connectedCallback();
+		this.hidden = true;
+		this.#getPreviewOptions();
+	}
+
+	async #getPreviewOptions() {
+		this.observe(
+			umbExtensionsRegistry.byTypeAndFilter('workspaceActionMenuItem', (ext) => ext.kind === 'previewOption'),
+			(manifests) => {
+				this._items = manifests.map((manifest) => ({
+					alias: manifest.alias,
+					label: (manifest.meta as any).label || manifest.name,
+					icon: (manifest.meta as any).icon || this.#fallbackIcon,
+					urlProviderAlias: (manifest.meta as any).urlProviderAlias,
+				}));
+
+				this.hidden = !this._items.length;
+			},
+		);
+	}
+
+	async #onClick(item: UmbPreviewEnvironmentItem) {
+		if (!this._unique) return;
+		if (!item.urlProviderAlias) return;
+
+		const previewUrlData = await this.#previewRepository.getPreviewUrl(
+			this._unique,
+			item.urlProviderAlias,
+			this._culture,
+			this._segment,
+		);
+
+		if (previewUrlData.url) {
+			const previewWindow = window.open(previewUrlData.url, `umbpreview-${this._unique}`);
+			previewWindow?.focus();
+			return;
+		}
+
+		if (previewUrlData.message) {
+			umbPeekError(this, {
+				color: 'danger',
+				headline: this.localize.term('general_preview'),
+				message: previewUrlData.message,
+			});
+		}
+	}
+
+	#onPopoverToggle(event: UmbPopoverToggleEvent) {
+		this._popoverOpen = event.newState === 'open';
+	}
+
+	override render() {
+		if (!this._items.length) return nothing;
+		return html`
+			<uui-button look="primary" popovertarget="options-popover">
+				<div>
+					<uui-icon name=${this.#fallbackIcon}></uui-icon>
+					<span>Preview environments</span>
+				</div>
+				<uui-symbol-expand slot="extra" id="expand-symbol" .open=${this._popoverOpen}></uui-symbol-expand>
+			</uui-button>
+			<uui-popover-container id="options-popover" placement="top-end" @toggle=${this.#onPopoverToggle}>
+				<umb-popover-layout>
+					${repeat(
+						this._items,
+						(item) => item.alias,
+						(item) => html`
+							<uui-menu-item label=${this.localize.string(item.label)} @click=${() => this.#onClick(item)}>
+								<uui-icon slot="icon" name=${item.icon}></uui-icon>
+							</uui-menu-item>
+						`,
+					)}
+				</umb-popover-layout>
+			</uui-popover-container>
+		`;
+	}
+
+	static override styles = [
+		css`
+			:host {
+				display: flex;
+				border-left: 1px solid var(--uui-color-header-contrast);
+				--uui-button-font-weight: 400;
+				--uui-button-padding-left-factor: 3;
+				--uui-button-padding-right-factor: 3;
+				--uui-menu-item-flat-structure: 1;
+			}
+
+			:host([hidden]) {
+				display: none;
+			}
+
+			#expand-symbol {
+				transform: rotate(-90deg);
+				margin-left: var(--uui-size-space-3, 9px);
+
+				&[open] {
+					transform: rotate(0deg);
+				}
+			}
+
+			uui-button > div {
+				display: flex;
+				align-items: center;
+				gap: var(--uui-size-2, 6px);
+			}
+
+			umb-popover-layout {
+				--uui-color-surface: var(--uui-color-header-surface);
+				--uui-color-border: var(--uui-color-header-surface);
+				color: var(--uui-color-header-contrast);
+			}
+		`,
+	];
+}
+
+export { UmbPreviewEnvironmentsElement as element };
+
+declare global {
+	interface HTMLElementTagNameMap {
+		'umb-preview-environments': UmbPreviewEnvironmentsElement;
+	}
+}
diff --git a/src/Umbraco.Web.UI.Client/src/apps/preview/apps/preview-exit.element.ts b/src/Umbraco.Web.UI.Client/src/packages/preview/preview-apps/preview-exit.element.ts
similarity index 91%
rename from src/Umbraco.Web.UI.Client/src/apps/preview/apps/preview-exit.element.ts
rename to src/Umbraco.Web.UI.Client/src/packages/preview/preview-apps/preview-exit.element.ts
index c1a45b753d..80ccec9c7b 100644
--- a/src/Umbraco.Web.UI.Client/src/apps/preview/apps/preview-exit.element.ts
+++ b/src/Umbraco.Web.UI.Client/src/packages/preview/preview-apps/preview-exit.element.ts
@@ -1,4 +1,4 @@
-import { UMB_PREVIEW_CONTEXT } from '../preview.context.js';
+import { UMB_PREVIEW_CONTEXT } from '../context/preview.context-token.js';
 import { css, customElement, html } from '@umbraco-cms/backoffice/external/lit';
 import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element';
 
@@ -33,7 +33,7 @@ export class UmbPreviewExitElement extends UmbLitElement {
 			uui-button > div {
 				display: flex;
 				align-items: center;
-				gap: 5px;
+				gap: var(--uui-size-2, 6px);
 			}
 		`,
 	];
diff --git a/src/Umbraco.Web.UI.Client/src/apps/preview/apps/preview-open-website.element.ts b/src/Umbraco.Web.UI.Client/src/packages/preview/preview-apps/preview-open-website.element.ts
similarity index 91%
rename from src/Umbraco.Web.UI.Client/src/apps/preview/apps/preview-open-website.element.ts
rename to src/Umbraco.Web.UI.Client/src/packages/preview/preview-apps/preview-open-website.element.ts
index 4a77454df8..7021ad9426 100644
--- a/src/Umbraco.Web.UI.Client/src/apps/preview/apps/preview-open-website.element.ts
+++ b/src/Umbraco.Web.UI.Client/src/packages/preview/preview-apps/preview-open-website.element.ts
@@ -1,4 +1,4 @@
-import { UMB_PREVIEW_CONTEXT } from '../preview.context.js';
+import { UMB_PREVIEW_CONTEXT } from '../context/preview.context-token.js';
 import { css, customElement, html } from '@umbraco-cms/backoffice/external/lit';
 import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element';
 
@@ -33,7 +33,7 @@ export class UmbPreviewOpenWebsiteElement extends UmbLitElement {
 			uui-button > div {
 				display: flex;
 				align-items: center;
-				gap: 5px;
+				gap: var(--uui-size-2, 6px);
 			}
 		`,
 	];
diff --git a/src/Umbraco.Web.UI.Client/src/apps/preview/apps/preview-segment.element.ts b/src/Umbraco.Web.UI.Client/src/packages/preview/preview-apps/preview-segment.element.ts
similarity index 62%
rename from src/Umbraco.Web.UI.Client/src/apps/preview/apps/preview-segment.element.ts
rename to src/Umbraco.Web.UI.Client/src/packages/preview/preview-apps/preview-segment.element.ts
index dc49628d49..c3817d1d95 100644
--- a/src/Umbraco.Web.UI.Client/src/apps/preview/apps/preview-segment.element.ts
+++ b/src/Umbraco.Web.UI.Client/src/packages/preview/preview-apps/preview-segment.element.ts
@@ -1,28 +1,35 @@
-import { UMB_PREVIEW_CONTEXT } from '../preview.context.js';
-import {
-	css,
-	customElement,
-	html,
-	nothing,
-	repeat,
-	state,
-	type PropertyValues,
-} from '@umbraco-cms/backoffice/external/lit';
+import { UMB_PREVIEW_CONTEXT } from '../context/preview.context-token.js';
+import type { UmbPopoverToggleEvent } from './types.js';
+import { css, customElement, html, nothing, query, repeat, state } from '@umbraco-cms/backoffice/external/lit';
 import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element';
-import { UmbSegmentCollectionRepository, type UmbSegmentCollectionItemModel } from '@umbraco-cms/backoffice/segment';
+import { UmbSegmentCollectionRepository } from '@umbraco-cms/backoffice/segment';
+import type { UmbSegmentCollectionItemModel } from '@umbraco-cms/backoffice/segment';
+import type { UUIPopoverContainerElement } from '@umbraco-cms/backoffice/external/uui';
 
 @customElement('umb-preview-segment')
 export class UmbPreviewSegmentElement extends UmbLitElement {
 	#segmentRepository = new UmbSegmentCollectionRepository(this);
 
+	@query('#segments-popover')
+	private _popoverElement?: UUIPopoverContainerElement;
+
 	@state()
 	private _segment?: UmbSegmentCollectionItemModel;
 
 	@state()
 	private _segments: Array<UmbSegmentCollectionItemModel> = [];
 
-	protected override firstUpdated(_changedProperties: PropertyValues): void {
-		super.firstUpdated(_changedProperties);
+	@state()
+	private _popoverOpen = false;
+
+	constructor() {
+		super();
+		this.addEventListener('blur', this.#onBlur, true); // Use capture phase to catch blur events
+	}
+
+	override connectedCallback() {
+		super.connectedCallback();
+		this.hidden = true;
 		this.#loadSegments();
 	}
 
@@ -36,6 +43,8 @@ export class UmbPreviewSegmentElement extends UmbLitElement {
 		if (segment && segment !== this._segment?.unique) {
 			this._segment = this._segments.find((c) => c.unique === segment);
 		}
+
+		this.hidden = !this._segments.length;
 	}
 
 	async #onClick(segment?: UmbSegmentCollectionItemModel) {
@@ -44,8 +53,20 @@ export class UmbPreviewSegmentElement extends UmbLitElement {
 
 		const previewContext = await this.getContext(UMB_PREVIEW_CONTEXT);
 		previewContext?.updateIFrame({ segment: segment?.unique });
+
+		this._popoverElement?.hidePopover();
 	}
 
+	#onPopoverToggle(event: UmbPopoverToggleEvent) {
+		this._popoverOpen = event.newState === 'open';
+	}
+
+	#onBlur = () => {
+		if (this._popoverOpen) {
+			this._popoverElement?.hidePopover();
+		}
+	};
+
 	override render() {
 		if (!this._segments.length) return nothing;
 		return html`
@@ -54,8 +75,9 @@ export class UmbPreviewSegmentElement extends UmbLitElement {
 					<uui-icon name="icon-filter"></uui-icon>
 					<span>${this._segment?.name ?? 'Segments'}</span>
 				</div>
+				<uui-symbol-expand slot="extra" id="expand-symbol" .open=${this._popoverOpen}></uui-symbol-expand>
 			</uui-button>
-			<uui-popover-container id="segments-popover" placement="top-end">
+			<uui-popover-container id="segments-popover" placement="top-end" @toggle=${this.#onPopoverToggle}>
 				<umb-popover-layout>
 					<uui-menu-item label="Default" ?active=${!this._segment} @click=${() => this.#onClick()}></uui-menu-item>
 					${repeat(
@@ -82,12 +104,26 @@ export class UmbPreviewSegmentElement extends UmbLitElement {
 				--uui-button-font-weight: 400;
 				--uui-button-padding-left-factor: 3;
 				--uui-button-padding-right-factor: 3;
+				--uui-menu-item-flat-structure: 1;
+			}
+
+			:host([hidden]) {
+				display: none;
+			}
+
+			#expand-symbol {
+				transform: rotate(-90deg);
+				margin-left: var(--uui-size-space-3, 9px);
+
+				&[open] {
+					transform: rotate(0deg);
+				}
 			}
 
 			uui-button > div {
 				display: flex;
 				align-items: center;
-				gap: 5px;
+				gap: var(--uui-size-2, 6px);
 			}
 
 			umb-popover-layout {
diff --git a/src/Umbraco.Web.UI.Client/src/packages/preview/preview-apps/types.ts b/src/Umbraco.Web.UI.Client/src/packages/preview/preview-apps/types.ts
new file mode 100644
index 0000000000..8284655869
--- /dev/null
+++ b/src/Umbraco.Web.UI.Client/src/packages/preview/preview-apps/types.ts
@@ -0,0 +1,6 @@
+/**
+ * Custom event type for popover toggle events
+ */
+export interface UmbPopoverToggleEvent extends Event {
+	newState: string;
+}
diff --git a/src/Umbraco.Web.UI.Client/src/packages/preview/repository/index.ts b/src/Umbraco.Web.UI.Client/src/packages/preview/repository/index.ts
new file mode 100644
index 0000000000..7f9694a5bc
--- /dev/null
+++ b/src/Umbraco.Web.UI.Client/src/packages/preview/repository/index.ts
@@ -0,0 +1 @@
+export { UmbPreviewRepository } from './preview.repository.js';
diff --git a/src/Umbraco.Web.UI.Client/src/packages/preview/repository/preview.repository.ts b/src/Umbraco.Web.UI.Client/src/packages/preview/repository/preview.repository.ts
new file mode 100644
index 0000000000..c3172c6e30
--- /dev/null
+++ b/src/Umbraco.Web.UI.Client/src/packages/preview/repository/preview.repository.ts
@@ -0,0 +1,74 @@
+import { tryExecute } from '@umbraco-cms/backoffice/resources';
+import { DocumentService, PreviewService } from '@umbraco-cms/backoffice/external/backend-api';
+import { UmbRepositoryBase } from '@umbraco-cms/backoffice/repository';
+import type { DocumentUrlInfoModel } from '@umbraco-cms/backoffice/external/backend-api';
+import type { UmbControllerHost } from '@umbraco-cms/backoffice/controller-api';
+
+export class UmbPreviewRepository extends UmbRepositoryBase {
+	constructor(host: UmbControllerHost) {
+		super(host);
+	}
+
+	/**
+	 * Gets the preview URL for a document.
+	 * @param {string} unique The unique identifier of the document.
+	 * @param {string} providerAlias The alias of the URL provider registered on the server.
+	 * @param {string | undefined} culture The culture to preview (undefined means invariant).
+	 * @param {string | undefined} segment The segment to preview (undefined means no specific segment).
+	 * @returns {DocumentUrlInfoModel} The preview URLs of the document.
+	 * @memberof UmbPreviewRepository
+	 */
+	async getPreviewUrl(
+		unique: string,
+		providerAlias: string,
+		culture?: string,
+		segment?: string,
+	): Promise<DocumentUrlInfoModel> {
+		const { data, error } = await tryExecute(
+			this,
+			DocumentService.getDocumentByIdPreviewUrl({
+				path: { id: unique },
+				query: { providerAlias, culture, segment },
+			}),
+		);
+
+		if (error) {
+			throw new Error(error.message);
+		}
+
+		return data;
+	}
+
+	/**
+	 * Gets the published URL info for a document.
+	 * @param {string} unique The unique identifier of the document.
+	 * @param {string | undefined} culture The culture to preview (undefined means invariant).
+	 * @returns {DocumentUrlInfoModel} The published URL info of the document.
+	 * @memberof UmbPreviewRepository
+	 */
+	async getPublishedUrl(unique: string, culture?: string): Promise<DocumentUrlInfoModel | null | undefined> {
+		if (!unique) return null;
+
+		const { data, error } = await tryExecute(this, DocumentService.getDocumentUrls({ query: { id: [unique] } }));
+
+		if (error) {
+			throw new Error(error.message);
+		}
+
+		if (!data?.length) return null;
+
+		// TODO: [LK] Review the logic here, unsure whether this is correct. When will the array have more than one item?
+		const urlInfo = culture ? data[0].urlInfos.find((x) => x.culture === culture) : data[0].urlInfos[0];
+		return urlInfo;
+	}
+
+	/**
+	 * Exits preview mode.
+	 * @returns {Promise<void>}
+	 * @memberof UmbPreviewRepository
+	 */
+	async exit(): Promise<void> {
+		await tryExecute(this, PreviewService.deletePreview(), { disableNotifications: true });
+		return;
+	}
+}
diff --git a/src/Umbraco.Web.UI.Client/src/packages/preview/umbraco-package.ts b/src/Umbraco.Web.UI.Client/src/packages/preview/umbraco-package.ts
new file mode 100644
index 0000000000..b86e47d21b
--- /dev/null
+++ b/src/Umbraco.Web.UI.Client/src/packages/preview/umbraco-package.ts
@@ -0,0 +1,9 @@
+export const name = 'Umbraco.Core.Preview';
+export const extensions = [
+	{
+		name: 'Preview Bundle',
+		alias: 'Umb.Bundle.Preview',
+		type: 'bundle',
+		js: () => import('./manifests.js'),
+	},
+];
diff --git a/src/Umbraco.Web.UI.Client/src/packages/preview/vite.config.ts b/src/Umbraco.Web.UI.Client/src/packages/preview/vite.config.ts
new file mode 100644
index 0000000000..c667d802ca
--- /dev/null
+++ b/src/Umbraco.Web.UI.Client/src/packages/preview/vite.config.ts
@@ -0,0 +1,12 @@
+import { defineConfig } from 'vite';
+import { rmSync } from 'fs';
+import { getDefaultConfig } from '../../vite-config-base';
+
+const dist = '../../../dist-cms/packages/preview';
+
+// delete the unbundled dist folder
+rmSync(dist, { recursive: true, force: true });
+
+export default defineConfig({
+	...getDefaultConfig({ dist }),
+});
diff --git a/src/Umbraco.Web.UI.Client/tsconfig.json b/src/Umbraco.Web.UI.Client/tsconfig.json
index e1928fbeec..16c2d20bec 100644
--- a/src/Umbraco.Web.UI.Client/tsconfig.json
+++ b/src/Umbraco.Web.UI.Client/tsconfig.json
@@ -114,6 +114,7 @@ DON'T EDIT THIS FILE DIRECTLY. It is generated by /devops/tsconfig/index.js
 			"@umbraco-cms/backoffice/picker-input": ["./src/packages/core/picker-input/index.ts"],
 			"@umbraco-cms/backoffice/picker-data-source": ["./src/packages/core/picker-data-source/index.ts"],
 			"@umbraco-cms/backoffice/picker": ["./src/packages/core/picker/index.ts"],
+			"@umbraco-cms/backoffice/preview": ["./src/packages/preview/index.ts"],
 			"@umbraco-cms/backoffice/property-action": ["./src/packages/core/property-action/index.ts"],
 			"@umbraco-cms/backoffice/property-editor-data-source": [
 				"./src/packages/core/property-editor-data-source/index.ts"