webfonts addon

.eslintrc.json

@@ -33,6 +33,8 @@
       "addons/addon-unicode-graphemes/src/tsconfig.json",
       "addons/addon-unicode-graphemes/test/tsconfig.json",
       "addons/addon-unicode-graphemes/benchmark/tsconfig.json",
+      "addons/addon-web-fonts/src/tsconfig.json",
+      "addons/addon-web-fonts/test/tsconfig.json",
       "addons/addon-web-links/src/tsconfig.json",
       "addons/addon-web-links/test/tsconfig.json",
       "addons/addon-webgl/src/tsconfig.json",

.github/workflows/ci.yml

@@ -59,6 +59,9 @@ jobs:
           ./addons/addon-web-links/lib/* \
           ./addons/addon-web-links/out/* \
           ./addons/addon-web-links/out-*/* \
+          ./addons/addon-web-fonts/lib/* \
+          ./addons/addon-web-fonts/out/* \
+          ./addons/addon-web-fonts/out-*/* \
           ./addons/addon-webgl/lib/* \
           ./addons/addon-webgl/out/* \
           ./addons/addon-webgl/out-*st/*
@@ -220,6 +223,8 @@ jobs:
       run: yarn test-integration-${{ matrix.browser }} --workers=50% --forbid-only --suite=addon-unicode-graphemes
     - name: Integration tests (addon-unicode11)
       run: yarn test-integration-${{ matrix.browser }} --workers=50% --forbid-only --suite=addon-unicode11
+    - name: Integration tests (addon-web-fonts)
+      run: yarn test-integration-${{ matrix.browser }} --workers=50% --forbid-only --suite=addon-web-fonts
     - name: Integration tests (addon-web-links)
       run: yarn test-integration-${{ matrix.browser }} --workers=50% --forbid-only --suite=addon-web-links
     - name: Integration tests (addon-webgl)

addons/addon-web-fonts/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2024, The xterm.js authors (https://github.com/xtermjs/xterm.js)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

addons/addon-web-fonts/README.md

@@ -0,0 +1,220 @@
+## @xterm/addon-web-fonts
+
+Addon to use webfonts with [xterm.js](https://github.com/xtermjs/xterm.js).
+This addon requires xterm.js v5+.
+
+### Install
+
+```bash
+npm install --save @xterm/addon-web-fonts
+```
+
+### Issue with Webfonts
+
+Webfonts are announced by CSS `font-face` rules (or its Javascript `FontFace` counterparts).
+Since font files tend to be quite big assets, browser engines often postpone their loading
+to an actual styling request of a codepoint matching a font file's `unicode-range`.
+In short - font files will not be loaded until really needed.
+
+xterm.js on the other hand heavily relies on exact measurement of character glyphs
+to layout its output. This is done by determining the glyph width (DOM renderer) or
+by creating a glyph texture (WebGl renderer) for every output character.
+For performance reasons both is done in synchronous code and cached.
+This logic only works properly, if a font glyph is available on its first usage,
+otherwise the browser will pick a glyph from a fallback font messing up the metrics.
+
+For webfonts and xterm.js this means that we cannot rely on the default loading strategy
+of the browser, but have to preload the font files before using that font in xterm.js.
+
+
+### Static Preloading for the Rescue?
+
+If you dont mind higher initial loading times with a white page shown,
+you can tell the browser to preload the needed font files by placing the following
+link elements in the document's head above any other CSS/Javascript:
+```html
+  <link rel="preload" as="font" href="/path/to/your/fontfile1.woff" type="font/woff2" crossorigin="anonymous">
+  <link rel="preload" as="font" href="/path/to/your/fontfile2.woff" type="font/woff2" crossorigin="anonymous">
+  ...
+  <!-- CSS with font-face rules matching the URLs above -->
+```
+Browsers also will resort to system fonts, if the preloading takes too long.
+So this solution has only a very limited scope.
+
+
+### Loading with WebFontsAddon
+
+The webfonts addon offers several ways to deal with font assets loading
+without leaving the terminal in an unusable state.
+
+Recap - normally boostrapping of a new terminal involves these basic steps (Typescript):
+
+```typescript
+import { Terminal } from '@xterm/xterm';
+import { XYAddon } from '@xterm/addon-xy';
+
+// create a `Terminal` instance with some options, e.g. a custom font family
+const terminal = new Terminal({fontFamily: 'monospace'});
+
+// create and load all addons you want to use, e.g. fit addon
+const xyInstance = new XYAddon();
+terminal.loadAddon(xyInstance);
+
+// finally: call `open` of the terminal instance
+terminal.open(your_terminal_div_element);   // <-- critical path for webfonts
+// more boostrapping goes here ...
+```
+This code is guaranteed to work in all browsers synchronously, as the identifier `monospace`
+will always be available. It will also work synchronously with any installed system font,
+but breaks horribly with webfonts. The actual culprit here is the call to `terminal.open`,
+which attaches the terminal to the DOM and starts the renderer with all the glyph caching
+mentioned above, while the webfont is not yet fully available.
+
+To fix that, the webfonts addon provides a waiting condition (Typescript):
+```typescript
+import { Terminal } from '@xterm/xterm';
+import { XYAddon } from '@xterm/addon-xy';
+import { WebFontsAddon } from '@xterm/addon-web-fonts';
+
+// create a `Terminal` instance, now with webfonts
+const terminal = new Terminal({fontFamily: '"Web Mono 1", "Super Powerline", monospace'});
+const xyInstance = new XYAddon();
+terminal.loadAddon(xyInstance);
+
+const webFontsInstance = new WebFontsAddon();
+terminal.loadAddon(webFontsInstance);  
+
+// wait for webfonts to be fully loaded
+webFontsInstance.loadFonts(['Web Mono 1', 'Super Powerline']).then(() => {
+  terminal.open(your_terminal_div_element);
+  // more boostrapping goes here ...
+});
+```
+Here `loadFonts` will look up the font face objects in `document.fonts`
+and load them before continuing. For this to work, you have to make sure,
+that the CSS `font-face` rules for these webfonts are loaded beforehand,
+otherwise `loadFonts` will not find the font family names (promise will be
+rejected for missing font family names).
+
+Please note, that this cannot run synchronous anymore, so you will have to split your
+bootstrapping code into several stages. If that is too much of a hassle,
+you can also move the whole bootstrapping under the waiting condition by using
+the static loader instead (Typescript):
+```typescript
+import { Terminal } from '@xterm/xterm';
+import { XYAddon } from '@xterm/addon-xy';
+// import static loader
+import { loadFonts } from '@xterm/addon-web-fonts';
+
+loadFonts(['Web Mono 1', 'Super Powerline']).then(() => {
+  // create a `Terminal` instance, now with webfonts
+  const terminal = new Terminal({fontFamily: '"Web Mono 1", "Super Powerline", monospace'});
+  const xyInstance = new XYAddon();
+  terminal.loadAddon(xyInstance);
+
+  // optional when using static loader
+  const webfontsInstance = new WebFontsAddon();
+  terminal.loadAddon(webfontsInstance);
+
+  terminal.open(your_terminal_div_element);
+  // more boostrapping goes here ...
+});
+```
+With the static loader creating and loading of the actual addon can be omitted,
+as fonts are already loaded before any terminal setup happens.
+
+### Webfont Loading at Runtime
+
+Given you have a terminal already running and want to change the font family
+to a different not yet loaded webfont:
+```typescript
+// either create font face objects in javascript
+const ff1 = new FontFace('New Web Mono', url1, ...);
+const ff2 = new FontFace('New Web Mono', url2, ...);
+// and await their loading
+loadFonts([ff1, ff2]).then(() => {
+  // apply new webfont to terminal
+  terminal.options.fontFamily = 'New Web Mono';
+  // since the new font might have slighly different metrics,
+  // also run the fit addon here (or any other custom resize logic)
+  fitAddon.fit();
+});
+
+// or alternatively use CSS to add new font-face rules, e.g.
+document.styleSheets[0].insertRule(
+  "@font-face { font-family: 'New Web Mono'; src: url(newfont.woff); }", 0);
+// and await the new font family name
+loadFonts(['New Web Mono']).then(() => {
+  // apply new webfont to terminal
+  terminal.options.fontFamily = 'New Web Mono';
+  // since the new font might have slighly different metrics,
+  // also run the fit addon here (or any other custom resize logic)
+  fitAddon.fit();
+});
+```
+
+### Forced Layout Update
+
+If you have the addon loaded into your terminal, you can force the terminal to update
+the layout with the method `WebFontsAddon.relayout`. This might come handy,
+if the terminal shows webfont related output issue for unknown reasons:
+```typescript
+...
+// given - terminal shows weird font issues, run:
+webFontsInstance.relayout().then(() => {
+  // also run resize logic here, e.g. fit addon
+  fitAddon.fit();
+});
+```
+Note that this method is only meant as a quickfix on a running terminal to keep it
+in a working condition. A production-ready integration should never rely on it,
+better fix the  real root cause (most likely not properly awaiting the font loader
+higher up in the code).
+
+
+### Webfonts from Fontsource
+
+The addon has been tested to work with webfonts from fontsource.
+Javascript example for `vite` with ESM import:
+```javascript
+import { Terminal } from '@xterm/xterm';
+import { FitAddon } from '@xterm/addon-fit';
+import { loadFonts } from '@xterm/addon-web-fonts';
+import '@xterm/xterm/css/xterm.css';
+import '@fontsource/roboto-mono';
+import '@fontsource/roboto-mono/400.css';
+import '@fontsource/roboto-mono/400-italic.css';
+import '@fontsource/roboto-mono/700.css';
+import '@fontsource/roboto-mono/700-italic.css';
+
+async function main() {
+  let fontFamily = '"Roboto Mono", monospace';
+  try {
+    await loadFonts(['Roboto Mono']);
+  } catch (e) {
+    fontFamily = 'monospace';
+  }
+
+  const terminal = new Terminal({ fontFamily });
+  const fitAddon = new FitAddon();
+  terminal.loadAddon(fitAddon);
+  terminal.open(document.getElementById('your-xterm-container-div'));
+  fitAddon.fit();
+
+  // sync writing shows up in Roboto Mono w'o FOUT
+  // and a fallback to monospace
+  terminal.write('put any unicode char here');
+}
+
+main();
+```
+The fontsource packages download the font files to your project folder to be delivered
+from there later on. For security sensitive projects this should be the preferred way,
+as it brings the font files under your control.
+
+The example furthermore contains proper exception handling with a fallback
+(skipped in all other examples for better readability).
+
+---
+
+Also see the full [API](https://github.com/xtermjs/xterm.js/blob/master/addons/addon-web-fonts/typings/addon-web-fonts.d.ts).

addons/addon-web-fonts/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@xterm/addon-web-fonts",
+  "version": "0.1.0",
+  "author": {
+    "name": "The xterm.js authors",
+    "url": "https://xtermjs.org/"
+  },
+  "main": "lib/addon-web-fonts.js",
+  "module": "lib/addon-web-fonts.mjs",
+  "types": "typings/addon-web-fonts.d.ts",
+  "repository": "https://github.com/xtermjs/xterm.js/tree/master/addons/addon-web-fonts",
+  "license": "MIT",
+  "keywords": [
+    "terminal",
+    "xterm",
+    "xterm.js"
+  ],
+  "scripts": {
+    "build": "../../node_modules/.bin/tsc -p .",
+    "prepackage": "npm run build",
+    "package": "../../node_modules/.bin/webpack",
+    "prepublishOnly": "npm run package",
+    "start": "node ../../demo/start"
+  },
+  "peerDependencies": {
+    "@xterm/xterm": "^5.0.0"
+  },
+  "dependencies": {}
+}