diff --git a/src-docs/faq/compat.md b/src-docs/faq/compat.md
index 7d0cb8c..667acda 100644
--- a/src-docs/faq/compat.md
+++ b/src-docs/faq/compat.md
@@ -8,6 +8,8 @@ Webxdc apps run in a restricted environment, but the following practices are per
- `localStorage`, `sessionStorage`, `indexedDB`
- `visibilitychange` events
- `window.navigator.language`
+- `window.location.href` but you can not specify or assume anything
+ about the scheme or domain part of the url.
- internal links, such as ``
- `mailto` links, such as ``
- `` is useful especially as webviews from different platforms have different defaults
diff --git a/src-docs/spec/format.md b/src-docs/spec/format.md
index 9de6a47..ad1954d 100644
--- a/src-docs/spec/format.md
+++ b/src-docs/spec/format.md
@@ -7,7 +7,8 @@
- the ZIP-file MUST contain at least the file `index.html`
- the ZIP-file MAY contain a `manifest.toml` and `icon.png` or
`icon.jpg` files
-- if the webxdc app is started, `index.html` MUST be opened in a [restricted webview](#webview-constraints-for-running-apps) that only allows accessing
+- if the webxdc app is started, `index.html` MUST be opened in a
+ [restricted webview](../faq/compat.html) that only allows accessing
resources from the ZIP-file.
### The manifest.toml File
diff --git a/src-docs/spec/selfAddr_and_selfName.md b/src-docs/spec/selfAddr_and_selfName.md
index 84874d4..c5eacab 100644
--- a/src-docs/spec/selfAddr_and_selfName.md
+++ b/src-docs/spec/selfAddr_and_selfName.md
@@ -1,27 +1,76 @@
# selfAddr & selfName
+## selfName
+
+```js
+window.webxdc.selfName
+```
+
+`selfName` is the nick or display name for the user
+which can be displayed in the user interface of the webxdc application.
+
+
## selfAddr
```js
window.webxdc.selfAddr
```
-A string with an unique ID identifying the user in the current webxdc.
-Every user of an webxdc must get a different ID
-and that ID must be the same if the webxdc is started again later for the same user.
-The same user in different webxdc, however, may have different IDs.
+`selfAddr` is a unique string within a webxdc application that
-Especially useful if you want to differentiate between different peers -
-just send the ID along with the payload,
-and, if needed, compare the payload addresses against `selfAddr` later on.
+- has no meaning outside the webxdc app,
-## selfName
+- can be used in other webxdc APIs,
+
+- should not be shown in the user interface of the webxdc application,
+
+- is identical across multiple invocations of the same webxdc application,
+
+- is identical on multiple devices of the user using the same webxdc application.
+
+- is not linkable to addresses in other webxdc apps:
+ even if a web app manipulates users to share addresses via copy+paste with another web app,
+ addresses between the two web apps can not be correlated.
+
+
+## Example using selfAddr and selfName
+
+Here is a simple chat app that sends out a reply using the display names
+but uses the addresses for notifications.
```js
-window.webxdc.selfName
-```
-Name of the current account, as defined in settings.
-If empty, this defaults to the peer's address.
+// Receive a message from anyone in the chat
+let users = new Set();
+
+setUpdateListener((update) => {
+ const prompt = `${update.payload.senderName} (${update.payload.senderAddr}):`;
+ users.add(update.payload.senderAddr);
+ console.log(`${prompt} ${update.message}`);
+})
+
+// start some user interface which calls the following function for
+// message sending
+
+sendMessage(text) => {
+ let payload = {
+ senderAddr: webxdc.selfAddr,
+ senderName: webxdc.selfName,
+ message: text
+ };
+
+ // notify all users who ever sent a message in the chat app
+ let notify = {};
+ for (const addr of users) {
+ notify[addr] = `new message from ${webxdc.selfName}`;
+ }
+
+ sendUpdate({
+ payload: payload,
+ notify: notify
+ })
+})
+```
+[`sendUpdate()`]: ./sendUpdate.html
diff --git a/src-docs/spec/sendUpdate.md b/src-docs/spec/sendUpdate.md
index 84e45c8..57bef80 100644
--- a/src-docs/spec/sendUpdate.md
+++ b/src-docs/spec/sendUpdate.md
@@ -6,34 +6,60 @@ window.webxdc.sendUpdate(update);
Send an update to all peers.
-- `update`: an object with the following properties:
- - `update.payload`: string, number, boolean, array, object or `null`.
- MUST NOT be `undefined`.
- Everything that is not JSON serializable will be skipped,
- this especially affects Binary data buffers as used in `File`, `Blob`, `Int*Array` etc.;
- if needed, use eg. base64.
- - `update.info`: optional, short, informational message that will be added to the chat,
- e.g. "Alice voted" or "Bob scored 123 in MyGame".
- Do not add linebreaks; implementations will truncate the text at about 50 characters or less.
- If there are series of info messages, older ones may be dropped.
- use this option sparingly to not spam the chat.
- - `update.document`: optional, name of the document in edit
- (eg. the title of a poll or the name of a text in an editor)
- Implementations show the document name e.g. beside the app icon or in the title bar.
- MUST NOT be used if the webxdc does not create documents, e.g. in games.
- Do not add linebreaks; implementations will truncate the text at about 20 characters or less.
- - `update.summary`: optional, short text, shown beside the app icon;
- it is recommended to use some aggregated value, e.g. "8 votes", "Highscore: 123".
- Do not add linebreaks; implementations will truncate the text at about 20 characters or less.
-
All peers, including the sending one,
will receive the update by the callback given to [`setUpdateListener()`](./setUpdateListener.html).
There are situations where the user cannot send messages to a chat,
e.g. if the webxdc instance comes as a contact request or if the user has left a group.
-In these cases, you can still call `sendUpdate()`,
-however, the update won't be sent to other peers
-and you won't get the update by [`setUpdateListener()`](./setUpdateListener.html).
+In these cases, an app can still call `sendUpdate()`,
+but the update won't be sent to other peers
+and it will not be passed to [`setUpdateListener()`](./setUpdateListener.html).
+
+The `update` object has the following properties:
+
+- `update.payload`: string, number, boolean, array, object or `null`.
+ MUST NOT be `undefined`.
+ Everything that is not JSON serializable will be skipped,
+ this especially affects Binary data buffers as used in `File`, `Blob`, `Int*Array` etc.;
+ if needed, use eg. base64.
+
+- `update.info`: optional, short, informational message that will be added to the chat,
+ e.g. "Alice voted" or "Bob scored 123 in MyGame".
+ Do not add linebreaks; implementations will truncate the text at about 50 characters or less.
+ If there are series of info messages, older ones may be dropped.
+ use this option sparingly to not spam the chat.
+
+- `update.notify`: optional dictionary mapping an [address](./selfAddr_and_selfName.md)
+ to a text that should be shown as a user-visible notification to the addressed user.
+ The optional special key "\*" serves as a catch-all address
+ whose text shall be notified if `selfAddr` is not contained in the dictionary.
+
+- `update.href`: optional string that specifies a relative URL
+ (for example `index.html#about`)
+ When a receiver starts the webxdc app based on the update object
+ the app will be navigated to the `href` location with the application root url prepended.
+
+- `update.document`: optional, name of the document in edit
+ (eg. the title of a poll or the name of a text in an editor)
+ mplementations show the document name e.g. beside the app icon or in the title bar.
+ MUST NOT be used if the webxdc does not create documents, e.g. in games.
+ Do not add linebreaks; implementations will truncate the text at about 20 characters or less.
+
+- `update.summary`: optional, short text, shown beside the app icon;
+ it is recommended to use some aggregated value, e.g. "8 votes", "Highscore: 123".
+ Do not add linebreaks; implementations will truncate the text
+ at about 20 characters or less.
+
+
+## Using `info` and `href` to provide navigation
+
+If a user clicks on an `info` message that has a `href` specified
+then the webxdc app will be started and navigate to the specified location.
+
+For example, a calendar app can send an update to add a new calendar event.
+The info would be shown in the chat and if the user taps or clicks on it
+the app is started (if it is not running already) and navigates
+to the new href which can for example directly show the day and highlight the added event.
## Messaging layer limits for sendUpdate
@@ -69,4 +95,3 @@ updates might get queued for a longer time than just the `sendUpdateInterval`.
Moreover, an editor can also inspect `sendUpdateMaxSize`
and send oversized updates in smaller chunks
and recombine them on the receiving side.
-
diff --git a/src-docs/spec/setUpdateListener.md b/src-docs/spec/setUpdateListener.md
index ff5a063..fabf2f7 100644
--- a/src-docs/spec/setUpdateListener.md
+++ b/src-docs/spec/setUpdateListener.md
@@ -9,6 +9,9 @@ sent by [`sendUpdate()`]. The callback is called for updates sent by you or othe
The `serial` specifies the last serial that you know about (defaults to 0).
The returned promise resolves when the listener has processed all the update messages known at the time when `setUpdateListener` was called.
+
+## Application update object
+
Each `update` which is passed to the callback comes with the following properties:
- `update.payload`: equals the payload given to [`sendUpdate()`]