Namespace (rename) iframe messages in FDC3 for the web to avoid potential conflicts

docs/api/specs/browserResidentDesktopAgents.md

@@ -244,10 +244,10 @@ User interface iframes are initially injected into the application window with C
 
 and are always displayed with `position: "fixed"` so that they are not part of the document flow.
 
-Implementations of the UIs may then indicate a limited set of CSS to apply to their frame in the initial `iFrameHello` message (when the width and height will be removed if not explicitly set in that message), and later adjust that via `iFrameRestyle`. See the [Controlling injected User Interfaces section](./desktopAgentCommunicationProtocol#controlling-injected-user-interfaces-section) in the DACP specification for more details.
+Implementations of the UIs may then indicate a limited set of CSS to apply to their frame in the initial `Fdc3UserInterfaceHello` message (when the width and height will be removed if not explicitly set in that message), and later adjust that via `Fdc3UserInterfaceRestyle`. See the [Controlling injected User Interfaces section](./desktopAgentCommunicationProtocol#controlling-injected-user-interfaces-section) in the DACP specification for more details.
 
-Communication between the `DesktopAgentProxy` and the iframes it injects is achieved via a similar mechanism to that used for communication between an App and the Desktop Agent: a `MessageChannel` is established between the app and iframe, via a `postMessage` sent from the iframe (`iFrameHello`) and responded to by the `DesktopAgentProxy` in the app's window (`iFrameHandshake`), with a `MessagePort` from a `MessageChannel` appended.
+Communication between the `DesktopAgentProxy` and the iframes it injects is achieved via a similar mechanism to that used for communication between an App and the Desktop Agent: a `MessageChannel` is established between the app and iframe, via a `postMessage` sent from the iframe (`Fdc3UserInterfaceHello`) and responded to by the `DesktopAgentProxy` in the app's window (`Fdc3UserInterfaceHandshake`), with a `MessagePort` from a `MessageChannel` appended.
 
-A further set of messages are provided for working with the injected user interfaces over their `MessageChannel` as part of the DACP, these are: `iFrameRestyle`, `iFrameDrag`, `iFrameChannels`, `iFrameChannelSelected`, `iFrameResolve` and `iFrameResolveAction`.
+A further set of messages are provided for working with the injected user interfaces over their `MessageChannel` as part of the DACP, these are: `Fdc3UserInterfaceRestyle`, `Fdc3UserInterfaceDrag`, `Fdc3UserInterfaceChannels`, `Fdc3UserInterfaceChannelSelected`, `Fdc3UserInterfaceResolve` and `Fdc3UserInterfaceResolveAction`.
 
 See the [Desktop Agent Communication Protocol](./desktopAgentCommunicationProtocol) (DACP) for more details.

docs/api/specs/desktopAgentCommunicationProtocol.md

@@ -439,19 +439,19 @@ Additional procedures are defined in the [Browser Resident Desktop Agents specif
 
 Desktop Agent implementations, such as those based on the [Browser Resident Desktop Agents specification](./browserResidentDesktopAgents) and [Web Connection Protocol](./webConnectionProtocol), may either provide their own user interfaces (or other appropriate mechanisms) for the selection of User Channels or Intent Resolution, or they may work with implementations injected into the application (for example, as described in the [Web Connection Protocol](./webConnectionProtocol#providing-channel-selector-and-intent-resolver-uis) and implemented in [`getAgent()`](../ref/GetAgent)).
 
-Where injected user interfaces are used, standardized messaging is needed to communicate with those interfaces. This is provided in the DACP via the following 'iframe' messages, which are governed by the [`iFrameMessage`](https://fdc3.finos.org/schemas/next/api/iFrameMessage.schema.json) schema. The following messages are provided:
+Where injected user interfaces are used, standardized messaging is needed to communicate with those interfaces. This is provided in the DACP via the following 'iframe' messages, which are governed by the [`Fdc3UserInterfaceMessage`](https://fdc3.finos.org/schemas/next/api/fdc3UserInterface.schema.json) schema. The following messages are provided:
 
-- [`iFrameHello`](https://fdc3.finos.org/schemas/next/api/iFrameHello.schema.json): Sent by the iframe to its `window.parent` frame to initiate communication and to provide initial CSS to apply to the frame. This message should have a `MessagePort` appended over which further communication will be conducted.
-- [`iFrameHandshake`](https://fdc3.finos.org/schemas/next/api/iFrameHandshake.schema.json):  Response to the `iFrameHello` message sent by the application frame, which should be sent over the `MessagePort`. Includes details of the FDC3 version that the application is using.
-- [`iFrameDrag`](https://fdc3.finos.org/schemas/next/api/iFrameDrag.schema.json): Message sent by the iframe to indicate that it is being dragged to a new position and including offsets to indicate direction and distance.
-- [`iFrameRestyle`](https://fdc3.finos.org/schemas/next/api/iFrameRestyle.schema.json): Message sent by the iframe to indicate that its frame should have updated CSS applied to it, for example to support a channel selector interface that can be 'popped open' or an intent resolver that wishes to resize itself to show additional content.
+- [`Fdc3UserInterfaceHello`](https://fdc3.finos.org/schemas/next/api/fdc3UserInterfaceHello.schema.json): Sent by the iframe to its `window.parent` frame to initiate communication and to provide initial CSS to apply to the frame. This message should have a `MessagePort` appended over which further communication will be conducted.
+- [`Fdc3UserInterfaceHandshake`](https://fdc3.finos.org/schemas/next/api/fdc3UserInterfaceHandshake.schema.json):  Response to the `Fdc3UserInterfaceHello` message sent by the application frame, which should be sent over the `MessagePort`. Includes details of the FDC3 version that the application is using.
+- [`Fdc3UserInterfaceDrag`](https://fdc3.finos.org/schemas/next/api/fdc3UserInterfaceDrag.schema.json): Message sent by the iframe to indicate that it is being dragged to a new position and including offsets to indicate direction and distance.
+- [`Fdc3UserInterfaceRestyle`](https://fdc3.finos.org/schemas/next/api/fdc3UserInterfaceRestyle.schema.json): Message sent by the iframe to indicate that its frame should have updated CSS applied to it, for example to support a channel selector interface that can be 'popped open' or an intent resolver that wishes to resize itself to show additional content.
 
 Messages are also provided that are specific to each interface type provided by a Desktop Agent. The following messages are specific to Channel Selector user interfaces:
 
-- [`iFrameChannels`](https://fdc3.finos.org/schemas/next/api/iFrameChannels.schema.json): Sent by the parent frame to initialize a Channel Selector user interface by providing metadata for the Desktop Agent's user channels and details of any channel that is already selected. This message will typically be sent by a `getAgent()` implementation immediately after the `iFrameHandshake` and before making the injected iframe visible.
-- [`iFrameChannelSelected`](https://fdc3.finos.org/schemas/next/api/iFrameChannelSelected.schema.json): Sent by the Channel Selector to indicate that a channel has been selected or deselected.
+- [`fdc3UserInterfaceChannels`](https://fdc3.finos.org/schemas/next/api/fdc3UserInterfaceChannels.schema.json): Sent by the parent frame to initialize a Channel Selector user interface by providing metadata for the Desktop Agent's user channels and details of any channel that is already selected. This message will typically be sent by a `getAgent()` implementation immediately after the `fdc3UserInterfaceHandshake` and before making the injected iframe visible.
+- [`fdc3UserInterfaceChannelSelected`](https://fdc3.finos.org/schemas/next/api/fdc3UserInterfaceChannelSelected.schema.json): Sent by the Channel Selector to indicate that a channel has been selected or deselected.
 
 Messages specific to Intent Resolver user interfaces:
 
-- [`iFrameResolve`](https://fdc3.finos.org/schemas/next/api/iFrameResolve.schema.json): Sent by the parent frame to initialize a Intent Resolver user interface to resolve a raised intent, before making it visible. The message includes the context object sent with the intent and an array of one or more [`AppIntent`](../ref/Metadata#appintent) objects representing the resolution options for the intent ([`raiseIntent`](../ref/DesktopAgent#raiseintent)) or context ([`raiseIntentForContext`](../ref/DesktopAgent#raiseintentforcontext)) that was raised.
-- [`iFrameResolveAction`](https://fdc3.finos.org/schemas/next/api/iFrameResolveAction.schema.json): Sent by the Intent Resolver to indicate actions taken by the user in the interface, including hovering over an option, clicking a cancel button, or selecting a resolution option. The Intent Resolver should be hidden by the `getAgent()` implementation after a resolution option is selected.
+- [`Fdc3UserInterfaceResolve`](https://fdc3.finos.org/schemas/next/api/fdc3UserInterfaceResolve.schema.json): Sent by the parent frame to initialize a Intent Resolver user interface to resolve a raised intent, before making it visible. The message includes the context object sent with the intent and an array of one or more [`AppIntent`](../ref/Metadata#appintent) objects representing the resolution options for the intent ([`raiseIntent`](../ref/DesktopAgent#raiseintent)) or context ([`raiseIntentForContext`](../ref/DesktopAgent#raiseintentforcontext)) that was raised.
+- [`fdc3UserInterfaceResolveAction`](https://fdc3.finos.org/schemas/next/api/fdc3UserInterfaceResolveAction.schema.json): Sent by the Intent Resolver to indicate actions taken by the user in the interface, including hovering over an option, clicking a cancel button, or selecting a resolution option. The Intent Resolver should be hidden by the `getAgent()` implementation after a resolution option is selected.

docs/api/specs/webConnectionProtocol.md

@@ -286,6 +286,8 @@ SessionStorage is ephemeral, only existing for the duration of the window's life
 
 Resolve the `getAgent()` promise with an object containing either a `DesktopAgent` implementation (that was found at `window.fdc3` or returned by a `failover` function) or a 'Desktop Agent Proxy' implementation (a class implementing the `DesktopAgent` interface that uses the [Desktop Agent Communication Protocol (DACP)](./desktopAgentCommunicationProtocol) to communicate with a Desktop Agent over the `MessagePort`).
 
+Where a `DesktopAgent` or 'Desktop Agent Proxy' implementation was successfully returned, any subsequent calls to `getAgent()` that are not preceded by a navigation or refresh event, should resolve to the same instance.
+
 ### Step 5: Disconnection
 
 Desktop Agent Preload interfaces, as used in container-based Desktop Agent implementations, are usually able to track the lifecycle and current URL of windows that host web apps in their scope. Hence, this is currently no requirement nor means for an app to indicate that it is closing, rather it is the responsibility of the Desktop Agent to update its internal state when an app closes or changes identity.

schemas/api/iFrameChannelSelected.schema.json → schemas/api/fdc3UserInterfaceChannelSelected.schema.json

@@ -1,27 +1,27 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://fdc3.finos.org/schemas/next/api/iframeChannelSelected.schema.json",
-  "title": "iframe Channel Selected",
-  "description": "Message from the channel selector UI to the DA proxy sent when the channel selection changes.",
+  "$id": "https://fdc3.finos.org/schemas/next/api/fdc3UserInterfaceChannelSelected.schema.json",
+  "title": "Fdc3 UserInterface Channel Selected",
+  "description": "Message from a channel selector UI to the DA proxy sent when the channel selection changes.",
   "type": "object",
   "allOf": [
     {
-      "$ref": "#/$defs/IframeChannelSelectedBase"
+      "$ref": "#/$defs/Fdc3UserInterfaceChannelSelectedBase"
     },
     {
-      "$ref": "iFrameMessage.schema.json"
+      "$ref": "fdc3UserInterfaceMessage.schema.json"
     }
   ],
   "$defs": {
-    "IframeChannelSelectedBase": {
+    "Fdc3UserInterfaceChannelSelectedBase": {
       "type": "object",
       "properties": {
         "type": {
-          "title": "iframeChannelSelected Message Type",
-          "const": "iframeChannelSelected"
+          "title": "Fdc3 UserInterface ChannelSelected Message Type",
+          "const": "Fdc3UserInterfaceChannelSelected"
         },
         "payload": {
-          "title": "iframeChannelSelected Payload",
+          "title": "Fdc3 UserInterface ChannelSelected Payload",
           "type": "object",
           "properties": {
             "selected": {

schemas/api/iFrameChannels.schema.json → schemas/api/fdc3UserInterfaceChannels.schema.json

@@ -1,27 +1,27 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://fdc3.finos.org/schemas/next/api/iframeChannels.schema.json",
-  "title": "iframe Channels",
+  "$id": "https://fdc3.finos.org/schemas/next/api/fdc3UserInterfaceChannels.schema.json",
+  "title": "Fdc3 UserInterface Channels",
   "description": "Setup message sent by the DA proxy code in getAgent() to a channel selector UI in an iframe with the channel definitions and current channel selection.",
   "type": "object",
   "allOf": [
     {
-      "$ref": "#/$defs/IframeChannelsBase"
+      "$ref": "#/$defs/Fdc3UserInterfaceChannelsBase"
     },
     {
-      "$ref": "iFrameMessage.schema.json"
+      "$ref": "fdc3UserInterfaceMessage.schema.json"
     }
   ],
   "$defs": {
-    "IframeChannelsBase": {
+    "Fdc3UserInterfaceChannelsBase": {
       "type": "object",
       "properties": {
         "type": {
-          "title": "iframeChannels Message Type",
-          "const": "iframeChannels"
+          "title": "Fdc3 UserInterface Channels Message Type",
+          "const": "Fdc3UserInterfaceChannels"
         },
         "payload": {
-          "title": "iframeChannels Payload",
+          "title": "Fdc3 UserInterface Channels Payload",
           "type": "object",
           "properties": {
             "userChannels": {

schemas/api/iFrameDrag.schema.json → schemas/api/fdc3UserInterfaceDrag.schema.json

@@ -1,27 +1,27 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://fdc3.finos.org/schemas/next/api/iframeDrag.schema.json",
-  "title": "iframe Drag",
+  "$id": "https://fdc3.finos.org/schemas/next/api/fdc3UserInterfaceDrag.schema.json",
+  "title": "Fdc3 UserInterface Drag",
   "description": "Message from a UI iframe to the DA proxy (setup by `getAgent()`) indicating that the user is dragging the UI to a new location and providing the offset to apply to the location. The DA proxy implementation should limit the location to the current bounds of the window's viewport",
   "type": "object",
   "allOf": [
     {
-      "$ref": "#/$defs/IframeDragBase"
+      "$ref": "#/$defs/Fdc3UserInterfaceDragBase"
     },
     {
-      "$ref": "iFrameMessage.schema.json"
+      "$ref": "fdc3UserInterfaceMessage.schema.json"
     }
   ],
   "$defs": {
-    "IframeDragBase": {
+    "Fdc3UserInterfaceDragBase": {
       "type": "object",
       "properties": {
         "type": {
-          "title": "iframeDrag Message Type",
-          "const": "iframeDrag"
+          "title": "Fdc3 UserInterface Drag Message Type",
+          "const": "Fdc3UserInterfaceDrag"
         },
         "payload": {
-          "title": "iframeDrag Payload",
+          "title": "Fdc3 UserInterface Drag Payload",
           "type": "object",
           "properties": {
             "mouseOffsets": {

schemas/api/iFrameHandshake.schema.json → schemas/api/fdc3UserInterfaceHandshake.schema.json

@@ -1,27 +1,27 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://fdc3.finos.org/schemas/next/api/iframeHandshake.schema.json",
-  "title": "iframe Handshake",
-  "description": "Handshake message sent back to an iframe from the DA proxy code (setup by `getAgent()`) over the `MessagePort` provide in the preceding iFrameHello message, confirming that it is listening to the `MessagePort` for further communication.",
+  "$id": "https://fdc3.finos.org/schemas/next/api/fdc3UserInterfaceHandshake.schema.json",
+  "title": "Fdc3 UserInterface Handshake",
+  "description": "Handshake message sent back to a user interface from the DA proxy code (setup by `getAgent()`) over the `MessagePort` provide in the preceding iFrameHello message, confirming that it is listening to the `MessagePort` for further communication.",
   "type": "object",
   "allOf": [
     {
-      "$ref": "#/$defs/IframeHandshakeBase"
+      "$ref": "#/$defs/Fdc3UserInterfaceHandshakeBase"
     },
     {
-      "$ref": "iFrameMessage.schema.json"
+      "$ref": "fdc3UserInterfaceMessage.schema.json"
     }
   ],
   "$defs": {
-    "IframeHandshakeBase": {
+    "Fdc3UserInterfaceHandshakeBase": {
       "type": "object",
       "properties": {
         "type": {
-          "title": "iframeHandshake Message Type",
-          "const": "iframeHandshake"
+          "title": "Fdc3 UserInterface Handshake Message Type",
+          "const": "Fdc3UserInterfaceHandshake"
         },
         "payload": {
-          "title": "iframeHandshake Payload",
+          "title": "Fdc3 UserInterface Handshake Payload",
           "type": "object",
           "properties": {
             "fdc3Version": {

schemas/api/iFrameHello.schema.json → schemas/api/fdc3UserInterfaceHello.schema.json

@@ -1,38 +1,38 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://fdc3.finos.org/schemas/next/api/iframeHello.schema.json",
-  "title": "iframe Hello",
-  "description": "Hello message sent by a UI iframe to the Desktop Agent proxy setup by `getAgent()` to indicate it is ready to communicate, containing initial CSS to set on the iframe, and including an appended `MessagePort` to be used for further communication.",
+  "$id": "https://fdc3.finos.org/schemas/next/api/fdc3UserInterfaceHello.schema.json",
+  "title": "Fdc3 UserInterface Hello",
+  "description": "Hello message sent by a UI to the Desktop Agent proxy setup by `getAgent()` to indicate it is ready to communicate, containing initial CSS to set on the iframe, and including an appended `MessagePort` to be used for further communication.",
   "type": "object",
   "allOf": [
     {
-      "$ref": "#/$defs/IframeHelloBase"
+      "$ref": "#/$defs/Fdc3UserInterfaceHelloBase"
     },
     {
-      "$ref": "iFrameMessage.schema.json"
+      "$ref": "fdc3UserInterfaceMessage.schema.json"
     }
   ],
   "$defs": {
-    "IframeHelloBase": {
+    "Fdc3UserInterfaceHelloBase": {
       "type": "object",
       "properties": {
         "type": {
-          "title": "iframeHello Message Type",
-          "const": "iframeHello"
+          "title": "Fdc3 UserInterface Hello Message Type",
+          "const": "Fdc3UserInterfaceHello"
         },
         "payload": {
-          "title": "iframeHello Payload",
+          "title": "Fdc3 UserInterface Hello Payload",
           "type": "object",
           "properties": {
             "implementationDetails": {
               "title": "Implementation Details",
               "type": "string",
-              "description": "Details about the UI implementation in the iframe, such as vendor and version, for logging purposes."
+              "description": "Details about the UI implementation, such as vendor and version, for logging purposes."
             },
             "initialCSS": {
               "title": "Initial CSS",
               "type": "object",
-              "description": "A constrained set of CSS properties that should be set on the iframe before it is displayed. Note `position` cannot be specified and should always be set to `fixed`.",
+              "description": "A constrained set of styling properties that should be set on the user interface before it is displayed. Note `position` cannot be specified and should always be set to `fixed`.",
               "properties": {
                 "height": {"type": "string", "title": "height", "description": "The initial height of the iframe"},
                 "width": {"type": "string", "title": "width", "description": "The initial width of the iframe"},