@iebh/tera-fy 1.0.17 → 1.0.18

package/api.md

@@ -49,40 +49,51 @@
     *   [Properties][45]
 *   [getUser][46]
 *   [requireUser][47]
-*   [][48]
-*   [Project][49]
-*   [getProject][50]
-*   [getProjects][51]
-*   [setActiveProject][52]
-    *   [Parameters][53]
-*   [requireProject][54]
-    *   [Parameters][55]
-*   [selectProject][56]
-    *   [Parameters][57]
-*   [getProjectState][58]
-    *   [Parameters][59]
-*   [setProjectState][60]
-    *   [Parameters][61]
-*   [setProjectStateDefaults][62]
-    *   [Parameters][63]
-*   [saveProjectState][64]
-*   [replaceProjectState][65]
-    *   [Parameters][66]
-*   [applyProjectStatePatch][67]
-    *   [Parameters][68]
-*   [subscribeProjectState][69]
-*   [ProjectFile][70]
-    *   [Properties][71]
-*   [getProjectFiles][72]
-    *   [Parameters][73]
-*   [selectProjectLibrary][74]
-    *   [Parameters][75]
-*   [setProjectLibrary][76]
-    *   [Parameters][77]
-*   [setProjectLibrary][78]
-    *   [Parameters][79]
-*   [uiAlert][80]
-    *   [Parameters][81]
+    *   [Parameters][48]
+*   [][49]
+*   [Project][50]
+*   [getProject][51]
+*   [getProjects][52]
+*   [setActiveProject][53]
+    *   [Parameters][54]
+*   [requireProject][55]
+    *   [Parameters][56]
+*   [selectProject][57]
+    *   [Parameters][58]
+*   [getProjectState][59]
+    *   [Parameters][60]
+*   [setProjectState][61]
+    *   [Parameters][62]
+*   [setProjectStateDefaults][63]
+    *   [Parameters][64]
+*   [saveProjectState][65]
+*   [replaceProjectState][66]
+    *   [Parameters][67]
+*   [applyProjectStatePatch][68]
+    *   [Parameters][69]
+*   [subscribeProjectState][70]
+*   [ProjectFile][71]
+    *   [Properties][72]
+*   [FileFilters][73]
+    *   [Properties][74]
+*   [selectProjectFile][75]
+    *   [Parameters][76]
+*   [getProjectFiles][77]
+    *   [Parameters][78]
+*   [selectProjectLibrary][79]
+    *   [Parameters][80]
+*   [parseProjectLibrary][81]
+    *   [Parameters][82]
+*   [setProjectLibrary][83]
+    *   [Parameters][84]
+*   [setProjectLibrary][85]
+    *   [Parameters][86]
+*   [uiAlert][87]
+    *   [Parameters][88]
+*   [uiSplat][89]
+    *   [Parameters][90]
+*   [uiWindow][91]
+    *   [Parameters][92]
 
 ## TeraFy
 
@@ -92,16 +103,18 @@ Main Tera-Fy Client (class singleton) to be used in a frontend browser
 
 Various settings to configure behaviour
 
-Type: [Object][82]
+Type: [Object][93]
 
 #### Properties
 
-*   `devMode` **[Boolean][83]** Operate in devMode - i.e. force outer refresh when encountering an existing TeraFy instance
-*   `How` **(`"detect"` | `"parent"` | `"child"`)** to communicate with TERA. 'parent' assumes that the parent of the current document is TERA, 'child' spawns an iFrame and uses TERA there, 'detect' tries parent and fallsback to 'child'
-*   `modeTimeout` **[Number][84]** How long entities have in 'detect' mode to identify themselves
-*   `siteUrl` **[String][85]** The TERA URL to connect to
-*   `restrictOrigin` **[String][85]** URL to restrict communications to
-*   `List` **[Array][86]<[String][85]>** of sandbox allowables for the embedded if in embed mode
+*   `devMode` **[Boolean][94]** Operate in devMode - i.e. force outer refresh when encountering an existing TeraFy instance
+*   `mode` **(`"detect"` | `"parent"` | `"child"` | `"popup"`)** How to communicate with TERA. 'parent' assumes that the parent of the current document is TERA, 'child' spawns an iFrame and uses TERA there, 'detect' tries parent and switches to `modeFallback` if communication fails
+*   `modeFallback` **[String][95]** Method to use when all method detection fails
+*   `modeTimeout` **[Number][96]** How long entities have in 'detect' mode to identify themselves
+*   `siteUrl` **[String][95]** The TERA URL to connect to
+*   `restrictOrigin` **[String][95]** URL to restrict communications to
+*   `List` **[Array][97]<[String][95]>** of sandbox allowables for the embedded if in embed mode
+*   `handshakeInterval` **[Number][96]** Interval in milliseconds when sanning for a handshake
 
 ### events
 
@@ -113,12 +126,13 @@ Type: Mitt
 
 DOMElements for this TeraFy instance
 
-Type: [Object][82]
+Type: [Object][93]
 
 #### Properties
 
 *   `el` **DOMElement** The main tera-fy div wrapper
-*   `iframe` **DOMElement** The internal iFrame element
+*   `iframe` **DOMElement** The internal iFrame element  (if `settings.mode == 'child'`)
+*   `popup` **[Window][98]** The popup window context (if `settings.mode == 'popup'`)
 *   `stylesheet` **DOMElement** The corresponding stylesheet
 
 ### methods
@@ -126,13 +140,13 @@ Type: [Object][82]
 List of function stubs mapped here from the server
 This array is forms the reference of `TeraFy.METHOD()` objects to provide locally which will be mapped via `TeraFy.rpc(METHOD, ...args)`
 
-Type: [Array][86]<[String][85]>
+Type: [Array][97]<[String][95]>
 
 ### plugins
 
 Loaded plugins via Use()
 
-Type: [Array][86]\<TeraFyPlugin>
+Type: [Array][97]\<TeraFyPlugin>
 
 ### send
 
@@ -140,9 +154,9 @@ Send a message + wait for a response object
 
 #### Parameters
 
-*   `message` **[Object][82]** Message object to send
+*   `message` **[Object][93]** Message object to send
 
-Returns **[Promise][87]\<any>** A promise which resolves when the operation has completed with the remote reply
+Returns **[Promise][99]\<any>** A promise which resolves when the operation has completed with the remote reply
 
 ### sendRaw
 
@@ -151,7 +165,7 @@ This function does not return or wait for a reply - use `send()` for that
 
 #### Parameters
 
-*   `message` **[Object][82]** Message object to send
+*   `message` **[Object][93]** Message object to send
 
 ### rpc
 
@@ -159,10 +173,10 @@ Call an RPC function in the server instance
 
 #### Parameters
 
-*   `method` **[String][85]** The method name to call
+*   `method` **[String][95]** The method name to call
 *   `args` **...any**&#x20;
 
-Returns **[Promise][87]\<any>** The resolved output of the server function
+Returns **[Promise][99]\<any>** The resolved output of the server function
 
 ### acceptMessage
 
@@ -171,7 +185,7 @@ Accept an incoming message
 #### Parameters
 
 *   `rawMessage` &#x20;
-*   `Raw` **[MessageEvent][88]** message event to process
+*   `Raw` **[MessageEvent][100]** message event to process
 
 ### acceptPostboxes
 
@@ -180,27 +194,27 @@ Listening postboxes, these correspond to outgoing message IDs that expect a resp
 ### createProjectStatePatch
 
 Create + transmit a new project state patch base on the current and previous states
-The transmitted patch follows the [JSPatch][89] standard
+The transmitted patch follows the [JSPatch][101] standard
 This function accepts an entire projectState instance, computes the delta and transmits that to the server for merging
 
 #### Parameters
 
-*   `newState` **[Object][82]** The local projectState to accept
-*   `oldState` **[Object][82]** The previous projectState to examine against
+*   `newState` **[Object][93]** The local projectState to accept
+*   `oldState` **[Object][93]** The previous projectState to examine against
 
-Returns **[Promise][87]** A promise which will resolve when the operation has completed
+Returns **[Promise][99]** A promise which will resolve when the operation has completed
 
 ### applyProjectStatePatchLocal
 
 Client function which accepts a patch from the server and applies it to local project state
-The patch should follow the [JSPatch][89] standard
+The patch should follow the [JSPatch][101] standard
 This function is expected to be sub-classed by a plugin
 
 #### Parameters
 
-*   `patch` **[Array][86]** A JSPatch patch to apply
+*   `patch` **[Array][97]** A JSPatch patch to apply
 
-Returns **[Promise][87]** A promise which will resolve when the operation has completed
+Returns **[Promise][99]** A promise which will resolve when the operation has completed
 
 ### init
 
@@ -209,22 +223,22 @@ This function can only be called once and will return the existing init() worker
 
 #### Parameters
 
-*   `options` **[Object][82]?** Additional options to merge into `settings` via `set`
+*   `options` **[Object][93]?** Additional options to merge into `settings` via `set`
 
-Returns **[Promise][87]<[TeraFy][1]>** An eventual promise which will resovle with this terafy instance
+Returns **[Promise][99]<[TeraFy][1]>** An eventual promise which will resovle with this terafy instance
 
 ### detectMode
 
 Populate `settings.mode`
 Try to communicate with a parent frame, if none assume we need to fallback to child mode
 
-Returns **[Promise][87]<[String][85]>** A promise which will resolve with the detected mode to use
+Returns **[Promise][99]<[String][95]>** A promise which will resolve with the detected mode to use
 
 ### injectComms
 
 Find an existing active TERA server OR initalize one
 
-Returns **[Promise][87]** A promise which will resolve when the loading has completed and we have found a parent TERA instance or initiallized a child
+Returns **[Promise][99]** A promise which will resolve when the loading has completed and we have found a parent TERA instance or initiallized a child
 
 ### injectStylesheet
 
@@ -251,7 +265,7 @@ This function also routes 'special' keys like `devMode` to their internal handle
 
 #### Parameters
 
-*   `key` **([String][85] | [Object][82])** Either a single setting key to set or an object to merge
+*   `key` **([String][95] | [Object][93])** Either a single setting key to set or an object to merge
 *   `value` **any** The value to set if `key` is a string
 
 Returns **[TeraFy][1]** This chainable terafy instance
@@ -264,7 +278,7 @@ Set or merge settings - but only in dev mode and only if the value is not undefi
 
 #### Parameters
 
-*   `key` **([String][85] | [Object][82])** Either a single setting key to set or an object to merge
+*   `key` **([String][95] | [Object][93])** Either a single setting key to set or an object to merge
 *   `value` **any** The value to set if `key` is a string
 
 Returns **[TeraFy][1]** This chainable terafy instance
@@ -276,8 +290,8 @@ Include a TeraFy client plugin
 #### Parameters
 
 *   `mod` &#x20;
-*   `options` **[Object][82]?** Additional options to mutate behaviour during construction (pass options to init() to intialize later options)
-*   `The` **[Object][82]** module function to include. Invoked as `(teraClient:TeraFy, options:Object)`
+*   `options` **[Object][93]?** Additional options to mutate behaviour during construction (pass options to init() to intialize later options)
+*   `The` **[Object][93]** module function to include. Invoked as `(teraClient:TeraFy, options:Object)`
 
 Returns **[TeraFy][1]** This chainable terafy instance
 
@@ -287,8 +301,8 @@ Internal function used by use() to merge an external declared singleton against
 
 #### Parameters
 
-*   `target` **[Object][82]** Initalied class instance to extend
-*   `source` **[Object][82]** Initalized source object to extend from
+*   `target` **[Object][93]** Initalied class instance to extend
+*   `source` **[Object][93]** Initalized source object to extend from
 
 ### toggleDevMode
 
@@ -296,7 +310,7 @@ Set or toggle devMode
 
 #### Parameters
 
-*   `devModeEnabled` **([String][85] | [Boolean][83])** Optional boolean to force dev mode (optional, default `'toggle'`)
+*   `devModeEnabled` **([String][95] | [Boolean][94])** Optional boolean to force dev mode (optional, default `'toggle'`)
 
 Returns **[TeraFy][1]** This chainable terafy instance
 
@@ -307,7 +321,7 @@ This is usually because the server component wants to perform some user activity
 
 #### Parameters
 
-*   `isFocused` **([String][85] | [Boolean][83])** Whether to fullscreen the embedded component (optional, default `'toggle'`)
+*   `isFocused` **([String][95] | [Boolean][94])** Whether to fullscreen the embedded component (optional, default `'toggle'`)
 
 ## handshake
 
@@ -315,9 +329,9 @@ Return basic server information as a form of validation
 
 ### Properties
 
-*   `date` **[Date][90]** Server date
+*   `date` **[Date][102]** Server date
 
-Returns **[Promise][87]<[Object][82]>** Basic promise result
+Returns **[Promise][99]<[Object][93]>** Basic promise result
 
 ## User
 
@@ -325,16 +339,16 @@ User / active session within TERA
 
 ### Properties
 
-*   `id` **[String][85]** Unique identifier of the user
-*   `email` **[String][85]** The email address of the current user
-*   `name` **[String][85]** The provided full name of the user
-*   `isSubscribed` **[Boolean][83]** Whether the active user has a TERA subscription
+*   `id` **[String][95]** Unique identifier of the user
+*   `email` **[String][95]** The email address of the current user
+*   `name` **[String][95]** The provided full name of the user
+*   `isSubscribed` **[Boolean][94]** Whether the active user has a TERA subscription
 
 ## getUser
 
 Fetch the current session user
 
-Returns **[Promise][87]<[User][44]>** The current logged in user or null if none
+Returns **[Promise][99]<[User][44]>** The current logged in user or null if none
 
 ## requireUser
 
@@ -342,7 +356,13 @@ Require a user login to TERA
 If there is no user OR they are not logged in a prompt is shown to go and do so
 This is an pre-requisite step for requireProject()
 
-Returns **[Promise][87]** A promise which will resolve if the there is a user and they are logged in
+### Parameters
+
+*   `options` **[Object][93]?** Additional options to mutate behaviour
+
+    *   `options.forceRetry` **[Boolean][94]** Forcabily try to refresh the user state (optional, default `false`)
+
+Returns **[Promise][99]<[User][44]>** The current logged in user or null if none
 
 ##
 
@@ -350,7 +370,7 @@ Require a user login to TERA
 If there is no user OR they are not logged in a prompt is shown to go and do so
 This is an pre-requisite step for requireProject()
 
-Returns **[Promise][87]** A promise which will resolve if the there is a user and they are logged in
+Returns **[Promise][99]** A promise which will resolve if the there is a user and they are logged in
 
 ## Project
 
@@ -360,13 +380,13 @@ Project entry within TERA
 
 Get the currently active project, if any
 
-Returns **[Promise][87]<([Project][49] | null)>** The currently active project, if any
+Returns **[Promise][99]<([Project][50] | null)>** The currently active project, if any
 
 ## getProjects
 
 Get a list of projects the current session user has access to
 
-Returns **[Promise][87]<[Array][86]<[Project][49]>>** Collection of projects the user has access to
+Returns **[Promise][99]<[Array][97]<[Project][50]>>** Collection of projects the user has access to
 
 ## setActiveProject
 
@@ -374,7 +394,7 @@ Set the currently active project within TERA
 
 ### Parameters
 
-*   `project` **([Object][82] | [String][85])** The project to set as active - either the full Project object or its ID
+*   `project` **([Object][93] | [String][95])** The project to set as active - either the full Project object or its ID
 
 ## requireProject
 
@@ -383,14 +403,14 @@ Note that this function will percist in asking the uesr even if they try to canc
 
 ### Parameters
 
-*   `options` **[Object][82]?** Additional options to mutate behaviour
+*   `options` **[Object][93]?** Additional options to mutate behaviour
 
-    *   `options.autoSetActiveProject` **[Boolean][83]** After selecting a project set that project as active in TERA (optional, default `true`)
-    *   `options.title` **[String][85]** The title of the dialog to display (optional, default `"Select a project to work with"`)
-    *   `options.noSelectTitle` **[String][85]** Dialog title when warning the user they need to select something (optional, default `'Select project'`)
-    *   `options.noSelectBody` **[String][85]** Dialog body when warning the user they need to select something (optional, default `'A project needs to be selected to continue'`)
+    *   `options.autoSetActiveProject` **[Boolean][94]** After selecting a project set that project as active in TERA (optional, default `true`)
+    *   `options.title` **[String][95]** The title of the dialog to display (optional, default `"Select a project to work with"`)
+    *   `options.noSelectTitle` **[String][95]** Dialog title when warning the user they need to select something (optional, default `'Select project'`)
+    *   `options.noSelectBody` **[String][95]** Dialog body when warning the user they need to select something (optional, default `'A project needs to be selected to continue'`)
 
-Returns **[Promise][87]<[Project][49]>** The active project
+Returns **[Promise][99]<[Project][50]>** The active project
 
 ## selectProject
 
@@ -398,13 +418,13 @@ Prompt the user to select a project from those available
 
 ### Parameters
 
-*   `options` **[Object][82]?** Additional options to mutate behaviour
+*   `options` **[Object][93]?** Additional options to mutate behaviour
 
-    *   `options.title` **[String][85]** The title of the dialog to display (optional, default `"Select a project to work with"`)
-    *   `options.allowCancel` **[Boolean][83]** Advertise cancelling the operation, the dialog can still be cancelled by closing it (optional, default `true`)
-    *   `options.setActive` **[Boolean][83]** Also set the project as active when selected (optional, default `false`)
+    *   `options.title` **[String][95]** The title of the dialog to display (optional, default `"Select a project to work with"`)
+    *   `options.allowCancel` **[Boolean][94]** Advertise cancelling the operation, the dialog can still be cancelled by closing it (optional, default `true`)
+    *   `options.setActive` **[Boolean][94]** Also set the project as active when selected (optional, default `false`)
 
-Returns **[Promise][87]<[Project][49]>** The active project
+Returns **[Promise][99]<[Project][50]>** The active project
 
 ## getProjectState
 
@@ -412,12 +432,12 @@ Return the current, full snapshot state of the active project
 
 ### Parameters
 
-*   `options` **[Object][82]?** Additional options to mutate behaviour
+*   `options` **[Object][93]?** Additional options to mutate behaviour
 
-    *   `options.autoRequire` **[Boolean][83]** Run `requireProject()` automatically before continuing (optional, default `true`)
-*   `Paths` **[Array][86]<[String][85]>** to subscribe to e.g. \['/users/'],
+    *   `options.autoRequire` **[Boolean][94]** Run `requireProject()` automatically before continuing (optional, default `true`)
+*   `Paths` **[Array][97]<[String][95]>** to subscribe to e.g. \['/users/'],
 
-Returns **[Promise][87]<[Object][82]>** The current project state snapshot
+Returns **[Promise][99]<[Object][93]>** The current project state snapshot
 
 ## setProjectState
 
@@ -429,14 +449,14 @@ Paths can be any valid Lodash.set() value such as:
 
 ### Parameters
 
-*   `path` **([String][85] | [Array][86]<[String][85]>)** The sub-path within the project state to set
+*   `path` **([String][95] | [Array][97]<[String][95]>)** The sub-path within the project state to set
 *   `value` **any** The value to set
-*   `options` **[Object][82]?** Additional options to mutate behaviour
+*   `options` **[Object][93]?** Additional options to mutate behaviour
 
-    *   `options.save` **[Boolean][83]** Save the changes to the server immediately, disable to queue up multiple writes (optional, default `true`)
-    *   `options.sync` **[Boolean][83]** Wait for the server to acknowledge the write, you almost never need to do this (optional, default `false`)
+    *   `options.save` **[Boolean][94]** Save the changes to the server immediately, disable to queue up multiple writes (optional, default `true`)
+    *   `options.sync` **[Boolean][94]** Wait for the server to acknowledge the write, you almost never need to do this (optional, default `false`)
 
-Returns **[Promise][87]** A promise which resolves when the operation has synced with the server
+Returns **[Promise][99]** A promise which resolves when the operation has synced with the server
 
 ## setProjectStateDefaults
 
@@ -446,17 +466,17 @@ Set a nested value within the project state - just like `setProjectState()` - bu
 
 ### Parameters
 
-*   `path` **([String][85] | [Array][86]<[String][85]>)** The sub-path within the project state to set
+*   `path` **([String][95] | [Array][97]<[String][95]>)** The sub-path within the project state to set
 *   `value` **any** The value to set
-*   `options` **[Object][82]?** Additional options to mutate behaviour, see setProjectState() for the full list of supported options
+*   `options` **[Object][93]?** Additional options to mutate behaviour, see setProjectState() for the full list of supported options
 
-Returns **[Promise][87]<[Boolean][83]>** A promise which resolves to whether any changes were made - True if defaults were applied, false otherwise
+Returns **[Promise][99]<[Boolean][94]>** A promise which resolves to whether any changes were made - True if defaults were applied, false otherwise
 
 ## saveProjectState
 
 Force-Save the currently active project state
 
-Returns **[Promise][87]** A promise which resolves when the operation has completed
+Returns **[Promise][99]** A promise which resolves when the operation has completed
 
 ## replaceProjectState
 
@@ -467,9 +487,9 @@ You almost never want to use this function directly, see `setProjectState(path,
 
 ### Parameters
 
-*   `newState` **[Object][82]** The new state to replace the current state with
+*   `newState` **[Object][93]** The new state to replace the current state with
 
-Returns **[Promise][87]** A promise which resolves when the operation has completed
+Returns **[Promise][99]** A promise which resolves when the operation has completed
 
 ## applyProjectStatePatch
 
@@ -477,9 +497,9 @@ Apply a computed `just-diff` patch to the current project state
 
 ### Parameters
 
-*   `Patch` **[Object][82]** to apply
+*   `Patch` **[Object][93]** to apply
 
-Returns **[Promise][87]** A promise which resolves when the operation has completed
+Returns **[Promise][99]** A promise which resolves when the operation has completed
 
 ## subscribeProjectState
 
@@ -487,7 +507,7 @@ Subscribe to project state changes
 This will dispatch an RPC call to the source object `applyProjectStatePatchLocal()` function with the patch
 If the above call fails the subscriber is assumed as dead and unsubscribed from the polling list
 
-Returns **[Promise][87]<[Function][91]>** A promise which resolves when a subscription has been created, call the resulting function to unsubscribe
+Returns **[Promise][99]<[Function][103]>** A promise which resolves when a subscription has been created, call the resulting function to unsubscribe
 
 ## ProjectFile
 
@@ -495,19 +515,50 @@ Data structure for a project file
 
 ### Properties
 
-*   `id` **[String][85]** A UUID string representing the unique ID of the file
-*   `name` **[String][85]** Relative name path (can contain prefix directories) for the human readable file name
-*   `parsedName` **[Object][82]** An object representing meta file parts of a file name
+*   `id` **[String][95]** A UUID string representing the unique ID of the file
+*   `name` **[String][95]** Relative name path (can contain prefix directories) for the human readable file name
+*   `parsedName` **[Object][93]** An object representing meta file parts of a file name
 
-    *   `parsedName.basename` **[String][85]** The filename + extention (i.e. everything without directory name)
-    *   `parsedName.filename` **[String][85]** The file portion of the name (basename without the extension)
-    *   `parsedName.ext` **[String][85]** The extension portion of the name (always lower case)
-    *   `parsedName.dirName` **[String][85]** The directory path portion of the name
-*   `created` **[Date][90]** A date representing when the file was created
-*   `modified` **[Date][90]** A date representing when the file was created
-*   `accessed` **[Date][90]** A date representing when the file was last accessed
-*   `size` **[Number][84]** Size, in bytes, of the file
-*   `mime` **[String][85]** The associated mime type for the file
+    *   `parsedName.basename` **[String][95]** The filename + extention (i.e. everything without directory name)
+    *   `parsedName.filename` **[String][95]** The file portion of the name (basename without the extension)
+    *   `parsedName.ext` **[String][95]** The extension portion of the name (always lower case)
+    *   `parsedName.dirName` **[String][95]** The directory path portion of the name
+*   `created` **[Date][102]** A date representing when the file was created
+*   `modified` **[Date][102]** A date representing when the file was created
+*   `accessed` **[Date][102]** A date representing when the file was last accessed
+*   `size` **[Number][96]** Size, in bytes, of the file
+*   `mime` **[String][95]** The associated mime type for the file
+
+## FileFilters
+
+Data structure for a file filter
+
+### Properties
+
+*   `library` **[Boolean][94]?** Restrict to library files only
+*   `filename` **[String][95]?** CSV of @momsfriendlydevco/match expressions to filter the filename by (filenames are the basename sans extension)
+*   `basename` **[String][95]?** CSV of @momsfriendlydevco/match expressions to filter the basename by
+*   `ext` **[String][95]?** CSV of @momsfriendlydevco/match expressions to filter the file extension by
+
+## selectProjectFile
+
+Prompt the user to select a library to operate on
+
+### Parameters
+
+*   `options` **[Object][93]?** Additional options to mutate behaviour
+
+    *   `options.title` **[String][95]** The title of the dialog to display (optional, default `"Select a file"`)
+    *   `options.hint` **([String][95] | [Array][97]<[String][95]>)?** Hints to identify the file to select in array order of preference
+    *   `options.filters` **[FileFilters][73]?** Optional file filters
+    *   `options.allowUpload` **[Boolean][94]** Allow uploading new files (optional, default `true`)
+    *   `options.allowRefresh` **[Boolean][94]** Allow the user to manually refresh the file list (optional, default `true`)
+    *   `options.allowDownloadZip` **[Boolean][94]** Allow the user to download a Zip of all files (optional, default `true`)
+    *   `options.allowCancel` **[Boolean][94]** Allow cancelling the operation. Will throw `'CANCEL'` as the promise rejection if acationed (optional, default `true`)
+    *   `options.autoRequire` **[Boolean][94]** Run `requireProject()` automatically before continuing (optional, default `true`)
+    *   `options.filter` **[FileFilters][73]?** Optional file filters
+
+Returns **[Promise][99]<[ProjectFile][71]>** The eventually selected file
 
 ## getProjectFiles
 
@@ -515,30 +566,47 @@ Fetch the files associated with a given project
 
 ### Parameters
 
-*   `options` **[Object][82]** Options which mutate behaviour
+*   `options` **[Object][93]** Options which mutate behaviour
 
-    *   `options.autoRequire` **[Boolean][83]** Run `requireProject()` automatically before continuing (optional, default `true`)
-    *   `options.meta` **[Boolean][83]** Pull meta information for each file entity (optional, default `true`)
+    *   `options.autoRequire` **[Boolean][94]** Run `requireProject()` automatically before continuing (optional, default `true`)
+    *   `options.meta` **[Boolean][94]** Pull meta information for each file entity (optional, default `true`)
 
-Returns **[Promise][87]<[ProjectFile][70]>** A collection of project files for the given project
+Returns **[Promise][99]<[Array][97]<[ProjectFile][71]>>** A collection of project files for the given project
 
 ## selectProjectLibrary
 
-Prompt the user to select a library to operate on
+Prompt the user to select a library to operate on and return a array of references in a given format
+
+### Parameters
+
+*   `options` **[Object][93]?** Additional options to mutate behaviour
+
+    *   `options.title` **[String][95]** The title of the dialog to display (optional, default `"Select a citation library"`)
+    *   `options.hint` **([String][95] | [Array][97]<[String][95]>)?** Hints to identify the library to select in array order of preference. Generally corresponds to the previous stage - e.g. 'deduped', 'review1', 'review2', 'dedisputed'
+    *   `options.allowUpload` **[Boolean][94]** Allow uploading new files (optional, default `true`)
+    *   `options.allowRefresh` **[Boolean][94]** Allow the user to manually refresh the file list (optional, default `true`)
+    *   `options.allowDownloadZip` **[Boolean][94]** Allow the user to download a Zip of all files (optional, default `true`)
+    *   `options.allowCancel` **[Boolean][94]** Allow cancelling the operation. Will throw `'CANCEL'` as the promise rejection if acationed (optional, default `true`)
+    *   `options.autoRequire` **[Boolean][94]** Run `requireProject()` automatically before continuing (optional, default `true`)
+    *   `options.filters` **[FileFilters][73]?** Optional file filters, defaults to citation library selection only
+
+Returns **[Promise][99]<[Array][97]\<Ref>>** A collection of references from the selected file
+
+## parseProjectLibrary
+
+Convert a project file into a library of citations
 
 ### Parameters
 
-*   `options` **[Object][82]?** Additional options to mutate behaviour
+*   `path` **[String][95]** File path to read, if omitted the contents of `options` are used to guess at a suitable file
+*   `options` **[Object][93]?** Additional options to mutate behaviour
 
-    *   `options.title` **[String][85]** The title of the dialog to display (optional, default `"Select a citation library"`)
-    *   `options.hint` **([String][85] | [Array][86]<[String][85]>)?** Hints to identify the library to select in array order of preference. Generally corresponds to the previous stage - e.g. 'deduped', 'review1', 'review2', 'dedisputed'
-    *   `options.allowUpload` **[Boolean][83]** Allow uploading new files (optional, default `true`)
-    *   `options.allowRefresh` **[Boolean][83]** Allow the user to manually refresh the file list (optional, default `true`)
-    *   `options.allowDownloadZip` **[Boolean][83]** Allow the user to download a Zip of all files (optional, default `true`)
-    *   `options.allowCancel` **[Boolean][83]** Allow cancelling the operation. Will throw `'CANCEL'` as the promise rejection if acationed (optional, default `true`)
-    *   `options.autoRequire` **[Boolean][83]** Run `requireProject()` automatically before continuing (optional, default `true`)
+    *   `options.format` **[String][95]** Format for the file. ENUM: 'pojo' (return a parsed JS collection), 'blob' (raw JS Blob object), 'file' (named JS File object) (optional, default `'json'`)
+    *   `options.autoRequire` **[Boolean][94]** Run `requireProject()` automatically before continuing (optional, default `true`)
+    *   `options.filter` **[Function][103]?** Optional async file filter, called each time as `(File:ProjectFile)`
+    *   `options.find` **[Function][103]?** Optional async final stage file filter to reduce all candidates down to one subject file
 
-Returns **([Promise][87]<[Array][86]\<Ref>> | [Promise][87]\<any>)** A collection of references (default bevahiour) or a whatever format was requested
+Returns **([Promise][99]<[Array][97]\<Ref>> | [Promise][99]\<any>)** A collection of references (default bevahiour) or a whatever format was requested
 
 ## setProjectLibrary
 
@@ -546,17 +614,17 @@ Save back a citation library from some input
 
 ### Parameters
 
-*   `path` **[String][85]?** File path to save back to
-*   `Collection` **[Array][86]\<RefLibRef>** of references for the selected library
-*   `options` **[Object][82]?** Additional options to mutate behaviour
+*   `path` **[String][95]?** File path to save back to
+*   `Collection` **[Array][97]\<RefLibRef>** of references for the selected library
+*   `options` **[Object][93]?** Additional options to mutate behaviour
 
-    *   `options.format` **[String][85]** Input format used. ENUM: 'pojo' (return a parsed JS collection), 'blob' (raw JS Blob object), 'file' (named JS File object) (optional, default `'json'`)
-    *   `options.autoRequire` **[Boolean][83]** Run `requireProject()` automatically before continuing (optional, default `true`)
-    *   `options.hint` **[String][85]?** Hint to store against the library. Generally corresponds to the current operation being performed - e.g. 'deduped'
-    *   `options.overwrite` **[Boolean][83]** Allow existing file upsert (optional, default `true`)
-    *   `options.meta` **[Object][82]?** Optional meta data to merge into the file data
+    *   `options.format` **[String][95]** Input format used. ENUM: 'pojo' (return a parsed JS collection), 'blob' (raw JS Blob object), 'file' (named JS File object) (optional, default `'json'`)
+    *   `options.autoRequire` **[Boolean][94]** Run `requireProject()` automatically before continuing (optional, default `true`)
+    *   `options.hint` **[String][95]?** Hint to store against the library. Generally corresponds to the current operation being performed - e.g. 'deduped'
+    *   `options.overwrite` **[Boolean][94]** Allow existing file upsert (optional, default `true`)
+    *   `options.meta` **[Object][93]?** Optional meta data to merge into the file data
 
-Returns **[Promise][87]** A promise which resolves when the save operation has completed
+Returns **[Promise][99]** A promise which resolves when the save operation has completed
 
 ## setProjectLibrary
 
@@ -564,13 +632,13 @@ Save back a projects citation library
 
 ### Parameters
 
-*   `Collection` **[Array][86]\<RefLibRef>** of references for the selected library
-*   `options` **[Object][82]?** Additional options to mutate behaviour
+*   `Collection` **[Array][97]\<RefLibRef>** of references for the selected library
+*   `options` **[Object][93]?** Additional options to mutate behaviour
 
-    *   `options.autoRequire` **[Boolean][83]** Run `requireProject()` automatically before continuing (optional, default `true`)
-    *   `options.hint` **[String][85]?** Hint to store against the library. Generally corresponds to the current operation being performed - e.g. 'deduped'
+    *   `options.autoRequire` **[Boolean][94]** Run `requireProject()` automatically before continuing (optional, default `true`)
+    *   `options.hint` **[String][95]?** Hint to store against the library. Generally corresponds to the current operation being performed - e.g. 'deduped'
 
-Returns **[Promise][87]** A promise which resolves when the save operation has completed
+Returns **[Promise][99]** A promise which resolves when the save operation has completed
 
 ## uiAlert
 
@@ -578,13 +646,41 @@ Display simple text within TERA
 
 ### Parameters
 
-*   `text` **[String][85]** The text to display
-*   `options` **[Object][82]?** Additional options to mutate behaviour
+*   `text` **[String][95]** The text to display
+*   `options` **[Object][93]?** Additional options to mutate behaviour
 
-    *   `options.title` **[String][85]** The title of the alert box (optional, default `'TERA'`)
-    *   `options.isHtml` **[Boolean][83]** If falsy the text is rendered as plain-text otherwise it will be assumed as HTML content (optional, default `false`)
+    *   `options.title` **[String][95]** The title of the alert box (optional, default `'TERA'`)
+    *   `options.isHtml` **[Boolean][94]** If falsy the text is rendered as plain-text otherwise it will be assumed as HTML content (optional, default `false`)
 
-Returns **[Promise][87]** A promise which resolves when the alert has been dismissed
+Returns **[Promise][99]** A promise which resolves when the alert has been dismissed
+
+## uiSplat
+
+Display HTML content full-screen within TERA
+This function is ideally called within a requestFocus() wrapper
+
+### Parameters
+
+*   `content` **(DOMElement | [String][95] | `false`)** Either a prepared DOM element or string to compile, set to falsy to remove existing content
+*   `options` **[Object][93]?** Additional options to mutate behaviour
+
+    *   `options.logo` **([Boolean][94] | [String][95])** Add a logo to the output, if boolean true the Tera-tools logo is used otherwise specify a path or URL (optional, default `false`)
+
+## uiWindow
+
+Open a popup window containing a new site
+
+### Parameters
+
+*   `url` **[String][95]** The URL to open
+*   `options` **[Object][93]?** Additional options to mutate behaviour
+
+    *   `options.width` **[Number][96]** The desired width of the window (optional, default `500`)
+    *   `options.height` **[Number][96]** The desired height of the window (optional, default `600`)
+    *   `options.center` **[Boolean][94]** Attempt to center the window on the screen (optional, default `true`)
+    *   `options.permissions` **[Object][93]?** 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)
 
 [1]: #terafy
 
@@ -680,90 +776,114 @@ Returns **[Promise][87]** A promise which resolves when the alert has been dismi
 
 [47]: #requireuser
 
-[48]: #
+[48]: #parameters-14
+
+[49]: #
+
+[50]: #project
+
+[51]: #getproject
+
+[52]: #getprojects
+
+[53]: #setactiveproject
+
+[54]: #parameters-15
+
+[55]: #requireproject
+
+[56]: #parameters-16
+
+[57]: #selectproject
+
+[58]: #parameters-17
+
+[59]: #getprojectstate
+
+[60]: #parameters-18
 
-[49]: #project
+[61]: #setprojectstate
 
-[50]: #getproject
+[62]: #parameters-19
 
-[51]: #getprojects
+[63]: #setprojectstatedefaults
 
-[52]: #setactiveproject
+[64]: #parameters-20
 
-[53]: #parameters-14
+[65]: #saveprojectstate
 
-[54]: #requireproject
+[66]: #replaceprojectstate
 
-[55]: #parameters-15
+[67]: #parameters-21
 
-[56]: #selectproject
+[68]: #applyprojectstatepatch
 
-[57]: #parameters-16
+[69]: #parameters-22
 
-[58]: #getprojectstate
+[70]: #subscribeprojectstate
 
-[59]: #parameters-17
+[71]: #projectfile
 
-[60]: #setprojectstate
+[72]: #properties-4
 
-[61]: #parameters-18
+[73]: #filefilters
 
-[62]: #setprojectstatedefaults
+[74]: #properties-5
 
-[63]: #parameters-19
+[75]: #selectprojectfile
 
-[64]: #saveprojectstate
+[76]: #parameters-23
 
-[65]: #replaceprojectstate
+[77]: #getprojectfiles
 
-[66]: #parameters-20
+[78]: #parameters-24
 
-[67]: #applyprojectstatepatch
+[79]: #selectprojectlibrary
 
-[68]: #parameters-21
+[80]: #parameters-25
 
-[69]: #subscribeprojectstate
+[81]: #parseprojectlibrary
 
-[70]: #projectfile
+[82]: #parameters-26
 
-[71]: #properties-4
+[83]: #setprojectlibrary
 
-[72]: #getprojectfiles
+[84]: #parameters-27
 
-[73]: #parameters-22
+[85]: #setprojectlibrary-1
 
-[74]: #selectprojectlibrary
+[86]: #parameters-28
 
-[75]: #parameters-23
+[87]: #uialert
 
-[76]: #setprojectlibrary
+[88]: #parameters-29
 
-[77]: #parameters-24
+[89]: #uisplat
 
-[78]: #setprojectlibrary-1
+[90]: #parameters-30
 
-[79]: #parameters-25
+[91]: #uiwindow
 
-[80]: #uialert
+[92]: #parameters-31
 
-[81]: #parameters-26
+[93]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
 
-[82]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
+[94]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
 
-[83]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
+[95]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
 
-[84]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
+[96]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
 
-[85]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
+[97]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array
 
-[86]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array
+[98]: https://developer.mozilla.org/docs/Web/API/Window
 
-[87]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise
+[99]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise
 
-[88]: https://developer.mozilla.org/docs/Web/API/MessageEvent
+[100]: https://developer.mozilla.org/docs/Web/API/MessageEvent
 
-[89]: http://jsonpatch.com
+[101]: http://jsonpatch.com
 
-[90]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Date
+[102]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Date
 
-[91]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function
+[103]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function