@xterm/addon-web-fonts 0.1.0

package/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.

package/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).

package/lib/addon-web-fonts.js

@@ -0,0 +1,2 @@
+!function(t,e){"object"==typeof exports&&"object"==typeof module?module.exports=e():"function"==typeof define&&define.amd?define([],e):"object"==typeof exports?exports.WebFontsAddon=e():t.WebFontsAddon=e()}(globalThis,()=>(()=>{"use strict";var t={};return(()=>{var e=t;function n(t){return'"'===t[0]&&'"'===t[t.length-1]||"'"===t[0]&&"'"===t[t.length-1]?t.slice(1,-1):t}function o(t){const e=t.match(/([-_a-zA-Z0-9\xA0-\u{10FFFF}]+)/u);return!t.match(/^(-?\d|--)/m)&&e&&e[1]===t?t:`"${t.replace(/"/g,'\\"')}"`}function r(t){return JSON.stringify([n(t.family),t.stretch,t.style,t.unicodeRange,t.weight])}function i(t){const e=Array.from(document.fonts);if(!t||!t.length)return Promise.all(e.map(t=>t.load()));let o=[];const i=e.map(t=>r(t));for(const s of t)if(s instanceof FontFace){const t=r(s),n=i.indexOf(t);-1===n?(document.fonts.add(s),e.push(s),i.push(t),o.push(s)):o.push(e[n])}else{const t=e.filter(t=>s===n(t.family));if(o=o.concat(t),!t.length)return Promise.reject(`font family "${s}" not registered in document.fonts`)}return Promise.all(o.map(t=>t.load()))}function s(t){return document.fonts.ready.then(()=>i(t))}Object.defineProperty(e,"__esModule",{value:!0}),e.WebFontsAddon=void 0,e.loadFonts=s,e.WebFontsAddon=class{constructor(t=!0){this.initialRelayout=t}dispose(){this._term=void 0}activate(t){this._term=t,this.initialRelayout&&document.fonts.ready.then(()=>this.relayout())}loadFonts(t){return s(t)}async relayout(){if(!this._term)return;await document.fonts.ready;const t=this._term.options.fontFamily,e=function(t){return t?t.split(",").map(t=>n(t.trim())):[]}(t),r=Array.from(new Set(Array.from(document.fonts).map(t=>n(t.family)))),s=[],a=[];for(const t of e)(-1!==r.indexOf(t)?s:a).push(t);s.length&&(await i(s),this._term&&(this._term.options.fontFamily=a.length?function(t){return t.map(o).join(", ")}(a):"monospace",this._term.options.fontFamily=t))}}})(),t})());
+//# sourceMappingURL=addon-web-fonts.js.map

package/lib/addon-web-fonts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"addon-web-fonts.js","mappings":"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","sources":["webpack://WebFontsAddon/webpack/universalModuleDefinition","webpack://WebFontsAddon/./src/WebFontsAddon.ts"],"sourcesContent":["(function webpackUniversalModuleDefinition(root, factory) {\n\tif(typeof exports === 'object' && typeof module === 'object')\n\t\tmodule.exports = factory();\n\telse if(typeof define === 'function' && define.amd)\n\t\tdefine([], factory);\n\telse if(typeof exports === 'object')\n\t\texports[\"WebFontsAddon\"] = factory();\n\telse\n\t\troot[\"WebFontsAddon\"] = factory();\n})(globalThis, () => {\nreturn ","/**\n * Copyright (c) 2024 The xterm.js authors. All rights reserved.\n * @license MIT\n */\n\nimport type { Terminal, ITerminalAddon } from '@xterm/xterm';\nimport type { WebFontsAddon as IWebFontsApi } from '@xterm/addon-web-fonts';\n\n\n/**\n * Unquote a font family name.\n */\nfunction unquote(s: string): string {\n  if (s[0] === '\"' && s[s.length - 1] === '\"') return s.slice(1, -1);\n  if (s[0] === '\\'' && s[s.length - 1] === '\\'') return s.slice(1, -1);\n  return s;\n}\n\n\n/**\n * Quote a font family name conditionally.\n * @see https://mathiasbynens.be/notes/unquoted-font-family\n */\nfunction quote(s: string): string {\n  const pos = s.match(/([-_a-zA-Z0-9\\xA0-\\u{10FFFF}]+)/u);\n  const neg = s.match(/^(-?\\d|--)/m);\n  if (!neg && pos && pos[1] === s) return s;\n  return `\"${s.replace(/\"/g, '\\\\\"')}\"`;\n}\n\n\nfunction splitFamily(family: string | undefined): string[] {\n  if (!family) return [];\n  return family.split(',').map(e => unquote(e.trim()));\n}\n\n\nfunction createFamily(families: string[]): string {\n  return families.map(quote).join(', ');\n}\n\n\n/**\n * Hash a font face from it properties.\n * Used in `loadFonts` to avoid bloating\n * `document.fonts` from multiple calls.\n */\nfunction hashFontFace(ff: FontFace): string {\n  return JSON.stringify([\n    unquote(ff.family),\n    ff.stretch,\n    ff.style,\n    ff.unicodeRange,\n    ff.weight\n  ]);\n}\n\n\n/**\n * Wait for webfont resources to be loaded.\n *\n * Without any argument, all fonts currently listed in\n * `document.fonts` will be loaded.\n * For a more fine-grained loading strategy you can populate\n * the `fonts` argument with:\n * - font families      :   loads all fontfaces in `document.fonts`\n *                          matching the family names\n * - fontface objects   :   loads given fontfaces and adds them to\n *                          `document.fonts`\n *\n * The returned promise will resolve, when all loading is done.\n */\nfunction _loadFonts(fonts?: (string | FontFace)[]): Promise<FontFace[]> {\n  const ffs = Array.from(document.fonts);\n  if (!fonts || !fonts.length) {\n    return Promise.all(ffs.map(ff => ff.load()));\n  }\n  let toLoad: FontFace[] = [];\n  const ffsHashed = ffs.map(ff => hashFontFace(ff));\n  for (const font of fonts) {\n    if (font instanceof FontFace) {\n      const fontHashed = hashFontFace(font);\n      const idx = ffsHashed.indexOf(fontHashed);\n      if (idx === -1) {\n        document.fonts.add(font);\n        ffs.push(font);\n        ffsHashed.push(fontHashed);\n        toLoad.push(font);\n      } else {\n        toLoad.push(ffs[idx]);\n      }\n    } else {\n      // string as font\n      const familyFiltered = ffs.filter(ff => font === unquote(ff.family));\n      toLoad = toLoad.concat(familyFiltered);\n      if (!familyFiltered.length) {\n        return Promise.reject(`font family \"${font}\" not registered in document.fonts`);\n      }\n    }\n  }\n  return Promise.all(toLoad.map(ff => ff.load()));\n}\n\n\nexport function loadFonts(fonts?: (string | FontFace)[]): Promise<FontFace[]> {\n  return document.fonts.ready.then(() => _loadFonts(fonts));\n}\n\n\nexport class WebFontsAddon implements ITerminalAddon, IWebFontsApi {\n  private _term: Terminal | undefined;\n\n  constructor(public initialRelayout: boolean = true) { }\n\n  public dispose(): void {\n    this._term = undefined;\n  }\n\n  public activate(term: Terminal): void {\n    this._term = term;\n    if (this.initialRelayout) {\n      document.fonts.ready.then(() => this.relayout());\n    }\n  }\n\n  public loadFonts(fonts?: (string | FontFace)[]): Promise<FontFace[]> {\n    return loadFonts(fonts);\n  }\n\n  public async relayout(): Promise<void> {\n    if (!this._term) {\n      return;\n    }\n    await document.fonts.ready;\n    const family = this._term.options.fontFamily;\n    const families = splitFamily(family);\n    const webFamilies = Array.from(new Set(Array.from(document.fonts).map(e => unquote(e.family))));\n    const dirty: string[] = [];\n    const clean: string[] = [];\n    for (const fam of families) {\n      (webFamilies.indexOf(fam) !== -1 ? dirty : clean).push(fam);\n    }\n    if (!dirty.length) {\n      return;\n    }\n    await _loadFonts(dirty);\n    if (this._term) {\n      this._term.options.fontFamily = clean.length ? createFamily(clean) : 'monospace';\n      this._term.options.fontFamily = family;\n    }\n  }\n}\n"],"names":["root","factory","exports","module","define","amd","globalThis","unquote","s","length","slice","quote","pos","match","replace","hashFontFace","ff","JSON","stringify","family","stretch","style","unicodeRange","weight","_loadFonts","fonts","ffs","Array","from","document","Promise","all","map","load","toLoad","ffsHashed","font","FontFace","fontHashed","idx","indexOf","add","push","familyFiltered","filter","concat","reject","loadFonts","ready","then","constructor","initialRelayout","dispose","this","_term","undefined","activate","term","relayout","options","fontFamily","families","split","e","trim","splitFamily","webFamilies","Set","dirty","clean","fam","join","createFamily"],"ignoreList":[],"sourceRoot":""}

package/lib/addon-web-fonts.mjs

@@ -0,0 +1,18 @@
+/**
+ * Copyright (c) 2014-2024 The xterm.js authors. All rights reserved.
+ * @license MIT
+ *
+ * Copyright (c) 2012-2013, Christopher Jeffrey (MIT License)
+ * @license MIT
+ *
+ * Originally forked from (with the author's permission):
+ *   Fabrice Bellard's javascript vt100 for jslinux:
+ *   http://bellard.org/jslinux/
+ *   Copyright (c) 2011 Fabrice Bellard
+ */
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+function s(t){return t[0]==='"'&&t[t.length-1]==='"'||t[0]==="'"&&t[t.length-1]==="'"?t.slice(1,-1):t}function u(t){let n=t.match(/([-_a-zA-Z0-9\xA0-\u{10FFFF}]+)/u);return!t.match(/^(-?\d|--)/m)&&n&&n[1]===t?t:`"${t.replace(/"/g,'\\"')}"`}function f(t){return t?t.split(",").map(n=>s(n.trim())):[]}function d(t){return t.map(u).join(", ")}function m(t){return JSON.stringify([s(t.family),t.stretch,t.style,t.unicodeRange,t.weight])}function l(t){let n=Array.from(document.fonts);if(!t||!t.length)return Promise.all(n.map(e=>e.load()));let r=[],a=n.map(e=>m(e));for(let e of t)if(e instanceof FontFace){let i=m(e),o=a.indexOf(i);o===-1?(document.fonts.add(e),n.push(e),a.push(i),r.push(e)):r.push(n[o])}else{let i=n.filter(o=>e===s(o.family));if(r=r.concat(i),!i.length)return Promise.reject(`font family "${e}" not registered in document.fonts`)}return Promise.all(r.map(e=>e.load()))}function F(t){return document.fonts.ready.then(()=>l(t))}var c=class{constructor(n=!0){this.initialRelayout=n}dispose(){this._term=void 0}activate(n){this._term=n,this.initialRelayout&&document.fonts.ready.then(()=>this.relayout())}loadFonts(n){return F(n)}async relayout(){if(!this._term)return;await document.fonts.ready;let n=this._term.options.fontFamily,r=f(n),a=Array.from(new Set(Array.from(document.fonts).map(o=>s(o.family)))),e=[],i=[];for(let o of r)(a.indexOf(o)!==-1?e:i).push(o);e.length&&(await l(e),this._term&&(this._term.options.fontFamily=i.length?d(i):"monospace",this._term.options.fontFamily=n))}};export{c as WebFontsAddon,F as loadFonts};
+//# sourceMappingURL=addon-web-fonts.mjs.map

package/lib/addon-web-fonts.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/WebFontsAddon.ts"],
+  "sourcesContent": ["/**\n * Copyright (c) 2024 The xterm.js authors. All rights reserved.\n * @license MIT\n */\n\nimport type { Terminal, ITerminalAddon } from '@xterm/xterm';\nimport type { WebFontsAddon as IWebFontsApi } from '@xterm/addon-web-fonts';\n\n\n/**\n * Unquote a font family name.\n */\nfunction unquote(s: string): string {\n  if (s[0] === '\"' && s[s.length - 1] === '\"') return s.slice(1, -1);\n  if (s[0] === '\\'' && s[s.length - 1] === '\\'') return s.slice(1, -1);\n  return s;\n}\n\n\n/**\n * Quote a font family name conditionally.\n * @see https://mathiasbynens.be/notes/unquoted-font-family\n */\nfunction quote(s: string): string {\n  const pos = s.match(/([-_a-zA-Z0-9\\xA0-\\u{10FFFF}]+)/u);\n  const neg = s.match(/^(-?\\d|--)/m);\n  if (!neg && pos && pos[1] === s) return s;\n  return `\"${s.replace(/\"/g, '\\\\\"')}\"`;\n}\n\n\nfunction splitFamily(family: string | undefined): string[] {\n  if (!family) return [];\n  return family.split(',').map(e => unquote(e.trim()));\n}\n\n\nfunction createFamily(families: string[]): string {\n  return families.map(quote).join(', ');\n}\n\n\n/**\n * Hash a font face from it properties.\n * Used in `loadFonts` to avoid bloating\n * `document.fonts` from multiple calls.\n */\nfunction hashFontFace(ff: FontFace): string {\n  return JSON.stringify([\n    unquote(ff.family),\n    ff.stretch,\n    ff.style,\n    ff.unicodeRange,\n    ff.weight\n  ]);\n}\n\n\n/**\n * Wait for webfont resources to be loaded.\n *\n * Without any argument, all fonts currently listed in\n * `document.fonts` will be loaded.\n * For a more fine-grained loading strategy you can populate\n * the `fonts` argument with:\n * - font families      :   loads all fontfaces in `document.fonts`\n *                          matching the family names\n * - fontface objects   :   loads given fontfaces and adds them to\n *                          `document.fonts`\n *\n * The returned promise will resolve, when all loading is done.\n */\nfunction _loadFonts(fonts?: (string | FontFace)[]): Promise<FontFace[]> {\n  const ffs = Array.from(document.fonts);\n  if (!fonts || !fonts.length) {\n    return Promise.all(ffs.map(ff => ff.load()));\n  }\n  let toLoad: FontFace[] = [];\n  const ffsHashed = ffs.map(ff => hashFontFace(ff));\n  for (const font of fonts) {\n    if (font instanceof FontFace) {\n      const fontHashed = hashFontFace(font);\n      const idx = ffsHashed.indexOf(fontHashed);\n      if (idx === -1) {\n        document.fonts.add(font);\n        ffs.push(font);\n        ffsHashed.push(fontHashed);\n        toLoad.push(font);\n      } else {\n        toLoad.push(ffs[idx]);\n      }\n    } else {\n      // string as font\n      const familyFiltered = ffs.filter(ff => font === unquote(ff.family));\n      toLoad = toLoad.concat(familyFiltered);\n      if (!familyFiltered.length) {\n        return Promise.reject(`font family \"${font}\" not registered in document.fonts`);\n      }\n    }\n  }\n  return Promise.all(toLoad.map(ff => ff.load()));\n}\n\n\nexport function loadFonts(fonts?: (string | FontFace)[]): Promise<FontFace[]> {\n  return document.fonts.ready.then(() => _loadFonts(fonts));\n}\n\n\nexport class WebFontsAddon implements ITerminalAddon, IWebFontsApi {\n  private _term: Terminal | undefined;\n\n  constructor(public initialRelayout: boolean = true) { }\n\n  public dispose(): void {\n    this._term = undefined;\n  }\n\n  public activate(term: Terminal): void {\n    this._term = term;\n    if (this.initialRelayout) {\n      document.fonts.ready.then(() => this.relayout());\n    }\n  }\n\n  public loadFonts(fonts?: (string | FontFace)[]): Promise<FontFace[]> {\n    return loadFonts(fonts);\n  }\n\n  public async relayout(): Promise<void> {\n    if (!this._term) {\n      return;\n    }\n    await document.fonts.ready;\n    const family = this._term.options.fontFamily;\n    const families = splitFamily(family);\n    const webFamilies = Array.from(new Set(Array.from(document.fonts).map(e => unquote(e.family))));\n    const dirty: string[] = [];\n    const clean: string[] = [];\n    for (const fam of families) {\n      (webFamilies.indexOf(fam) !== -1 ? dirty : clean).push(fam);\n    }\n    if (!dirty.length) {\n      return;\n    }\n    await _loadFonts(dirty);\n    if (this._term) {\n      this._term.options.fontFamily = clean.length ? createFamily(clean) : 'monospace';\n      this._term.options.fontFamily = family;\n    }\n  }\n}\n"],
+  "mappings": "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",
+  "names": ["unquote", "s", "quote", "pos", "splitFamily", "family", "e", "createFamily", "families", "hashFontFace", "ff", "_loadFonts", "fonts", "ffs", "toLoad", "ffsHashed", "font", "fontHashed", "idx", "familyFiltered", "loadFonts", "WebFontsAddon", "initialRelayout", "term", "webFamilies", "dirty", "clean", "fam"]
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "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"
+  },
+  "dependencies": {},
+  "commit": "e1bfc7dd1f379dee9e2dc4cafc6b53efbff4154f",
+  "peerDependencies": {
+    "@xterm/xterm": "^6.1.0-beta.86"
+  }
+}

package/src/WebFontsAddon.ts

@@ -0,0 +1,152 @@
+/**
+ * Copyright (c) 2024 The xterm.js authors. All rights reserved.
+ * @license MIT
+ */
+
+import type { Terminal, ITerminalAddon } from '@xterm/xterm';
+import type { WebFontsAddon as IWebFontsApi } from '@xterm/addon-web-fonts';
+
+
+/**
+ * Unquote a font family name.
+ */
+function unquote(s: string): string {
+  if (s[0] === '"' && s[s.length - 1] === '"') return s.slice(1, -1);
+  if (s[0] === '\'' && s[s.length - 1] === '\'') return s.slice(1, -1);
+  return s;
+}
+
+
+/**
+ * Quote a font family name conditionally.
+ * @see https://mathiasbynens.be/notes/unquoted-font-family
+ */
+function quote(s: string): string {
+  const pos = s.match(/([-_a-zA-Z0-9\xA0-\u{10FFFF}]+)/u);
+  const neg = s.match(/^(-?\d|--)/m);
+  if (!neg && pos && pos[1] === s) return s;
+  return `"${s.replace(/"/g, '\\"')}"`;
+}
+
+
+function splitFamily(family: string | undefined): string[] {
+  if (!family) return [];
+  return family.split(',').map(e => unquote(e.trim()));
+}
+
+
+function createFamily(families: string[]): string {
+  return families.map(quote).join(', ');
+}
+
+
+/**
+ * Hash a font face from it properties.
+ * Used in `loadFonts` to avoid bloating
+ * `document.fonts` from multiple calls.
+ */
+function hashFontFace(ff: FontFace): string {
+  return JSON.stringify([
+    unquote(ff.family),
+    ff.stretch,
+    ff.style,
+    ff.unicodeRange,
+    ff.weight
+  ]);
+}
+
+
+/**
+ * Wait for webfont resources to be loaded.
+ *
+ * Without any argument, all fonts currently listed in
+ * `document.fonts` will be loaded.
+ * For a more fine-grained loading strategy you can populate
+ * the `fonts` argument with:
+ * - font families      :   loads all fontfaces in `document.fonts`
+ *                          matching the family names
+ * - fontface objects   :   loads given fontfaces and adds them to
+ *                          `document.fonts`
+ *
+ * The returned promise will resolve, when all loading is done.
+ */
+function _loadFonts(fonts?: (string | FontFace)[]): Promise<FontFace[]> {
+  const ffs = Array.from(document.fonts);
+  if (!fonts || !fonts.length) {
+    return Promise.all(ffs.map(ff => ff.load()));
+  }
+  let toLoad: FontFace[] = [];
+  const ffsHashed = ffs.map(ff => hashFontFace(ff));
+  for (const font of fonts) {
+    if (font instanceof FontFace) {
+      const fontHashed = hashFontFace(font);
+      const idx = ffsHashed.indexOf(fontHashed);
+      if (idx === -1) {
+        document.fonts.add(font);
+        ffs.push(font);
+        ffsHashed.push(fontHashed);
+        toLoad.push(font);
+      } else {
+        toLoad.push(ffs[idx]);
+      }
+    } else {
+      // string as font
+      const familyFiltered = ffs.filter(ff => font === unquote(ff.family));
+      toLoad = toLoad.concat(familyFiltered);
+      if (!familyFiltered.length) {
+        return Promise.reject(`font family "${font}" not registered in document.fonts`);
+      }
+    }
+  }
+  return Promise.all(toLoad.map(ff => ff.load()));
+}
+
+
+export function loadFonts(fonts?: (string | FontFace)[]): Promise<FontFace[]> {
+  return document.fonts.ready.then(() => _loadFonts(fonts));
+}
+
+
+export class WebFontsAddon implements ITerminalAddon, IWebFontsApi {
+  private _term: Terminal | undefined;
+
+  constructor(public initialRelayout: boolean = true) { }
+
+  public dispose(): void {
+    this._term = undefined;
+  }
+
+  public activate(term: Terminal): void {
+    this._term = term;
+    if (this.initialRelayout) {
+      document.fonts.ready.then(() => this.relayout());
+    }
+  }
+
+  public loadFonts(fonts?: (string | FontFace)[]): Promise<FontFace[]> {
+    return loadFonts(fonts);
+  }
+
+  public async relayout(): Promise<void> {
+    if (!this._term) {
+      return;
+    }
+    await document.fonts.ready;
+    const family = this._term.options.fontFamily;
+    const families = splitFamily(family);
+    const webFamilies = Array.from(new Set(Array.from(document.fonts).map(e => unquote(e.family))));
+    const dirty: string[] = [];
+    const clean: string[] = [];
+    for (const fam of families) {
+      (webFamilies.indexOf(fam) !== -1 ? dirty : clean).push(fam);
+    }
+    if (!dirty.length) {
+      return;
+    }
+    await _loadFonts(dirty);
+    if (this._term) {
+      this._term.options.fontFamily = clean.length ? createFamily(clean) : 'monospace';
+      this._term.options.fontFamily = family;
+    }
+  }
+}

package/typings/addon-web-fonts.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Copyright (c) 2024 The xterm.js authors. All rights reserved.
+ * @license MIT
+ */
+
+
+import { Terminal, ITerminalAddon } from '@xterm/xterm';
+
+declare module '@xterm/addon-web-fonts' {
+
+  /**
+   * Addon to use webfonts in xterm.js
+   */
+  export class WebFontsAddon implements ITerminalAddon {
+    /**
+     * @param initialRelayout Force initial relayout, if a webfont was found (default true).
+     */
+    constructor(initialRelayout?: boolean);
+    public activate(terminal: Terminal): void;
+    public dispose(): void;
+
+    /**
+     * Wait for webfont resources to be loaded.
+     *
+     * Without any argument, all fonts currently listed in
+     * `document.fonts` will be loaded.
+     * For a more fine-grained loading strategy you can populate
+     * the `fonts` argument with:
+     * - font families      :   loads all fontfaces in `document.fonts`
+     *                          matching the family names
+     * - fontface objects   :   loads given fontfaces and adds them to
+     *                          `document.fonts`
+     *
+     * The returned promise will resolve, when all loading is done.
+     */
+    public loadFonts(fonts?: (string | FontFace)[]): Promise<FontFace[]>;
+
+    /**
+     * Force a terminal relayout by altering `options.FontFamily`.
+     *
+     * Found webfonts in `fontFamily` are temporarily removed until the webfont
+     * resources are fully loaded.
+     * 
+     * Call this method, if a terminal with webfonts is stuck with broken
+     * glyph metrics.
+     * 
+     * The returned promise will resolve, when font loading and layouting are done.
+     */
+    public relayout(): Promise<void>;
+  }
+
+  /**
+   * Wait for webfont resources to be loaded.
+   *
+   * Without any argument, all fonts currently listed in
+   * `document.fonts` will be loaded.
+   * For a more fine-grained loading strategy you can populate
+   * the `fonts` argument with:
+   * - font families      :   loads all fontfaces in `document.fonts`
+   *                          matching the family names
+   * - fontface objects   :   loads given fontfaces and adds them to
+   *                          `document.fonts`
+   *
+   * The returned promise will resolve, when all loading is done.
+   */
+  function loadFonts(fonts?: (string | FontFace)[]): Promise<FontFace[]>;
+}