Add documentation on plugin load/execute lifecycle and edit operations.

Expand "Accessing APIs" doc to list at a high level the different categories
of APIs (XD, UXP, etc.)

Author: peterflynn

SUMMARY.md

@@ -15,12 +15,13 @@
     * [Sync and async](./reference/javascript/sync-async.md)
     * [API environment](./reference/javascript/environment.md)
   * [XD concepts](./reference/core/index.md)
+    * [Plugin lifecycle](./reference/core/lifecycle.md)
     * [The scenegraph](./reference/core/scenegraph.md)
-    * [The edit context](./reference/core/edit-context.md)
-    * [Coordinate spaces & units](./reference/core/coordinate-spaces-and-units.md)
+    * [Edit Context rules](./reference/core/edit-context.md)
     * [Properties with object values](./reference/core/properties-with-object-values.md)
+    * [Coordinate spaces & units](./reference/core/coordinate-spaces-and-units.md)
     * [Automatic cleanups](./reference/core/automatic-cleanups.md)
-    * [APIs](./reference/core/apis.md)
+    * [Accessing APIs](./reference/core/apis.md)
   * [Development best practices](./devbestpractices/index.md)
     * [1.0 Performance](./devbestpractices/1-performance.md)
     * [2.0 Scenegraph](./devbestpractices/2-scenegraph.md)

reference/core/apis.md

@@ -1,32 +1,49 @@
 # Available APIs
 
-Adobe XD provides several APIs to you, via the `require` method. You can also import your own modules and files using `require`.
+Adobe XD provides several categories of APIs:
 
-## Principal API modules
+* **[APIs for interacting with XD itself](#xd-specific-apis)**, especially its document model, the **scenegraph**
+
+* The **UXP runtime**, which provides all the capabilities that aren't XD-specific:
+    * A [_browser-like_ HTML and CSS engine](../uxp/ui-index.md) which drives actual XD _native UI components_ -- it is **not** a complete browser engine, but lets you build your UI using familiar web APIs and frameworks.
+    * [Network APIs](../uxp/network-index.md) similar to the web standard XHR, `fetch`, and WebSocket found in browsers.
+    * The [`storage` API](../uxp/storage-index.md), offering sandboxed filesystem access.
+
+* The usual **[core JavaScript language APIs](../javascript/javascript-support.md)** you see in all JS runtimes, such as `setTimeout()` and `Date`.
+
+* A simple **[module-loader `require()` API](../javascript/javascript-support.md#can-i-use-require)**
+
+Read below for **how to access** XD and UXP APIs...
+
+
+## XD-specific APIs
+
+Most XD APIs are accessed by loading a module via `require()`, but some are passed directly to your plugin's handler functions.
 
 * [selection](../selection.md) - Indicates the selected nodes and related context
     * This object is passed as an argument to your command handler function (see above)
 * [scenegraph](../scenegraph.md) - APIs available on document nodes
-    * Normally you can use these APIs by simply accessing the arguments passed to your command's handler function
+    * Typically you use scenegraph objects by simply accessing the arguments passed to your command's handler function
       (`selection` and `documentRoot`).
     * To create _new_ nodes in the document, load this module explicitly to access the constructor functions:
       ```js
       let Rectangle = require("scenegraph").Rectangle;
       let node = new Rectangle();
       ```
 * [commands](../commands.md) - Invoke commands to change the document structure and perform other complex operations.
-    * Load this module explicitly: `let commands = require("commands");`
+    * `let commands = require("commands");`
 * [interactions](../interactions.md) - Data model for interactive prototyping features (also accessible from scenegraph nodes).
-    * Load this module explicitly: `let interactions = require("interactions");`
-* [storage](../uxp/storage-index.md) - Read and write files on disk
-    * Load this module explicitly: `const fs = require("uxp").storage.localFileSystem;`
-* [Network](../uxp/network-index.md) - Use browser-style `XMLHttpRequest`, `fetch()`, and `WebSocket` APIs to access the network.
-    * These APIs are in the global namespace, so you can use them without any `require()` statements
+    * `let interactions = require("interactions");`
 * [application](../application.md) - Version and locale information, and APIs for exporting content.
-    * Load this module explicitly: `let application = require("application");`
+    * `let application = require("application");`
 * [clipboard](../clipboard.md) - Copy text to the clipboard.
-    * Load this module explicitly: `let clipboard = require("clipboard");`
+    * `let clipboard = require("clipboard");`
+
+
+## UXP
+
+* HTML DOM APIs -- access just as in a browser, via the global `document`. Each plugin in XD gets its own `document` tree.
 
-## Helper classes
+* Network APIs -- access just as in a browser, via the global classes `XMLHttpRequest` and `WebSocket`, and the global function `fetch()`
 
-* [SceneNodeList](../SceneNodeList.md) - This is the type of the `children` property on scenenodes
+* Storage APIs -- access via `const fs = require("uxp").storage.localFileSystem;`

reference/core/index.md

@@ -1,10 +1,11 @@
 # XD concepts
 
-Since your plugin code will run within XD, it's important to understand some concepts that are specific to the application.
+These important concepts are specific to plugins for XD:
 
+- [Plugin lifecycle](./lifecycle.md)
 - [Scenegraph](./scenegraph.md)
-- [Edit context rules](./edit-context.md)
-- [Coordinate spaces & units](./coordinate-spaces-and-units.md)
+- [Edit Context rules](./edit-context.md)
 - [Properties with object values](./properties-with-object-values.md)
+- [Coordinate spaces & units](./coordinate-spaces-and-units.md)
 - [Automatic cleanups](./automatic-cleanups.md)
-- [APIs](./apis.md)
+- [Accessing APIs](./apis.md)

reference/core/lifecycle.md

@@ -0,0 +1,51 @@
+# Plugin lifecycle
+
+Here's an overview of how plugins are loaded, when plugin code runs, and how plugin "edit operations" work.
+
+
+## Plugin loading
+
+Each XD document window loads a separate copy of your plugin's JavaScript code with a separate UXP UI `document` global (as if they were, say, separate browser windows). It's not yet possible for the JavaScript in one window to communicate with other windows, short of using a web server or other external channel.
+
+Each plugin is loaded into an isolated context with its own set of global variables. Different plugins cannot share objects or functions with each other.
+
+Your plugin's code remains resident until the document is closed (or until a developer runs the Reload Plugins command). This means you can store temporary "session" state in global or module-level variables.
+
+
+## When plugins run
+
+Several different situations can cause code in your plugin to get executed:
+
+* **Initialization** -- When loading, any "top-level" code in each module (JS file) is executed immediately. You can't edit the document or show UI at this point. Only perform tasks that are absolutely necessary for basic loading and initialization -- defer as much as possible until later, when the user invokes your plugin for the first time.
+
+* **Command handlers** -- Each time one of your plugin's menu commands is invoked, XD calls your [_command handler function_ for the relevant `commandId`](../structure/handlers.md). Your command handler can edit the document or open a dialog box; if you return a Promise, these privileges extend until the Promise completes. See ["Edit operations"](#edit-operations) for details.
+
+* **DOM events** -- Handlers you've attached to dialog box UI are triggered whenever the event occurs (while the dialog box is open). Since dialogs are typically open only during an [edit operation](#edit-operations), this event handler code can edit the document too.
+
+* **Network API handlers and timers** -- Other events can happen at any time, such as a network call finishing or a `setTimeout()` firing.
+    * If you've engineered an async edit operation's Promise to wait for these events before resolving, then these handlers can also edit the document.
+    * You can also run network requests and timers entirely in the background, outside of any edit operation, though this is discouraged. Plugin code running in the background can make XD slow. And although you'll have read-only access to the scenegraph, this is unsafe since your background code may run _in the middle of_ some other asynchronous edit operation (whether from a built-in XD command, another plugin, etc.) -- so your code might see an incorect intermediate state of the document.
+
+
+## Edit operations
+
+An edit operation is the window of time in which your plugin is making a batch of related changes to the document. One edit operation equals one Undo step.
+
+Your plugin can modify multiple properties on multiple scenegraph nodes during an edit operation, and they are all automatically batched together.
+
+#### Edit operation duration
+* An edit operation begins when your plugin's [command handler](../structure/handlers.md) is called.
+* If the command handler returns synchronously, the edit operation is done as soon as it returns.
+* If the command handler returns a Promise, the edit operation continues asynchronously until the Promise completes. _The user can't do anything else in XD_ until the operation completes, so normally a Promise is only returned if the plugin has a dialog box open that the user is interacting with or that is showing a progress indicator.
+
+If the command handler throws an exception, or its Promise is rejected, the entire edit batch is atomically rolled back automatically by XD.
+
+#### Modal/exclusive UI
+While an edit operation is in progress, XD prevents any edits from other plugins or other features. The user can't interact with any XD UI other than dialogs shown by your plugin.
+
+Even if your plugin doesn't have a dialog box open during an async edit operation, the XD UI still remains frozen. If an edit operation continues for over 1 second without any UI being shown, XD shows a "Plugin is working" message which allows users to forcibly abort the edit operation. For this reason, during long-running async steps like network requests it's best to display your own nicer progress UI (users can always still cancel this too, by pressing Escape at any time).
+
+#### UI updates
+Just as in a web browser, XD won't update the UI in the middle of your plugin code's _synchronous_ execution. As soon as there's an async gap in execution, any changes you've made to dialog box DOM or to the document scenegraph will be reflected in XD's UI.
+
+For example, if your plugin makes some partial edits to the scenegraph, then waits on a network request, then uses the results to make more edits -- although the entire operation is atomic with respect to Undo, the user will see the partial edits displayed onscreen for a brief moment while your plugin code is idle waiting for the async network request to complete.

reference/javascript/javascript-support.md

@@ -51,6 +51,4 @@ const someLib = require("somelib");  // no package.json lookup
 
 ## Can I use npm packages or Node.js APIs?
 
-You may be able to use some npm packages without modification, but chances are good that you’ll need to use webpack or rollup in order to generate a bundle.
-
-Node.js APIs themselves are not supported.
+XD's plugin sandbox does not include most Node.js APIs, such as unrestricted filesystem access or the ability to spawn external processes. Npm packages that only depend on the core JavaScript language APIs can work in XD, but because XD's `require()` differs (see above), you will likely have to use webpack or rollup in order to generate a single-file bundle first.