From aeba77f3c0406d24c0bda6d95a3a1d8a460b2d0e Mon Sep 17 00:00:00 2001
From: Yuto Nishida <yuto@berkeley.edu>
Date: Sun, 9 Aug 2026 17:58:48 -0700
Subject: [PATCH] [papyrus] Self-host terminal fonts, bundled from nix
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The terminal font came from the Google Fonts CDN (JetBrains Mono, weights
400/500, no italic — so bold/italic were browser-synthesized). Self-host the
terminal fonts instead: a flake `terminalFonts` derivation assembles the RIBBI
faces of JetBrains Mono + Iosevka/IosevkaTerm Nerd Font (base + Mono) from
nixpkgs; the client buildPhase drops them into Vite's publicDir so they ship in
dist/fonts/ and load via @font-face in index.css. JetBrains Mono is dropped from
the Google Fonts <link> (Inter, the UI font, stays).

The .ttf are generated, not committed (Nerd Font TTFs are ~10 MB each):
client/public/fonts/ is gitignored and regenerated for `bun run dev` by
scripts/sync-terminal-fonts.sh (invoked from run-dev-instance.sh) and by the Nix
build, both from the same `terminalFonts` derivation.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GBWyw3DyRvvNmgJpFZBsC5
---
 experimental/papyrus/.gitignore               |  4 +
 experimental/papyrus/client/index.html        |  3 +-
 experimental/papyrus/client/src/index.css     | 86 +++++++++++++++++++
 experimental/papyrus/flake.nix                | 22 ++++-
 experimental/papyrus/run-dev-instance.sh      |  3 +
 .../papyrus/scripts/sync-terminal-fonts.sh    | 16 ++++
 6 files changed, 131 insertions(+), 3 deletions(-)
 create mode 100755 experimental/papyrus/scripts/sync-terminal-fonts.sh

diff --git a/experimental/papyrus/.gitignore b/experimental/papyrus/.gitignore
index 5d3b822..6ab76c3 100644
--- a/experimental/papyrus/.gitignore
+++ b/experimental/papyrus/.gitignore
@@ -11,6 +11,10 @@ dist/
 client/dist/
 *.tsbuildinfo
 
+# Terminal fonts, generated from nix (flake `terminalFonts` / scripts/sync-terminal-fonts.sh).
+# Bundled into the build; never committed (Nerd Font TTFs are ~10 MB each).
+client/public/fonts/
+
 # Environment
 .env
 .env.local
diff --git a/experimental/papyrus/client/index.html b/experimental/papyrus/client/index.html
index 0d219df..28ce80c 100644
--- a/experimental/papyrus/client/index.html
+++ b/experimental/papyrus/client/index.html
@@ -7,7 +7,8 @@
     <title>papyrus</title>
     <link rel="preconnect" href="https://fonts.googleapis.com">
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
-    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet">
+    <!-- Inter (UI font) only; terminal mono fonts are self-hosted from /fonts (see index.css). -->
+    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap" rel="stylesheet">
     <!-- Resolve the saved theme preference before first paint to avoid a flash.
          Mirrors src/theme.ts (fixed theme, or follow-system via matchMedia). -->
     <script>
diff --git a/experimental/papyrus/client/src/index.css b/experimental/papyrus/client/src/index.css
index d096231..59ed2b2 100644
--- a/experimental/papyrus/client/src/index.css
+++ b/experimental/papyrus/client/src/index.css
@@ -2,6 +2,92 @@
 @tailwind components;
 @tailwind utilities;
 
+/* Self-hosted terminal fonts. The .ttf are bundled from nixpkgs by the flake (`terminalFonts`)
+   and served at /fonts/*.ttf (dev: client/public/fonts via scripts/sync-terminal-fonts.sh;
+   prod: dist/fonts). Every family declares all four real faces (Regular/Bold/Italic/
+   BoldItalic) so terminal attributes render without browser synthesis. Selectable per emulator
+   in Settings — see settings.ts TERMINAL_FONTS. Keep families/files in sync with both. */
+@font-face {
+  font-family: "JetBrains Mono"; font-weight: 400; font-style: normal; font-display: swap;
+  src: url("/fonts/JetBrainsMono-Regular.ttf") format("truetype");
+}
+@font-face {
+  font-family: "JetBrains Mono"; font-weight: 700; font-style: normal; font-display: swap;
+  src: url("/fonts/JetBrainsMono-Bold.ttf") format("truetype");
+}
+@font-face {
+  font-family: "JetBrains Mono"; font-weight: 400; font-style: italic; font-display: swap;
+  src: url("/fonts/JetBrainsMono-Italic.ttf") format("truetype");
+}
+@font-face {
+  font-family: "JetBrains Mono"; font-weight: 700; font-style: italic; font-display: swap;
+  src: url("/fonts/JetBrainsMono-BoldItalic.ttf") format("truetype");
+}
+@font-face {
+  font-family: "Iosevka Nerd Font"; font-weight: 400; font-style: normal; font-display: swap;
+  src: url("/fonts/IosevkaNerdFont-Regular.ttf") format("truetype");
+}
+@font-face {
+  font-family: "Iosevka Nerd Font"; font-weight: 700; font-style: normal; font-display: swap;
+  src: url("/fonts/IosevkaNerdFont-Bold.ttf") format("truetype");
+}
+@font-face {
+  font-family: "Iosevka Nerd Font"; font-weight: 400; font-style: italic; font-display: swap;
+  src: url("/fonts/IosevkaNerdFont-Italic.ttf") format("truetype");
+}
+@font-face {
+  font-family: "Iosevka Nerd Font"; font-weight: 700; font-style: italic; font-display: swap;
+  src: url("/fonts/IosevkaNerdFont-BoldItalic.ttf") format("truetype");
+}
+@font-face {
+  font-family: "Iosevka Nerd Font Mono"; font-weight: 400; font-style: normal; font-display: swap;
+  src: url("/fonts/IosevkaNerdFontMono-Regular.ttf") format("truetype");
+}
+@font-face {
+  font-family: "Iosevka Nerd Font Mono"; font-weight: 700; font-style: normal; font-display: swap;
+  src: url("/fonts/IosevkaNerdFontMono-Bold.ttf") format("truetype");
+}
+@font-face {
+  font-family: "Iosevka Nerd Font Mono"; font-weight: 400; font-style: italic; font-display: swap;
+  src: url("/fonts/IosevkaNerdFontMono-Italic.ttf") format("truetype");
+}
+@font-face {
+  font-family: "Iosevka Nerd Font Mono"; font-weight: 700; font-style: italic; font-display: swap;
+  src: url("/fonts/IosevkaNerdFontMono-BoldItalic.ttf") format("truetype");
+}
+@font-face {
+  font-family: "IosevkaTerm Nerd Font"; font-weight: 400; font-style: normal; font-display: swap;
+  src: url("/fonts/IosevkaTermNerdFont-Regular.ttf") format("truetype");
+}
+@font-face {
+  font-family: "IosevkaTerm Nerd Font"; font-weight: 700; font-style: normal; font-display: swap;
+  src: url("/fonts/IosevkaTermNerdFont-Bold.ttf") format("truetype");
+}
+@font-face {
+  font-family: "IosevkaTerm Nerd Font"; font-weight: 400; font-style: italic; font-display: swap;
+  src: url("/fonts/IosevkaTermNerdFont-Italic.ttf") format("truetype");
+}
+@font-face {
+  font-family: "IosevkaTerm Nerd Font"; font-weight: 700; font-style: italic; font-display: swap;
+  src: url("/fonts/IosevkaTermNerdFont-BoldItalic.ttf") format("truetype");
+}
+@font-face {
+  font-family: "IosevkaTerm Nerd Font Mono"; font-weight: 400; font-style: normal; font-display: swap;
+  src: url("/fonts/IosevkaTermNerdFontMono-Regular.ttf") format("truetype");
+}
+@font-face {
+  font-family: "IosevkaTerm Nerd Font Mono"; font-weight: 700; font-style: normal; font-display: swap;
+  src: url("/fonts/IosevkaTermNerdFontMono-Bold.ttf") format("truetype");
+}
+@font-face {
+  font-family: "IosevkaTerm Nerd Font Mono"; font-weight: 400; font-style: italic; font-display: swap;
+  src: url("/fonts/IosevkaTermNerdFontMono-Italic.ttf") format("truetype");
+}
+@font-face {
+  font-family: "IosevkaTerm Nerd Font Mono"; font-weight: 700; font-style: italic; font-display: swap;
+  src: url("/fonts/IosevkaTermNerdFontMono-BoldItalic.ttf") format("truetype");
+}
+
 /* Theme tokens. Each theme is a named block of semantic color variables (space-
    separated RGB channels, consumed via `rgb(var(--x) / <alpha-value>)` from
    tailwind.config.js). `:root` holds the dark defaults; a theme is applied by
diff --git a/experimental/papyrus/flake.nix b/experimental/papyrus/flake.nix
index f03a2b2..558df39 100644
--- a/experimental/papyrus/flake.nix
+++ b/experimental/papyrus/flake.nix
@@ -46,6 +46,17 @@
         # shells out to it for all durable state.
         silverwood-bin = silverwood.packages.${system}.default;
 
+        # The terminal fonts the client self-hosts, assembled from nixpkgs so they're
+        # reproducible (no CDN) and each ships real Regular/Bold/Italic/BoldItalic faces.
+        # Single source of truth for both the client build (preBuild below) and the dev
+        # sync script (scripts/sync-terminal-fonts.sh); `nix build .#terminalFonts`.
+        terminalFonts = pkgs.runCommandLocal "papyrus-terminal-fonts" { } ''
+          mkdir -p $out
+          cp ${pkgs.jetbrains-mono}/share/fonts/truetype/JetBrainsMono-{Regular,Bold,Italic,BoldItalic}.ttf $out/
+          cp ${pkgs.nerd-fonts.iosevka}/share/fonts/truetype/NerdFonts/Iosevka/IosevkaNerdFont{,Mono}-{Regular,Bold,Italic,BoldItalic}.ttf $out/
+          cp ${pkgs.nerd-fonts.iosevka-term}/share/fonts/truetype/NerdFonts/IosevkaTerm/IosevkaTermNerdFont{,Mono}-{Regular,Bold,Italic,BoldItalic}.ttf $out/
+        '';
+
         # The Vite/React client, built to static `dist`. Pure JS (no native
         # modules); installed + built with bun from client/bun.nix.
         client = b2n.mkDerivation {
@@ -53,7 +64,14 @@
           version = "1.2.1";
           src = ./client;
           bunDeps = b2n.fetchBunDeps { bunNix = ./client/bun.nix; };
-          buildPhase = "bun run build"; # package.json build: tsc && vite build -> dist
+          # Drop the self-hosted fonts into Vite's publicDir first (inline, not a preBuild hook —
+          # the custom buildPhase string below would skip runHook preBuild), so Vite copies them
+          # verbatim into dist/fonts/ and they're served at /fonts/*.ttf (see index.css).
+          buildPhase = ''
+            mkdir -p public/fonts
+            cp ${terminalFonts}/*.ttf public/fonts/
+            bun run build
+          ''; # package.json build: tsc && vite build -> dist
           installPhase = ''
             runHook preInstall
             cp -r dist "$out"
@@ -115,7 +133,7 @@
       {
         packages = {
           default = papyrus;
-          inherit client;
+          inherit client terminalFonts;
         };
 
         checks = {
diff --git a/experimental/papyrus/run-dev-instance.sh b/experimental/papyrus/run-dev-instance.sh
index 4c593d0..4263bce 100755
--- a/experimental/papyrus/run-dev-instance.sh
+++ b/experimental/papyrus/run-dev-instance.sh
@@ -7,5 +7,8 @@ set -euo pipefail
 # Run from this script's dir so `path:../silverwood` and `bun run dev` resolve.
 cd "$(dirname "$0")"
 
+# Self-hosted terminal fonts are bundled from nix and gitignored — populate them for Vite.
+./scripts/sync-terminal-fonts.sh
+
 exec nix shell path:../silverwood nixpkgs#bun --impure \
   --command bash -c 'PORT=7968 CLIENT_PORT=7969 bun run dev'
diff --git a/experimental/papyrus/scripts/sync-terminal-fonts.sh b/experimental/papyrus/scripts/sync-terminal-fonts.sh
new file mode 100755
index 0000000..bbb5914
--- /dev/null
+++ b/experimental/papyrus/scripts/sync-terminal-fonts.sh
@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+# Populate client/public/fonts/ with the self-hosted terminal fonts for `bun run dev`.
+#
+# The fonts are bundled from nixpkgs by the flake's `terminalFonts` derivation (the same
+# source the Nix build's preBuild uses), so dev and the packaged build serve identical files.
+# The .ttf are gitignored (not committed); this script regenerates them. Idempotent.
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+dest="client/public/fonts"
+
+out=$(nix build --no-link --print-out-paths .#terminalFonts)
+mkdir -p "$dest"
+cp -f "$out"/*.ttf "$dest"/
+chmod -R u+w "$dest"  # store files are read-only; make writable so re-runs can overwrite
+echo "synced $(ls "$dest"/*.ttf | wc -l | tr -d ' ') font files -> $dest"
-- 
2.51.2