Rewrite Share interface docs and split into two APIs.

docs/interface_share_target.md

Index: docs/interface_share_target.md
diff --git a/docs/interface_share_target.md b/docs/interface_share_target.md
new file mode 100644
index 0000000000000000000000000000000000000000..b0ea383c223a46e9735882505221dfcb9f1e36a0
--- /dev/null
+++ b/docs/interface_share_target.md
@@ -0,0 +1,134 @@
+# Web Share Target Interface
+
+**Date**: 2016-05-30
+
+This document is a rough spec (i.e., *not* a formal web standard draft) of the
+Web Share Target API. This API allows websites to register to receive shared
+content from either the [Web Share API](interface_share.md), or system events
+(e.g., shares from native apps).
+
+This API requires the user agent to support both [service
+workers](https://www.w3.org/TR/service-workers/) and [web app
+manifests](https://www.w3.org/TR/appmanifest/). The [Web Share
+API](interface_share.md) is not required, but recommended.
+
+Examples of using the Share Target API for sharing can be seen in the
+[explainer document](explainer.md).
+
+**Note**: The Web Share Target API is a proposal of the [Ballista
+project](../README.md), which aims to explore website-to-website and
+website-to-native interoperability.
+
+## App manifest
+
+The first thing a handler needs to do is declare its share handling capabilities
+in its [web app manifest](https://www.w3.org/TR/appmanifest/):
+
+```WebIDL
+partial dictionary Manifest {
+  boolean supports_share;
+};
+```
+
+The `"supports_share"` member of the manifest, if `true`, indicates that the app
+can receive share events from requesters, or the system. The declarative nature
+of the manifest allows search services to index and present web applications
+that handle shares.
+
+Handlers declaring `supports_share` in their manifest will **not** be
+automatically registered; the user must explicitly authorize the registration.
+How this takes place is still under consideration (see [User
+Flow](user_flow.md#registering-a-website-as-a-handler-on-mobile), but will
+ultimately be at the discretion of the user agent (the user may be automatically
+prompted, or may have to explicitly request registration).
+
+**For consideration**: We may wish to provide a method for websites to
+explicitly request to prompt the user for handler registration. There would
+still be a requirement to declare `supports_share` in the manifest. For now, we
+have omitted such a method from the design to keep control in the hands of user
+agents. It is easier to add such a method later than remove it.
+
+## Event handlers
+
+Handlers **must** have a registered [service
+worker](https://www.w3.org/TR/service-workers/).
+
+When the user picks a registered web app as the target of a share, the
+handler's service worker starts up (if it is not already running), and a
+`"share"` event is fired at the global object.
+
+```WebIDL
+partial interface WorkerGlobalScope {
+  attribute EventHandler onshare;
+};
+
+interface ShareEvent : ExtendableEvent {
+  readonly attribute ShareData data;
+
+  void reject(DOMException error);
+};
+
+dictionary ShareData {
+  DOMString? title;
+  DOMString? text;
+  DOMString? url;
+};
+```
+
+The `onshare` handler (with corresponding event type `"share"`) takes a
+`ShareEvent`. The `data` field provides data from the sending application.
+
+How the handler deals with the data object is at the handler's discretion, and
+will generally depend on the type of app. Here are some suggestions:
+
+* An email client might draft a new email, using `title` as the subject of an
+  email, with `text` and `url` concatenated together as the body.
+* A social networking app might draft a new post, ignoring `title`, using `text`
+  as the body of the message and adding `url` as a link. If `text` is missing,
+  it might use `url` in the body as well. If `url` is missing, it might scan
+  `text` looking for a URL and add that as a link.
+* A text messaging app might draft a new message, ignoring `title` and using
+  `text` and `url` concatenated together. It might truncate the text or replace
+  `url` with a short link to fit into the message size.
+
+A share fails if:
+
+* The handler had no registered service worker.
+* There was an error during service worker initialization.
+* There is no event handler for `share` events.
+* The event handler explicitly calls the event's `reject` method (either in the
+  event handler, or in the promise passed to the event's
+  [`waitUntil`](https://www.w3.org/TR/service-workers/#wait-until-method)
+  method).
+* The promise passed to `waitUntil` is rejected.
+
+Once the event completes without failing, the share automatically succeeds, and
+the requester's promise is resolved. The end of the event's lifetime marks the
+end of the share, and there is no further communication in either direction.
+
+The Share Target API is defined entirely within the service worker. If the
+handler needs to provide UI (which should be the common case), the service
+worker must create a foreground page and send the appropriate data between the
+worker and foreground page, out of band. The `share` event handler is [allowed
+to show a
+popup](https://html.spec.whatwg.org/multipage/browsers.html#allowed-to-show-a-popup),
+which means it can call the
+[`clients.openWindow`](https://www.w3.org/TR/service-workers/#clients-openwindow-method)
+method.
+
+## Where do shares come from?
+
+Share events can be sent from a variety of places:
+
+* Built-in trigger (e.g., user picks "Share" from a browser's menu, to share the
+  URL in the address bar).
+* A native application.
+* A web application using the [Web Share API](interface_share.md).
+
+There will usually be a picker that lets the user select a target app. This
+could be the native system app picker, or a user-agent-supplied picker. The apps
+could include other system apps and actions alongside the web app handlers.
+
+If an event comes from a web app, the `data` field of the event should be a
+clone of the `data` parameter to `navigator.share`. If the event comes from some
+other source, the user agent may construct the `data` object as appropriate.