experiment with a public stable browser API that extensions can use

ui/@types/lichess/index.d.ts

@@ -161,8 +161,26 @@ interface Fipr {
   x64hash128(input: string, seed: number): string;
 }
 
+interface Api {
+  initializeDom: (root?: HTMLElement) => void;
+  onlineFriends: {
+    request: () => void;
+    events: {
+      on(key: string, cb: (...args: any[]) => void): void;
+      off(key: string, cb: (...args: any[]) => void): void;
+    };
+  };
+  chat: {
+    post: (text: string) => void;
+  };
+  overrides: {
+    [key: string]: (...args: any[]) => unknown;
+  };
+}
+
 interface Window {
   site: Site;
+  lichess: Api;
   fipr: Fipr;
   i18n: I18n;
   $as<T>(cash: Cash): T;

ui/analyse/src/keyboard.ts

@@ -69,7 +69,7 @@ export const bind = (ctrl: AnalyseCtrl) => {
     .bind('f', ctrl.flip)
     .bind('?', () => {
       ctrl.keyboardHelp = !ctrl.keyboardHelp;
-      if (ctrl.keyboardHelp) pubsub.emit('analyse.close-all');
+      if (ctrl.keyboardHelp) pubsub.emit('analysis.closeAll');
       ctrl.redraw();
     })
     .bind('l', ctrl.toggleCeval)

ui/analyse/src/plugins/analyse.study.tour.ts

@@ -206,7 +206,7 @@ class TourCtrl {
       },
       exitOnEsc: true,
     });
-    pubsub.on('analyse.close-all', this.tour.cancel);
+    pubsub.on('analysis.closeAll', this.tour.cancel);
   }
 
   buildTour(steps: Shepherd.Step.StepOptions[]) {

ui/analyse/src/study/chapterNewForm.ts

@@ -48,11 +48,11 @@ export class StudyChapterNewForm {
     readonly setTab: () => void,
     readonly root: AnalyseCtrl,
   ) {
-    pubsub.on('analyse.close-all', () => this.isOpen(false));
+    pubsub.on('analysis.closeAll', () => this.isOpen(false));
   }
 
   open = () => {
-    pubsub.emit('analyse.close-all');
+    pubsub.emit('analysis.closeAll');
     this.isOpen(true);
     this.loadVariants();
     this.initial(false);

ui/analyse/src/study/inviteForm.ts

@@ -30,12 +30,12 @@ export function makeCtrl(
     spectators = prop<string[]>([]);
 
   const toggle = () => {
-    if (!open()) pubsub.emit('analyse.close-all');
+    if (!open()) pubsub.emit('analysis.closeAll');
     open(!open());
     redraw();
   };
 
-  pubsub.on('analyse.close-all', () => open(false));
+  pubsub.on('analysis.closeAll', () => open(false));
 
   const previouslyInvited = storedSet<string>('study.previouslyInvited', 10);
   return {

ui/bits/src/bits.challengePage.ts

@@ -1,7 +1,6 @@
 import * as xhr from 'common/xhr';
 import StrongSocket from 'common/socket';
 import { userComplete } from 'common/userComplete';
-import { pubsub } from 'common/pubsub';
 
 interface ChallengeOpts {
   xhrUrl: string;
@@ -19,7 +18,7 @@ export function initModule(opts: ChallengeOpts): void {
         xhr.text(opts.xhrUrl).then(html => {
           $(selector).replaceWith($(html).find(selector));
           init();
-          pubsub.emit('content-loaded', $(selector)[0]);
+          window.lichess.initializeDom($(selector)[0]);
         });
       },
     },

ui/bits/src/bits.infiniteScroll.ts

@@ -1,6 +1,5 @@
 import * as xhr from 'common/xhr';
 import { spinnerHtml } from 'common/spinner';
-import { pubsub } from 'common/pubsub';
 
 export function initModule(selector: string = '.infinite-scroll'): void {
   $(selector).each(function (this: HTMLElement) {
@@ -37,7 +36,7 @@ function register(el: HTMLElement, selector: string, backoff = 500) {
           nav.remove();
           $(el).append(($(html).is(selector) ? $(html) : $(html).find(selector)).html());
           dedupEntries(el);
-          pubsub.emit('content-loaded', el);
+          window.lichess.initializeDom(el);
           setTimeout(() => register(el, selector, backoff * 1.05), backoff); // recursion with backoff
         },
         e => {

ui/bits/src/bits.tvGames.ts

@@ -28,8 +28,8 @@ const requestReplacementGame = () => {
       .json(url.toString())
       .then((data: ReplacementResponse) => {
         main.find(`.mini-game[href^="/${oldId}"]`).replaceWith(data.html);
-        if (data.html.includes('mini-game__result')) onFinish(data.id);
-        pubsub.emit('content-loaded');
+        if (data.html.includes('mini-game__result')) window.lichess.overrides.tvGamesOnFinish(data.id);
+        window.lichess.initializeDom();
       })
       .then(done, done);
   });
@@ -40,17 +40,17 @@ const done = () => {
   requestReplacementGame();
 };
 
-const onFinish = (id: string) =>
+window.lichess.overrides.tvGamesOnFinish = (id: string) =>
   setTimeout(() => {
     finishedIdQueue.push(id);
     requestReplacementGame();
   }, 7000); // 7000 matches the rematch wait duration in /modules/tv/main/Tv.scala
 
 site.load.then(() => {
-  pubsub.on('socket.in.finish', ({ id }) => onFinish(id));
+  pubsub.on('socket.in.finish', ({ id }) => window.lichess.overrides.tvGamesOnFinish(id));
   $('main.tv-games')
     .find('.mini-game')
     .each((_i, el) => {
-      if ($(el).find('.mini-game__result').length > 0) onFinish(getId(el)!);
+      if ($(el).find('.mini-game__result').length > 0) window.lichess.overrides.tvGamesOnFinish(getId(el)!);
     });
 });

ui/bits/src/bits.user.ts

@@ -1,6 +1,5 @@
 import * as xhr from 'common/xhr';
 import { makeLinkPopups } from 'common/linkPopup';
-import { pubsub } from 'common/pubsub';
 import { alert } from 'common/dialog';
 
 export function initModule(): void {
@@ -48,7 +47,7 @@ export function initModule(): void {
       browseTo = (path: string) =>
         xhr.text(path).then(html => {
           $content.html(html);
-          pubsub.emit('content-loaded', $content[0]);
+          window.lichess.initializeDom($content[0]);
           history.replaceState({}, '', path);
           site.asset.loadEsm('bits.infiniteScroll');
         });

ui/chat/src/ctrl.ts

@@ -102,7 +102,7 @@ export default class ChatCtrl {
       alert('Max length: 140 chars. ' + text.length + ' chars used.');
       return false;
     }
-    pubsub.emit('socket.send', 'talk', text);
+    window.lichess.chat.post(text);
     return true;
   };
 

ui/chat/src/moderation.ts

@@ -158,7 +158,7 @@ export function moderationView(ctrl?: ModerationCtrl): VNode[] | undefined {
             {
               hook: {
                 insert() {
-                  pubsub.emit('content-loaded');
+                  window.lichess.initializeDom();
                 },
               },
             },

ui/common/src/pubsub.ts

@@ -1,6 +1,6 @@
 export type PubsubEvent =
   | 'ab.rep'
-  | 'analyse.close-all'
+  | 'analysis.closeAll'
   | 'analysis.change'
   | 'analysis.chart.click'
   | 'analysis.comp.toggle'
@@ -29,11 +29,6 @@ export type PubsubEvent =
   | 'socket.in.announce'
   | 'socket.in.fen'
   | 'socket.in.finish'
-  | 'socket.in.following_enters'
-  | 'socket.in.following_leaves'
-  | 'socket.in.following_onlines'
-  | 'socket.in.following_playing'
-  | 'socket.in.following_stopped_playing'
   | 'socket.in.message'
   | 'socket.in.mlat'
   | 'socket.in.msgNew'

ui/lobby/src/lobby.ts

@@ -35,12 +35,12 @@ export function initModule(opts: LobbyOpts) {
       reload_timeline() {
         xhr.text('/timeline').then(html => {
           $('.timeline').html(html);
-          pubsub.emit('content-loaded');
+          window.lichess.initializeDom();
         });
       },
       featured(o: { html: string }) {
         $('.lobby__tv').html(o.html);
-        pubsub.emit('content-loaded');
+        window.lichess.initializeDom();
       },
       redirect(e: RedirectTo) {
         lobbyCtrl.setRedirecting();

ui/mod/src/mod.user.ts

@@ -5,7 +5,6 @@ import extendTablesortNumber from 'common/tablesortNumber';
 import tablesort from 'tablesort';
 import { expandCheckboxZone, shiftClickCheckboxRange, selector } from './checkBoxes';
 import { spinnerHtml } from 'common/spinner';
-import { pubsub } from 'common/pubsub';
 import { confirm } from 'common/dialog';
 
 site.load.then(() => {
@@ -64,7 +63,7 @@ site.load.then(() => {
   const getLocationHash = (a: HTMLAnchorElement) => a.href.replace(/.+(#\w+)$/, '$1');
 
   function userMod($inZone: Cash) {
-    pubsub.emit('content-loaded', $inZone[0]);
+    window.lichess.initializeDom($inZone[0]);
 
     const makeReady = (selector: string, f: (el: HTMLElement, i: number) => void, cls = 'ready') => {
       $inZone.find(selector + `:not(.${cls})`).each(function (this: HTMLElement, i: number) {

ui/notify/src/view.ts

@@ -3,7 +3,6 @@ import { h, VNode } from 'snabbdom';
 import * as licon from 'common/licon';
 import { spinnerVdom as spinner } from 'common/spinner';
 import makeRenderers from './renderers';
-import { pubsub } from 'common/pubsub';
 
 const renderers = makeRenderers();
 
@@ -74,7 +73,7 @@ function clickHook(f: () => void) {
   };
 }
 
-const contentLoaded = (vnode: VNode) => pubsub.emit('content-loaded', vnode.elm);
+const contentLoaded = (vnode: VNode) => window.lichess.initializeDom(vnode.elm as HTMLElement);
 
 function recentNotifications(d: NotifyData, scrolling: boolean): VNode {
   return h(

ui/round/src/round.ts

@@ -74,7 +74,7 @@ async function boot(
           $meta.length && $('.game__meta').replaceWith($meta);
           $('.crosstable').replaceWith($html.find('.crosstable'));
           startTournamentClock();
-          pubsub.emit('content-loaded');
+          window.lichess.initializeDom();
         });
       },
       tourStanding(s: TourPlayer[]) {

ui/simul/src/simul.home.ts

@@ -7,6 +7,6 @@ site.load.then(() => {
     const rsp = await fetch('/simul/reload');
     const html = await rsp.text();
     $('.simul-list__content').html(html);
-    pubsub.emit('content-loaded');
+    window.lichess.initializeDom();
   });
 });

ui/site/src/announce.ts

@@ -1,5 +1,4 @@
 import { escapeHtml } from 'common';
-import { pubsub } from 'common/pubsub';
 
 let timeout: Timeout | undefined;
 
@@ -25,7 +24,7 @@ const announce = (d: LichessAnnouncement) => {
     const millis = d.date ? new Date(d.date).getTime() - Date.now() : 5000;
     if (millis > 0) timeout = setTimeout(kill, millis);
     else kill();
-    if (d.date) pubsub.emit('content-loaded');
+    if (d.date) window.lichess.initializeDom();
   }
 };
 

ui/site/src/api.ts

@@ -0,0 +1,54 @@
+import { Pubsub, PubsubCallback, PubsubEvent } from 'common/pubsub';
+
+// #TODO document these somewhere
+const publicEvents = ['ply', 'analysis.change', 'chat.resize', 'analysis.closeAll'];
+const socketEvents = ['lag', 'close'];
+const socketInEvents = ['mlat', 'fen', 'notifications', 'endData'];
+const friendsEvents = ['playing', 'stopped_playing', 'onlines', 'enters', 'leaves'];
+
+export const api = (pubsub: Pubsub) => ({
+  initializeDom: (root?: HTMLElement) => pubsub.emit('content-loaded', root),
+  events: {
+    on(name: PubsubEvent, cb: PubsubCallback): void {
+      if (!publicEvents.includes(name)) throw 'This event is not part of the public API';
+      pubsub.on(name, cb);
+    },
+    off(name: PubsubEvent, cb: PubsubCallback): void {
+      pubsub.off(name, cb);
+    },
+  },
+  socket: {
+    subscribeToMoveLatency: () => pubsub.emit('socket.send', 'moveLat', true),
+    events: {
+      on(key: string, cb: PubsubCallback): void {
+        if (socketInEvents.includes(key)) pubsub.on(`socket.in.${key}` as PubsubEvent, cb);
+        else if (socketEvents.includes(key)) pubsub.on(`socket.${key}` as PubsubEvent, cb);
+        else throw 'This event is not part of the public API';
+      },
+      off(key: string, cb: PubsubCallback): void {
+        const ev = socketInEvents.includes(key)
+          ? (`socket.in.${key}` as PubsubEvent)
+          : (`socket.${key}` as PubsubEvent);
+        pubsub.off(ev, cb);
+      },
+    },
+  },
+  onlineFriends: {
+    request: () => pubsub.emit('socket.send', 'following_onlines'),
+    events: {
+      on(key: string, cb: PubsubCallback): void {
+        if (!friendsEvents.includes(key)) throw 'This event is not part of the public API';
+        pubsub.on(`socket.in.following_${key}` as PubsubEvent, cb);
+      },
+      off(key: string, cb: PubsubCallback): void {
+        pubsub.off(`socket.in.following_${key}` as PubsubEvent, cb);
+      },
+    },
+  },
+  chat: {
+    post: (text: string) => pubsub.emit('socket.send', 'talk', text),
+  },
+  // some functions will be exposed here
+  // to be overriden by browser extensions
+  overrides: {},
+});

ui/site/src/friends.ts

@@ -1,6 +1,5 @@
 import { notNull } from 'common/common';
 import * as licon from 'common/licon';
-import { pubsub } from 'common/pubsub';
 
 type TitleName = string;
 
@@ -18,20 +17,21 @@ export default class OnlineFriends {
   users: Map<string, Friend>;
 
   constructor(readonly el: HTMLElement) {
+    const api = window.lichess.onlineFriends;
     this.titleEl = this.el.querySelector('.friend_box_title') as HTMLElement;
     this.titleEl.addEventListener('click', () => {
       this.el.querySelector('.content_wrap')?.classList.toggle('none');
       if (!this.loaded) {
         this.loaded = true;
-        pubsub.emit('socket.send', 'following_onlines');
+        api.request();
       }
     });
     this.users = new Map();
-    pubsub.on('socket.in.following_onlines', this.receive);
-    pubsub.on('socket.in.following_enters', this.enters);
-    pubsub.on('socket.in.following_leaves', this.leaves);
-    pubsub.on('socket.in.following_playing', this.playing);
-    pubsub.on('socket.in.following_stopped_playing', this.stopped_playing);
+    api.events.on('onlines', this.receive);
+    api.events.on('enters', this.enters);
+    api.events.on('leaves', this.leaves);
+    api.events.on('playing', this.playing);
+    api.events.on('stopped_playing', this.stopped_playing);
   }
   receive = (friends: TitleName[], msg: { playing: string[]; patrons: string[] }) => {
     this.users.clear();

ui/site/src/powertip.ts

@@ -2,7 +2,6 @@ import * as licon from 'common/licon';
 import * as xhr from 'common/xhr';
 import { requestIdleCallback, $as } from 'common';
 import { spinnerHtml } from 'common/spinner';
-import { pubsub } from 'common/pubsub';
 
 // Thanks Steven Benner! - adapted from https://github.com/stevenbenner/jquery-powertip
 
@@ -14,7 +13,7 @@ const onPowertipPreRender = (id: string, preload?: (url: string) => void) => (el
   xhr.text(url + '/mini').then(html => {
     const el = document.getElementById(id) as HTMLElement;
     el.innerHTML = html;
-    pubsub.emit('content-loaded', el);
+    window.lichess.initializeDom(el);
   });
 };