@adecore/shell 0.40.1 → 0.40.2

package/README.md

@@ -23,8 +23,8 @@ The package registers no IPC handler and listens to no app-wide Electron event.
 
 | Import | What it holds |
 |---|---|
-| `@adecore/shell` | For the main process: `createWindows`, `createWindowState`, `createUpdater`, `createTheme`, `menuTemplateOf`, `staticMenuTemplate`, `createMenuCommands`, `createPageKeys`, `createAppScheme` and the web guards |
-| `@adecore/shell/bridge` | The shapes that cross IPC: `MenuSpec`, `MenuNode`, `MENU_ROLES`, `MENU_BAR_ROLES`, `UpdateState`, `ThemeState` and `compareVersions`. It imports nothing from Electron, so a preload and the page read it too. |
+| `@adecore/shell` | For the main process: `createWindows`, `createWindowState`, `createUpdater`, `createTheme`, `menuTemplateOf`, `staticMenuTemplate`, `createMenuCommands`, `createPageKeys`, `createAppScheme`, `createGestureGate` and the web guards |
+| `@adecore/shell/bridge` | The shapes that cross IPC: `MenuSpec`, `MenuNode`, `MENU_ROLES`, `MENU_BAR_ROLES`, `UpdateState`, `ThemeState` and `compareVersions`, and `ipcSubscriber` for a preload. It imports nothing from Electron, so a preload and the page read it too. |
 
 ## Documentation
 

package/dist/bridge/index.d.ts

@@ -1,3 +1,4 @@
+export { ipcSubscriber, type IpcListeners, type Subscribe } from './ipc.ts';
 export { MENU_ROLES, type MenuBarRole, type MenuNode, type MenuRole, type MenuSpec } from './menu.ts';
 export type { ThemeState } from './theme.ts';
 export type { UpdateErrorCode, UpdateState } from './update.ts';

package/dist/bridge/index.js

@@ -2,5 +2,6 @@
  * The shapes that cross IPC between the shell and the page it hosts. Nothing here imports Electron, so
  * a preload and a page read them as well as the main process.
  */
+export { ipcSubscriber } from './ipc.js';
 export { MENU_ROLES } from './menu.js';
 export { compareVersions, isVersion } from './versions.js';

package/dist/bridge/ipc.d.ts

@@ -0,0 +1,6 @@
+export interface IpcListeners {
+    on(channel: string, listener: (event: unknown, ...args: unknown[]) => void): unknown;
+    removeListener(channel: string, listener: (event: unknown, ...args: unknown[]) => void): unknown;
+}
+export type Subscribe<Args extends unknown[]> = (listener: (...args: Args) => void) => () => void;
+export declare const ipcSubscriber: (ipc: IpcListeners) => <Args extends unknown[]>(channel: string) => Subscribe<Args>;

package/dist/bridge/ipc.js

@@ -0,0 +1,12 @@
+/*
+ * For a preload: turns a channel the main process sends on into what the page subscribes with, a
+ * listener in and what removes it again out. The event stays behind: it carries the sender, which the
+ * page must never hold.
+ */
+export const ipcSubscriber = (ipc) => (channel) => (listener) => {
+    const handler = (_event, ...args) => listener(...args);
+    ipc.on(channel, handler);
+    return () => {
+        ipc.removeListener(channel, handler);
+    };
+};

package/dist/index.d.ts

@@ -6,8 +6,8 @@ export { createPageKeys } from './page-keys.ts';
 export type { PageKey, PageKeys } from './page-keys.ts';
 export { createUpdater } from './updater.ts';
 export type { Updater, UpdaterOptions } from './updater.ts';
-export { appWindowNavigation, isAppSender, isAppUrl, isExternalLink, isWebLink, originOf } from './web-guards.ts';
-export type { NavigationVerdict, SenderFrame } from './web-guards.ts';
+export { appWindowNavigation, createGestureGate, isAppSender, isAppUrl, isExternalLink, isWebLink, originOf } from './web-guards.ts';
+export type { GestureGate, NavigationVerdict, SenderFrame } from './web-guards.ts';
 export { createWindowState, fileStorage } from './window-state.ts';
 export type { SavedWindow, StateWindow, WindowDisplay, WindowSize, WindowState, WindowStateOptions, WindowStateStorage } from './window-state.ts';
 export { createTheme } from './theme.ts';

package/dist/index.js

@@ -2,7 +2,7 @@ export { createAppScheme, segmentsOf } from './app-scheme.js';
 export { createMenuCommands, devToolsAccelerator, menuTemplateOf, staticMenuTemplate } from './menu.js';
 export { createPageKeys } from './page-keys.js';
 export { createUpdater } from './updater.js';
-export { appWindowNavigation, isAppSender, isAppUrl, isExternalLink, isWebLink, originOf } from './web-guards.js';
+export { appWindowNavigation, createGestureGate, isAppSender, isAppUrl, isExternalLink, isWebLink, originOf } from './web-guards.js';
 export { createWindowState, fileStorage } from './window-state.js';
 export { createTheme } from './theme.js';
 export { createWindows } from './windows.js';

package/dist/web-guards.d.ts

@@ -4,6 +4,11 @@ export declare const isWebLink: (url: string) => boolean;
 export declare const isExternalLink: (url: string) => boolean;
 export type NavigationVerdict = 'allow' | 'external' | 'refuse';
 export declare const appWindowNavigation: (url: string, appOrigin: string, schemes?: readonly string[]) => NavigationVerdict;
+export declare const createGestureGate: (now?: () => number) => {
+    saw: (type: string) => void;
+    consume: () => boolean;
+};
+export type GestureGate = ReturnType<typeof createGestureGate>;
 export interface SenderFrame {
     readonly url: string;
     readonly parent: unknown;

package/dist/web-guards.js

@@ -34,6 +34,30 @@ export const appWindowNavigation = (url, appOrigin, schemes = []) => {
     }
     return isWebLink(url) ? 'external' : 'refuse';
 };
+/* What a person does on purpose: a press or a key, never a move, a wheel or a scroll. */
+const DELIBERATE_INPUT = new Set(['mouseDown', 'mouseUp', 'rawKeyDown', 'keyDown', 'gestureTap', 'touchEnd']);
+/* How long after a press a link may still leave, which is longer than any click takes to navigate. */
+const GESTURE_MS = 1000;
+/*
+ * Whether a link a page wants to open in the system browser follows a press of the person. A page that
+ * runs scripts nobody vetted could otherwise send the person's browser anywhere, over and over. One
+ * press lets one link out. `saw` takes the `type` of each `input-event` of the page.
+ */
+export const createGestureGate = (now = Date.now) => {
+    let pressedAt = null;
+    return {
+        saw: (type) => {
+            if (DELIBERATE_INPUT.has(type)) {
+                pressedAt = now();
+            }
+        },
+        consume: () => {
+            const recent = pressedAt !== null && now() - pressedAt <= GESTURE_MS;
+            pressedAt = null;
+            return recent;
+        }
+    };
+};
 /*
  * Whether an IPC message came from the app itself: the top frame of an app window, still on the app's
  * origin. The web contents alone says nothing, since it stays the same object whatever it navigates to.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adecore/shell",
-  "version": "0.40.1",
+  "version": "0.40.2",
   "description": "The main process of an Electron app: its menu, its updater and the guards around its page.",
   "license": "FSL-1.1-MIT",
   "author": "Bas Milius",

package/src/bridge/index.ts

@@ -3,6 +3,7 @@
  * a preload and a page read them as well as the main process.
  */
 
+export { ipcSubscriber, type IpcListeners, type Subscribe } from './ipc.ts';
 export { MENU_ROLES, type MenuBarRole, type MenuNode, type MenuRole, type MenuSpec } from './menu.ts';
 export type { ThemeState } from './theme.ts';
 export type { UpdateErrorCode, UpdateState } from './update.ts';

package/src/bridge/ipc.ts

@@ -0,0 +1,24 @@
+/* The part of `ipcRenderer` a subscription uses, so this module imports nothing from Electron. */
+export interface IpcListeners {
+    on(channel: string, listener: (event: unknown, ...args: unknown[]) => void): unknown;
+    removeListener(channel: string, listener: (event: unknown, ...args: unknown[]) => void): unknown;
+}
+
+export type Subscribe<Args extends unknown[]> = (listener: (...args: Args) => void) => () => void;
+
+/*
+ * For a preload: turns a channel the main process sends on into what the page subscribes with, a
+ * listener in and what removes it again out. The event stays behind: it carries the sender, which the
+ * page must never hold.
+ */
+export const ipcSubscriber =
+    (ipc: IpcListeners) =>
+    <Args extends unknown[]>(channel: string): Subscribe<Args> =>
+    (listener) => {
+        const handler = (_event: unknown, ...args: unknown[]): void => listener(...(args as Args));
+        ipc.on(channel, handler);
+
+        return () => {
+            ipc.removeListener(channel, handler);
+        };
+    };

package/src/index.ts

@@ -6,8 +6,8 @@ export { createPageKeys } from './page-keys.ts';
 export type { PageKey, PageKeys } from './page-keys.ts';
 export { createUpdater } from './updater.ts';
 export type { Updater, UpdaterOptions } from './updater.ts';
-export { appWindowNavigation, isAppSender, isAppUrl, isExternalLink, isWebLink, originOf } from './web-guards.ts';
-export type { NavigationVerdict, SenderFrame } from './web-guards.ts';
+export { appWindowNavigation, createGestureGate, isAppSender, isAppUrl, isExternalLink, isWebLink, originOf } from './web-guards.ts';
+export type { GestureGate, NavigationVerdict, SenderFrame } from './web-guards.ts';
 export { createWindowState, fileStorage } from './window-state.ts';
 export type { SavedWindow, StateWindow, WindowDisplay, WindowSize, WindowState, WindowStateOptions, WindowStateStorage } from './window-state.ts';
 export { createTheme } from './theme.ts';

package/src/web-guards.ts

@@ -44,6 +44,37 @@ export const appWindowNavigation = (url: string, appOrigin: string, schemes: rea
     return isWebLink(url) ? 'external' : 'refuse';
 };
 
+/* What a person does on purpose: a press or a key, never a move, a wheel or a scroll. */
+const DELIBERATE_INPUT: ReadonlySet<string> = new Set(['mouseDown', 'mouseUp', 'rawKeyDown', 'keyDown', 'gestureTap', 'touchEnd']);
+
+/* How long after a press a link may still leave, which is longer than any click takes to navigate. */
+const GESTURE_MS = 1000;
+
+/*
+ * Whether a link a page wants to open in the system browser follows a press of the person. A page that
+ * runs scripts nobody vetted could otherwise send the person's browser anywhere, over and over. One
+ * press lets one link out. `saw` takes the `type` of each `input-event` of the page.
+ */
+export const createGestureGate = (now: () => number = Date.now) => {
+    let pressedAt: number | null = null;
+
+    return {
+        saw: (type: string): void => {
+            if (DELIBERATE_INPUT.has(type)) {
+                pressedAt = now();
+            }
+        },
+        consume: (): boolean => {
+            const recent = pressedAt !== null && now() - pressedAt <= GESTURE_MS;
+            pressedAt = null;
+
+            return recent;
+        }
+    };
+};
+
+export type GestureGate = ReturnType<typeof createGestureGate>;
+
 /* The part of an IPC event's sender frame the check reads. */
 export interface SenderFrame {
     readonly url: string;