From a4a7e5bfc98232fe6cac3992ce56d1bc818b1b4e Mon Sep 17 00:00:00 2001 From: David Mark Clements Date: Thu, 7 Dec 2023 13:34:16 +0100 Subject: [PATCH 1/4] subdirs, cli --- README.md | 14 +- .../getting-started.md | 0 .../releasing-a-pear-app.md | 0 .../sharing-a-pear-app.md | 0 reference/api.md | 0 reference/cli.md | 126 ++++++++++++++++++ reference/configuration.md | 0 7 files changed, 133 insertions(+), 7 deletions(-) rename getting-started.md => guide/getting-started.md (100%) rename releasing-a-pear-app.md => guide/releasing-a-pear-app.md (100%) rename sharing-a-pear-app.md => guide/sharing-a-pear-app.md (100%) create mode 100644 reference/api.md create mode 100644 reference/cli.md create mode 100644 reference/configuration.md diff --git a/README.md b/README.md index f5c5968..82bfee8 100644 --- a/README.md +++ b/README.md @@ -15,13 +15,13 @@ Welcome to the Internet of Peers ### Guide -* [Getting Started](./getting-started.md) -* [Making a Pear App](./making-a-pear-app.md) -* [Sharing a Pear App](./sharing-a-pear-app.md) -* [Releasing a Pear App](./releasing-a-pear-app.md) +* [Getting Started](./guide/getting-started.md) +* [Making a Pear App](./guide/making-a-pear-app.md) +* [Sharing a Pear App](./guide/sharing-a-pear-app.md) +* [Releasing a Pear App](./guide/releasing-a-pear-app.md) ### Reference -* [Application Configuration](./configuration.md) -* [Command-Line-Interface (CLI)](./cli.md) -* [Application-Programming-Interface (API)](./api.md) +* [Application Configuration](./reference/configuration.md) +* [Command-Line-Interface (CLI)](./reference/cli.md) +* [Application-Programming-Interface (API)](./reference/api.md) diff --git a/getting-started.md b/guide/getting-started.md similarity index 100% rename from getting-started.md rename to guide/getting-started.md diff --git a/releasing-a-pear-app.md b/guide/releasing-a-pear-app.md similarity index 100% rename from releasing-a-pear-app.md rename to guide/releasing-a-pear-app.md diff --git a/sharing-a-pear-app.md b/guide/sharing-a-pear-app.md similarity index 100% rename from sharing-a-pear-app.md rename to guide/sharing-a-pear-app.md diff --git a/reference/api.md b/reference/api.md new file mode 100644 index 0000000..e69de29 diff --git a/reference/cli.md b/reference/cli.md new file mode 100644 index 0000000..bc7b447 --- /dev/null +++ b/reference/cli.md @@ -0,0 +1,126 @@ +# Command Line Interface + +Pear's Command Line Interface (CLI) is the primary interface for Pear Development. + +## pear init [dir] + +Create initial project files. + +``` + --yes|-y Autoselect all defaults +``` + +## pear dev [dir] + +Start a project in development mode. + +Edit project files on disk. + +``` + --no-watch Disable watch-reload + --launch=key Launch an app in dev mode + --link=url Simulate deep-link click open + --store|-s=path Set the Application Storage path + --tmp-store|-t Use a temporary Application Storage path +``` +## pear stage [dir] + +Synchronize local changes to key. + +Channel name must be specified on first stage, +in order to generate the initial key. + +Outputs diff information and project key. + +``` + --json Newline delimited JSON output + --dry-run|-d Execute a stage without writing + --bare|-b File data only, no warmup optimization + --ignore Comma separated file path ignore list + --name Advanced. Override app name +``` + +## pear seed [dir] + +Seed project or reseed key. + +Specify channel or key to seed a project. + +Specify a remote key to reseed. + +``` + --json Newline delimited JSON output + --seeders|-s Additional public keys to seed from + --name Advanced. Override app name + --verbose|-v Additional output +``` + +## pear launch + +Launch an application. + +``` + --dev Launch the app in dev mode + --store|-s=path Set the Application Storage path + --tmp-store|-t Automatic new tmp folder as store path + --checkout=n|release|staged Launch a version +``` + +## pear release [dir] + +Set production release version. + +Set the release pointer against a version (default latest). + +Use this to indicate production release points. + +``` + --json Newline delimited JSON output + --checkout=n|current Set a custom release length (version) +``` + +## pear info + +Get metadata for a key. + +``` + --json Newline delimited JSON output +``` + +## pear dump + +Synchronize files from key to dir. + +``` + --json Newline delimited JSON output + --checkout=n Dump from a custom release length (version) +``` + +## pear sidecar + +The Pear Sidecar is a local-running HTTP and IPC server which +provides access to corestores. + +This command instructs any existing sidecar process to shutdown +and then becomes the sidecar. + +``` + --mem memory mode: RAM corestore + --attach-boot-io include initial sidecar I/O (if applicable) +``` + +## pear repl + +Connect to a Read-Eval-Print-Loop session with sidecar. + +A key is printed out, use with repl-swarm module to connect. + +## pear versions + +Output version information. + +``` +--json Single JSON object +``` + + diff --git a/reference/configuration.md b/reference/configuration.md new file mode 100644 index 0000000..e69de29 From 34f798051989c09fa3dc35b8b2f4776cfadf2449 Mon Sep 17 00:00:00 2001 From: David Mark Clements Date: Thu, 7 Dec 2023 15:42:02 +0100 Subject: [PATCH 2/4] api docs, cli tweaks --- reference/api.md | 946 +++++++++++++++++++++++++++++++++++++++++++++++ reference/cli.md | 23 +- 2 files changed, 964 insertions(+), 5 deletions(-) diff --git a/reference/api.md b/reference/api.md index e69de29..7e39e93 100644 --- a/reference/api.md +++ b/reference/api.md @@ -0,0 +1,946 @@ +# Application Programming Interface (API) + +The Pear API enables applications to interact with Pear platform features. + +Most application peer-to-peer functionality is provided by ecosystem modules rather than the API. + +Platform APIs are unchangable. Compatiblity cannot break. So the Pear API surface aims to be (and remain) +as small as possible. + +## `import pear from 'pear'` + +To use the Pear Platform API: import `pear`. + +```js +import pear from 'pear' +``` + +Import namespaces are also supported, for example: + +```js +import { config } from 'pear' +``` + +## `pear.config ` + +Contains application configuration data. + +### `pear.config.key ` + +The application key, `null` in development mode. +The `config.key` object holds both Hexadecimal and Z-Base-32 encodings of the key, and is of the form `{ z32: , hex: }`, + +### `pear.config.dev ` + +Whether application is in development mode + +### `pear.config.tier ` + +Runtime scenario (dev, staging or production) + +### `pear.config.storage ` + +Application storage path + +### `pear.config.name ` + +Application name + +### `pear.config.main ` + +Application entry file + +### `pear.config.channel ` + +Application release/staging channel, `null` in development mode. + +### `pear.config.options ` + +Configuration options. +The `pear` configuration object as supplied via an applications `package.json` file. + +**References** + +* [Configuration](./configuration.md) + +### `pear.config.env ` + +The environment variables that an application was started with, as key-value pairs in an object. + +### `pear.config.cwd ` + +The current working directory that an application was started from. + +### `pear.config.flags ` + +Parsed command-line flag values as supplied when an application was started. + +### `pear.config.tools ` + +Indicates whether or not Devtools is enabled. + +### `pear.config.watch ` + +Indicates whether or not Watch-Reload functionality is enabled. + +### `pear.config.storage ` + +Application storage path. + +### `pear.config.args ` + +Command-line application arguments passed after double dash `--`. + +### `pear.config.release ` + +The current release length as marked by the `pear release` command. + +**References** + +* [`pear release`](./cli.md) + +### `pear.config.link ` + +The Pear link of an application. Takes the form `pear:///`. + +In development, `pear://dev/`. + +**References** +* [pear.config.link](#pearconfiglinkdata-string) +* [`pear dev`](./cli.md) +* [`pear launch`](./cli.md) + +### `pear.config.linkData ` + +Holds just the data portion of a Pear link. + +The Pear link of an application. Takes the form `pear:///`. + +In development, `pear://dev/`. + +**References** + +* [pear.config.link](#pearconfiglink-string) +* [`pear dev`](./cli.md) +* [`pear launch`](./cli.md) + + +### `pear.config.checkpoint ` + +Holds state as set by `pear.checkpoint()`. When an application restarts it will hold the most recent value passed to `pear.checkpoint()`. + +Stores state that will be available as `pear.config.checkpoint` next time the application starts. + +The `pear.config.checkpoint` property immediately reflects the latest checkpoint. + +The returned `Promise` will resolve once the checkpoint has been successfully stored. + +**References** + +* [pear.checkpoint()](#pear-checkpoint-any) + +### `pear.config.release ` + +Application release sequence integer, `null` in development mode. + +### `pear.config.flags ` + +Parsed runtime flags. For internal/advanced use. + +## `pear.checkpoint() => Promise` + +Stores state that will be available as `pear.config.checkpoint` next time the application starts. + +The `pear.config.checkpoint` property immediately reflects the latest checkpoint. + +The returned `Promise` will resolve once the checkpoint has been successfully stored. + +**References** + +* [pear.config.checkpoint()](#pear--config-checkpoint-any) + +## pear.messages([ pattern ], [ listener ]) + +A function which accepts a pattern object and returns an [`Iambus`](https://github.com/holepunchto/iambus) subscriber (which inherits from [`streamx`](https://github.com/mafintosh/streamx) `Readable`) which emits message objects matching a provided pattern object. + +If no pattern object or an empty pattern object is provided all messages will be emitted. A pattern object is an object (typically) containing a subset of matching values for a given target object. Message objects can be user generated or platform generated. + +The subscriber stream has a `data` event which can be listened to, it can also be consumed with `for await` and an listener function can be passed in addition to pattern (`message(pattern, listener)`) or as a single argument (`messages(listener)`) (indicateding a catch-all pattern). + +A message object may have any properties. Platform-generated messages are given a `type` property. + +### Examples: + +Listen for an internal platform message using a pattern object and listener function: + +```js +import { messages } from 'pear' + +messages({ type: 'pear/wakeup' }, ({ data, link }) => { + console.log('pear/wakeup', data, link) +}) +``` + +Tiny utility module which logs all messages using `for await`: + +```js +import { messages } from 'pear' + +for await (const message of messages()) { + if (global.LOGBUS) console.log('BUS:', message) +} +``` + +Use `message` to create an application message: + +```js +import { message, messages } from 'pear' + +const ctaClicks = message({ type: 'my-app/user-cta' }) + +ctaClicks.on('data', (msg) => { console.log('cta click', msg) }) + +// elsewhere +onUserClickCta((event, data) => { + message({ type: 'my-app/user-cta', event, data }) +}) +``` + +## `await pear.message()` + +Send a message which will be: + +```js +import { message, messages } from 'pear' + +async function logMessages () { + for await (const message of messages()) console.log(message) +} + +logMessages().catch(console.error) + +let count = 0 +do { + await message({ type: 'tick', count }) + await new Promise((resolve) => setTimeout(resolve, 1000)) +} while (count++ < 1000) +``` + +## `pear.preferences ` + +User preferences management. + +### `for await (const [operation, key, value] of pear.preferences())` + +An async iterable that yields arrays containing `operation `, `key ` and `value `. + +Watch for application updates. The `operation` may be `set` or `del`. In the case of `del`, `value` is always `null`. + +### `for await (const [key, value] of pear.preferences.list())` + +Iterate through all available application preferences. + +### `const success = await pear.preferences.set(key, value)` + +Set a preference. The promise resolves to a boolean indicating success when the operation is complete. + +### `const value = await pear.preferences.get(key)` + +Get a preference. The promise resolves with the value. + +### `const success = await pear.preferences.del(key)` + +Delete a preference. The promise resolves to a boolean indicating success when the operation is complete. + + +```js +import { preferences } from 'pear' + +async function logPrefUpdates () { + for await (const [ operation, key, value ] of preferences()) console.table({ update: { operation, key, value }}) +} + +logPrefUpdates().catch(console.error) +``` + +## `pear.media ` + +Media interface + +### `const status = await pear.media.status.microphone()` + +Resolves to: ``. + +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 pear.media.status.camera()` + +Resolves to: ``. + +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 pear.media.status.screen()` + +Resolves to: `` + +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 pear.media.access.microphone()` + +Resolves to: `` + +Request access to the microphone. Resolves to `true` if permission is granted. + +### `const success = await pear.media.access.camera()` + +Resolves to: `` + +Request access to the camera. Resolves to `true` if permission is granted. + +### `const success = await pear.media.access.screen()` + +Resolves to: `` + +Request access to screen sharing. Resolves to `true` if permission is granted. + +### `const sources = await pear.media.desktopSources(options )` + +Captures available desktop sources. Resolves to an array of objects with shape `{ id , name , thumbnail , display_id , appIcon }`. The `id` is the window or screen identifier. The `name` is the window title or `'Screen '` 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. + +**Options** + +* `types >` - Default: `['screen', 'window']`. Filter by types. Types are `'screen'` and `'window'`. +* `thumbnailSize ` - Default: `{width: 150, height: 150}`. Set thumbnail scaling (pixels) +* `fetchWindowIcons ` - Default: `false`. Populate `appIcon` with Window icons, or else `null`. + +**References** + +* [win.getMediaSourceId()](#const-sourceid--await-wingetmediasourceid) +* [view.getMediaSourceId()](#const-sourceid--await-viewgetmediasourceid) +* [self.getMediaSourceId()](#const-sourceid--await-selfgetmediasourceid) +* [parent.getMediaSourceId()](#const-sourceid--await-parentgetmediasourceid) +* https://www.electronjs.org/docs/latest/api/desktop-capturer#desktopcapturergetsourcesoptions +* https://www.electronjs.org/docs/latest/api/structures/desktop-capturer-source +* [``](https://www.electronjs.org/docs/latest/api/native-image) + +### `pear.versions ` + +Versions object. Pear versions are objects with the shape `{ fork , length , key }`. + +The `key` is a Buffer of the launch key. The `length` is the size of the relevant Hypercore. The `fork` property is determined by data truncation. + +These three properties together are a unique identifier for the entire state of both applications and the Pear platform. + +### `pear.versions.platform { fork , length , key }` + +The platform version. + +### `pear.versions.application { fork , length , key }` + +The application version. + +**References** + +* [pear.config.key](#pearconfigkey-objectnull) + + +### `pear.teardown(fn )` + +Register application clean-up handlers to be called when an application begins to unload. + +May be called multiple times to register multiple teardown handlers. + +Functions supplied to teardown will be executed in order of registration when +an application begins to unload. Any promise returned from each supplied function +will be waited upon until resolution before calling the next teardown handler. + +### `pear.restart()` + +Restart the application. + +### `const win = new pear.Window(entry , options )` + +Create a new `Window` instance. + +**Options** + +* `show` Default: `true` - show the window as soon as it has been opened +* `x ` - the horizontal position of left side of the window (pixels) +* `y ` - vertical window position (pixels) +* `width ` - the width of the window (pixels) +* `height ` - the height of the window (pixels) +* `animate ` Default: `false` - animate the dimensional change. MacOS only, ignored on other OS's. +* `center ` - window minimum width (pixels) +* `minHeight ` - window minimum height (pixels) +* `maxWidth ` - window maximum width (pixels) +* `maxHeight ` - window maximum height (pixels) +* `resizable ` - window resizability +* `movable ` - window movability +* `minimizable ` - window minimizability +* `maximizable ` - window maximizability +* `closable ` - window closability +* `focusable ` - window focusability +* `alwaysOnTop ` - Set window to always be on top +* `fullscreen ` - Set window to fullscreen upon open +* `kiosk ` - Set window to enter kiosk mode upon open +* `autoHideMenuBar ` - Hide menu bar unless Alt key is pressed (Linux, Windows) +* `hasShadow ` - Set window shadow +* `opacity ` - Set window opacity (0.0 - 1.0) (Windows, macOS) +* `transparent ` - Set window transparency +* `backgroundColor ` Default: `'#FFF'` - window default background color. Hex, RGB, RGBA, HSL HSLA, CSS color + +### `win.on[ce]('message', (...args) => { })` +### `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 )` + +Resolves to: `` + +Open the window. + +**Options** + +* `show` Default: `true` - show the window as soon as it has been opened +* `x ` - the horizontal position of left side of the window (pixels) +* `y ` - vertical window position (pixels) +* `width ` - the width of the window (pixels) +* `height ` - the height of the window (pixels) +* `animate ` Default: `false` - animate the dimensional change. MacOS only, ignored on other OS's. +* `center ` - window minimum width (pixels) +* `minHeight ` - window minimum height (pixels) +* `maxWidth ` - window maximum width (pixels) +* `maxHeight ` - window maximum height (pixels) +* `resizable ` - window resizability +* `movable ` - window movability +* `minimizable ` - window minimizability +* `maximizable ` - window maximizability +* `closable ` - window closability +* `focusable ` - window focusability +* `alwaysOnTop ` - Set window to always be on top +* `fullscreen ` - Set window to fullscreen upon open +* `kiosk ` - Set window to enter kiosk mode upon open +* `autoHideMenuBar ` - Hide menu bar unless Alt key is pressed (Linux, Windows) +* `hasShadow ` - Set window shadow +* `opacity ` - Set window opacity (0.0 - 1.0) (Windows, macOS) +* `transparent ` - Set window transparency +* `backgroundColor ` Default: `'#FFF'` - window default background color. Hex, RGB, RGBA, HSL HSLA, CSS color + +### `const success = await win.close()` + +Resolves to: `` + +Close the window. + +### `const success = await win.show()` + +Resolves to: `` + +Show the window. + +### `const success = await win.hide()` + +Resolves to: `` + +Hide the window. + +### `const success = await win.focus()` + +Resolves to: `` + +Focus the window. + +### `const success = await win.blur()` + +Resolves to: `` + +Blur the window. + +### `const success = await win.minimize()` + +Resolves to: `` + +Minimize the window. + +### `const success = await win.maximize()` + +Resolves to: `` + +Maximize the window. + +### `const success = await win.restore()` + +Resolves to: `` + +Unmaximize/unminimize the window if it is currently maximized/minimized. + +### `await win.send(...args)` + +Send arguments to the window. They will be serialized with `JSON.stringify`. + + +### `const sourceId = await win.getMediaSourceId()` + +Resolves to: `` + +Correlates to the `id` property of objects in the array returned from [pear.media.desktopSources](#const-sources---await-appmediadesktopsources-options). + +**References** + +* [pear.media.desktopSources](#const-sources--await-appmediadesktopsourcesoptions-object) +* https://www.electronjs.org/docs/latest/api/browser-window#wingetmediasourceid + +### `const dimensions = await win.dimensions()` + +Resolves to: `{x , y , width , height } | null`. + +The height, width, horizontal (`x`), vertical (`y`) position of the window relative to the screen. + +All units ar (pixels) + +If the window is closed this will resolve to `null`. + +**References** + +* [await win.dimensions(options)](#await-windimensionsoptions-object) + +### `await win.dimensions(options )` + +```js +import { Window } from 'pear' +const win = new Window('./some.html', { + x: 10, + y: 450, + width: 300, + height: 350 +}) + +await win.open() +await new Promise((resolve) => setTimeout(resolve, 1000)) + +await win.dimensions({ + x: 20, + y: 50, + width: 550, + height: 300, + animate: true // only has an effect on macOS +}) + +``` + +Sets the dimensions of the window. + +**Options** + +* `x ` - the horizontal position of left side of the window (pixels) +* `y ` - the vertical position of the top of the window (pixels) +* `width ` - the width of the window (pixels) +* `height ` - the height of the window (pixels) +* `animate ` Default: `false` - animate the dimensional change. MacOS only, ignored on other OS's. +* `position ` - 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()` + +Resolves to: `` + +Whether the window is visible. + +### `const minimized = await win.isMinimized()` + +Resolves to: `` + +Whether the window is minimized. + +### `const maximized = await win.isMaximized()` + +Resolves to: `` + +Whether the window is maximized. + +### `const closed = await win.isClosed()` + +Resolves to: `` + +Whether the window is closed. + +### `const closed = await win.isClosed()` + +Resolves to: `` + +Whether the window is closed. + +### `const view = new pear.View(options )` + +Create a new `View` instance. Views provide isolated content views. Frameless, chromeless windows that can be embedded inside other windows and views. + +**Options** + +* `x ` - the horizontal position of left side of the view (pixels) +* `y ` - vertical view position (pixels) +* `width ` - the width of the view (pixels) +* `height ` - the height of the view (pixels) +* `backgroundColor ` Default: `'#FFF'` - view default background color. Hex, RGB, RGBA, HSL HSLA, CSS color +* `autoresize ` 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) => { })` +### `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 )` + +Resolves to: `` + +Open the view. + +**Options** + +* `x ` - the horizontal position of left side of the view (pixels) +* `y ` - vertical view position (pixels) +* `width ` - the width of the view (pixels) +* `height ` - the height of the view (pixels) +* `backgroundColor ` Default: `'#FFF'` - view default background color. Hex, RGB, RGBA, HSL HSLA, CSS color +* `autoresize ` 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()` + +Resolves to: `` + +Close the view. + +### `const success = await view.show()` + +Resolves to: `` + +Show the view. + +### `const success = await view.hide()` + +Resolves to: `` + +Hide the view. + +### `const success = await view.focus()` + +Resolves to: `` + +Focus the view. + +### `const success = await view.blur()` + +Resolves to: `` + +Blur the view. + +### `await view.send(...args)` + +Send arguments to the view. They will be serialized with `JSON.stringify`. + +### `const sourceId = await view.getMediaSourceId()` + +Resolves to: `` + +Supplies the `id` property of objects in the array returned from [pear.media.desktopSources](#const-sources---await-appmediadesktopsources-options). + +**References** + +* [pear.media.desktopSources](#const-sources---await-appmediadesktopsources-options) +* https://www.electronjs.org/docs/latest/api/browser-window#wingetmediasourceid + +### `const dimensions = await view.dimensions()` + +Resolves to: `{x , y , width , height } | null`. + +The height, width, horizontal (`x`), vertical (`y`) position of the window relative to the screen. + +All units ar (pixels) + +If the Window is closed this will resolve to `null`. + +**References** + +* [await view.dimensions(options)](#await-viewdimensionsoptions-object) + +### `await view.dimensions(options )` + +```js +import { View } from 'pear' +const view = new View('./some.html', { + x: 10, + y: 450, + width: 300, + height: 350 +}) + +await view.open() +await new Promise((resolve) => setTimeout(resolve, 1000)) + +await view.dimensions({ + x: 20, + y: 50, + width: 550, + height: 300 +}) +``` + +Sets the dimensions of the view. + +**Options** + +* `x ` - the horizontal position of left side of the window (pixels) +* `y ` - the vertical position of the top of the window (pixels) +* `width ` - the width of the window (pixels) +* `height ` - the height of the window (pixels) + + +**References** + +* [const dimensions = await view.dimensions()](#const-dimensions--await-viewdimensions) + +### `const visible = await view.isVisible()` + +Resolves to: `` + +Whether the view is visible. + +### `const closed = await view.isClosed()` + +Resolves to: `` + +Whether the view is closed. + +### `const { self } = pear.Window` `const { self } = pear.View` + +### `const success = await self.focus()` + +Resolves to: `` + +Focus current view or window. + +### `const success = await self.blur()` + +Resolves to: `` + +Blur current view or window. + +### `const success = await self.show()` + +Resolves to: `` + +Show current view or window. + +### `const success = await self.hide()` + +Resolves to: `` + +Hide current view or window. + +### `const sourceId = await self.getMediaSourceId()` + +Get the sourceId of the current window or view. + +**References** + +* [win.getMediaSourceId()](const-sourceId--await-wingetMediaSourceId) + + +### `const success = await self.minimize()` + +Resolves to: `` + +Minimize current window. + +Throws a `TypeError` if `self` is a view. + +### `const success = await self.maximize()` + +Resolves to: `` + +Maximize current window. + +Throws a `TypeError` if `self` is a view. + +### `const success = await self.restore()` + +Resolves to: `` + +Unmaximize/unminimize the current window if it is currently maximized/minimized. + +Throws a `TypeError` if `self` is a view. + + +### `const success = await self.close()` + +Resolves to: `` + +Closes the current view or window. + + +### `const isVisible = await self.isVisible()` + +Resolves to: `` + +Whether the current window or view is visible. + +### `const isMaximized = await self.isMaximized()` +Resolves to: `` + +Whether the current window is maximized. Throws a `TypeError` if `self` is a view. + + +### `const isMinimized = await self.isMinimized()` + +Resolves to: `` + +Whether the current window is minmized. Throws a `TypeError` if `self` is a view. + +### `const { parent } = pear.Window` `const { parent } = pear.View` + +### `parent.on[ce]('message', (...args) => { })` +### `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)` + +Send arguments to the parent view or window. They will be serialized with `JSON.stringify`. + + +### `const success = await parent.focus()` + +Resolves to: `` + +Focus parent view or window. + +### `const success = await parent.blur()` + +Resolves to: `` + +Blur parent view or window. + +### `const success = await parent.show()` + +Resolves to: `` + +Show parent view or window. + +### `const success = await parent.hide()` + +Resolves to: `` + +Hide parent view or window. + +### `const sourceId = await parent.getMediaSourceId()` + +Get the sourceId of the parent window or view. + +**References** + +* [win.getMediaSourceId()](#const-sourceId--await-wingetMediaSourceId) + + +### `const success = await parent.minimize()` + +Resolves to: `` + +Minimize parent window. + +Throws a `TypeError` if `parent` is a view. + +### `const success = await parent.maximize()` + +Resolves to: `` + +Maximize parent window. + +Throws a `TypeError` if `parent` is a view. + +### `const success = await parent.restore()` + +Resolves to: `` + +Unmaximize/unminimize the parent window if it is currently maximized/minimized. + +Throws a `TypeError` if `parent` is a view. + +### `const success = await parent.close()` + +Resolves to: `` + +Closes the parent view or window. + +### `const isVisible = await parent.isVisible()` + +Resolves to: `` + +Whether the parent window or view is visible. + +### `const isMaximized = await parent.isMaximized()` +Resolves to: `` + +Whether the parent window is maximized. Throws a `TypeError` if `parent` is a view. + + +### `const isMinimized = await parent.isMinimized()` + +Resolves to: `` + +Whether the parent window is minmized. Throws a `TypeError` if `parent` is a view. + + +## Web APIs + +Most [Web APIs](https://developer.mozilla.org/en-US/docs/Web/API) will work as-is. + +This section details deviations in behavior from and notable aspects of Web APIs as they relate to Pear. + +### `window.open` + +The [`window.open`](https://developer.mozilla.org/en-US/docs/Web/API/Window/open) Web API function will ignore all arguments except for the URL parameter. + +In browsers, `window.open` opens a new browser window. The opened window belongs to the same browser from which `window.open` is called. + +In Pear, `window.open` loads the URL in the **default system browser**. It does *not* create a new application window (use `pear.Window` to create application windows). + +Therefore Pear's `window.open` only supports a single url argument. The `target` and `windowFeatures` parameters that browsers support are discarded. + +### Scripts and Modules + +Like browsers, there is no support for CommonJS (e.g. the `require` function as used by Node.js is not supported in Pear Applications). + +Like browsers, there is support for native EcmaScript Modules (ESM). A JavaScript Script has no module capabilities. A JavaScript Module has ESM capabilities. + +Use `