Apply suggestions from code review

from @hughtroeger's review

Co-authored-by: Hugh Troeger <htroeger@factset.com>

docs/api/ref/GetAgent.md

@@ -42,7 +42,7 @@ try {
 
 The  `getAgent()` function allows web applications to retrieve an FDC3 Desktop Agent API interface to work with, whether they are running in an environment that supports a Desktop Agent Preload (a container-injected API implementation) or a Desktop Agent Proxy (a Browser-based Desktop Agent running in another window or frame). The behavior of `getAgent()` is defined by the [FDC3 Web Connection Protocol (WCP)](../specs/webConnectionProtocol) and communication with a Desktop Agent Proxy in a web-browser is defined by the [Desktop Agent Communication Protocol (DACP)](../specs/desktopAgentCommunicationProtocol). Hence, it allows applications to be written that will work in either scenario without modification or the inclusion of vendor-specific libraries.
 
-To handle situations where no Desktop Agent is found, a failover function may be supplied by app allowing it to start or otherwise connect to a Desktop Agent (e.g. by loading a proprietary adaptor that returns a `DesktopAgent` implementation or by creating a window or iframe of its own that will provide a Desktop Agent Proxy).
+To handle situations where no Desktop Agent is found, a failover function may be supplied by an app allowing it to start or otherwise connect to a Desktop Agent (e.g. by loading a proprietary adaptor that returns a `DesktopAgent` implementation or by creating a window or iframe of its own that will provide a Desktop Agent Proxy).
 
 The definition of the `getAgent()` function is as follows:
 
@@ -52,7 +52,7 @@ type GetAgentType = (
 ) => Promise<DesktopAgent>; 
 ```
 
-A small number of arguments are accepted that can affect the behavior of `getAgent` and to provide a fallback in case a Desktop Agent is not found, allowing the application to start its own agent or use another mechanism (such a proprietary adaptor) to connect to one.
+A small number of arguments are accepted that can affect the behavior of `getAgent` and to provide a fallback in case a Desktop Agent is not found, allowing the application to start its own agent or use another mechanism (such as a proprietary adaptor) to connect to one.
 
 ```ts
 /** 
@@ -111,7 +111,7 @@ type GetAgentParams = {
 
 :::note
 
-As web applications can navigate to or be navigated by users to different URLs and become different applications, validation of apps identity is often necessary. The web application's current URL is passed to web browser-based Desktop Agents to allow them to establish the app's identity - usually connecting it with an App Directory record already known to the Desktop Agent. For more details on identity validation see the identity validation section of the  [Web Connection Protocol (WCP)](specs/webConnectionProtocol).
+As web applications can navigate to or be navigated by users to different URLs and become different applications, validation of an app's identity is necessary. The web application's current URL is passed to web browser-based Desktop Agents to allow them to establish the app's identity - usually connecting it with an App Directory record already known to the Desktop Agent. For more details on identity validation see the identity validation section of the  [Web Connection Protocol (WCP)](specs/webConnectionProtocol).
 
 :::
 
@@ -123,7 +123,7 @@ The `getAgent()` function may try to create hidden iframes within an application
 
 :::warning
 
-The [Content-Security-Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy) directives [frame-src](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/frame-src), [child-src](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/child-src) and [default-src](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/default-src) can prevent iframes injected into an application from loading content. Where these are used, please ensure that they allow the loading of content from the domains of Desktop Agents and UI implementations that you wish to work with (including [fdc3.finos.org](https://fdc3.finos.org/) where the reference Intent Resolver and Channel Selector UIs may be laoded from).
+The [Content-Security-Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy) directives [frame-src](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/frame-src), [child-src](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/child-src) and [default-src](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/default-src) can prevent iframes injected into an application from loading content. Where these are used, please ensure that they allow the loading of content from the domains of Desktop Agents and UI implementations that you wish to work with (including [fdc3.finos.org](https://fdc3.finos.org/) where the reference Intent Resolver and Channel Selector UIs may be loaded from).
 
 :::
 

docs/api/spec.md

@@ -48,7 +48,7 @@ The FDC3 API specification consists of interfaces.  It is expected that each Des
 - [`Channel`](ref/Channel)
 - [`PrivateChannel`](ref/PrivateChannel)
 - [`Listener`](ref/Types#listener)
-- [Utility types](ref/Types#listener) and [Metadata Objects](ref/Metadata).
+- [Utility types](ref/Types) and [Metadata Objects](ref/Metadata).
 
 The means to access the main FDC3 API interface (a `DesktopAgent` implementation) is defined separately for each language in which FDC3 is implemented. These definitions are important as they affect whether applications can be written in a vendor agnostic format so that they run under any Standards-conformant implementation.
 

docs/api/specs/browserResidentDesktopAgents.md

@@ -6,7 +6,7 @@ title: Browser-Resident Desktop Agents (next)
 
 :::info _[@experimental](../fdc3-compliance#experimental-features)_
 
-Browser Resident Desktop Agents (DAs) are an experimental feature added to FDC3 in 2.2. Limited aspects of their design may change in future versions and they are exempted from the FDC3 Standard's normal versioning and deprecation polices in order to facilitate any necessary change.
+Browser Resident Desktop Agents (DAs) are an experimental feature added to FDC3 in 2.2. Limited aspects of their design may change in future versions and they are exempted from the FDC3 Standard's normal versioning and deprecation policies in order to facilitate any necessary change.
 
 :::
 
@@ -24,7 +24,7 @@ Prior to FDC3 2.2, only [Preload Desktop Agents](./preloadDesktopAgents) were su
 
 :::note
 
-This document covers the requirements for _implementors of Browser-Resident Desktop Agents_. The `getAgent()` function that applications use to gain access to an fdc3 interface is provided by the [`@finos/fdc3` NPM module](https://www.npmjs.com/package/@finos/fdc3). Many behavioral details of `getAgent()` are purposefully omitted from this document in order to reduce the required scope of understanding. Please refer to the [getAgent() specification in the FDC3 Web Connection Protocol](webConnectionProtocol.md) for information on how the client side operates or [supported platforms](../supported-platforms) for details of how to access the Desktop Agent API in an application.
+This document covers the requirements for _implementors of Browser-Resident Desktop Agents_. The `getAgent()` function that applications use to gain access to an FDC3 interface is provided by the [`@finos/fdc3` NPM module](https://www.npmjs.com/package/@finos/fdc3). Many behavioral details of `getAgent()` are purposefully omitted from this document in order to reduce the required scope of understanding. Please refer to the [getAgent() specification in the FDC3 Web Connection Protocol](webConnectionProtocol.md) for information on how the client side operates or [supported platforms](../supported-platforms) for details of how to access the Desktop Agent API in an application.
 
 :::
 
@@ -71,7 +71,7 @@ Upon receiving an incoming [`"WCP1Hello"`](https://fdc3.finos.org/schemas/next/a
 
     :::
 2. Create a [`MessageChannel`](https://developer.mozilla.org/en-US/docs/Web/API/Channel_Messaging_API) with two entangled `MessagePort` instances that will be used for further communication with the application.
-    - Before returning one of `MessagePort` instances, the DA MUST set up event listeners to to receive and process a [`"WCP4ValidateAppIdentity"`](https://fdc3.finos.org/schemas/next/api/WCP4ValidateAppIdentity.schema.json) message from the application.
+    - Before returning one of `MessagePort` instances, the DA MUST set up event listeners to receive and process a [`"WCP4ValidateAppIdentity"`](https://fdc3.finos.org/schemas/next/api/WCP4ValidateAppIdentity.schema.json) message from the application.
     - To deliver the `MessagePort`, the DA MUST respond to the event's `source` window by responding with a [`WCP3Handshake`](https://fdc3.finos.org/schemas/next/api/WCP3Handshake.schema.json) message (as defined in the [Web Connection Protocol](./webConnectionProtocol)) and append `port2` from the `MessageChannel` to the message.
 
 All further communication is conducted over the `MessageChannel`. The Desktop Agent should consider the newly created port to be inactive until a [`"WCP4ValidateAppIdentity"`](https://fdc3.finos.org/schemas/next/api/WCP4ValidateAppIdentity.schema.json) message is received via the `MessagePort` and successfully processed.

docs/api/specs/desktopAgentCommunicationProtocol.md

@@ -307,7 +307,7 @@ An additional response message is provided for the delivery of an `IntentResult`
 
 - [`raiseIntentResultResponse`](https://fdc3.finos.org/schemas/next/api/raiseIntentResultResponse.schema.json)
 
-There is no request message to indicate a call to the `resolution.getResult()` function of `IntentResolution`. Hence, Desktop Agents should always send this additional response message to indicate the status of the intent handling functino and to deliver its result (or void if none was returned).
+There is no request message to indicate a call to the `resolution.getResult()` function of `IntentResolution`. Hence, Desktop Agents should always send this additional response message to indicate the status of the intent handling function and to deliver its result (or void if none was returned).
 
 :::tip
 
@@ -453,5 +453,5 @@ Messages are also provided that are specific to each user interface type provide
 
 Messages specific to Intent Resolver user interfaces:
 
-- [`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 the iframe 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.
+- [`Fdc3UserInterfaceResolve`](https://fdc3.finos.org/schemas/next/api/fdc3UserInterfaceResolve.schema.json): Sent by the parent frame to initialize an Intent Resolver user interface to resolve a raised intent, before making the iframe 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 to ensure that it does not interfere with user's ongoing interaction with the app's user interface.

docs/api/specs/webConnectionProtocol.md

@@ -6,7 +6,7 @@ title: Web Connection Protocol (next)
 
 :::info _[@experimental](../fdc3-compliance#experimental-features)_
 
-FDC3's Web Connection Protocol (WCP) is an experimental feature added to FDC3 in 2.2. Limited aspects of its  design may change in future versions and it is exempted from the FDC3 Standard's normal versioning and deprecation polices in order to facilitate any necessary change.
+FDC3's Web Connection Protocol (WCP) is an experimental feature added to FDC3 in 2.2. Limited aspects of its design may change in future versions and it is exempted from the FDC3 Standard's normal versioning and deprecation polices in order to facilitate any necessary change.
 
 :::
 
@@ -98,7 +98,7 @@ Check the SessionStorage key `FDC3-Desktop-Agent-Details` for a `DesktopAgentDet
 
 Any data stored under the `FDC3-Desktop-Agent-Details` MUST conform to the [DesktopAgentDetails](../ref/GetAgent#persisted-connection-data) type.
 
-Existing `DesktopAgentDetails` records MUST be used to limit discovery actions (in the next step) to the same mechanism as previously used or to skip the discovery step entirely if a `agentUrl` exists, indicating that the connection should be established by loading the URL into a hidden iframe and initiating communication with that instead.
+Existing `DesktopAgentDetails` records MUST be used to limit discovery actions (in the next step) to the same mechanism as previously used or to skip the discovery step entirely if an `agentUrl` exists, indicating that the connection should be established by loading the URL into a hidden iframe and initiating communication with that instead.
 
 If use of the persisted data fails to establish a connection to the DA then `getAgent()` should reject its promise with `AgentNotFound` error from the [`AgentError`](../ref/Errors#agenterror) enumeration.
 
@@ -193,7 +193,7 @@ Setup a timer for specified timeout, and then for each `candidate` found, attemp
 
   Note that the `targetOrigin` is set to `*` as the origin of the Desktop Agent is not known at this point.
   3. Accept the first correct response received from a candidate. Correct responses MUST correspond to either the [`WCP2LoadUrl`](https://fdc3.finos.org/schemas/next/api/WCP2LoadUrl.schema.json) or [`WCP3Handshake`](https://fdc3.finos.org/schemas/next/api/WCP3Handshake.schema.json) message schemas and MUST quote the same `meta.connectionAttemptUuid` value provided in the original `WCP1Hello` message. Stop the timeout when a correct response is received. If no response is received from any candidate, the `getAgent()` implementation MAY retry sending the `WCP1Hello` message periodically until the timeout is reached.
-  4. If a [`WCP3Handshake`](https://fdc3.finos.org/schemas/next/api/WCP3Handshake.schema.json) was received in the previous step, skip this this step and move on to step 5. However, If a [`WCP2LoadUrl`](https://fdc3.finos.org/schemas/next/api/WCP2LoadUrl.schema.json) was received in the previous step:
+  4. If a [`WCP3Handshake`](https://fdc3.finos.org/schemas/next/api/WCP3Handshake.schema.json) was received in the previous step, skip this step and move on to step 5. However, If a [`WCP2LoadUrl`](https://fdc3.finos.org/schemas/next/api/WCP2LoadUrl.schema.json) was received in the previous step:
       - Create a hidden iframe within the page, set its URL to the URL provided by the `payload.iframeUrl` field of the message and add a handler to run when the iframe has loaded:
           ```ts
           const loadIframe = (url: string, loadedHandler: () => void): WindowProxy => {

docs/api/supported-platforms.md

@@ -38,7 +38,7 @@ getAgent().then((desktopAgent: DesktopAgent) => {
 
 :::
 
-For a web application to use the FDC3 API it needs to retrieve a copy of the `DesktopAgent` API interface, which it will use to communicate with the Desktop Agent (this interface is often referred to as the `fdc3` object or the "FDC3 API"). FDC3 offers the [`@finos/fdc3` npm package](https://www.npmjs.com/package/@finos/fdc3) that can by used by web applications to retrieve a `DesktopAgent` interface and to provide typing. Each FDC3-compliant Desktop Agent that the application runs in, can then provide an implementation of the FDC3 API operations.
+For a web application to use the FDC3 API it needs to retrieve a copy of the `DesktopAgent` API interface, which it will use to communicate with the Desktop Agent (this interface is often referred to as the `fdc3` object or the "FDC3 API"). FDC3 offers the [`@finos/fdc3` npm package](https://www.npmjs.com/package/@finos/fdc3) that can be used by web applications to retrieve a `DesktopAgent` interface and to provide typing. Each FDC3-compliant Desktop Agent that the application runs in, can then provide an implementation of the FDC3 API operations.
 
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';

s2tQuicktypeUtil.js

@@ -9,8 +9,9 @@
  * to be interpreted as JSON input, rather than JSONSchema).
  * 
  * Individual file arguments will be interpreted as 'additional' schema files
- * that will be referenced from the other schemas and may not have top-level output 
- * schemas generated, while folders of files w
+ * that will be referenced from the other schemas and will not have top-level output 
+ * schemas generated, while folders will be listed and the schema files they contain
+ * added as inputs and will have top-level types generated. 
  * 
  *  */
 

schemas/api/fdc3UserInterfaceHello.schema.json

@@ -39,8 +39,8 @@
                 "zIndex": {"type": "string", "title": "zIndex", "description": "The initial zindex to apply to the iframe"},
                 "left": {"type": "string", "title": "left", "description": "The initial left property to apply to the iframe"},
                 "top": {"type": "string", "title": "top", "description": "The initial top property to apply to the iframe"},
-                "bottom": {"type": "string", "title": "left", "description": "The initial bottom property to apply to the iframe"},
-                "right": {"type": "string", "title": "top", "description": "The initial right property to apply to the iframe"},
+                "bottom": {"type": "string", "title": "bottom", "description": "The initial bottom property to apply to the iframe"},
+                "right": {"type": "string", "title": "right", "description": "The initial right property to apply to the iframe"},
                 "transition": {"type": "string", "title": "transition", "description": "The transition property to apply to the iframe"},
                 "maxHeight": {"type": "string", "title": "maxHeight", "description": "The maximum height to apply to the iframe"},
                 "maxWidth": {"type": "string", "title": "maxWidth", "description": "The maximum with to apply to the iframe"}

schemas/api/fdc3UserInterfaceRestyle.schema.json

@@ -34,8 +34,8 @@
                 "zIndex": {"type": "string", "title": "zIndex", "description": "The updated zindex to apply to the iframe"},
                 "left": {"type": "string", "title": "left", "description": "The initial left property to apply to the iframe"},
                 "top": {"type": "string", "title": "top", "description": "The initial top property to apply to the iframe"},
-                "bottom": {"type": "string", "title": "left", "description": "The initial bottom property to apply to the iframe"},
-                "right": {"type": "string", "title": "top", "description": "The initial right property to apply to the iframe"},
+                "bottom": {"type": "string", "title": "bottom", "description": "The initial bottom property to apply to the iframe"},
+                "right": {"type": "string", "title": "right", "description": "The initial right property to apply to the iframe"},
                 "transition": {"type": "string", "title": "transition", "description": "The updated transition property to apply to the iframe"},
                 "maxHeight": {"type": "string", "title": "maxHeight", "description": "The updated maximum height to apply to the iframe"},
                 "maxWidth": {"type": "string", "title": "maxWidth", "description": "The updated maximum with to apply to the iframe"}