@iebh/tera-fy 1.3.2 → 1.4.0

package/api.md

@@ -3,33 +3,33 @@
 ### Table of Contents
 
 *   [ProjectFile][1]
-    *   [tera][2]
-        *   [Parameters][3]
-    *   [id][4]
-    *   [name][5]
-    *   [icon][6]
-    *   [path][7]
-    *   [parsedName][8]
-        *   [Properties][9]
-    *   [created][10]
-    *   [createdFormatted][11]
-    *   [modified][12]
-    *   [modifiedFormatted][13]
-    *   [accessed][14]
-    *   [accessedFormatted][15]
-    *   [size][16]
-    *   [sizeFormatted][17]
-    *   [mime][18]
-    *   [meta][19]
-    *   [getContents][20]
-    *   [setContents][21]
-        *   [Parameters][22]
-    *   [getRefs][23]
-    *   [setRefs][24]
-        *   [Parameters][25]
-    *   [serialize][26]
-    *   [deserialize][27]
-        *   [Parameters][28]
+    *   [id][2]
+    *   [name][3]
+    *   [icon][4]
+    *   [path][5]
+    *   [parsedName][6]
+        *   [Properties][7]
+    *   [created][8]
+    *   [createdFormatted][9]
+    *   [modified][10]
+    *   [modifiedFormatted][11]
+    *   [accessed][12]
+    *   [accessedFormatted][13]
+    *   [size][14]
+    *   [sizeFormatted][15]
+    *   [mime][16]
+    *   [meta][17]
+    *   [getContents][18]
+    *   [setContents][19]
+        *   [Parameters][20]
+    *   [getRefs][21]
+    *   [setRefs][22]
+        *   [Parameters][23]
+    *   [serialize][24]
+    *   [deserialize][25]
+        *   [Parameters][26]
+*   [tera][27]
+    *   [Parameters][28]
 *   [TeraFy][29]
     *   [settings][30]
         *   [Properties][31]
@@ -117,122 +117,116 @@
     *   [Parameters][113]
 *   [setProjectLibrary][114]
     *   [Parameters][115]
-*   [uiAlert][116]
+*   [projectLog][116]
     *   [Parameters][117]
-*   [uiSplat][118]
+*   [uiAlert][118]
     *   [Parameters][119]
-*   [uiWindow][120]
+*   [uiSplat][120]
     *   [Parameters][121]
+*   [uiWindow][122]
+    *   [Parameters][123]
 
 ## ProjectFile
 
 A project file fetched from TERA
 
-### tera
-
-Parent TeraClient instance used by all helper functions
-
-#### Parameters
-
-*   `TeraClient`  
-
 ### id
 
 A UUID string representing the unique ID of the file
 
-Type: [String][122]
+Type: [String][124]
 
 ### name
 
 Relative name path (can contain prefix directories) for the human readable file name
 
-Type: [String][122]
+Type: [String][124]
 
 ### icon
 
 CSS class to use as the file icon
 
-Type: [String][122]
+Type: [String][124]
 
 ### path
 
 Full path to the file
 This is also used as the unique identifier within the project
 
-Type: [String][122]
+Type: [String][124]
 
 ### parsedName
 
 An object representing meta file parts of a file name
 
-Type: [Object][123]
+Type: [Object][125]
 
 #### Properties
 
-*   `basename` **[String][122]** The filename + extention (i.e. everything without directory name)
-*   `filename` **[String][122]** The file portion of the name (basename without the extension)
-*   `ext` **[String][122]** The extension portion of the name (always lower case)
-*   `dirName` **[String][122]** The directory path portion of the name
+*   `basename` **[String][124]** The filename + extention (i.e. everything without directory name)
+*   `filename` **[String][124]** The file portion of the name (basename without the extension)
+*   `ext` **[String][124]** The extension portion of the name (always lower case)
+*   `dirName` **[String][124]** The directory path portion of the name
 
 ### created
 
 A date representing when the file was created
 
-Type: [Date][124]
+Type: [Date][126]
 
 ### createdFormatted
 
 A human readable, formatted version of "created"
 
-Type: [String][122]
+Type: [String][124]
 
 ### modified
 
 A date representing when the file was created
 
-Type: [Date][124]
+Type: [Date][126]
 
 ### modifiedFormatted
 
 A human readable, formatted version of "modified"
 
-Type: [String][122]
+Type: [String][124]
 
 ### accessed
 
 A date representing when the file was last accessed
 
-Type: [Date][124]
+Type: [Date][126]
 
 ### accessedFormatted
 
 A human readable, formatted version of "accessed"
 
-Type: [String][122]
+Type: [String][124]
 
 ### size
 
 Size, in bytes, of the file
 
-Type: [Number][125]
+Type: [Number][127]
 
 ### sizeFormatted
 
 A human readable, formatted version of the file size
 
-Type: [String][122]
+Type: [String][124]
 
 ### mime
 
 The associated mime type for the file
 
-Type: [String][122]
+Type: [String][124]
 
 ### meta
 
 Additional meta information for the file
 
-Type: [Object][123]
+Type: [Object][125]
 
 ### getContents
 
@@ -250,9 +244,9 @@ Overwrite the contents of a file with new content
 
 #### Parameters
 
-*   `contents` **(File | [Blob][126] | [FormData][127] | [Object][123] | [Array][128])** The new file contents
+*   `contents` **(File | [Blob][128] | [FormData][129] | [Object][125] | [Array][130])** The new file contents
 
-Returns **[Promise][129]** A promise which resolves when the operation has completed
+Returns **[Promise][131]** A promise which resolves when the operation has completed
 
 ### getRefs
 
@@ -260,7 +254,7 @@ Returns **[Promise][129]** A promise which resolves when the operation has compl
 
 Fetch the file contents as an array of Reflib refs
 
-Returns **[Promise][129]<[Array][128]\<Ref>>** An eventual array of RefLib references
+Returns **[Promise][131]<[Array][130]\<Ref>>** An eventual array of RefLib references
 
 ### setRefs
 
@@ -271,18 +265,18 @@ Overwrite the contents of a file with a new collection of Reflib refs
 #### Parameters
 
 *   `refs` &#x20;
-*   `Collection` **[Array][128]\<RefLibRef>** of references for the selected library
+*   `Collection` **[Array][130]\<RefLibRef>** of references for the selected library
 
-Returns **[Promise][129]** A promise which resolves when the operation has completed
+Returns **[Promise][131]** A promise which resolves when the operation has completed
 
 ### serialize
 
-*   **See**: [https://developer.mozilla.org/en-US/docs/Web/API/Web\_Workers\_API/Structured\_clone\_algorithm][130]
+*   **See**: [https://developer.mozilla.org/en-US/docs/Web/API/Web\_Workers\_API/Structured\_clone\_algorithm][132]
 
 Compress a file state down into a serializable entity
 By default this computes a Structured Clone which can be stringified
 
-Returns **[Object][123]** A Structured Clone compatible representation of this ProjectFile instance
+Returns **[Object][125]** A Structured Clone compatible representation of this ProjectFile instance
 
 ### deserialize
 
@@ -290,10 +284,18 @@ Restore an entity created with serialize
 
 #### Parameters
 
-*   `data` **[Object][123]** An input object created via `ProjectFiles.serialize()`
+*   `data` **[Object][125]** An input object created via `ProjectFiles.serialize()`
 
 Returns **[ProjectFile][1]** A ProjectFile instance setup against the deserializzed data
 
+## tera
+
+Parent TeraClient instance used by all helper functions
+
+### Parameters
+
+*   `TeraClient` &#x20;
+
 ## TeraFy
 
 Main Tera-Fy Client (class singleton) to be used in a frontend browser
@@ -302,18 +304,18 @@ Main Tera-Fy Client (class singleton) to be used in a frontend browser
 
 Various settings to configure behaviour
 
-Type: [Object][123]
+Type: [Object][125]
 
 #### Properties
 
-*   `devMode` **[Boolean][131]** Operate in devMode - i.e. force outer refresh when encountering an existing TeraFy instance
+*   `devMode` **[Boolean][133]** 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][122]** Method to use when all method detection fails
-*   `modeTimeout` **[Number][125]** How long entities have in 'detect' mode to identify themselves
-*   `siteUrl` **[String][122]** The TERA URL to connect to
-*   `restrictOrigin` **[String][122]** URL to restrict communications to
-*   `List` **[Array][128]<[String][122]>** of sandbox allowables for the embedded if in embed mode
-*   `handshakeInterval` **[Number][125]** Interval in milliseconds when sanning for a handshake
+*   `modeFallback` **[String][124]** Method to use when all method detection fails
+*   `modeTimeout` **[Number][127]** How long entities have in 'detect' mode to identify themselves
+*   `siteUrl` **[String][124]** The TERA URL to connect to
+*   `restrictOrigin` **[String][124]** URL to restrict communications to
+*   `List` **[Array][130]<[String][124]>** of sandbox allowables for the embedded if in embed mode
+*   `handshakeInterval` **[Number][127]** Interval in milliseconds when sanning for a handshake
 
 ### events
 
@@ -325,13 +327,13 @@ Type: Mitt
 
 DOMElements for this TeraFy instance
 
-Type: [Object][123]
+Type: [Object][125]
 
 #### Properties
 
 *   `el` **DOMElement** The main tera-fy div wrapper
 *   `iframe` **DOMElement** The internal iFrame element  (if `settings.mode == 'child'`)
-*   `popup` **[Window][132]** The popup window context (if `settings.mode == 'popup'`)
+*   `popup` **[Window][134]** The popup window context (if `settings.mode == 'popup'`)
 *   `stylesheet` **DOMElement** The corresponding stylesheet
 
 ### methods
@@ -339,13 +341,13 @@ Type: [Object][123]
 List of function stubs mapped from the server to here
 This array is forms the reference of `TeraFy.METHOD()` objects to provide locally which will be mapped via `TeraFy.rpc(METHOD, ...args)`
 
-Type: [Array][128]<[String][122]>
+Type: [Array][130]<[String][124]>
 
 ### plugins
 
 Loaded plugins via Use()
 
-Type: [Array][128]\<TeraFyPlugin>
+Type: [Array][130]\<TeraFyPlugin>
 
 ### send
 
@@ -353,9 +355,9 @@ Send a message + wait for a response object
 
 #### Parameters
 
-*   `message` **[Object][123]** Message object to send
+*   `message` **[Object][125]** Message object to send
 
-Returns **[Promise][129]\<any>** A promise which resolves when the operation has completed with the remote reply
+Returns **[Promise][131]\<any>** A promise which resolves when the operation has completed with the remote reply
 
 ### sendRaw
 
@@ -364,7 +366,7 @@ This function does not return or wait for a reply - use `send()` for that
 
 #### Parameters
 
-*   `message` **[Object][123]** Message object to send
+*   `message` **[Object][125]** Message object to send
 
 ### rpc
 
@@ -372,10 +374,10 @@ Call an RPC function in the server instance
 
 #### Parameters
 
-*   `method` **[String][122]** The method name to call
+*   `method` **[String][124]** The method name to call
 *   `args` **...any**&#x20;
 
-Returns **[Promise][129]\<any>** The resolved output of the server function
+Returns **[Promise][131]\<any>** The resolved output of the server function
 
 ### acceptMessage
 
@@ -384,7 +386,7 @@ Accept an incoming message
 #### Parameters
 
 *   `rawMessage` &#x20;
-*   `Raw` **[MessageEvent][133]** message event to process
+*   `Raw` **[MessageEvent][135]** message event to process
 
 ### acceptPostboxes
 
@@ -393,27 +395,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][134] standard
+The transmitted patch follows the [JSPatch][136] standard
 This function accepts an entire projectState instance, computes the delta and transmits that to the server for merging
 
 #### Parameters
 
-*   `newState` **[Object][123]** The local projectState to accept
-*   `oldState` **[Object][123]** The previous projectState to examine against
+*   `newState` **[Object][125]** The local projectState to accept
+*   `oldState` **[Object][125]** The previous projectState to examine against
 
-Returns **[Promise][129]** A promise which will resolve when the operation has completed
+Returns **[Promise][131]** 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][134] standard
+The patch should follow the [JSPatch][136] standard
 This function is expected to be sub-classed by a plugin
 
 #### Parameters
 
-*   `patch` **[Array][128]** A JSPatch patch to apply
+*   `patch` **[Array][130]** A JSPatch patch to apply
 
-Returns **[Promise][129]** A promise which will resolve when the operation has completed
+Returns **[Promise][131]** A promise which will resolve when the operation has completed
 
 ### init
 
@@ -422,28 +424,28 @@ This function can only be called once and will return the existing init() worker
 
 #### Parameters
 
-*   `options` **[Object][123]?** Additional options to merge into `settings` via `set`
+*   `options` **[Object][125]?** Additional options to merge into `settings` via `set`
 
-Returns **[Promise][129]<[TeraFy][29]>** An eventual promise which will resovle with this terafy instance
+Returns **[Promise][131]<[TeraFy][29]>** 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][129]<[String][122]>** A promise which will resolve with the detected mode to use
+Returns **[Promise][131]<[String][124]>** A promise which will resolve with the detected mode to use
 
 ### injectComms
 
 Find an existing active TERA server OR initalize one
 
-Returns **[Promise][129]** A promise which will resolve when the loading has completed and we have found a parent TERA instance or initiallized a child
+Returns **[Promise][131]** A promise which will resolve when the loading has completed and we have found a parent TERA instance or initiallized a child
 
 ### injectStylesheet
 
 Inject a local stylesheet to handle TERA server functionality
 
-Returns **[Promise][129]** A promise which will resolve when the loading has completed and we have found a parent TERA instance or initiallized a child
+Returns **[Promise][131]** A promise which will resolve when the loading has completed and we have found a parent TERA instance or initiallized a child
 
 ### injectMethods
 
@@ -466,7 +468,7 @@ This function also routes 'special' keys like `devMode` to their internal handle
 
 #### Parameters
 
-*   `key` **([String][122] | [Object][123])** Either a single setting key to set or an object to merge
+*   `key` **([String][124] | [Object][125])** 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][29]** This chainable terafy instance
@@ -479,7 +481,7 @@ Set or merge settings - but only in dev mode and only if the value is not undefi
 
 #### Parameters
 
-*   `key` **([String][122] | [Object][123])** Either a single setting key to set or an object to merge
+*   `key` **([String][124] | [Object][125])** 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][29]** This chainable terafy instance
@@ -491,8 +493,8 @@ Include a TeraFy client plugin
 #### Parameters
 
 *   `mod` &#x20;
-*   `options` **[Object][123]?** Additional options to mutate behaviour during construction (pass options to init() to intialize later options)
-*   `The` **[Object][123]** module function to include. Invoked as `(teraClient:TeraFy, options:Object)`
+*   `options` **[Object][125]?** Additional options to mutate behaviour during construction (pass options to init() to intialize later options)
+*   `The` **[Object][125]** module function to include. Invoked as `(teraClient:TeraFy, options:Object)`
 
 Returns **[TeraFy][29]** This chainable terafy instance
 
@@ -502,8 +504,8 @@ Internal function used by use() to merge an external declared singleton against
 
 #### Parameters
 
-*   `target` **[Object][123]** Initalied class instance to extend
-*   `source` **[Object][123]** Initalized source object to extend from
+*   `target` **[Object][125]** Initalied class instance to extend
+*   `source` **[Object][125]** Initalized source object to extend from
 
 ### toggleDevMode
 
@@ -511,7 +513,7 @@ Set or toggle devMode
 
 #### Parameters
 
-*   `devModeEnabled` **([String][122] | [Boolean][131])** Optional boolean to force dev mode (optional, default `'toggle'`)
+*   `devModeEnabled` **([String][124] | [Boolean][133])** Optional boolean to force dev mode (optional, default `'toggle'`)
 
 Returns **[TeraFy][29]** This chainable terafy instance
 
@@ -522,7 +524,7 @@ This is usually because the server component wants to perform some user activity
 
 #### Parameters
 
-*   `isFocused` **([String][122] | [Boolean][131])** Whether to fullscreen the embedded component (optional, default `'toggle'`)
+*   `isFocused` **([String][124] | [Boolean][133])** Whether to fullscreen the embedded component (optional, default `'toggle'`)
 
 ### selectProjectFile
 
@@ -534,7 +536,7 @@ This is an pre-requisite step for requireProject()
 
 *   `options` &#x20;
 
-Returns **[Promise][129]** A promise which will resolve if the there is a user and they are logged in
+Returns **[Promise][131]** A promise which will resolve if the there is a user and they are logged in
 
 ### getProjectFiles
 
@@ -542,12 +544,12 @@ Fetch the files associated with a given project
 
 #### Parameters
 
-*   `options` **[Object][123]** Options which mutate behaviour
+*   `options` **[Object][125]** Options which mutate behaviour
 
-    *   `options.autoRequire` **[Boolean][131]** Run `requireProject()` automatically before continuing (optional, default `true`)
-    *   `options.meta` **[Boolean][131]** Pull meta information for each file entity (optional, default `true`)
+    *   `options.autoRequire` **[Boolean][133]** Run `requireProject()` automatically before continuing (optional, default `true`)
+    *   `options.meta` **[Boolean][133]** Pull meta information for each file entity (optional, default `true`)
 
-Returns **[Promise][129]<[Array][128]<[ProjectFile][1]>>** A collection of project files for the given project
+Returns **[Promise][131]<[Array][130]<[ProjectFile][1]>>** A collection of project files for the given project
 
 ### getProjectFile
 
@@ -555,9 +557,9 @@ Fetch a project file
 
 #### Parameters
 
-*   `path` **[String][122]** File path to read
+*   `path` **[String][124]** File path to read
 
-Returns **[Promise][129]<[Blob][126]>** The eventual fetched file as a blob
+Returns **[Promise][131]<[Blob][128]>** The eventual fetched file as a blob
 
 ## handshake
 
@@ -565,9 +567,9 @@ Return basic server information as a form of validation
 
 ### Properties
 
-*   `date` **[Date][124]** Server date
+*   `date` **[Date][126]** Server date
 
-Returns **[Promise][129]<[Object][123]>** Basic promise result
+Returns **[Promise][131]<[Object][125]>** Basic promise result
 
 ## User
 
@@ -575,16 +577,16 @@ User / active session within TERA
 
 ### Properties
 
-*   `id` **[String][122]** Unique identifier of the user
-*   `email` **[String][122]** The email address of the current user
-*   `name` **[String][122]** The provided full name of the user
-*   `isSubscribed` **[Boolean][131]** Whether the active user has a TERA subscription
+*   `id` **[String][124]** Unique identifier of the user
+*   `email` **[String][124]** The email address of the current user
+*   `name` **[String][124]** The provided full name of the user
+*   `isSubscribed` **[Boolean][133]** Whether the active user has a TERA subscription
 
 ## getUser
 
 Fetch the current session user
 
-Returns **[Promise][129]<[User][78]>** The current logged in user or null if none
+Returns **[Promise][131]<[User][78]>** The current logged in user or null if none
 
 ## requireUser
 
@@ -594,11 +596,11 @@ This is an pre-requisite step for requireProject()
 
 ### Parameters
 
-*   `options` **[Object][123]?** Additional options to mutate behaviour
+*   `options` **[Object][125]?** Additional options to mutate behaviour
 
-    *   `options.forceRetry` **[Boolean][131]** Forcabily try to refresh the user state (optional, default `false`)
+    *   `options.forceRetry` **[Boolean][133]** Forcabily try to refresh the user state (optional, default `false`)
 
-Returns **[Promise][129]<[User][78]>** The current logged in user or null if none
+Returns **[Promise][131]<[User][78]>** The current logged in user or null if none
 
 ## Project
 
@@ -608,13 +610,13 @@ Project entry within TERA
 
 Get the currently active project, if any
 
-Returns **[Promise][129]<([Project][83] | null)>** The currently active project, if any
+Returns **[Promise][131]<([Project][83] | null)>** The currently active project, if any
 
 ## getProjects
 
 Get a list of projects the current session user has access to
 
-Returns **[Promise][129]<[Array][128]<[Project][83]>>** Collection of projects the user has access to
+Returns **[Promise][131]<[Array][130]<[Project][83]>>** Collection of projects the user has access to
 
 ## setActiveProject
 
@@ -622,7 +624,7 @@ Set the currently active project within TERA
 
 ### Parameters
 
-*   `project` **([Object][123] | [String][122])** The project to set as active - either the full Project object or its ID
+*   `project` **([Object][125] | [String][124])** The project to set as active - either the full Project object or its ID
 
 ## requireProject
 
@@ -631,14 +633,14 @@ Note that this function will percist in asking the uesr even if they try to canc
 
 ### Parameters
 
-*   `options` **[Object][123]?** Additional options to mutate behaviour
+*   `options` **[Object][125]?** Additional options to mutate behaviour
 
-    *   `options.autoSetActiveProject` **[Boolean][131]** After selecting a project set that project as active in TERA (optional, default `true`)
-    *   `options.title` **[String][122]** The title of the dialog to display (optional, default `"Select a project to work with"`)
-    *   `options.noSelectTitle` **[String][122]** Dialog title when warning the user they need to select something (optional, default `'Select project'`)
-    *   `options.noSelectBody` **[String][122]** Dialog body when warning the user they need to select something (optional, default `'A project needs to be selected to continue'`)
+    *   `options.autoSetActiveProject` **[Boolean][133]** After selecting a project set that project as active in TERA (optional, default `true`)
+    *   `options.title` **[String][124]** The title of the dialog to display (optional, default `"Select a project to work with"`)
+    *   `options.noSelectTitle` **[String][124]** Dialog title when warning the user they need to select something (optional, default `'Select project'`)
+    *   `options.noSelectBody` **[String][124]** Dialog body when warning the user they need to select something (optional, default `'A project needs to be selected to continue'`)
 
-Returns **[Promise][129]<[Project][83]>** The active project
+Returns **[Promise][131]<[Project][83]>** The active project
 
 ## selectProject
 
@@ -646,13 +648,13 @@ Prompt the user to select a project from those available
 
 ### Parameters
 
-*   `options` **[Object][123]?** Additional options to mutate behaviour
+*   `options` **[Object][125]?** Additional options to mutate behaviour
 
-    *   `options.title` **[String][122]** The title of the dialog to display (optional, default `"Select a project to work with"`)
-    *   `options.allowCancel` **[Boolean][131]** Advertise cancelling the operation, the dialog can still be cancelled by closing it (optional, default `true`)
-    *   `options.setActive` **[Boolean][131]** Also set the project as active when selected (optional, default `false`)
+    *   `options.title` **[String][124]** The title of the dialog to display (optional, default `"Select a project to work with"`)
+    *   `options.allowCancel` **[Boolean][133]** Advertise cancelling the operation, the dialog can still be cancelled by closing it (optional, default `true`)
+    *   `options.setActive` **[Boolean][133]** Also set the project as active when selected (optional, default `false`)
 
-Returns **[Promise][129]<[Project][83]>** The active project
+Returns **[Promise][131]<[Project][83]>** The active project
 
 ## getProjectState
 
@@ -660,12 +662,12 @@ Return the current, full snapshot state of the active project
 
 ### Parameters
 
-*   `options` **[Object][123]?** Additional options to mutate behaviour
+*   `options` **[Object][125]?** Additional options to mutate behaviour
 
-    *   `options.autoRequire` **[Boolean][131]** Run `requireProject()` automatically before continuing (optional, default `true`)
-*   `Paths` **[Array][128]<[String][122]>** to subscribe to e.g. \['/users/'],
+    *   `options.autoRequire` **[Boolean][133]** Run `requireProject()` automatically before continuing (optional, default `true`)
+*   `Paths` **[Array][130]<[String][124]>** to subscribe to e.g. \['/users/'],
 
-Returns **[Promise][129]<[Object][123]>** The current project state snapshot
+Returns **[Promise][131]<[Object][125]>** The current project state snapshot
 
 ## setProjectState
 
@@ -677,13 +679,13 @@ Paths can be any valid Lodash.set() value such as:
 
 ### Parameters
 
-*   `path` **([String][122] | [Array][128]<[String][122]>)** The sub-path within the project state to set
+*   `path` **([String][124] | [Array][130]<[String][124]>)** The sub-path within the project state to set
 *   `value` **any** The value to set
-*   `options` **[Object][123]?** Additional options to mutate behaviour
+*   `options` **[Object][125]?** Additional options to mutate behaviour
 
-    *   `options.save` **[Boolean][131]** Save the changes to the server immediately, disable to queue up multiple writes (optional, default `true`)
+    *   `options.save` **[Boolean][133]** Save the changes to the server immediately, disable to queue up multiple writes (optional, default `true`)
 
-Returns **[Promise][129]** A promise which resolves when the operation has been dispatched to the server
+Returns **[Promise][131]** A promise which resolves when the operation has been dispatched to the server
 
 ## setProjectStateDefaults
 
@@ -693,17 +695,17 @@ Set a nested value within the project state - just like `setProjectState()` - bu
 
 ### Parameters
 
-*   `path` **([String][122] | [Array][128]<[String][122]>)** The sub-path within the project state to set
+*   `path` **([String][124] | [Array][130]<[String][124]>)** The sub-path within the project state to set
 *   `value` **any** The value to set
-*   `options` **[Object][123]?** Additional options to mutate behaviour, see setProjectState() for the full list of supported options
+*   `options` **[Object][125]?** Additional options to mutate behaviour, see setProjectState() for the full list of supported options
 
-Returns **[Promise][129]<[Boolean][131]>** A promise which resolves to whether any changes were made - True if defaults were applied, false otherwise
+Returns **[Promise][131]<[Boolean][133]>** 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][129]** A promise which resolves when the operation has completed
+Returns **[Promise][131]** A promise which resolves when the operation has completed
 
 ## replaceProjectState
 
@@ -714,9 +716,9 @@ You almost never want to use this function directly, see `setProjectState(path,
 
 ### Parameters
 
-*   `newState` **[Object][123]** The new state to replace the current state with
+*   `newState` **[Object][125]** The new state to replace the current state with
 
-Returns **[Promise][129]** A promise which resolves when the operation has completed
+Returns **[Promise][131]** A promise which resolves when the operation has completed
 
 ## applyProjectStatePatch
 
@@ -724,9 +726,9 @@ Apply a computed `just-diff` patch to the current project state
 
 ### Parameters
 
-*   `Patch` **[Object][123]** to apply
+*   `Patch` **[Object][125]** to apply
 
-Returns **[Promise][129]** A promise which resolves when the operation has completed
+Returns **[Promise][131]** A promise which resolves when the operation has completed
 
 ## subscribeProjectState
 
@@ -734,7 +736,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][129]<[Function][135]>** A promise which resolves when a subscription has been created, call the resulting function to unsubscribe
+Returns **[Promise][131]<[Function][137]>** A promise which resolves when a subscription has been created, call the resulting function to unsubscribe
 
 ## FileFilters
 
@@ -742,10 +744,10 @@ Data structure for a file filter
 
 ### Properties
 
-*   `library` **[Boolean][131]?** Restrict to library files only
-*   `filename` **[String][122]?** CSV of @momsfriendlydevco/match expressions to filter the filename by (filenames are the basename sans extension)
-*   `basename` **[String][122]?** CSV of @momsfriendlydevco/match expressions to filter the basename by
-*   `ext` **[String][122]?** CSV of @momsfriendlydevco/match expressions to filter the file extension by
+*   `library` **[Boolean][133]?** Restrict to library files only
+*   `filename` **[String][124]?** CSV of @momsfriendlydevco/match expressions to filter the filename by (filenames are the basename sans extension)
+*   `basename` **[String][124]?** CSV of @momsfriendlydevco/match expressions to filter the basename by
+*   `ext` **[String][124]?** CSV of @momsfriendlydevco/match expressions to filter the file extension by
 
 ## selectProjectFile
 
@@ -753,20 +755,20 @@ Prompt the user to select a library to operate on
 
 ### Parameters
 
-*   `options` **[Object][123]?** Additional options to mutate behaviour
+*   `options` **[Object][125]?** Additional options to mutate behaviour
 
-    *   `options.title` **[String][122]** The title of the dialog to display (optional, default `"Select a file"`)
-    *   `options.hint` **([String][122] | [Array][128]<[String][122]>)?** Hints to identify the file to select in array order of preference
-    *   `options.save` **[Boolean][131]** Set to truthy if saving a new file, UI will adjust to allowing overwrite OR new file name input (optional, default `false`)
+    *   `options.title` **[String][124]** The title of the dialog to display (optional, default `"Select a file"`)
+    *   `options.hint` **([String][124] | [Array][130]<[String][124]>)?** Hints to identify the file to select in array order of preference
+    *   `options.save` **[Boolean][133]** Set to truthy if saving a new file, UI will adjust to allowing overwrite OR new file name input (optional, default `false`)
     *   `options.filters` **[FileFilters][104]?** Optional file filters
-    *   `options.allowUpload` **[Boolean][131]** Allow uploading new files (optional, default `true`)
-    *   `options.allowRefresh` **[Boolean][131]** Allow the user to manually refresh the file list (optional, default `true`)
-    *   `options.allowDownloadZip` **[Boolean][131]** Allow the user to download a Zip of all files (optional, default `true`)
-    *   `options.allowCancel` **[Boolean][131]** Allow cancelling the operation. Will throw `'CANCEL'` as the promise rejection if acationed (optional, default `true`)
-    *   `options.autoRequire` **[Boolean][131]** Run `requireProject()` automatically before continuing (optional, default `true`)
+    *   `options.allowUpload` **[Boolean][133]** Allow uploading new files (optional, default `true`)
+    *   `options.allowRefresh` **[Boolean][133]** Allow the user to manually refresh the file list (optional, default `true`)
+    *   `options.allowDownloadZip` **[Boolean][133]** Allow the user to download a Zip of all files (optional, default `true`)
+    *   `options.allowCancel` **[Boolean][133]** Allow cancelling the operation. Will throw `'CANCEL'` as the promise rejection if acationed (optional, default `true`)
+    *   `options.autoRequire` **[Boolean][133]** Run `requireProject()` automatically before continuing (optional, default `true`)
     *   `options.filter` **[FileFilters][104]?** Optional file filters
 
-Returns **[Promise][129]<[ProjectFile][1]>** The eventually selected file
+Returns **[Promise][131]<[ProjectFile][1]>** The eventually selected file
 
 ## setProjectFile
 
@@ -774,10 +776,10 @@ Replace a project files contents
 
 ### Parameters
 
-*   `path` **[String][122]** File path to write
-*   `contents` **(File | [Blob][126] | [FormData][127] | [Object][123] | [Array][128])** The new file contents
+*   `path` **[String][124]** File path to write
+*   `contents` **(File | [Blob][128] | [FormData][129] | [Object][125] | [Array][130])** The new file contents
 
-Returns **[Promise][129]** A promise which will resolve when the write operation has completed
+Returns **[Promise][131]** A promise which will resolve when the write operation has completed
 
 ## selectProjectLibrary
 
@@ -785,18 +787,18 @@ Prompt the user to select a library to operate on and return a array of referenc
 
 ### Parameters
 
-*   `options` **[Object][123]?** Additional options to mutate behaviour
+*   `options` **[Object][125]?** Additional options to mutate behaviour
 
-    *   `options.title` **[String][122]** The title of the dialog to display (optional, default `"Select a citation library"`)
-    *   `options.hint` **([String][122] | [Array][128]<[String][122]>)?** 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][131]** Allow uploading new files (optional, default `true`)
-    *   `options.allowRefresh` **[Boolean][131]** Allow the user to manually refresh the file list (optional, default `true`)
-    *   `options.allowDownloadZip` **[Boolean][131]** Allow the user to download a Zip of all files (optional, default `true`)
-    *   `options.allowCancel` **[Boolean][131]** Allow cancelling the operation. Will throw `'CANCEL'` as the promise rejection if acationed (optional, default `true`)
-    *   `options.autoRequire` **[Boolean][131]** Run `requireProject()` automatically before continuing (optional, default `true`)
+    *   `options.title` **[String][124]** The title of the dialog to display (optional, default `"Select a citation library"`)
+    *   `options.hint` **([String][124] | [Array][130]<[String][124]>)?** 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][133]** Allow uploading new files (optional, default `true`)
+    *   `options.allowRefresh` **[Boolean][133]** Allow the user to manually refresh the file list (optional, default `true`)
+    *   `options.allowDownloadZip` **[Boolean][133]** Allow the user to download a Zip of all files (optional, default `true`)
+    *   `options.allowCancel` **[Boolean][133]** Allow cancelling the operation. Will throw `'CANCEL'` as the promise rejection if acationed (optional, default `true`)
+    *   `options.autoRequire` **[Boolean][133]** Run `requireProject()` automatically before continuing (optional, default `true`)
     *   `options.filters` **[FileFilters][104]?** Optional file filters, defaults to citation library selection only
 
-Returns **[Promise][129]<[Array][128]\<Ref>>** A collection of references from the selected file
+Returns **[Promise][131]<[Array][130]\<Ref>>** A collection of references from the selected file
 
 ## getProjectLibrary
 
@@ -804,15 +806,15 @@ Fetch + convert a project file into a library of citations
 
 ### Parameters
 
-*   `path` **[String][122]** File path to read, if omitted the contents of `options` are used to guess at a suitable file
-*   `options` **[Object][123]?** Additional options to mutate behaviour
+*   `path` **[String][124]** File path to read, if omitted the contents of `options` are used to guess at a suitable file
+*   `options` **[Object][125]?** Additional options to mutate behaviour
 
-    *   `options.format` **[String][122]** 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][131]** Run `requireProject()` automatically before continuing (optional, default `true`)
-    *   `options.filter` **[Function][135]?** Optional async file filter, called each time as `(File:ProjectFile)`
-    *   `options.find` **[Function][135]?** Optional async final stage file filter to reduce all candidates down to one subject file
+    *   `options.format` **[String][124]** 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][133]** Run `requireProject()` automatically before continuing (optional, default `true`)
+    *   `options.filter` **[Function][137]?** Optional async file filter, called each time as `(File:ProjectFile)`
+    *   `options.find` **[Function][137]?** Optional async final stage file filter to reduce all candidates down to one subject file
 
-Returns **([Promise][129]<[Array][128]\<Ref>> | [Promise][129]\<any>)** A collection of references (default bevahiour) or a whatever format was requested
+Returns **([Promise][131]<[Array][130]\<Ref>> | [Promise][131]\<any>)** A collection of references (default bevahiour) or a whatever format was requested
 
 ## setProjectLibrary
 
@@ -820,21 +822,33 @@ Save back a citation library from some input
 
 ### Parameters
 
-*   `path` **[String][122]?** File path to save back to, if omitted one will be prompted for
-*   `refs` **([Array][128]\<RefLibRef> | [Blob][126] | File)?** Collection of references for the selected library or the raw Blob/File
-*   `options` **[Object][123]?** Additional options to mutate behaviour
+*   `path` **[String][124]?** File path to save back to, if omitted one will be prompted for
+*   `refs` **([Array][130]\<RefLibRef> | [Blob][128] | File)?** Collection of references for the selected library or the raw Blob/File
+*   `options` **[Object][125]?** Additional options to mutate behaviour
+
+    *   `options.path` **[String][124]?** Alternate method to specify the path to save as, if omitted one will be prompted for
+    *   `options.refs` **([Array][130]\<RefLibRef> | [Blob][128] | File)?** Alternate method to specify the refs to save as an array or raw Blob/File
+    *   `options.format` **[String][124]** 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][133]** Run `requireProject()` automatically before continuing (optional, default `true`)
+    *   `options.hint` **[String][124]?** Hint to store against the library. Generally corresponds to the current operation being performed - e.g. 'deduped'
+    *   `options.filename` **[String][124]?** Suggested filename if path is unspecified
+    *   `options.title` **[String][124]** Dialog title if path is unspecified and we need to prompt (optional, default `'Save citation library'`)
+    *   `options.overwrite` **[Boolean][133]** Allow existing file upsert (optional, default `true`)
+    *   `options.meta` **[Object][125]?** Optional meta data to merge into the file data
+
+Returns **[Promise][131]** A promise which resolves when the save operation has completed
+
+## projectLog
+
+Create a log entry for the currently active project
 
-    *   `options.path` **[String][122]?** Alternate method to specify the path to save as, if omitted one will be prompted for
-    *   `options.refs` **([Array][128]\<RefLibRef> | [Blob][126] | File)?** Alternate method to specify the refs to save as an array or raw Blob/File
-    *   `options.format` **[String][122]** 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][131]** Run `requireProject()` automatically before continuing (optional, default `true`)
-    *   `options.hint` **[String][122]?** Hint to store against the library. Generally corresponds to the current operation being performed - e.g. 'deduped'
-    *   `options.filename` **[String][122]?** Suggested filename if path is unspecified
-    *   `options.title` **[String][122]** Dialog title if path is unspecified and we need to prompt (optional, default `'Save citation library'`)
-    *   `options.overwrite` **[Boolean][131]** Allow existing file upsert (optional, default `true`)
-    *   `options.meta` **[Object][123]?** Optional meta data to merge into the file data
+The required log object can be of various forms. See [https://tera-tools.com/api/logs.json][138] for the full list
 
-Returns **[Promise][129]** A promise which resolves when the save operation has completed
+### Parameters
+
+*   `log` **[Object][125]** The log entry to create
+
+Returns **[Promise][131]** A promise which resolves when the operation has completed
 
 ## uiAlert
 
@@ -842,13 +856,13 @@ Display simple text within TERA
 
 ### Parameters
 
-*   `text` **[String][122]** The text to display
-*   `options` **[Object][123]?** Additional options to mutate behaviour
+*   `text` **[String][124]** The text to display
+*   `options` **[Object][125]?** Additional options to mutate behaviour
 
-    *   `options.title` **[String][122]** The title of the alert box (optional, default `'TERA'`)
-    *   `options.isHtml` **[Boolean][131]** If falsy the text is rendered as plain-text otherwise it will be assumed as HTML content (optional, default `false`)
+    *   `options.title` **[String][124]** The title of the alert box (optional, default `'TERA'`)
+    *   `options.isHtml` **[Boolean][133]** If falsy the text is rendered as plain-text otherwise it will be assumed as HTML content (optional, default `false`)
 
-Returns **[Promise][129]** A promise which resolves when the alert has been dismissed
+Returns **[Promise][131]** A promise which resolves when the alert has been dismissed
 
 ## uiSplat
 
@@ -857,10 +871,10 @@ This function is ideally called within a requestFocus() wrapper
 
 ### Parameters
 
-*   `content` **(DOMElement | [String][122] | `false`)** Either a prepared DOM element or string to compile, set to falsy to remove existing content
-*   `options` **[Object][123]?** Additional options to mutate behaviour
+*   `content` **(DOMElement | [String][124] | `false`)** Either a prepared DOM element or string to compile, set to falsy to remove existing content
+*   `options` **[Object][125]?** Additional options to mutate behaviour
 
-    *   `options.logo` **([Boolean][131] | [String][122])** Add a logo to the output, if boolean true the Tera-tools logo is used otherwise specify a path or URL (optional, default `false`)
+    *   `options.logo` **([Boolean][133] | [String][124])** 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
 
@@ -868,69 +882,69 @@ Open a popup window containing a new site
 
 ### Parameters
 
-*   `url` **[String][122]** The URL to open
-*   `options` **[Object][123]?** Additional options to mutate behaviour
+*   `url` **[String][124]** The URL to open
+*   `options` **[Object][125]?** Additional options to mutate behaviour
 
-    *   `options.width` **[Number][125]** The desired width of the window (optional, default `500`)
-    *   `options.height` **[Number][125]** The desired height of the window (optional, default `600`)
-    *   `options.center` **[Boolean][131]** Attempt to center the window on the screen (optional, default `true`)
-    *   `options.permissions` **[Object][123]?** Additional permissions to set on opening, defaults to a suitable set of permission for popups (see code)
+    *   `options.width` **[Number][127]** The desired width of the window (optional, default `500`)
+    *   `options.height` **[Number][127]** The desired height of the window (optional, default `600`)
+    *   `options.center` **[Boolean][133]** Attempt to center the window on the screen (optional, default `true`)
+    *   `options.permissions` **[Object][125]?** 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]: #projectfile
 
-[2]: #tera
+[2]: #id
 
-[3]: #parameters
+[3]: #name
 
-[4]: #id
+[4]: #icon
 
-[5]: #name
+[5]: #path
 
-[6]: #icon
+[6]: #parsedname
 
-[7]: #path
+[7]: #properties
 
-[8]: #parsedname
+[8]: #created
 
-[9]: #properties
+[9]: #createdformatted
 
-[10]: #created
+[10]: #modified
 
-[11]: #createdformatted
+[11]: #modifiedformatted
 
-[12]: #modified
+[12]: #accessed
 
-[13]: #modifiedformatted
+[13]: #accessedformatted
 
-[14]: #accessed
+[14]: #size
 
-[15]: #accessedformatted
+[15]: #sizeformatted
 
-[16]: #size
+[16]: #mime
 
-[17]: #sizeformatted
+[17]: #meta
 
-[18]: #mime
+[18]: #getcontents
 
-[19]: #meta
+[19]: #setcontents
 
-[20]: #getcontents
+[20]: #parameters
 
-[21]: #setcontents
+[21]: #getrefs
 
-[22]: #parameters-1
+[22]: #setrefs
 
-[23]: #getrefs
+[23]: #parameters-1
 
-[24]: #setrefs
+[24]: #serialize
 
-[25]: #parameters-2
+[25]: #deserialize
 
-[26]: #serialize
+[26]: #parameters-2
 
-[27]: #deserialize
+[27]: #tera
 
 [28]: #parameters-3
 
@@ -1108,42 +1122,48 @@ Returns **WindowProxy** The opened window object (if `noopener` is not set in pe
 
 [115]: #parameters-34
 
-[116]: #uialert
+[116]: #projectlog
 
 [117]: #parameters-35
 
-[118]: #uisplat
+[118]: #uialert
 
 [119]: #parameters-36
 
-[120]: #uiwindow
+[120]: #uisplat
 
 [121]: #parameters-37
 
-[122]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
+[122]: #uiwindow
+
+[123]: #parameters-38
+
+[124]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
+
+[125]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
 
-[123]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
+[126]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Date
 
-[124]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Date
+[127]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
 
-[125]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
+[128]: https://developer.mozilla.org/docs/Web/API/Blob
 
-[126]: https://developer.mozilla.org/docs/Web/API/Blob
+[129]: https://developer.mozilla.org/docs/Web/API/FormData
 
-[127]: https://developer.mozilla.org/docs/Web/API/FormData
+[130]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array
 
-[128]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array
+[131]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise
 
-[129]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise
+[132]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm
 
-[130]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm
+[133]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
 
-[131]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
+[134]: https://developer.mozilla.org/docs/Web/API/Window
 
-[132]: https://developer.mozilla.org/docs/Web/API/Window
+[135]: https://developer.mozilla.org/docs/Web/API/MessageEvent
 
-[133]: https://developer.mozilla.org/docs/Web/API/MessageEvent
+[136]: http://jsonpatch.com
 
-[134]: http://jsonpatch.com
+[137]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function
 
-[135]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function
+[138]: https://tera-tools.com/api/logs.json