@iebh/tera-fy 1.0.16 → 1.0.18

package/lib/terafy.server.js

@@ -1,7 +1,8 @@
-import {cloneDeep, has as pathExists, set as pathSet} from 'lodash-es';
+import {cloneDeep, has as pathExists, get as pathGet, set as pathSet} from 'lodash-es';
 import {diffApply, jsonPatchPathConverter as jsPatchConverter} from 'just-diff-apply';
-import {nanoid} from 'nanoid';
 import mixin from '#utils/mixin';
+import {nanoid} from 'nanoid';
+import promiseDefer from '#utils/pDefer';
 import Reflib from '@iebh/reflib';
 
 /**
@@ -21,7 +22,9 @@ export default class TeraFyServer {
 	* @property {Number} subscribeTimeout Acceptable timeout period for subscribers to acklowledge a project change event, failing to respond will result in the subscriber being removed from the available subscriber list
 	* @property {String} restrictOrigin URL to restrict communications to
 	* @property {String} projectId The project to use as the default reference when calling various APIs
-	* @property {Number} The current server mode matching `SERVERMODE_*`
+	* @property {Number} serverMode The current server mode matching `SERVERMODE_*`
+	* @property {String} siteUrl The main site absolute URL
+	* @property {String} sitePathLogin Either an absolute URL or the relative path (taken from `siteUrl`) when trying to log in the user
 	*/
 	settings = {
 		devMode: false,
@@ -29,12 +32,15 @@ export default class TeraFyServer {
 		subscribeTimeout: 2000,
 		projectId: null,
 		serverMode: 0,
+		siteUrl: window.location.href,
+		sitePathLogin: '/login',
 	};
 
 	static SERVERMODE_NONE = 0;
 	static SERVERMODE_EMBEDDED = 1;
-	static SERVERMODE_WINDOW = 2;
-	static SERVERMODE_TERA = 3; // Terafy is running as the main TERA site
+	static SERVERMODE_FRAME = 2;
+	static SERVERMODE_POPUP = 3;
+	static SERVERMODE_TERA = 4; // Terafy is running as the main TERA site
 
 
 	// Contexts - createContext(), getClientContext(), messageEvent, senderRpc() {{{
@@ -94,7 +100,7 @@ export default class TeraFyServer {
 						}
 					},
 				});
-			case TeraFyServer.SERVERMODE_WINDOW:
+			case TeraFyServer.SERVERMODE_FRAME:
 				// Server is the top-level window so we need to send messages to an embedded iFrame
 				var iFrame = document.querySelector('iframe#external');
 				if (!iFrame) throw new Error('Cannot locate TERA-FY top-level->iFrame#external');
@@ -114,6 +120,7 @@ export default class TeraFyServer {
 						}
 					},
 				});
+			case TeraFyServer.SERVERMODE_POPUP:
 		}
 	}
 
@@ -202,10 +209,10 @@ export default class TeraFyServer {
 				TERA: 1,
 				...cloneDeep(message), // Need to clone to resolve promise nasties
 			};
-			this.debug('INFO', 'Parent send', message, '<=>', payload);
+			this.debug('INFO', 'Dispatch response', message, '<=>', payload);
 			(sendVia || globalThis.parent).postMessage(payload, this.settings.restrictOrigin);
 		} catch (e) {
-			this.debug('ERROR', 'Attempted to dispatch payload server->client', payload);
+			this.debug('ERROR', 'Attempted to dispatch response server->client', payload);
 			this.debug('ERROR', 'Message compose server->client:', e);
 		}
 	}
@@ -221,8 +228,11 @@ export default class TeraFyServer {
 			case 'embedded':
 				this.settings.serverMode = TeraFyServer.SERVERMODE_EMBEDDED;
 				break;
-			case 'window':
-				this.settings.serverMode = TeraFyServer.SERVERMODE_WINDOW;
+			case 'frame':
+				this.settings.serverMode = TeraFyServer.SERVERMODE_FRAME;
+				break;
+			case 'popup':
+				this.settings.serverMode = TeraFyServer.SERVERMODE_POPUP;
 				break;
 			default:
 				throw new Error(`Unsupported server mode "${mode}"`);
@@ -330,9 +340,17 @@ export default class TeraFyServer {
 	/**
 	* Fetch the current session user
 	*
+	* @param {Object} [options] Additional options to mutate behaviour
+	* @param {Boolean} [options.forceRetry=false] Forcabily try to refresh the user state
+	*
 	* @returns {Promise<User>} The current logged in user or null if none
 	*/
-	getUser() {
+	getUser(options) {
+		let settings = {
+			forceRetry: false,
+			...options,
+		};
+
 		let $auth = app.service('$auth');
 		let $subscriptions = app.service('$subscriptions');
 
@@ -340,7 +358,11 @@ export default class TeraFyServer {
 			$auth.promise(),
 			$subscriptions.promise(),
 		])
-			.then(()=> $auth.user.id ? {
+			.then(()=> {
+				if (!$auth.isLoggedIn && settings.forceRetry)
+					return $auth.restoreLogin();
+			})
+			.then(()=> $auth.user?.id ? {
 				id: $auth.user.id,
 				email: $auth.user.email,
 				name: [
@@ -349,6 +371,10 @@ export default class TeraFyServer {
 				].filter(Boolean).join(' '),
 				isSubscribed: $subscriptions.isSubscribed,
 			} : null)
+			.catch(e => {
+				console.warn('Catch', e);
+				debugger;
+			})
 	}
 
 
@@ -361,10 +387,91 @@ export default class TeraFyServer {
 	*/
 	requireUser() {
 		return this.getUser()
-			.then(user => user || this.uiAlert('You must be logged in to <a href="https://tera-tools.com" target="_blank">TERA-tools.com</a> to use this tool', {
+			.then(user => {
+				this.debug('Current user is', user ? user : 'Not valid');
+				if (user) throw 'EXIT'; // Valid user? Escape promise chain
+			})
+			.then(async ()=> { // No user present - try to validate with other methods
+				switch (this.settings.serverMode) {
+					case TeraFyServer.SERVERMODE_EMBEDDED:
+						/* - Doesn't work because Kinde sets the CSP header `frame-ancestors 'self'` which prevents usage within an iFrame
+						const $auth = app.service('$auth');
+						return this.requestFocus(()=>  $auth.login()
+							.then(()=> {
+								console.log('New user state', $auth.isLoggedIn);
+							})
+						);
+						*/
+
+						var focusContent = document.createElement('div');
+						focusContent.innerHTML = '<div>Authenticate with <a href="https://tera-tools.com" target="_blank">TERA-tools.com</a></div>'
+							+ '<div class="mt-2"><a class="btn btn-light">Open Popup...</a></div>';
+
+						// Attach click listner to internal button to re-popup the auth window (in case popups are blocked)
+						focusContent.querySelector('a.btn').addEventListener('click', ()=>
+							this.uiWindow(new URL(this.settings.sitePathLogin, this.settings.siteUrl))
+						);
+
+						// Create a deferred promise which will (eventually) resolve when the downstream window signals its ready
+						let waitOnWindowAuth = promiseDefer();
+
+						// Create a listener for the message from the downstream window to resolve the promise
+						let listenMessages = ({data}) => {
+							if (data.TERA && data.action == 'noop' && data.isLoggedIn) { // Signal sent from landing page - we're logged in, yey!
+								this.debug('Received ok message from popup window');
+								waitOnWindowAuth.resolve();
+							}
+						};
+						window.addEventListener('message', listenMessages);
+
+						// Go fullscreen, try to open the auth window + prompt the user to retry (if popups are blocked) and wait for resolution
+						await this.requestFocus(()=> {
+							// Try opening the popup automatically - this will likely fail if the user has popup blocking enabled
+							this.uiWindow(new URL(this.settings.sitePathLogin, this.settings.siteUrl));
+
+							// Display a message to the user, offering the ability to re-open the popup if it was originally denied
+							this.uiSplat(focusContent, {logo: true});
+
+							this.debug('Begin auth-check deferred wait...');
+							return waitOnWindowAuth.promise;
+						});
+
+						this.debug('Cleaning up popup auth');
+
+						// Remove message subscription
+						window.removeEventListener('message', listenMessages);
+
+						// Disable overlay content
+						this.uiSplat(false);
+
+						// Tell $auth to forcibly refresh its user data
+						await app.service('$auth').restoreLogin();
+
+						// ... then refresh the project list as we're likely going to need it
+						await app.service('$projects').refresh();
+
+						// Go back to start of auth checking loop and repull the user data
+						throw 'REDO';
+
+						break;
+					default:
+						// Pass - Implied - Cannot authenticate via other method so just fall through to scalding the user
+				}
+			})
+			.then(()=> this.uiAlert('You must be logged in to <a href="https://tera-tools.com" target="_blank">TERA-tools.com</a> to use this tool', {
 				title: 'TERA-tools account needed',
 				isHtml: true,
+				buttons: false,
 			}))
+			.then(()=> { throw 'REDO' }) // Go into loop to keep requesting user data
+			.catch(e => {
+				if (e === 'EXIT') {
+					return; // Exit with a valid user
+				} else if (e == 'REDO') {
+					return this.requireUser();
+				}
+				throw e;
+			})
 	}
 
 	// }}}
@@ -495,7 +602,7 @@ export default class TeraFyServer {
 	*
 	* @param {Object} [options] Additional options to mutate behaviour
 	* @param {String} [options.title="Select a project to work with"] The title of the dialog to display
-	* @param {Boolean} [options.allowCancel=true] Advertise cancelling the operation, the dialog can still be cancelled by closing it
+	* @param {Boolean} [options.allowCancel=true] Allow cancelling the operation, will throw `'CANCEL'` if actioned
 	* @param {Boolean} [options.setActive=false] Also set the project as active when selected
 	*
 	* @returns {Promise<Project>} The active project
@@ -526,7 +633,7 @@ export default class TeraFyServer {
 
 	// }}}
 
-	// Project State - getProjectState(), setProjectState(), saveProjectState(), replaceProjectState(), applyProjectStatePatch {{{
+	// Project State - getProjectState(), setProjectState(), saveProjectState(), replaceProjectState(), applyProjectStatePatch() {{{
 
 	/**
 	* Return the current, full snapshot state of the active project
@@ -576,16 +683,61 @@ export default class TeraFyServer {
 		if (!app.service('$projects').active) throw new Error('No active project');
 		if (typeof path != 'string' && !Array.isArray(path)) throw new Error('setProjectStateDefaults(path, value) - path must be a dotted string or array of path segments');
 
-		pathSet(app.service('$projects').active, path, value)
+		this._pathSet(app.service('$projects').active, path, value);
 
 		return (
-			this.save && this.sync ? this.saveProjectState()
-			: this.save ? void this.saveProjectState()
+			settings.save && settings.sync ? this.saveProjectState()
+			: settings.save ? void this.saveProjectState()
 			: (()=> { throw new Error('setProjectState({sync: true, save: false}) makes no sense') })()
 		);
 	}
 
 
+	/**
+	* Internal recursive path setter used by setProjectState() / setProjectStateDefaults()
+	* The implementation defaults to _.set() unless overriden by a plugin
+	*
+	* @private
+	* @param {Object} subject The base subject to operate on
+	* @param {String|Array} path The path to set in dotted or array notation
+	* @param {*} value The value to set
+	*
+	* @returns {*} The set value
+	*/
+	_pathSet(subject, path, value) {
+		return pathSet(subject, path, value);
+	}
+
+
+	/**
+	* Internal recursive path checker used by setProjectStateDefaults()
+	* The implementation defaults to _.has() unless overriden by a plugin
+	*
+	* @private
+	* @param {Object} subject The base subject to examine
+	* @param {String|Array} path The path to fetch in dotted or array notation
+	* @returns {Boolean} True if the given path already exists within the subject
+	*/
+	_pathHas(subject, path) {
+		return pathExists(subject, path);
+	}
+
+
+	/**
+	* Internal recursive path fetcher
+	* The implementation defaults to _.get() unless overriden by a plugin
+	*
+	* @private
+	* @param {Object} subject The base subject to examine
+	* @param {String|Array} path The path to fetch in dotted or array notation
+	* @param {*} [fallback] Optional fallback to return if the end point does not exist
+	* @returns {*} True if the given path already exists within the subject
+	*/
+	_pathGet(subject, path, fallback) {
+		return pathGet(subject, path, fallback);
+	}
+
+
 	/**
 	* Set a nested value within the project state - just like `setProjectState()` - but only if no value for that path exists
 	*
@@ -599,7 +751,7 @@ export default class TeraFyServer {
 	setProjectStateDefaults(path, value, options) {
 		if (!app.service('$projects').active) throw new Error('No active project');
 
-		if (!pathExists(app.service('$projects').active, path)) {
+		if (!this._pathHas(app.service('$projects').active, path)) {
 			return this.setProjectState(path, value, options)
 				.then(()=> true)
 		} else {
@@ -654,7 +806,7 @@ export default class TeraFyServer {
 	}
 	// }}}
 
-	// Project files - getProjectFiles() {{{
+	// Project files - selectProjectFile(), getProjectFiles() {{{
 
 	/**
 	* Data structure for a project file
@@ -674,6 +826,72 @@ export default class TeraFyServer {
 	* @property {String} mime The associated mime type for the file
 	*/
 
+	/**
+	* Data structure for a file filter
+	* @class FileFilters
+	*
+	* @property {Boolean} [library=false] Restrict to library files only
+	* @property {String} [filename] CSV of @momsfriendlydevco/match expressions to filter the filename by (filenames are the basename sans extension)
+	* @property {String} [basename] CSV of @momsfriendlydevco/match expressions to filter the basename by
+	* @property {String} [ext] CSV of @momsfriendlydevco/match expressions to filter the file extension by
+	*/
+
+	/**
+	* Prompt the user to select a library to operate on
+	*
+	* @param {Object} [options] Additional options to mutate behaviour
+	* @param {String} [options.title="Select a file"] The title of the dialog to display
+	* @param {String|Array<String>} [options.hint] Hints to identify the file to select in array order of preference
+	* @param {FileFilters} [options.filters] Optional file filters
+	* @param {Boolean} [options.allowUpload=true] Allow uploading new files
+	* @param {Boolean} [options.allowRefresh=true] Allow the user to manually refresh the file list
+	* @param {Boolean} [options.allowDownloadZip=true] Allow the user to download a Zip of all files
+	* @param {Boolean} [options.allowCancel=true] Allow cancelling the operation. Will throw `'CANCEL'` as the promise rejection if acationed
+	* @param {Boolean} [options.autoRequire=true] Run `requireProject()` automatically before continuing
+	* @param {FileFilters} [options.filter] Optional file filters
+	*
+	* @returns {Promise<ProjectFile>} The eventually selected file
+	*/
+	selectProjectFile(options) {
+		let settings = {
+			title: 'Select a file',
+			hint: null,
+			filters: {},
+			allowUpload: true,
+			allowRefresh: true,
+			allowDownloadZip: true,
+			allowCancel: true,
+			autoRequire: true,
+			...options,
+		};
+
+		return app.service('$projects').promise()
+			.then(()=> settings.autoRequire && this.requireProject())
+			.then(files => this.requestFocus(()=>
+				app.service('$prompt').dialog({
+					title: settings.title,
+					component: 'filesSelect',
+					componentProps: {
+						hint: settings.hint,
+						allowNavigate: false,
+						allowUpload: settings.allowUpload,
+						allowRefresh: settings.allowRefresh,
+						allowDownloadZip: settings.allowDownloadZip,
+						allowVerbs: false,
+						cardStyle: false,
+						filters: settings.filters,
+					},
+					componentEvents: {
+						fileSelect(file) {
+							app.service('$prompt').close(true, file);
+						},
+					},
+					modalDialogClass: 'modal-dialog-lg',
+					buttons: settings.allowCancel && ['cancel'],
+				})
+			))
+	}
+
 
 	/**
 	* Fetch the files associated with a given project
@@ -682,7 +900,7 @@ export default class TeraFyServer {
 	* @param {Boolean} [options.autoRequire=true] Run `requireProject()` automatically before continuing
 	* @param {Boolean} [options.meta=true] Pull meta information for each file entity
 	*
-	* @returns {Promise<ProjectFile>} A collection of project files for the given project
+	* @returns {Promise<Array<ProjectFile>>} A collection of project files for the given project
 	*/
 	getProjectFiles(options) {
 		let settings = {
@@ -700,61 +918,81 @@ export default class TeraFyServer {
 	}
 	// }}}
 
-	// Project Libraries - getProjectLibrary(), setProjectLibrary() {{{
+	// Project Libraries - selectProjectLibrary(), parseProjectLibrary(), setProjectLibrary() {{{
+
+	/**
+	* Prompt the user to select a library to operate on and return a array of references in a given format
+	*
+	* @param {Object} [options] Additional options to mutate behaviour
+	* @param {String} [options.title="Select a citation library"] The title of the dialog to display
+	* @param {String|Array<String>} [options.hint] Hints to identify the library to select in array order of preference. Generally corresponds to the previous stage - e.g. 'deduped', 'review1', 'review2', 'dedisputed'
+	* @param {Boolean} [options.allowUpload=true] Allow uploading new files
+	* @param {Boolean} [options.allowRefresh=true] Allow the user to manually refresh the file list
+	* @param {Boolean} [options.allowDownloadZip=true] Allow the user to download a Zip of all files
+	* @param {Boolean} [options.allowCancel=true] Allow cancelling the operation. Will throw `'CANCEL'` as the promise rejection if acationed
+	* @param {Boolean} [options.autoRequire=true] Run `requireProject()` automatically before continuing
+	* @param {FileFilters} [options.filters] Optional file filters, defaults to citation library selection only
+	* @param {*} [options.*] Additional options - see `parseProjectLibrary()`
+	*
+	* @returns {Promise<Array<Ref>>} A collection of references from the selected file
+	*/
+	selectProjectLibrary(options) {
+		let settings = {
+			title: 'Select a citation library',
+			hint: null,
+			allowUpload: true,
+			allowRefresh: true,
+			allowDownloadZip: true,
+			allowCancel: true,
+			autoRequire: true,
+			filters: {
+				library: true,
+				...options?.filter,
+			},
+			...options,
+		};
+
+		return app.service('$projects').promise()
+			.then(()=> this.selectProjectFile(settings))
+			.then(selectedFile => this.parseProjectLibrary(selectedFile.path, settings))
+	}
+
 
 	/**
-	* Fetch the active projects citation library
+	* Convert a project file into a library of citations
 	*
-	* @param {String} [path] Optional file path to use, if omitted the contents of `options` are used to guess at a suitable file
+	* @param {String} path File path to read, if omitted the contents of `options` are used to guess at a suitable file
 	*
 	* @param {Object} [options] Additional options to mutate behaviour
 	* @param {String} [options.format='json'] Format for the file. ENUM: 'pojo' (return a parsed JS collection), 'blob' (raw JS Blob object), 'file' (named JS File object)
 	* @param {Boolean} [options.autoRequire=true] Run `requireProject()` automatically before continuing
-	* @param {Boolean} [options.multiple=false] Allow selection of multiple libraries
 	* @param {Function} [options.filter] Optional async file filter, called each time as `(File:ProjectFile)`
 	* @param {Function} [options.find] Optional async final stage file filter to reduce all candidates down to one subject file
-	* @param {String|Array<String>} [options.hint] Hints to identify the library to select in array order of preference. Generally corresponds to the previous stage - e.g. 'deduped', 'review1', 'review2', 'dedisputed'
 	*
-	* @returns {Promise<Array<ProjectFile>>} Collection of references for the selected library matching the given hint + filter, this could be a zero length array
+	* @returns {Promise<Array<Ref>>|Promise<*>} A collection of references (default bevahiour) or a whatever format was requested
 	*/
-	getProjectLibrary(path, options) {
+	parseProjectLibrary(path, options) {
 		let settings = {
-			path,
 			format: 'pojo',
 			autoRequire: true,
-			multiple: false,
-			hint: null,
 			filter: file => true,
 			find: files => files.at(0),
-			...(typeof path == 'string' ? {path, ...options} : path),
+			...options,
 		};
 
 		return Promise.resolve()
-			.then(()=> {
-				if (settings.path) { // Already have a file name picked
-					if (!settings.path.startsWith('/')) throw new Error('All file names must start with a forward slash');
-					return settings.path;
-				} else { // Try to guess the file from the options structure
-					return this.getProjectFiles({
-						autoRequire: settings.autoRequire,
-					})
-					.then(files => files.filter(file =>
-						settings.filter(file)
-					))
-					.then(files => settings.find(files))
-					.then(file => file.path)
-				}
-			})
-			.then(filePath => app.service('$supabase').fileGet(filePath, {
+			.then(()=> settings.autoRequire && this.requireProject())
+			.then(()=> app.service('$supabase').fileGet(path, {
 				toast: false,
 			}))
 			.then(blob => {
 				switch (settings.format) {
+					// NOTE: Any updates to the format list should also extend setProjectLibrary()
 					case 'pojo':
 						return Reflib.uploadFile({
 							file: new File(
 								[blob],
-								app.service('$supabase')._parsePath(settings.path).basename,
+								app.service('$supabase')._parsePath(path).basename,
 							),
 						});
 					case 'blob':
@@ -762,7 +1000,7 @@ export default class TeraFyServer {
 					case 'file':
 						return new File(
 							[blob],
-							app.service('$supabase')._parsePath(settings.path).basename,
+							app.service('$supabase')._parsePath(path).basename,
 						);
 					default:
 						throw new Error(`Unsupported library format "${settings.format}"`);
@@ -772,26 +1010,59 @@ export default class TeraFyServer {
 
 
 	/**
-	* Save back a projects citation library
+	* Save back a citation library from some input
 	*
+	* @param {String} [path] File path to save back to
 	* @param {Array<RefLibRef>} Collection of references for the selected library
 	*
 	* @param {Object} [options] Additional options to mutate behaviour
+	* @param {String} [options.format='json'] Input format used. ENUM: 'pojo' (return a parsed JS collection), 'blob' (raw JS Blob object), 'file' (named JS File object)
 	* @param {Boolean} [options.autoRequire=true] Run `requireProject()` automatically before continuing
 	* @param {String} [options.hint] Hint to store against the library. Generally corresponds to the current operation being performed - e.g. 'deduped'
+	* @param {Boolean} [options.overwrite=true] Allow existing file upsert
+	* @param {Object} [options.meta] Optional meta data to merge into the file data
 	*
 	* @returns {Promise} A promise which resolves when the save operation has completed
 	*/
-	setProjectLibrary(refs, options) {
+	setProjectLibrary(path, refs, options) {
 		let settings = {
 			autoRequire: true,
 			hint: null,
+			overwrite: true,
+			meta: null,
 			...options,
 		};
 
 		return Promise.resolve()
 			.then(()=> settings.autoRequire && this.requireProject())
-		// FIXME: Stub
+			.then(()=> {
+				switch (settings.format) {
+					// NOTE: Any updates to the format list should also extend parseProjectLibrary()
+					case 'pojo': // Use as is
+						if (!Array.isArray(refs)) throw new Error('setProjectLibrary() with format=pojo requires an array of references');
+						return refs;
+					case 'blob':
+					case 'file':
+						return refs; // Following functions should pass thru these formats anyway
+					default:
+						throw new Error(`Unsupported library format "${settings.format}"`);
+				}
+			})
+			.then(refs =>
+				refs instanceof Blob ? new File([refs], app.service('$supabase')._parsePath(path).basename)
+				: refs instanceof File ? refs
+				: Reflib.downloadFile(refs, { // Get Reflib to encode for us
+					filename: path,
+					promptDownload: false, // Just return the fileBlob we hand to Supabase
+				})
+			)
+			.then(fileBlob => this.$supabase.fileUpload(path, {
+				file: fileBlob,
+				mode: 'encoded',
+				overwrite: true,
+				meta: settings.meta,
+				transcoders: false, // We can skip transcoders as we are supplying the meta information above anyway
+			}))
 	}
 
 	// }}}
@@ -825,6 +1096,7 @@ export default class TeraFyServer {
 	* @param {Object} [options] Additional options to mutate behaviour
 	* @param {String} [options.title='TERA'] The title of the alert box
 	* @param {Boolean} [options.isHtml=false] If falsy the text is rendered as plain-text otherwise it will be assumed as HTML content
+	* @param {'ok'|false} [options.buttons='ok'] Button set to use or falsy to disable
 	*
 	* @returns {Promise} A promise which resolves when the alert has been dismissed
 	*/
@@ -832,6 +1104,7 @@ export default class TeraFyServer {
 		let settings = {
 			title: 'TERA',
 			isHtml: false,
+			buttons: 'ok',
 			...options,
 		};
 
@@ -839,12 +1112,100 @@ export default class TeraFyServer {
 			app.service('$prompt').dialog({
 				title: settings.title,
 				body: text,
-				buttons: ['ok'],
+				buttons:
+					settings.buttons == 'ok' ? ['ok']
+					: false,
 				isHtml: settings.isHtml,
 				dialogClose: 'resolve',
 			})
 		);
 	}
+
+
+	/**
+	* Open a popup window containing a new site
+	*
+	* @param {String} url The URL to open
+	*
+	* @param {Object} [options] Additional options to mutate behaviour
+	* @param {Number} [options.width=500] The desired width of the window
+	* @param {Number} [options.height=600] The desired height of the window
+	* @param {Boolean} [options.center=true] Attempt to center the window on the screen
+	* @param {Object} [options.permissions] Additional permissions to set on opening, defaults to a suitable set of permission for popups (see code)
+	*
+	* @returns {WindowProxy} The opened window object (if `noopener` is not set in permissions)
+	*/
+	uiWindow(url, options) {
+		let settings = {
+			width: 500,
+			height: 600,
+			center: true,
+			permissions: {
+				popup: true,
+				location: false,
+				menubar: false,
+				status: false,
+				scrolbars: false,
+			},
+			...options,
+		};
+
+		return window.open(url, '_blank', Object.entries({
+			...settings.permissions,
+			width: settings.width,
+			height: settings.height,
+			...(settings.center && {
+				left: screen.width/2 - settings.width/2,
+				top: screen.height/2 - settings.height/2,
+			}),
+		})
+			.map(([key, val]) => key + '=' + (
+				typeof val == 'boolean' ? val ? '1' : '0' // Map booleans to 1/0
+				: val
+			))
+			.join(', ')
+		);
+	}
+
+
+	/**
+	* Display HTML content full-screen within TERA
+	* This function is ideally called within a requestFocus() wrapper
+	*
+	* @param {DOMElement|String|false} content Either a prepared DOM element or string to compile, set to falsy to remove existing content
+	*
+	* @param {Object} [options] Additional options to mutate behaviour
+	* @param {Boolean|String} [options.logo=false] Add a logo to the output, if boolean true the Tera-tools logo is used otherwise specify a path or URL
+	*/
+	uiSplat(content, options) {
+		let settings = {
+			logo: false,
+			...options,
+		};
+
+		if (!content) { // Remove content
+			globalThis.document.body.querySelector('.tera-fy-uiSplat').remove();
+			return;
+		}
+
+		let compiledContent = typeof content == 'string'
+			? (()=> {
+				let el = document.createElement('div')
+				el.innerHTML = content;
+				return el;
+			})()
+			: content;
+
+		compiledContent.classList.add('tera-fy-uiSplat');
+
+		if (settings.logo) {
+			let logoEl = document.createElement('div');
+			logoEl.innerHTML = `<img src="${typeof settings.logo == 'string' ? settings.logo : '/assets/logo/logo.svg'}" class="img-logo"/>`;
+			compiledContent.prepend(logoEl);
+		}
+
+		globalThis.document.body.append(compiledContent);
+	}
 	// }}}
 
 	// Utility - debug() {{{