pear-electron 1.7.19 → 1.7.21

package/README.md

@@ -2,13 +2,22 @@
 
 > Pear User-Interface Library for Electron
 
-## Installation
+## Installation <a name="installation"></a>
 
 ```sh
 npm install pear-electron
 ```
 
 ## Usage
+Ensure the `package.json` `pear` configuration object contains a `pre` field pointing to `pear-electron/pre`.
+
+```js
+{
+  "pear": {
+    "pre": "pear-electron/pre"
+  }
+}
+```
 
 Instantiate a `pear-electron` runtime instance from a Pear Application's entrypoint JavaScript file:
 
@@ -29,117 +38,177 @@ Call `runtime.start` to open the UI.
 
 > NOTE: naming the import `Runtime` instead of `PearElectron` is intentional, for two reasons. The `pear-electron` import resolves to a runtime start library or a User Interface library depending on environment and using `Runtime` and `ui` as assigned names means switching out `pear-electron` with an equivalent alternative only involves changing the two `pear-electron` import specifiers.
 
-## Initialization API
+Given an `index.html` containing `<script src="./app.js"></script>` in `app.js` import `pear-electron` User Interface API:
+
+```js
+import ui from 'pear-electron'
+
 
-### `new Runtime() -> runtime`
+```
+
+## Application Configuration <a name="application-configuration"></a>
+
+Set the [`pear.pre`](https://docs.pears.com/configuration#pear-pre) to `pear-electron/pre` (or ensure that it's imported at the top of any alternative pre script).
+
+
+```json
+{
+  "pear": {
+    "pre": "pear-electron/pre"
+  }
+}
+
+```
+
+Prior to run from disk and prior to run from key, the `pear-electron/pre` script automatically adjusts application configuration to include runtime binary [`pear.assets`](https://docs.pears.com/configuration#pear-assets) as well as adding statically analyzed script tags as [`pear.stage.entrypoints`](https://docs.pears.com/configuration#pear-stage-entrypoints) from the [`pear.gui.main`](#pear-gui-main) HTML entrypoint.
+
+The application `package.json` `pear` field can also define its own [`pear.assets`](https://docs.pears.com/configuration#pear-assets).
+
+## Initialization API <a name="initialization-api"></a>
+
+### `new Runtime() -> runtime` <a name="new-runtime"></a>
 
 Create the runtime instances with `new Runtime()`.
 
-### `runtime.ready()`
+### `runtime.ready()` <a name="runtime-ready"></a>
 
 Prepare the runtime, runtime binaries for the runtime version may be bootstrapped peer-to-peer at this point. This only runs once per version and any prior bootstraps can be reused for subsequent versions where state hasn't changed. In a production scenario any bootstrapping would be performed in advance by the application distributable.
 
-### `runtime.start(opts)`
+### `runtime.start(opts)` <a name="runtime-start"></a>
 
 Opens the UI. 
 
 #### Options
 
-* `bridge` - An instance of `pear-bridge`.
+* `bridge` - An instance of [`pear-bridge`](https://github.com/holepunchto/pear-bridge).
 
-## User-Interface API
+## User-Interface API <a name="user-interface-api"></a>
 
-Inside the pear-electron runtime desktop application, pear-electron resolves to a UI control API.
+Inside the `pear-electron` runtime desktop application, pear-electron resolves to a UI control API.
 
 **index.html**:
 ```html
-<script src="./app.js" type="module">
+<script src="./app.js" type="module"><script>
 ```
 
 **app.js**:
 ```js
 import ui from 'pear-electron'
+// do something with ui:
+setTimeout(async () => { await ui.app.focus({ steal: true }) })
 ```
 
 > NOTE: naming the import `ui` instead of `PearElectron` is intentional, for two reasons. The `pear-electron` import resolves to a runtime start library or a User Interface library depending on environment and using `Runtime` and `ui` as assigned names means switching out `pear-electron` with an equivalent alternative only involves changing the two `pear-electron` import specifiers.
 
-### `ui.app <Object>`
+### `ui.app <Object>` <a name="ui-app"></a>
 
 UI Application controls
 
-### `const success = await app.focus()`
+### `const success = await ui.app.focus([options <Object>])` <a name="ui-app-focus"></a>
 
 Resolves to: `<Boolean>`
 
-Focus current view or window.
+Foreground current view or window.
+
+**Options**
+
+* `steal` Default: `false` -  focus input as well as foregrounding 
 
-### `const success = await app.blur()`
+### `const success = await ui.app.blur()` <a name="ui-app-blur"></a>
 
 Resolves to: `<Boolean>`
 
 Blur current view or window.
 
-### `const success = await app.show()`
+### `const success = await ui.app.show()` <a name="ui-app-show"></a>
 
 Resolves to: `<Boolean>`
 
 Show current view or window.
 
-### `const success = await app.hide()`
+### `const success = await ui.app.hide()` <a name="ui-app-hide"></a>
 
 Resolves to: `<Boolean>`
 
 Hide current view or window.
 
-### `const sourceId = await app.getMediaSourceId()`
+#### `const success = await ui.app.badge(count <Integer|null>)` <a name="ui-app-badge"></a>
 
-Get the sourceId of the current window or view.
+Resolves to: `<Boolean>`
+
+Set the badge number for the application on desktop for Linux & MacOS. Setting the `count` to `0` will hide the badge while `null` will display a plain dot on MacOS only.
+
+Returns a `Boolean` promise for whether the call succeeded.
+
+#### `const untray = await ui.app.tray(options <Object>[, listener <Function>])` <a name="ui-app-tray"></a>
+
+Resolves to: `<Function>`
 
-**References**
+Configure a tray icon for the application. 
 
-* [win.getMediaSourceId()](const-sourceId--await-wingetMediaSourceId)
+This method will return a promise which resolves to an `untray()` function for removing the tray.
 
+The `listener` function is triggered whenever a menu item or the tray icon is clicked. It receives a single argument `key` that represents the menu item `key` that was clicked or the special value of `'click'` for when the menu icon itself was clicked. If no `listener` function is provided, a default listener will show the application window when triggered with `'click'` or `'show'` and quits with `'quit'`.
 
-### `const success = await app.minimize()`
+A Pear application should set `pear.gui.closeHide` option to `true` in `package.json` `pear` options object when using `ui.app.tray`.
+
+WARNING: Linux tray support varies which can cause scenarios where the application's tray doesn't work and closing the app will be hidden and inaccessible. Using a tray and `closeHide` on Linux is not recommended. Set `pear.gui.linux.closeHide` option to `false` in `package.json` `pear` options object.
+
+**Options**
+
+* `icon <String>` Default: The Pear icon - The path for icon for the tray
+  relative to the project root. Supported formats: PNG & JPEG
+* `menu <Object>` Default: ``{ show: `Show ${Pear.app.name}`, quit: 'Quit' }`` - The
+  tray menu items. Each property of the object is the `key` passed to the
+  `listener` and whose value is the text displayed in the menu.
+* `os <Object>` Default: `{ win32: true, linux: true, darwin: true  }` - which
+  platforms support using the tray menu. The platform is checked via the
+  `process.platform` value.
+
+### `const sourceId = await ui.app.getMediaSourceId()` <a name="ui-app-getmediasourceid"></a>
+
+Get the sourceId of the current window or view.
+
+### `const success = await ui.app.minimize()` <a name="ui-app-minimize"></a>
 
 Resolves to: `<Boolean>`
 
 Minimize current window.
 
-### `const success = await app.maximize()`
+### `const success = await ui.app.maximize()` <a name="ui-app-maximize"></a>
 
 Resolves to: `<Boolean>`
 
 Maximize current window.
 
-### `const success = await app.restore()`
+### `const success = await ui.app.restore()` <a name="ui-app-restore"></a>
 
 Resolves to: `<Boolean>`
 
 Unmaximize/unminimize the current window if it is currently maximized/minimized.
 
-### `const success = await app.close()`
+### `const success = await ui.app.close()` <a name="ui-app-close"></a>
 
 Resolves to: `<Boolean>`
 
 Closes the current view or window.
 
 
-### `const isVisible = await app.isVisible()`
+### `const isVisible = await ui.app.isVisible()` <a name="ui-app-isvisible"></a>
 
 Resolves to: `<Boolean>`
 
 Whether the current window or view is visible.
 
-### `const isMaximized = await app.isMaximized()`
+### `const isMaximized = await ui.app.isMaximized()` <a name="ui-app-ismaximized"></a>
 
 Resolves to: `<Boolean>`
 
-### `const isMinimized = await app.isMinimized()`
+### `const isMinimized = await ui.app.isMinimized()` <a name="ui-app-isminimized"></a>
 
 Resolves to: `<Boolean>`
 
-### `const found = await app.find(options <Object>)`
+### `const found = await ui.app.find(options <Object>)` <a name="ui-app-find"></a>
 
 Resolves to: `<Found> extends <streamx.Readable>`
 
@@ -150,28 +219,27 @@ Find and select text, emit matches as data events.
 * forward `<Boolean>` - search forward (`true`) or backward (`false`). Defaults `true`.
 * matchCase `<Boolean>`  - case-sensitivity. Default `false`.
 
-#### `await found.proceed()`
+#### `await found.proceed()` <a name="found-proceed"></a>
 
 Find & select next match, emit result as stream data.
 
-#### `await found.clear()`
+#### `await found.clear()` <a name="found-clear"></a>
 
 Stop search and clear matching text selection. Implies destroy.
 
-#### `await found.keep()`
+#### `await found.keep()` <a name="found-keep"></a>
 
 Stop search and convert matching text selection to text highlight. Implies destroy.
 
-#### `await found.activate()`
+#### `await found.activate()` <a name="found-activate"></a>
 
 Stop search and simulate a click event on the selected match. Implies destroy.
 
-
-### `ui.media <Object>`
+### `ui.media <Object>` <a name="ui-media"></a>
 
 Media interface
 
-#### `const status = await ui.media.status.microphone()`
+#### `const status = await ui.media.status.microphone()` <a name="ui-media-status-microphone"></a>
 
 Resolves to: `<String>`
 
@@ -179,7 +247,7 @@ If access to the microphone is available, resolved value will be `'granted'`.
 
 Any other string indicates lack of permission. Possible values are `'granted'`, `'not-determined'`, `'denied'`, `'restricted'`, `'unknown'`.
 
-#### `const status = await ui.media.status.camera()`
+#### `const status = await ui.media.status.camera()` <a name="ui-media-status-camera"></a>
 
 Resolves to: `<String>`
 
@@ -187,7 +255,7 @@ If access to the camera is available, resolved value will be `'granted'`.
 
 Any other string indicates lack of permission. Possible values are `'granted'`, `'not-determined'`, `'denied'`, `'restricted'`, `'unknown'`.
 
-#### `const status = await ui.media.status.screen()`
+#### `const status = await ui.media.status.screen()` <a name="ui-media-status-screen"></a>
 
 Resolves to: `<String>`
 
@@ -195,25 +263,25 @@ If access to the screen is available, resolved value will be `'granted'`.
 
 Any other string indicates lack of permission. Possible values are `'granted'`, `'not-determined'`, `'denied'`, `'restricted'`, `'unknown'`.
 
-#### `const success = await ui.media.access.microphone()`
+#### `const success = await ui.media.access.microphone()` <a name="ui-media-access-microphone"></a>
 
 Resolves to: `<Boolean>`
 
 Request access to the microphone. Resolves to `true` if permission is granted.
 
-#### `const success = await ui.media.access.camera()`
+#### `const success = await ui.media.access.camera()` <a name="ui-media-access-camera"></a>
 
 Resolves to: `<Boolean>`
 
 Request access to the camera. Resolves to `true` if permission is granted.
 
-#### `const success = await ui.media.access.screen()`
+#### `const success = await ui.media.access.screen()` <a name="ui-media-access-screen"></a>
 
 Resolves to: `<Boolean>`
 
 Request access to screen sharing. Resolves to `true` if permission is granted.
 
-#### `const sources = await ui.media.desktopSources(options <Object>)`
+#### `const sources = await ui.media.desktopSources(options <Object>)` <a name="ui-media-desktopsources"></a>
 
 Captures available desktop sources. Resolves to an array of objects with shape `{ id <String>, name <String>, thumbnail <NativeImage>, display_id <String>, appIcon <NativeImage> }`. The `id` is the window or screen identifier. The `name` is the window title or `'Screen <index>'` in multiscreen scenarios or else `Entire Screen`. The `display_id` identifies the screen. The thumbnail is a scaled down screen capture of the window/screen.
 
@@ -223,19 +291,19 @@ Captures available desktop sources. Resolves to an array of objects with shape `
 * `thumbnailSize <Object>` - Default: `{width: 150, height: 150}`. Set thumbnail scaling (pixels)
 * `fetchWindowIcons <Boolean>` - Default: `false`. Populate `appIcon` with Window icons, or else `null`.
 
-**References**
+**See Also**
 
-* [win.getMediaSourceId()](#const-sourceid--await-wingetmediasourceid)
-* [view.getMediaSourceId()](#const-sourceid--await-viewgetmediasourceid)
-* [self.getMediaSourceId()](#const-sourceid--await-selfgetmediasourceid)
-* [parent.getMediaSourceId()](#const-sourceid--await-parentgetmediasourceid)
+* [app.getMediaSourceId()](#app-getmediasourceid)
+* [view.getMediaSourceId()](#view-getmediasourceid)
+* [win.getMediaSourceId()](#win-getmediasourceid)
+* [parent.getMediaSourceId()](#parent-getmediasourceid)
 * https://www.electronjs.org/docs/latest/api/desktop-capturer#desktopcapturergetsourcesoptions
 * https://www.electronjs.org/docs/latest/api/structures/desktop-capturer-source
 * [`<NativeImage>`](https://www.electronjs.org/docs/latest/api/native-image)
 
 Exits the process with the provided exit code.
 
-### `const win = new ui.Window(entry <String>, options <Object>)`
+### `const win = new ui.Window(entry <String>, options <Object>)` <a name="ui-window"></a>
 
 Desktop Applications only.
 
@@ -269,16 +337,12 @@ Create a new `Window` instance.
 * `transparent <Boolean>` - Set window transparency
 * `backgroundColor <String>` Default: `'#FFF'` - window default background color. Hex, RGB, RGBA, HSL HSLA, CSS color
 
-### `win.on[ce]('message', (...args) => { })`
+### `win.on[ce]('message', (...args) => { })` <a name="win-recieve-messages"></a>
 ### `for await (const [ ...args ] of win)`
 
 Receive a message from the window. The received `args` array is deserialized via `JSON.parse`.
 
-**References**
-
-* [`win.send()`](#await-winsendargs)
-
-### `const success = await win.open(options <Object>)`
+### `const success = await win.open(options <Object>)` <a name="win-open">
 
 Resolves to: `<Boolean>`
 
@@ -312,25 +376,25 @@ Open the window.
 * `transparent <Boolean>` - Set window transparency
 * `backgroundColor <String>` Default: `'#FFF'` - window default background color. Hex, RGB, RGBA, HSL HSLA, CSS color
 
-### `const success = await win.close()`
+### `const success = await win.close()` <a name="win-close"></a>
 
 Resolves to: `<Boolean>`
 
 Close the window.
 
-### `const success = await win.show()`
+### `const success = await win.show()` <a name="win-show"></a>
 
 Resolves to: `<Boolean>`
 
 Show the window.
 
-### `const success = await win.hide()`
+### `const success = await win.hide()` <a name="win-hide"></a>
 
 Resolves to: `<Boolean>`
 
 Hide the window.
 
-### `const success = await win.focus(options <Object>)`
+### `const success = await win.focus([options <Object>])` <a name="win-focus"></a>
 
 Resolves to: `<Boolean>`
 
@@ -338,48 +402,43 @@ Focus the window.
 
 **Options**
 
-* `steal` Default: `true` - brings the window to the foreground and attempts to take focus, even if another application is currently active, or the window is hidden or minimized.
+* `steal` Default: `true` - 
 
-### `const success = await win.blur()`
+### `const success = await win.blur()` <a name="win-blur"></a>
 
 Resolves to: `<Boolean>`
 
 Blur the window.
 
-### `const success = await win.minimize()`
+### `const success = await win.minimize()` <a name="win-minimize"></a>
 
 Resolves to: `<Boolean>`
 
 Minimize the window.
 
-### `const success = await win.maximize()`
+### `const success = await win.maximize()` <a name="win-maximize"></a>
 
 Resolves to: `<Boolean>`
 
 Maximize the window.
 
-### `const success = await win.restore()`
+### `const success = await win.restore()` <a name="win-restore"></a>
 
 Resolves to: `<Boolean>`
 
 Unmaximize/unminimize the window if it is currently maximized/minimized.
 
-### `const sourceId = await win.getMediaSourceId()`
+### `const sourceId = await win.getMediaSourceId()`  <a name="win-getmediasourceid"></a>
 
 Resolves to: `<String>`
 
-Correlates to the `id` property of objects in the array returned from [ui.media.desktopSources](#const-sources---await-appmediadesktopsources-options).
+Correlates to the `id` property of objects in the array returned from [ui.media.desktopSources](#ui-media-desktopsources).
 
-**References**
-
-* [ui.media.desktopSources](#const-sources--await-appmediadesktopsourcesoptions-object)
-* https://www.electronjs.org/docs/latest/api/browser-window#wingetmediasourceid
-
-### `await win.send(...args)`
+### `await win.send(...args)`  <a name="win-send"></a>
 
 Send arguments to the window. They will be serialized with `JSON.stringify`.
 
-### `const found = await win.find(options <Object>)`
+### `const found = await win.find(options <Object>)`  <a name="win-find"></a>
 
 Resolves to: `<Found> extends <streamx.Readable>`
 
@@ -390,24 +449,25 @@ Find and select text, emit matches as data events.
 * forward `<Boolean>` - search forward (`true`) or backward (`false`). Defaults `true`.
 * matchCase `<Boolean>`  - case-sensitivity. Default `false`.
 
-#### `await found.proceed()`
+#### `await found.proceed()` <a name="win-find-found-proceed"></a>
 
 Find & select next match, emit result as stream data.
 
-#### `await found.clear()`
+#### `await found.clear()` <a name="win-find-found-clear"></a>
 
 Stop search and clear matching text selection. Implies destroy.
 
-#### `await found.keep()`
+#### `await found.keep()` <a name="win-find-found-keep"></a>
 
 Stop search and convert matching text selection to text highlight. Implies destroy.
 
-#### `await found.activate()`
+#### `await found.activate()` <a name="win-find-found-activate"></a>
 
 Stop search and simulate a click event on the selected match. Implies destroy.
 
+### `const dimensions = await win.dimensions([options <Object>])` <a name="win-dimensions"></a>
 
-### `const dimensions = await win.dimensions()`
+When options object is not provided, behaves as a getter and resolves to a a bounds object.
 
 Resolves to: `{x <Integer>, y <Integer>, width <Integer>, height <Integer>} | null`.
 
@@ -417,11 +477,7 @@ All units are (pixels)
 
 If the window is closed this will resolve to `null`.
 
-**References**
-
-* [await win.dimensions(options)](#await-windimensionsoptions-object)
-
-### `await win.dimensions(options <Object>)`
+When options object is provided, behaves as a setter and resolves to `undefined`.
 
 ```js
 const win = new ui.Window('./some.html', {
@@ -455,36 +511,31 @@ Sets the dimensions of the window.
 * `animate <Boolean>` Default: `false` - animate the dimensional change. MacOS only, ignored on other OS's.
 * `position <String>` - may be `'center'` to set the window in the center of the screen or else `undefined`.
 
-**References**
-
-* [const dimensions = await win.dimensions()](#const-dimensions-await-windimensions)
-
-
-### `const visible = await win.isVisible()`
+### `const visible = await win.isVisible()` <a name="win-isvisible"></a>
 
 Resolves to: `<Boolean>`
 
 Whether the window is visible.
 
-### `const minimized = await win.isMinimized()`
+### `const minimized = await win.isMinimized()` <a name="win-isminimized"></a>
 
 Resolves to: `<Boolean>`
 
 Whether the window is minimized.
 
-### `const maximized = await win.isMaximized()`
+### `const maximized = await win.isMaximized()` <a name="win-ismaximized"></a>
 
 Resolves to: `<Boolean>`
 
 Whether the window is maximized.
 
-### `const closed = await win.isClosed()`
+### `const closed = await win.isClosed()` <a name="win-isclosed"></a>
 
 Resolves to: `<Boolean>`
 
 Whether the window is closed.
 
-### `const view = new ui.View(options <Object>)`
+### `const view = new ui.View(options <Object>)` <a name="ui-view"></a>
 
 Desktop Applications only.
 
@@ -499,21 +550,17 @@ Create a new `View` instance. Views provide isolated content views. Frameless, c
 * `backgroundColor <String>` Default: `'#FFF'` - view default background color. Hex, RGB, RGBA, HSL HSLA, CSS color
 * `autoresize <Object>` Default `{ width=true, height=true, vertical=false, horizontal=false }` - dimensions for the view to autoresize alongside. For example, if `width` is `true` and the view container increases/decreases in width, the view will increase/decrease in width at the same rate.
 
-**References**
 
-* https://www.electronjs.org/docs/latest/api/browser-view#viewsetautoresizeoptions-experimental
 * https://www.electronjs.org/docs/latest/api/browser-view#viewsetbackgroundcolorcolor-experimental
 
-### `view.on[ce]('message', (...args) => { })`
+### `view.on[ce]('message', (...args) => { })` <a name="view-recieve-messages"></a>
 ### `for await (const [ ...args ] of view)`
 
 Receive a message from the view. The received `args` array is deserialized via `JSON.parse`.
 
-**References**
 
-* [`view.send()`](#await-viewsendargs)
 
-### `const success = await view.open(options <Object>)`
+### `const success = await view.open(options <Object>)` <a name="view-open"></a>
 
 Resolves to: `<Boolean>`
 
@@ -528,79 +575,81 @@ Open the view.
 * `backgroundColor <String>` Default: `'#FFF'` - view default background color. Hex, RGB, RGBA, HSL HSLA, CSS color
 * `autoresize <Object>` Default `{ width=true, height=true, vertical=false, horizontal=false }` - dimensions for the view to autoresize alongside. For example, if `width` is `true` and the view container increases/decreases in width, the view will increase/decrease in width at the same rate.
 
-### `const success = await view.close()`
+### `const success = await view.close()` <a name="view-close"></a>
 
 Resolves to: `<Boolean>`
 
 Close the view.
 
-### `const success = await view.show()`
+### `const success = await view.show()` <a name="view-show"></a>
 
 Resolves to: `<Boolean>`
 
 Show the view.
 
-### `const success = await view.hide()`
+### `const success = await view.hide()` <a name="view-hide"></a>
 
 Resolves to: `<Boolean>`
 
 Hide the view.
 
-### `const success = await view.focus()`
+### `const success = await view.focus([options <Object>])` <a name="view-focus"></a>
 
 Resolves to: `<Boolean>`
 
-Focus the view.
+Foreground the view.
+
+**Options**
+
+* `steal` Default: `false` -  focus input as well as foregrounding 
 
-### `const success = await view.blur()`
+### `const success = await view.blur()` <a name="view-blur"></a>
 
 Resolves to: `<Boolean>`
 
 Blur the view.
 
-### `const sourceId = await view.getMediaSourceId()`
+### `const sourceId = await view.getMediaSourceId()` <a name="view-getmediasourceid"></a>
 
 Resolves to: `<String>`
 
-Supplies the `id` property of objects in the array returned from [ui.media.desktopSources](#const-sources---await-appmediadesktopsources-options).
+Supplies the `id` property of objects in the array returned from [ui.media.desktopSources](#ui-media-desktopsources).
 
-**References**
-
-* [ui.media.desktopSources](#const-sources---await-appmediadesktopsources-options)
-* https://www.electronjs.org/docs/latest/api/browser-window#wingetmediasourceid
-
-### `await view.send(...args)`
+### `await view.send(...args)` <a name="view-send"></a>
 
 Send arguments to the view. They will be serialized with `JSON.stringify`.
 
-### `const found = await win.find(options <Object>)`
+### `const found = await view.find(options <Object>)` <a name="view-find"></a>
 
 Resolves to: `<Found> extends <streamx.Readable>`
 
 Find and select text, emit matches as data events.
 
 **Options**
+
 * text `<String>` - search term
 * forward `<Boolean>` - search forward (`true`) or backward (`false`). Defaults `true`.
 * matchCase `<Boolean>`  - case-sensitivity. Default `false`.
 
-#### `await found.proceed()`
+#### `await found.proceed()` <a name="view-find-found-proceed"></a>
 
 Find & select next match, emit result as stream data.
 
-#### `await found.clear()`
+#### `await found.clear()` <a name="view-find-found-clear"></a>
 
 Stop search and clear matching text selection. Implies destroy.
 
-#### `await found.keep()`
+#### `await found.keep()` <a name="view-find-found-keep"></a>
 
 Stop search and convert matching text selection to text highlight. Implies destroy.
 
-#### `await found.activate()`
+#### `await found.activate()` <a name="view-find-found-activate"></a>
 
 Stop search and simulate a click event on the selected match. Implies destroy.
 
-### `const dimensions = await view.dimensions()`
+### `const dimensions = await view.dimensions([options <Object>])` <a name="view-dimensions"></a>
+
+When options object is not provided, behaves as a getter and resolves to a a bounds object.
 
 Resolves to: `{x <Integer>, y <Integer>, width <Integer>, height <Integer>} | null`.
 
@@ -608,13 +657,9 @@ The height, width, horizontal (`x`), vertical (`y`) position of the window relat
 
 All units are (pixels)
 
-If the Window is closed this will resolve to `null`.
-
-**References**
-
-* [await view.dimensions(options)](#await-viewdimensionsoptions-object)
+If the parent window is closed this will resolve to `null`.
 
-### `await view.dimensions(options <Object>)`
+When options object is provided, behaves as a setter and resolves to `undefined`.
 
 ```js
 const view = new ui.View('./some.html', {
@@ -645,72 +690,98 @@ Sets the dimensions of the view.
 * `height <Integer>` - the height of the window (pixels)
 
 
-**References**
+```js
+const view = new ui.View('./some.html', {
+  x: 10,
+  y: 450,
+  width: 300,
+  height: 350
+})
 
-* [const dimensions = await view.dimensions()](#const-dimensions--await-viewdimensions)
+await view.open()
+await new Promise((resolve) => setTimeout(resolve, 1000))
 
-### `const visible = await view.isVisible()`
+await view.dimensions({
+  x: 20,
+  y: 50,
+  width: 550,
+  height: 300
+})
+```
+
+Sets the dimensions of the view.
+
+**Options**
+
+* `x <Integer>` - the horizontal position of left side of the window (pixels)
+* `y <Integer>` - the vertical position of the top of the window (pixels)
+* `width <Integer>` - the width of the window (pixels)
+* `height <Integer>` - the height of the window (pixels)
+
+### `const visible = await view.isVisible()` <a name="view-isvisible"></a>
 
 Resolves to: `<Boolean>`
 
 Whether the view is visible.
 
-### `const closed = await view.isClosed()`
+### `const closed = await view.isClosed()` <a name="view-isclosed"></a>
 
 Resolves to: `<Boolean>`
 
 Whether the view is closed.
 
-### `const { self } = ui.Window`  `const { self } = ui.View`
+### `const { self } = ui.Window`  `const { self } = ui.View` <a name="deprecated-self"></a>
 
 > DEPRECATED use `ui.app`.
 
-### `const { parent } = ui.Window`  `const { parent } = ui.View`
+### `const { parent } = ui.Window`  `const { parent } = ui.View` <a name="parent"></a>
 
-### `parent.on[ce]('message', (...args) => { })`
+### `parent.on[ce]('message', (...args) => { })` <a name="parent-receive-messages"></a>
 ### `for await (const [ ...args ] of parent)`
 
 Receive a message from the parent window or view. The received `args` array is deserialized via `JSON.parse`.
 
-### `await parent.send(...args)`
+### `await parent.send(...args)` <a name="parent-send"></a>
 
 Send arguments to the parent view or window. They will be serialized with `JSON.stringify`.
 
 
-### `const success = await parent.focus()`
+### `const success = await parent.focus([options <Object>])` <a name="parent-focus"></a>
 
 Resolves to: `<Boolean>`
 
-Focus parent view or window.
+Foreground parent view or window.
+
+**Options**
+
+* `steal` Default: `false` -  focus input as well as foregrounding 
 
-### `const success = await parent.blur()`
+### `const success = await parent.blur()` <a name="parent-blur"></a>
 
 Resolves to: `<Boolean>`
 
 Blur parent view or window.
 
-### `const success = await parent.show()`
+### `const success = await parent.show()` <a name="parent-show"></a>
 
 Resolves to: `<Boolean>`
 
 Show parent view or window.
 
-### `const success = await parent.hide()`
+### `const success = await parent.hide()` <a name="parent-hide"></a>
 
 Resolves to: `<Boolean>`
 
 Hide parent view or window.
 
-### `const sourceId = await parent.getMediaSourceId()`
+### `const sourceId = await parent.getMediaSourceId()` <a name="parent-getmediasourceid"></a>
 
 Get the sourceId of the parent window or view.
 
-**References**
 
-* [win.getMediaSourceId()](#const-sourceId--await-wingetMediaSourceId)
 
 
-### `const success = await parent.minimize()`
+### `const success = await parent.minimize()` <a name="parent-minimize"></a>
 
 Resolves to: `<Boolean>`
 
@@ -718,7 +789,7 @@ Minimize parent window.
 
 Throws a `TypeError` if `parent` is a view.
 
-### `const success = await parent.maximize()`
+### `const success = await parent.maximize()` <a name="parent-maximize"></a>
 
 Resolves to: `<Boolean>`
 
@@ -726,7 +797,7 @@ Maximize parent window.
 
 Throws a `TypeError` if `parent` is a view.
 
-### `const success = await parent.restore()`
+### `const success = await parent.restore()` <a name="parent-restore"></a>
 
 Resolves to: `<Boolean>`
 
@@ -734,31 +805,31 @@ Unmaximize/unminimize the parent window if it is currently maximized/minimized.
 
 Throws a `TypeError` if `parent` is a view.
 
-### `const success = await parent.close()`
+### `const success = await parent.close()` <a name="parent-close"></a>
 
 Resolves to: `<Boolean>`
 
 Closes the parent view or window.
 
-### `const isVisible = await parent.isVisible()`
+### `const isVisible = await parent.isVisible()` <a name="parent-isvisible"></a>
 
 Resolves to: `<Boolean>`
 
 Whether the parent window or view is visible.
 
-### `const isMaximized = await parent.isMaximized()`
+### `const isMaximized = await parent.isMaximized()` <a name="parent-ismaximized"></a>
 Resolves to: `<Boolean>`
 
 Whether the parent window is maximized. Throws a `TypeError` if `parent` is a view.
 
 
-### `const isMinimized = await parent.isMinimized()`
+### `const isMinimized = await parent.isMinimized()` <a name="parent-isminimized"></a>
 
 Resolves to: `<Boolean>`
 
 Whether the parent window is minimized. Throws a `TypeError` if `parent` is a view.
 
-### `const found = await parent.find(options <Object>)`
+### `const found = await parent.find(options <Object>)` <a name="parent-find"></a>
 
 Resolves to: `<Found> extends <streamx.Readable>`
 
@@ -769,119 +840,166 @@ Find and select text, emit matches as data events.
 * forward `<Boolean>` - search forward (`true`) or backward (`false`). Defaults `true`.
 * matchCase `<Boolean>`  - case-sensitivity. Default `false`.
 
-#### `await found.proceed()`
+#### `await found.proceed()` <a name="parent-find-found-proceed"></a>
 
 Find & select next match, emit result as stream data.
 
-#### `await found.clear()`
+#### `await found.clear()` <a name="parent-find-found-clear"></a>
 
 Stop search and clear matching text selection. Implies destroy.
 
-#### `await found.keep()`
+#### `await found.keep()` <a name="parent-find-found-keep"></a>
 
 Stop search and convert matching text selection to text highlight. Implies destroy.
 
-#### `await found.activate()`
+#### `await found.activate()` <a name="parent-find-found-activate"></a>
 
 Stop search and simulate a click event on the selected match. Implies destroy.
 
-## Graphical User Interface Options
+## Graphical User Interface Options <a name="pear-gui"></a>
 
 GUI options for an application are set in the application `package.json` `pear.gui` field.
 
-### `width <Number>`
+Example `package.json`:
+
+```json
+{
+  "name": "my-app",
+  "pear": {
+    "gui": {
+      "width": 800,
+      "height": 600
+    }
+  }
+}
+```
+
+### `pear.gui.width <Number>` <a name="pear-gui-width"></a>
 
 Window width (pixels).
 
-### `height <Number>`
+### `pear.gui.height <Number>` <a name="pear-gui-height"></a>
 
 Window height (pixels).
 
-### `x <Number>`
+### `pear.gui.x <Number>` <a name="pear-gui-x"></a>
 
 Horizontal window position (pixels).
 
-### `y <Number>`
+### `pear.gui.y <Number>` <a name="pear-gui-y"></a>
 
 Vertical window position (pixels).
 
-### `minWidth <Number>`
+### `pear.gui.minWidth <Number>` <a name="pear-gui-minwidth"></a>
 
 Window minimum width (pixels).
 
-### `minHeight <Number>`
+### `pear.gui.minHeight <Number>` <a name="pear-gui-minheight"></a>
 
 Window minimum height (pixels).
 
-### `maxWidth <Number>`
+### `pear.gui.maxWidth <Number>` <a name="pear-gui-maxwidth"></a>
 
 Window maximum width (pixels).
 
-### `maxHeight <Number>`
+### `pear.gui.maxHeight <Number>` <a name="pear-gui-maxheight"></a>
 
 Window maximum height (pixels).
 
-### `center <Boolean>` (default: `false`)
+### `pear.gui.center <Boolean>` (default: `false`) <a name="pear-gui-center"></a>
 
 Center window.
 
-### `resizable <Boolean>` (default: `true`)
+### `pear.gui.resizable <Boolean>` (default: `true`) <a name="pear-gui-resizable"></a>
 
 Window resizability.
 
-### `movable <Boolean>` (default: `true`)
+### `pear.gui.movable <Boolean>` (default: `true`) <a name="pear-gui-movable"></a>
 
 Window movability.
 
-### `minimizable <Boolean>` (default: `true`)
+### `pear.gui.minimizable <Boolean>` (default: `true`) <a name="pear-gui-minimizable"></a>
 
 Window minimizability.
 
-### `maximizable <Boolean>` (default: `true`)
+### `pear.gui.maximizable <Boolean>` (default: `true`) <a name="pear-gui-maximizable"></a>
 
 Window maximizability.
 
-### `closable <Boolean>` (default: `true`)
+### `pear.gui.closable <Boolean>` (default: `true`) <a name="pear-gui-closable"></a>
 
 Window closability.
 
-### `focusable <Boolean>` (default: `true`)
+### `pear.gui.focusable <Boolean>` (default: `true`) <a name="pear-gui-focusable"></a>
 
 Window focusability.
 
-### `alwaysOnTop <Boolean>` (default: `false`)
+#### `pear.gui.closeHides <Boolean>` (default: `false`) <a name="pear-gui-closehides"></a>
+
+Keep app running when all windows are closed.
+
+WARNING: Linux tray support varies which can cause scenarios where the application's tray doesn't work and closing the app will be hidden and inaccessible. Using a tray and `closeHides` on Linux is not recommended.
+
+### `pear.gui.alwaysOnTop <Boolean>` (default: `false`) <a name="pear-gui-alwaysontop"></a>
 
 Set window to always be on top.
 
-### `fullscreen <Boolean>` (default: `false`)
+### `pear.gui.fullscreen <Boolean>` (default: `false`) <a name="pear-gui-fullscreen"></a>
 
 Set window to fullscreen on start.
 
-### `kiosk <Boolean>` (default: `false`)
+### `pear.gui.kiosk <Boolean>` (default: `false`) <a name="pear-gui-kiosk"></a>
 
 Set window to enter kiosk mode on start.
 
-### `autoHideMenuBar <Boolean>` (default: `false`)
+### `pear.gui.autoHideMenuBar <Boolean>` (default: `false`) <a name="pear-gui-autohidemenubar"></a>
 
 Hide menu bar unless Alt key is pressed (Linux, Windows).
 
-### `hasShadow <Boolean>` (default: `true`)
+### `pear.gui.hasShadow <Boolean>` (default: `true`) <a name="pear-gui-hasshadow"></a>
 
 Window shadow.
 
-### `opacity <Number>` (default: `1`)
+### `pear.gui.opacity <Number>` (default: `1`) <a name="pear-gui-opacity"></a>
 
 Set window opacity (0.0 - 1.0) (Windows, macOS).
 
-### `transparent <Boolean>` (default: `false`)
+### `pear.gui.transparent <Boolean>` (default: `false`) <a name="pear-gui-transparent"></a>
 
 Enable transparency. Must be set for opacity to work.
 
-### `backgroundColor <String>` (default: "#000" non-transparent, "#00000000" transparent)
+### `pear.gui.backgroundColor <String>` (default: "#000" non-transparent, "#00000000" transparent) <a name="pear-gui-backgroundcolor"></a>
 
 Background color (Hex, RGB, RGBA, HSL, HSLA, CSS color).
 
-## Web APIs
+### `pear.gui.userAgent <string>` <a name="pear-gui-useragent"></a>
+
+User Agent override to use when electron makes web requests.
+
+#### `pear.gui[platform] <Object>` <a name="pear-gui-platform"></a>
+
+Platform specific options can be set by nesting options under the platform name. For example the following sets the macOS version to not be resizable:
+
+```json
+{
+  "pear": {
+    "gui": {
+      "darwin": {
+        "resizable": false
+      }
+    }
+  }
+}
+```
+
+The following `platform`s are supported:
+
+- `darwin`
+- `linux`
+- `win32`
+
+
+## Web APIs <a name="web-apis"></a>
 
 Most [Web APIs](https://developer.mozilla.org/en-US/docs/Web/API) will work as-is.
 
@@ -897,7 +1015,7 @@ With `pear-electron` UI Library, `window.open` loads the URL in the **default sy
 
 Therefore Pear's `window.open` only supports a single URL argument. The `target` and `windowFeatures` parameters that browsers support are discarded.
 
-### Scripts and Modules
+### Scripts and Modules <a name="scripts-and-modules"></a>
 
 Like browsers, there is no support for CommonJS (e.g. the `require` function as used by Node.js is not supported in Pear Applications).
 
@@ -907,24 +1025,41 @@ Use `<script type="module" src="path/to/my-file.js">` to load a JavaScript Modul
 
 Use `<script src="path/to/my-file.js">` to load a JavaScript Script.
 
-## Libraries
+## Development <a name="development"></a>
 
-### `pear-electron/api`
+The `pear-electron` library is a Pear User Interface Runtime Library, providing multiple capabilities:
 
-Function that takes a base Pear API class and extends it with pear-electron APIs. Only really useful when working with spoofed/mock Pear global in ui tests.
+* When loaded into a pear entrypoint JS file, `pear-electron` exports `runtime.js`, the runtime initializor.
+* When loaded into electron, `pear-electron` exports a UI library that is injected via `Pear[Pear.constructor.UI]` inside the runtime build that becomes the asset defined on `pear.assets.ui` configuration. 
+* The `pear-electron/pre` script provides autoconfiguration, it sets `pear.assets.ui` on the application per `pear.assets.ui` in the `pear-electron/package.json`.
 
+The `pear-electron` repo is self-bootstrapping and generates the runtime drive with `by-arch`, `prebuilds` and `boot.bundle`, which can then be staged with Pear. 
 
-## Development
+```sh
+npm run prestage
+```
+
+```sh
+pear stage dev
+```
 
-The `pear-electron` library is a Pear User Interface Runtime Library, as such `pear-electron` (and any Pear UI Lib.) is multifaceted and behaves differently depending on context.
+Set the `package.json` `pear.assets.ui.link` to the versioned pear link (`pear://<fork>.<length>.<key>`) of the staged application. This means the `pear-electron/pre` of the next publish of `pear-electron` will autoconfigure the applications `pear.assets.ui` to the updated versioned pear link. This effectively locks runtime builds for a given SemVer to a specific runtime drive checkout.
 
-* When loaded into a UI,  `pear-electron` is the UI API
-* When loaded into non-UI (i.e app entrypoint js file), `pear-electron` is the runtime initializor
-  * When there is no runtime binary on the system, `pear-electron` performs bootstrapping of the UI runtime executable, into `<pear-dir>/interfaces/pear-electron/<semver>`
-* The `pear-electron` repo is also self-bootstrapping and generates the runtime drive (with `by-arch`, `prebuilds` and `boot.bundle`), which can then be staged with Pear. The pear link for the staged `pear-electron` contents in `pear-electron` `package.json` `pear.gui.runtime` field is then set, with fork and length included. This locks runtime builds for a given semver to a specific runtime drive checkout.
-  * This is what `pear-electron` bootstraps from during `runtime.ready()`.
+To check a change with an application, use `npm pack` to get `tar.gz` archive and then install that archive into an application:
 
+```sh
+cd pear-electron
+npm pack
+cd ../some-pear-app
+npm i ../pear-electron/name-of-the-tar.gz
+```
+
+Then run the app with the `-d` (development) and `--pre-io` flag (to see any output from the `pear-electron/pre` script).
+
+```sh
+pear run --pre-io -d . 
+```
 
-# LICENSE
+# LICENSE <a name="license"></a>
 
 Apache 2.0

package/api.js

@@ -331,7 +331,7 @@ module.exports = (api) => {
             this.constructor.DECAL = {
               ipc,
               'hypercore-id-encoding': require('hypercore-id-encoding'),
-              'pear-api/constants': require('pear-api/constants')
+              'pear-constants': require('pear-constants')
             }
           }
         }

package/bootstrap.js

@@ -0,0 +1,15 @@
+'use strict'
+const pack = require('pear-pack')
+const Module = require('bare-module')
+const AppDrive = require('pear-appdrive')
+
+const drive = new AppDrive()
+const target = ['darwin-arm64', 'darwin-x64', 'linux-arm64', 'linux-x64', 'win32-x64']
+const builtins = [
+  'electron', 'net', 'assert', 'console', 'events', 'fs', 'fs/promises', 'http', 'https', 'os',
+  'path', 'child_process', 'repl', 'url', 'tty', 'module', 'process', 'timers', 'inspector'
+]
+const entry = '/node_modules/pear-electron/bootstrap.js'
+const { bundle, prebuilds } = await pack(drive, { entry, target, builtins })
+
+// TODO: setup module to consume bundle

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pear-electron",
-  "version": "1.7.19",
+  "version": "1.7.21",
   "description": "Pear User-Interface Library for Electron",
   "main": "index.js",
   "scripts": {
@@ -17,6 +17,14 @@
     "pre.js",
     "api.js"
   ],
+  "imports": {
+    "fs": {
+      "bare": "bare-fs"
+    },
+    "path": {
+      "bare": "bare-path"
+    }
+  },
   "pear": {
     "assets": {
       "ui": {
@@ -69,14 +77,22 @@
     "bare-path": "^3.0.0",
     "bare-subprocess": "^5.0.2",
     "compact-encoding": "^2.16.1",
-    "hypercore-crypto": "^3.6.1",
-    "hypercore-id-encoding": "^1.3.0",
-    "iambus": "^1.0.3",
     "localdrive": "^1.12.1",
     "paparam": "^1.6.1",
-    "pear-api": "^1.28.6",
+    "pear-api": "^1.29.1",
+    "pear-cmd": "^1.0.0",
+    "pear-constants": "^1.0.0",
+    "pear-crasher": "^1.0.1",
+    "pear-errors": "^1.0.0",
+    "pear-gunk": "^1.0.0",
     "pear-ipc": "^6.4.0",
-    "pear-pipe": "^1.0.1",
+    "pear-link": "^4.1.0",
+    "pear-logger": "^1.0.0",
+    "pear-pipe": "^1.0.2",
+    "pear-run": "^1.0.0",
+    "pear-state": "^1.0.2",
+    "pear-terminal": "^1.0.0",
+    "pear-tryboot": "^1.0.0",
     "script-linker": "^2.5.3",
     "streamx": "^2.20.2",
     "url-file-url": "^1.0.4",

package/runtime.js

@@ -8,17 +8,17 @@ const env = require('bare-env')
 const { command } = require('paparam')
 const { isLinux, isWindows, isMac } = require('which-runtime')
 const { pathToFileURL } = require('url-file-url')
-const constants = require('pear-api/constants')
-const plink = require('pear-api/link')
-const Logger = require('pear-api/logger')
-const { ERR_INVALID_APPLING, ERR_INVALID_PROJECT_DIR, ERR_INVALID_CONFIG } = require('pear-api/errors')
+const constants = require('pear-constants')
+const plink = require('pear-link')
+const Logger = require('pear-logger')
+const { ERR_INVALID_APPLING, ERR_INVALID_PROJECT_DIR, ERR_INVALID_CONFIG } = require('pear-errors')
 
 // cutover stops replaying & relaying subscriber streams between clients
 // set to false to stop run flow from auto cutover, so we can cutover at end of ui init
 Pear.constructor.CUTOVER = false
 
-const run = require('pear-api/cmd/run')
-const pear = require('pear-api/cmd')
+const pear = require('pear-cmd')
+const run = require('pear-cmd/run')
 const pkg = require('./package.json')
 
 const bin = (name) => {