Document extension and app types

extensions/docs/extension_and_app_types.md

Index: extensions/docs/extension_and_app_types.md
diff --git a/extensions/docs/extension_and_app_types.md b/extensions/docs/extension_and_app_types.md
new file mode 100644
index 0000000000000000000000000000000000000000..46c7e4ca8402034362dcc805c0f1823714abbb86
--- /dev/null
+++ b/extensions/docs/extension_and_app_types.md
@@ -0,0 +1,87 @@
+# Extension and App Types
+
+Generally, browser extensions cut across websites and web apps, while apps
+provide more isolated functionality.
+
+[TOC]
+
+![Summary of extension types](extension_types.png)
+
+## Browser extensions
+
+Unlike apps, a browser extension creates an icon in the Chrome toolbar, which
+may be interactive when `browser_action` or `page_action` manifest keys are
+used.
+
+Furthermore, browser extensions can be granted permission to read or modify:
+
+* web page content
+* cookies
+* downloads

[Devlin, 2017/02/21 14:05:10]

This list is very inexhaustive.  I wonder if we should instead concentrate on
the more fundamental aspects?  I usually consider an extension "something that
can alter my browsing experience through interaction with either the web content
or the browser itself."

[michaelpg, 2017/02/21 23:50:39]

Shortened to be less specific.

+
+`Extension` is also the class type for all extensions and apps, so technically

[Devlin, 2017/02/21 14:05:10]

This is pretty nitty-gritty, and is really a code implementation detail.  Do we
really want it here?  At the very least, I'd put it in a separate section. 
Conceptually, they are very different.

[michaelpg, 2017/02/21 23:50:39]

yeah, i've moved this to the end.

+speaking, an app *is-an* `Extension`. Usually, the word "extension" refers only
+to non-app extensions, a.k.a. *browser extensions*.
+

[Devlin, 2017/02/21 14:05:10]

Do we want to document shared modules or converted user scripts?

[michaelpg, 2017/02/21 23:50:39]

Feel free! (I didn't even know about converted user scripts...)

+## Apps
+
+### Platform app
+
+Platform apps (*v2 packaged apps*) have `app.background.page` and/or

[Devlin, 2017/02/21 14:05:10]

Here, too, I'd start with something more fundamental - what is a platform app?

Something along the lines of "an isolated application that runs independently of
the browser", and maybe give some canonical examples (e.g. calculator).

[michaelpg, 2017/02/21 23:50:40]

Done.

+`app.background.scripts` manifest keys. The background page and scripts are
+loaded when the platform app is enabled; they usually listen to the
+`chrome.app.runtime.onLaunched` event to create platform app windows and do
+app-y stuff.
+
+Unlike browser extensions, platform apps can connect to network sockets and
+bluetooth, hid, and usb devices.

[benwells, 2017/02/20 23:57:02]

Might want to add that these are deprecated on all platforms except ChromeOS.

I just saw in the .png there is a "Deprecated on desktop." Could you say
"Deprecated on non-ChromeOS platforms" instead?

[michaelpg, 2017/02/21 23:50:39]

Doh, yes indeed.
Done.

+
+### Packaged app (legacy)
+
+The idea behind [legacy (v1) packaged apps](
+https://developer.chrome.com/extensions/apps) was to combine the appearance of a
+[hosted app](#Hosted-app) -- a windowed wrapper around a website -- with the
+power of extension APIs.  With the launch of platform apps and the app-specific
+APIs, legacy packaged apps are deprecated.
+
+Legacy packaged apps have an `app.launch.local_path` manifest key.
+
+### Hosted app
+
+A [hosted app](https://developer.chrome.com/webstore/hosted_apps) is mostly
+metadata: a web URL to launch, a list of associated URLs, and a list of HTML5
+permissions. Chrome ask for these permissions during the app's installation,

[Devlin, 2017/02/21 14:05:10]

Should we mention Chrome?

(also, typo, *asks)

[michaelpg, 2017/02/21 23:50:40]

As opposed to "the browser" or something? (IIRC, Chrome is the product name as
far as documentation and descriptions are concerned, even in the Chromium
project.)

+allowing the associated URL to bypass the normal Chrome permission prompts for
+HTML5 features.
+
+### Bookmark app
+
+A bookmark app is generated when the user taps "Add to desktop" (or "Add to
+shelf" or Chrome OS) in the Chrome menu when visiting a web page or an extension

[Rahul Chaturvedi, 2017/02/17 22:28:55]

s/or/on

[benwells, 2017/02/20 23:57:02]

I think it is as it is?

[michaelpg, 2017/02/21 23:50:39]

Done.

[michaelpg, 2017/02/21 23:50:39]

The first "or" should be "on".

[benwells, 2017/02/22 06:46:49]

Doh!

+page in a tab. This user action creates a barebones extension containing the
+site's favicons and a manifest file with the `app.launch.web_url` key set to the
+tab's URL.
+
+The icon Chrome creates on the desktop is simply a shortcut to Chrome, with the
+`--profile-directory` and `--app-id` flags set. Activating the icon launches
+the app in a tab or a window, depending on a setting in Preferences.
+
+The icon will also appear in chrome://apps (even if it points to another
+extension already visible in chrome://apps).
+
+This kind of app is technically a hosted app.

[benwells, 2017/02/20 23:57:02]

This is true but there are some little differences. Maybe say "This kind of app
is implemented as a special type of hosted app." ??

[michaelpg, 2017/02/21 23:50:39]

Reworked into the opening paragraph.

+
+## See also
+
+* [`Manifest::Type` declaration](https://cs.chromium.org/chromium/src/extensions/common/manifest.h?gs=cpp%253Aextensions%253A%253Aclass-Manifest%253A%253Aenum-Type%2540chromium%252F..%252F..%252Fextensions%252Fcommon%252Fmanifest.h%257Cdef&gsn=Type&ct=xref_usages)
+* Extensions (3rd-party developer documentation)
+    * [Extension APIs](https://developer.chrome.com/extensions/api_index)
+    * [Extension manifest file format](
+      https://developer.chrome.com/extensions/manifest)
+* Apps (3rd-party developer documentation)
+    * [Platform app APIs](https://developer.chrome.com/apps/api_index)
+    * [Platform app manifest file format](
+      https://developer.chrome.com/apps/manifest)
+    * [Choosing an app type](https://developer.chrome.com/webstore/choosing)
+    * Ancient article introducing the [motivation for apps (outdated)](
+      https://developer.chrome.com/webstore/apps_vs_extensions)