feat: Add HarfBuzz text shaping (#735)

Adds HarfBuzz-backed shaping for OpenType features and complex scripts
while keeping Satori's published bundle close to its previous size by
loading the patched HarfBuzz runtime as an external dependency.
Measurement and SVG generation now share shaped run metrics, including
kerning, ligatures, WOFF conversion, and font fallback boundaries.

The PR also adds focused image coverage for OpenType features,
complex-script shaping, mixed-font letter spacing, and browser consumer
bundling. Full Unicode bidirectional layout remains explicitly
unsupported.

Author: shuding

README.md

@@ -215,11 +215,12 @@ Satori uses the same Flexbox [layout engine](https://yogalayout.com) as React Na
 <tr><td><code>justifyContent</code></td><td>Supported</td><td></td></tr>
 <tr><td><code>gap</code></td><td>Supported</td><td></td></tr>
 
-<tr><td rowspan="5">Font</td></tr>
+<tr><td rowspan="6">Font</td></tr>
 <tr><td><code>fontFamily</code></td><td>Supported</td><td></td></tr>
 <tr><td><code>fontSize</code></td><td>Supported</td><td></td></tr>
 <tr><td><code>fontWeight</code></td><td>Supported</td><td></td></tr>
 <tr><td><code>fontStyle</code></td><td>Supported</td><td></td></tr>
+<tr><td><code>fontFeatureSettings</code></td><td>Supported via HarfBuzz text shaping. Enables OpenType features like ligatures, small caps, stylistic sets, etc.</td><td></td></tr>
 
 <tr><td rowspan="13">Text</td></tr>
 <tr><td><code>tabSize</code></td><td>Supported</td><td></td></tr>
@@ -346,9 +347,24 @@ Note:
 
 ### Language and Typography
 
-Advanced typography features such as kerning, ligatures and other OpenType features are not currently supported.
+**OpenType Features**: Satori supports advanced typography features via HarfBuzz text shaping. Use the `font-feature-settings` CSS property to enable OpenType features such as:
+- Ligatures (`liga`, `dlig`, `hlig`)
+- Small caps (`smcp`, `c2sc`)
+- Stylistic sets (`ss01`-`ss20`)
+- Contextual alternates (`calt`)
+- Swashes (`swsh`, `cswh`)
+- And many more OpenType features
 
-RTL languages are not supported either.
+Example:
+```jsx
+<div style={{ fontFeatureSettings: '"smcp" 1, "liga" 0' }}>
+  This Text Uses Small Caps
+</div>
+```
+
+HarfBuzz also improves glyph shaping for complex scripts such as Arabic. Full
+Unicode bidirectional layout is not yet supported, so mixed LTR and RTL text
+may not follow browser ordering.
 
 #### Fonts
 

package.json

@@ -100,7 +100,6 @@
   "devDependencies": {
     "@resvg/resvg-js": "^2.1.0",
     "@types/node": "^16",
-    "@types/opentype.js": "^1.3.3",
     "@types/react": "^17.0.38",
     "@typescript-eslint/eslint-plugin": "^5.40.0",
     "@typescript-eslint/parser": "^5.40.0",
@@ -126,12 +125,14 @@
   },
   "dependencies": {
     "@shuding/opentype.js": "1.4.0-beta.0",
+    "fflate": "0.7.3",
     "css-background-parser": "^0.1.0",
     "css-box-shadow": "1.0.0-3",
     "css-gradient-parser": "^0.0.17",
     "css-to-react-native": "^3.0.0",
     "emoji-regex-xs": "^2.0.1",
     "escape-html": "^1.0.3",
+    "harfbuzzjs": "0.10.0",
     "linebreak": "^1.1.0",
     "parse-css-color": "^0.2.1",
     "postcss-value-parser": "^4.2.0",
@@ -140,10 +141,5 @@
   "packageManager": "pnpm@10.33.0+sha512.10568bb4a6afb58c9eb3630da90cc9516417abebd3fabbe6739f0ae795728da1491e9db5a544c76ad8eb7570f5c4bb3d6c637b2cb41bfdcdb47fa823c8649319",
   "engines": {
     "node": ">=16"
-  },
-  "pnpm": {
-    "patchedDependencies": {
-      "yoga-layout@3.2.1": "patches/yoga-layout@3.2.1.patch"
-    }
   }
 }

patches/harfbuzzjs@0.10.0.patch

@@ -3,30 +3,6 @@ export type Tabs = {
 }
 
 const playgroundTabs: Tabs = {
-  helloworld: `<div
-  style={{
-    height: '100%',
-    width: '100%',
-    display: 'flex',
-    flexDirection: 'column',
-    alignItems: 'center',
-    justifyContent: 'center',
-    backgroundColor: '#fff',
-    fontSize: 32,
-    fontWeight: 600,
-  }}
->
-  <svg
-    width="75"
-    viewBox="0 0 75 65"
-    fill="#000"
-    style={{ margin: '0 75px' }}
-  >
-    <path d="M37.59.25l36.95 64H.64l36.95-64z"></path>
-  </svg>
-  <div style={{ marginTop: 40 }}>Hello, World</div>
-</div>
-`,
   Vercel: `<div
   style={{
     height: '100%',
@@ -69,7 +45,7 @@ const playgroundTabs: Tabs = {
       whiteSpace: 'pre-wrap',
     }}
   >
-    <b>Vercel Edge Network</b>
+    <b>Agentic Infrastructure</b>
   </div>
 </div>
 `,
@@ -312,7 +288,7 @@ const playgroundTabs: Tabs = {
       </div>
     </div>
   )
-}  
+}
 `,
 }
 

playground/cards/playground-data.ts

@@ -1,5 +1,7 @@
 /// <reference types="next" />
 /// <reference types="next/image-types/global" />
+import './.next/dev/types/routes.d.ts'
+import './.next/dev/types/root-params.d.ts'
 
 // NOTE: This file should not be edited
-// see https://nextjs.org/docs/basic-features/typescript for more information.
+// see https://nextjs.org/docs/pages/api-reference/config/typescript for more information.

playground/next-env.d.ts

@@ -10,21 +10,20 @@
     "start": "next start"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=20.9.0"
   },
   "dependencies": {
     "@babel/runtime": "^7.19.0",
     "@monaco-editor/react": "^4.4.5",
     "@resvg/resvg-wasm": "^2.3.1",
     "blob-stream": "^0.1.3",
-    "copy-to-clipboard": "^3.3.2",
-    "fflate": "^0.7.3",
-    "intl-segmenter-polyfill": "^0.4.4",
-    "js-base64": "^3.7.2",
-    "next": "^12.2.5",
+    "copy-to-clipboard": "^4.0.2",
+    "fflate": "^0.8.3",
+    "js-base64": "^3.9.3",
+    "next": "^16.3.1",
     "pdfkit": "^0.13.0",
-    "react": "^17.0.2",
-    "react-dom": "^17.0.2",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
     "react-hot-toast": "^2.3.0",
     "react-live": "^2.4.1",
     "react-resizable-panels": "^0.0.30",

playground/package.json

@@ -2,7 +2,7 @@ import type { NextRequest } from 'next/server'
 import { FontDetector, languageFontMap } from '../../utils/font'
 
 export const config = {
-  runtime: 'experimental-edge',
+  runtime: 'edge',
 }
 
 const detector = new FontDetector()

playground/pages/api/font.ts

@@ -12,19 +12,18 @@ import { Base64 } from 'js-base64'
 import PDFDocument from 'pdfkit/js/pdfkit.standalone'
 import SVGtoPDF from 'svg-to-pdfkit'
 import blobStream from 'blob-stream'
-import { createIntlSegmenterPolyfill } from 'intl-segmenter-polyfill'
 import { Panel, PanelGroup } from 'react-resizable-panels'
 
 import { loadEmoji, getIconCode, apis } from '../utils/twemoji'
 import Introduction from '../components/introduction'
 import PanelResizeHandle from '../components/panel-resize-handle'
 import { languageFontMap } from '../utils/font'
 
-import playgroundTabs, { Tabs } from '../cards/playground-data'
+import playgroundTabs, { Tabs as TTabs } from '../cards/playground-data'
 import previewTabs from '../cards/preview-tabs'
 
 const cardNames = Object.keys(playgroundTabs)
-const editedCards: Tabs = { ...playgroundTabs }
+const editedCards: TTabs = { ...playgroundTabs }
 
 async function init() {
   if (typeof window === 'undefined') return []
@@ -41,16 +40,7 @@ async function init() {
       fetch('/material-icons-base-400-normal.woff').then((res) =>
         res.arrayBuffer()
       ),
-      !globalThis.Intl || !globalThis.Intl.Segmenter
-        ? createIntlSegmenterPolyfill(
-            fetch(
-              new URL(
-                'intl-segmenter-polyfill/dist/break_iterator.wasm',
-                import.meta.url
-              )
-            )
-          )
-        : null,
+      null,
     ]))
 
   if (Segmenter) {
@@ -928,7 +918,7 @@ function ResetCode({ activeCard }: { activeCard: string }) {
           const decoded = JSON.parse(decompressedData)
           card = decoded.code
           overrideOptions = decoded.options
-          tab = decoded.tab || 'helloworld'
+          tab = decoded.tab || 'Vercel'
         } catch (e) {
           card = decompressedData
         }
@@ -956,7 +946,7 @@ function ResetCode({ activeCard }: { activeCard: string }) {
 }
 
 export default function Playground() {
-  const [activeCard, setActiveCard] = useState<string>('helloworld')
+  const [activeCard, setActiveCard] = useState<string>('Vercel')
   const [showIntroduction, setShowIntroduction] = useState(false)
   const [isMobileView, setIsMobileView] = useState(false)
 

playground/pages/index.tsx

@@ -10,10 +10,10 @@
     "incremental": true,
     "esModuleInterop": true,
     "module": "esnext",
-    "moduleResolution": "node",
+    "moduleResolution": "bundler",
     "resolveJsonModule": true,
     "isolatedModules": true,
-    "jsx": "preserve"
+    "jsx": "react-jsx"
   },
   "include": ["decs.d.ts", "**/*.ts", "**/*.tsx"],
   "exclude": ["node_modules"]