Docs support for special pages & better organisation

Author: Shane Osbourne

.eslintignore

@@ -3,3 +3,4 @@ docs/
 lib/
 Sources/ContentScopeScripts/dist/
 integration-test/extension/contentScope.js
+packages/special-pages/pages/**/public

inject/android.js

@@ -1,5 +1,6 @@
 /**
  * @module Android integration
+ * @category Content Scope Scripts Integrations
  */
 /* global contentScopeFeatures */
 import { processConfig, isGloballyDisabled } from './../src/utils'

inject/apple.js

@@ -1,5 +1,6 @@
 /**
  * @module Apple integration
+ * @category Content Scope Scripts Integrations
  */
 /* global contentScopeFeatures */
 

inject/chrome-mv3.js

@@ -1,5 +1,6 @@
 /**
  * @module Chrome MV3 integration
+ * @category Content Scope Scripts Integrations
  */
 /* global contentScopeFeatures */
 

inject/chrome.js

@@ -1,5 +1,6 @@
 /**
  * @module Chrome integration
+ * @category Content Scope Scripts Integrations
  */
 import { isTrackerOrigin } from '../src/trackers'
 

inject/integration.js

@@ -1,7 +1,3 @@
-/**
- * @module Testing integration
- */
-
 /* global contentScopeFeatures */
 function getTopLevelURL () {
     try {

inject/mozilla.js

@@ -1,5 +1,6 @@
 /**
  * @module Mozilla integration
+ * @category Content Scope Scripts Integrations
  */
 /* global contentScopeFeatures */
 import { isTrackerOrigin } from '../src/trackers'

inject/windows.js

@@ -1,5 +1,6 @@
 /**
  * @module Windows integration
+ * @category Content Scope Scripts Integrations
  */
 /* global contentScopeFeatures */
 import { processConfig, isGloballyDisabled, windowsSpecificFeatures } from './../src/utils'

packages/messaging/index.js

@@ -1,6 +1,6 @@
 /**
  * @module Messaging
- *
+ * @category Libraries
  * @description
  *
  * An abstraction for communications between JavaScript and host platforms.
@@ -9,48 +9,20 @@
  * 2) Then use that to get an instance of the Messaging utility which allows
  * you to send and receive data in a unified way
  * 3) Each platform implements {@link MessagingTransport} along with its own Configuration
- *     - For example, to learn what configuration is required for Webkit, see: {@link "Webkit Messaging".WebkitMessagingConfig}
- *     - Or, to learn about how messages are sent and received in Webkit, see {@link "Webkit Messaging".WebkitMessagingTransport}
+ *     - For example, to learn what configuration is required for Webkit, see: {@link WebkitMessagingConfig}
+ *     - Or, to learn about how messages are sent and received in Webkit, see {@link WebkitMessagingTransport}
  *
  * @example Webkit Messaging
  *
- * ```js
- * import { Messaging, WebkitMessagingConfig } from "@duckduckgo/content-scope-scripts/lib/messaging.js"
- *
- * // This config would be injected into the UserScript
- * const injectedConfig = {
- *   hasModernWebkitAPI: true,
- *   webkitMessageHandlerNames: ["foo", "bar", "baz"],
- *   secret: "dax",
- * };
- *
- * // Then use that config to construct platform-specific configuration
- * const config = new WebkitMessagingConfig(injectedConfig);
- *
- * // finally, get an instance of Messaging and start sending messages in a unified way 🚀
- * const messaging = new Messaging(config);
- * messaging.notify("hello world!", {foo: "bar"})
- *
- * ```
+ * ```javascript
+ * [[include:packages/messaging/lib/examples/webkit.example.js]]```
  *
  * @example Windows Messaging
  *
- * ```js
- * import { Messaging, WindowsMessagingConfig } from "@duckduckgo/content-scope-scripts/lib/messaging.js"
- *
- * // Messaging on Windows is namespaced, so you can create multiple messaging instances
- * const autofillConfig  = new WindowsMessagingConfig({ featureName: "Autofill" });
- * const debugConfig     = new WindowsMessagingConfig({ featureName: "Debugging" });
- *
- * const autofillMessaging = new Messaging(autofillConfig);
- * const debugMessaging    = new Messaging(debugConfig);
- *
- * // Now send messages to both features as needed 🚀
- * autofillMessaging.notify("storeFormData", { "username": "dax" })
- * debugMessaging.notify("pageLoad", { time: window.performance.now() })
- * ```
+ * ```javascript
+ * [[include:packages/messaging/lib/examples/windows.example.js]]```
  */
-import { WindowsMessagingConfig, WindowsMessagingTransport } from './lib/windows.js'
+import { WindowsMessagingConfig, WindowsMessagingTransport, WindowsInteropMethods } from './lib/windows.js'
 import { WebkitMessagingConfig, WebkitMessagingTransport } from './lib/webkit.js'
 
 /**
@@ -176,4 +148,10 @@ export class MissingHandler extends Error {
 /**
  * Some re-exports for convenience
  */
-export { WebkitMessagingConfig, WindowsMessagingConfig }
+export {
+    WebkitMessagingConfig,
+    WebkitMessagingTransport,
+    WindowsMessagingConfig,
+    WindowsMessagingTransport,
+    WindowsInteropMethods
+}

packages/messaging/lib/examples/webkit.example.js

@@ -0,0 +1,23 @@
+import { Messaging, WebkitMessagingConfig } from '../../index.js'
+
+/**
+ * Webkit messaging involves calling methods on `window.webkit.messageHandlers`.
+ *
+ * For catalina support we support encryption which is the bulk of this configuration
+ */
+const config = new WebkitMessagingConfig({
+  hasModernWebkitAPI: true,
+  secret: 'SECRET',
+  webkitMessageHandlerNames: ['helloWorld', 'sendPixel'],
+})
+
+/**
+ * Send notifications!
+ */
+const messaging = new Messaging(config)
+messaging.notify('sendPixel')
+
+/**
+ * Or request some data
+ */
+messaging.request('helloWorld', { foo: 'bar' }).then(console.log).catch(console.error)

packages/messaging/lib/webkit.js

@@ -1,5 +1,4 @@
 /**
- * @module Webkit Messaging
  *
  * @description
  *
@@ -9,24 +8,8 @@
  * Note: If you wish to support Catalina then you'll need to implement the native
  * part of the message handling, see {@link WebkitMessagingTransport} for details.
  *
- * ```js
- * import { Messaging, WebkitMessagingConfig } from "@duckduckgo/content-scope-scripts/lib/messaging.js"
- *
- * // This config would be injected into the UserScript
- * const injectedConfig = {
- *   hasModernWebkitAPI: true,
- *   webkitMessageHandlerNames: ["foo", "bar", "baz"],
- *   secret: "dax",
- * };
- *
- * // Then use that config to construct platform-specific configuration
- * const config = new WebkitMessagingConfig(injectedConfig);
- *
- * // finally, get an instance of Messaging and start sending messages in a unified way 🚀
- * const messaging = new Messaging(config);
- * messaging.notify("hello world!", {foo: "bar"})
- *
- * ```
+ * ```javascript
+ * [[include:packages/messaging/lib/examples/webkit.example.js]]```
  */
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 import { MessagingTransport, MissingHandler } from '../'

packages/messaging/lib/windows.js

@@ -1,6 +1,4 @@
 /**
- * @module Windows Messaging
- *
  * @description
  *
  * A wrapper for messaging on Windows.

packages/messaging/package.json

@@ -7,7 +7,7 @@
   "devDependencies": {
   },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "echo '✅ No tests yet'"
   },
   "author": "",
   "license": "ISC"

packages/special-pages/index.js

@@ -1,21 +1,31 @@
+/**
+ * @module Special Pages
+ * @category Special Pages
+ *
+ * @description
+ *
+ * A collection of HTML/CSS/JS pages that can be loaded into privileged environments, like `about: pages`
+ *
+ * - {@link "Example Page"}
+ */
 import { join } from 'node:path'
 import { existsSync, cpSync, rmSync } from 'node:fs'
 const CWD = new URL('.', import.meta.url).pathname
 const ROOT = new URL('../../', import.meta.url).pathname
 const BUILD = join(ROOT, 'build')
 
 export const support = {
-    // example: ['windows']
+    example: ['windows']
 }
 
 /** @type {{src: string, dest: string}[]} */
 const copyJobs = []
 const errors = []
 
 for (const [pageName, platforms] of Object.entries(support)) {
-    const src = join(CWD, 'pages', pageName)
+    const src = join(CWD, 'pages', pageName, 'public')
     if (!existsSync(src)) {
-        errors.push(`${src} does not exist`)
+        errors.push(`${src} does not exist. Each page must have a 'public' directory`)
         continue
     }
     for (const platform of platforms) {
@@ -36,7 +46,7 @@ if (errors.length > 0) {
 
 if (errors.length === 0) {
     for (const copyJob of copyJobs) {
-        console.log('DRY RUN COPY: ', copyJob)
+        console.log('COPY: ', copyJob)
         rmSync(copyJob.dest, { force: true, recursive: true })
         cpSync(copyJob.src, copyJob.dest, { force: true, recursive: true })
     }

packages/special-pages/package.json

@@ -1,11 +1,13 @@
 {
   "name": "special-pages",
+  "private": "true",
   "version": "1.0.0",
   "description": "A collection of HTML/CSS/JS pages that can be loaded into privileged environments, like about: pages",
   "main": "index.js",
   "type": "module",
   "scripts": {
-    "build": "node index.js",
+    "build": "npm run build.pages; node index.js",
+    "build.pages": "node scripts/build.js",
     "test": "echo '✅ No tests yet'",
     "test.headed": "playwright test --headed",
     "test-int-x": "playwright test",
@@ -15,6 +17,8 @@
   "license": "ISC",
   "devDependencies": {
     "@playwright/test": "^1.31.2",
-    "serve": "^14.2.0"
+    "serve": "^14.2.0",
+    "@duckduckgo/messaging": "*",
+    "esbuild": "^0.17.12"
   }
 }

packages/special-pages/pages/example/.gitignore

@@ -0,0 +1 @@
+*

packages/special-pages/pages/example/public/generated/.gitignore

@@ -6,11 +6,11 @@
           content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
     <meta http-equiv="X-UA-Compatible" content="ie=edge">
     <title>Example special page</title>
-    <link rel="stylesheet" href="./style.css">
+    <link rel="stylesheet" href="style.css">
 </head>
 <body>
-    <header class="header"><img src="./img/logo-horizontal.svg" class="logo" /></header>
+    <header class="header"><img src="img/logo-horizontal.svg" class="logo" /></header>
     <h1 class="title">Hello world from a special page :)</h1>
-    <script src="./script.js"></script>
+    <script type="module" src="generated/js/index.js"></script>
 </body>
 </html>

packages/special-pages/pages/example/img/logo-horizontal.svg renamed to packages/special-pages/pages/example/public/img/logo-horizontal.svg

@@ -0,0 +1,2 @@
+This is an example 'special' page. It contains a `public` folder which will be the output
+that native platforms will refer to

packages/special-pages/pages/example/index.html renamed to packages/special-pages/pages/example/public/index.html

@@ -0,0 +1,46 @@
+/**
+ * @module Example Page
+ * @category Special Pages
+ *
+ * @description
+ *
+ * [[include:packages/special-pages/pages/example/readme.md]]
+ */
+
+import { Messaging, WindowsMessagingConfig } from '../../../../messaging/index.js'
+import { ExamplePageMessages,  } from './messages.js'
+import { Pixel, OverlayPixel, PlayPixel, PlayDoNotUse } from './pixels.js'
+
+/**
+ * An example of initialising Windows messaging
+ */
+const config = new WindowsMessagingConfig({
+    featureName: 'ExamplePage',
+    methods: {
+        postMessage: (...args) => {
+            console.log('postMessage', args)
+        },
+        addEventListener: (...args) => {
+            console.log('addEventListener', args)
+        },
+        removeEventListener: (...args) => {
+            console.log('removeEventListener', args)
+        }
+    }
+})
+
+const messages = new Messaging(config)
+console.log(messages)
+
+const h2 = document.createElement('h2')
+h2.innerText = 'This is an appended element'
+document.body.appendChild(h2)
+
+try {
+    // @ts-expect-error - this is deliberate to ensure tsc is checking this file
+    document.body.appendChild('ooops!')
+} catch (e) {
+    console.log('warn: Expected error')
+}
+
+export { ExamplePageMessages, Pixel, OverlayPixel, PlayPixel, PlayDoNotUse }

packages/special-pages/pages/example/style.css renamed to packages/special-pages/pages/example/public/style.css

@@ -0,0 +1,27 @@
+export class ExamplePageMessages {
+    /**
+     * @param {import("@duckduckgo/messaging").Messaging} messaging
+     * @internal
+     */
+    constructor (messaging) {
+        this.messaging = messaging
+    }
+
+    requests = {
+        /**
+         * @returns {Promise<boolean>}
+         */
+        getOptions: async () => {
+            return this.messaging.request('hello', { world: 'here' })
+        }
+    }
+
+    notifications = {
+        /**
+         * @param {import("./pixels.js").Pixel} knownPixel
+         */
+        sendPixel: (knownPixel) => {
+            this.messaging.notify(knownPixel.name(), knownPixel.params())
+        }
+    }
+}