### Install systemfonts Package

Source: https://github.com/r-lib/systemfonts/blob/main/README.md

Install the development version of the systemfonts package using the 'pak' package manager.

```r
# install.packages('pak')
pak::pak('r-lib/systemfonts')
```

--------------------------------

### List All Installed System Fonts with system_fonts()

Source: https://context7.com/r-lib/systemfonts/llms.txt

Retrieves a data frame of all installed font faces, including their paths and properties. Results are cached for performance. Use this to get an overview of available fonts.

```R
library(systemfonts)

# Get all fonts as a data frame
fonts <- system_fonts()
# # A tibble: 1,221 × 10
# path  index name  family style weight width italic monospace variable

# Filter to monospace fonts only
fonts[fonts$monospace, c("family", "style", "path")]

# Filter to variable fonts
fonts[fonts$variable, c("family", "path")]

# Find all bold italic sans-serif faces
fonts[fonts$italic & fonts$weight == "bold", c("family", "style")]
```

--------------------------------

### system_fonts() — List all installed system fonts

Source: https://context7.com/r-lib/systemfonts/llms.txt

Returns a data frame with one row per installed font face, including path, family name, style, weight, width, italic/monospace/variable flags, and file index. Results are cached internally for performance.

```APIDOC
## system_fonts()

### Description
Returns a data frame with one row per installed font face, including path, family name, style, weight, width, italic/monospace/variable flags, and file index. Results are cached internally for performance.

### Usage
```R
library(systemfonts)
fonts <- system_fonts()
```

### Examples
```R
# Get all fonts as a data frame
fonts <- system_fonts()

# Filter to monospace fonts only
fonts[fonts$monospace, c("family", "style", "path")]

# Filter to variable fonts
fonts[fonts$variable, c("family", "path")]

# Find all bold italic sans-serif faces
fonts[fonts$italic & fonts$weight == "bold", c("family", "style")]
```
```

--------------------------------

### Package Size Note

Source: https://github.com/r-lib/systemfonts/blob/main/revdep/problems.md

This note reports the installed size of the package and highlights sub-directories that exceed 1MB. This is a standard check for package distribution.

```R
installed size is  8.1Mb
sub-directories of 1Mb or more:
  R      1.5Mb
  libs   5.2Mb
```

--------------------------------

### Add Custom Fonts to Lookup

Source: https://github.com/r-lib/systemfonts/blob/main/README.md

Add custom font files to the systemfonts lookup database without installing them system-wide. Fonts in './fonts' and '~/fonts' are automatically added on startup.

```r
add_fonts(c('path/to/my/font1.ttf', 'path/to/my/font2.otf'))
```

--------------------------------

### Get Glyph Metrics (Recommended C API v2)

Source: https://context7.com/r-lib/systemfonts/llms.txt

Retrieves glyph metrics using the recommended v2 C API and FontSettings2 struct. Requires codepoint, FontSettings2, size, and resolution.

```c
// Get glyph metrics via FontSettings2
double a2, d2, w2;
systemfonts::ver2::glyph_metrics(0x0041, fs2, 12.0, 72.0, &a2, &d2, &w2);
```

--------------------------------

### Get Glyph Metrics (Legacy C API)

Source: https://context7.com/r-lib/systemfonts/llms.txt

Retrieves glyph metrics (ascent, descent, width) for a given Unicode codepoint using the legacy C API. Requires font file, index, size, and resolution.

```c
// Get glyph metrics (ascent, descent, width) for a Unicode codepoint
double ascent, descent, width;
int ok = glyph_metrics(0x0041 /*'A'*/, fs.file, fs.index,
                       12.0 /*size*/, 72.0 /*res*/,
                       &ascent, &descent, &width);
```

--------------------------------

### Side-load Local Font Files with add_fonts()

Source: https://context7.com/r-lib/systemfonts/llms.txt

Add font files directly from disk or URLs to the lookup database without system-wide installation using add_fonts(). scan_local_fonts() automatically picks up fonts from './fonts' and '~/fonts'. Use clear_local_fonts() to remove side-loaded fonts.

```r
library(systemfonts)

# Add a single font file (TTF, OTF, TTC, WOFF, WOFF2 all supported)
add_fonts("/path/to/NotoSans-Regular.ttf")

# Add multiple files
add_fonts(c(
  "/path/to/CustomFont-Regular.ttf",
  "/path/to/CustomFont-Bold.ttf"
))

# Download and add a font directly from a URL
add_fonts("https://example.com/fonts/CustomFont.ttf")

# Check the font is now visible
sys <- system_fonts()
sys[sys$family == "Noto Sans", c("family", "style", "path")]

# Fonts in ./fonts/ are loaded automatically — good for reproducible scripts:
# project/
#   myscript.R
#   fonts/
#     BrandFont-Regular.ttf
#     BrandFont-Bold.ttf

# Remove all side-loaded fonts (run scan_local_fonts() to reload ./fonts)
clear_local_fonts()
```

--------------------------------

### OlinkAnalyze R Package Check Log (Devel)

Source: https://github.com/r-lib/systemfonts/blob/main/revdep/failures.md

This log shows the output of a reverse dependency check for the OlinkAnalyze package in its development version. It indicates a '1 NOTE' status, suggesting potential issues that do not prevent installation but may warrant attention.

```log
* using log directory ‘/tmp/workdir/OlinkAnalyze/new/OlinkAnalyze.Rcheck’
* using R version 4.4.0 (2024-04-24)
* using platform: x86_64-pc-linux-gnu
* R was compiled by
    gcc (Ubuntu 13.3.0-6ubuntu2~24.04) 13.3.0
    GNU Fortran (Ubuntu 13.3.0-6ubuntu2~24.04) 13.3.0
* running under: Ubuntu 24.04.2 LTS
* using session charset: UTF-8
* using option ‘--no-manual’
* checking for file ‘OlinkAnalyze/DESCRIPTION’ ... OK
... 
* checking files in ‘vignettes’ ... OK
* checking examples ... OK
* checking for unstated dependencies in ‘tests’ ... OK
* checking tests ... OK
  Running ‘testthat.R’
* checking for unstated dependencies in vignettes ... OK
* checking package vignettes ... OK
* checking re-building of vignette outputs ... OK
* DONE
Status: 1 NOTE




```

--------------------------------

### Get Glyph Outline as SVG Path (C++ Recommended API v2)

Source: https://context7.com/r-lib/systemfonts/llms.txt

Obtains the outline of a glyph as an SVG path string using the recommended v2 C++ API. Requires glyph index, transform matrix, FontSettings2, and size.

```c++
// Get glyph outline as SVG <path> string (C++ only)
bool no_outline = false;
double transform[6] = {1,0,0,1,0,0};
std::string svg_path = systemfonts::ver2::get_glyph_path(
    glyph_index, transform, fs2, 48.0, &no_outline
);
```

--------------------------------

### add_fonts(), scan_local_fonts(), clear_local_fonts()

Source: https://context7.com/r-lib/systemfonts/llms.txt

Side-load local font files directly from disk or URLs into the lookup database without system-wide installation. scan_local_fonts() automatically picks up fonts from './fonts' and '~/fonts'.

```APIDOC
## `add_fonts()` / `scan_local_fonts()` / `clear_local_fonts()` — Side-load local font files

Adds font files directly from disk (or URLs) to the lookup database without system-wide installation. `scan_local_fonts()` is called automatically on package load and picks up fonts from `./fonts` and `~/fonts`.

```r
library(systemfonts)

# Add a single font file (TTF, OTF, TTC, WOFF, WOFF2 all supported)
add_fonts("/path/to/NotoSans-Regular.ttf")

# Add multiple files
add_fonts(c(
  "/path/to/CustomFont-Regular.ttf",
  "/path/to/CustomFont-Bold.ttf"
))

# Download and add a font directly from a URL
add_fonts("https://example.com/fonts/CustomFont.ttf")

# Check the font is now visible
sys <- system_fonts()
sys[sys$family == "Noto Sans", c("family", "style", "path")]

# Fonts in ./fonts/ are loaded automatically — good for reproducible scripts:
# project/
#   myscript.R
#   fonts/
#     BrandFont-Regular.ttf
#     BrandFont-Bold.ttf

# Remove all side-loaded fonts (run scan_local_fonts() to reload ./fonts)
clear_local_fonts()
```
```

--------------------------------

### Deprecated Function Warning in systemfonts

Source: https://github.com/r-lib/systemfonts/blob/main/revdep/problems.md

This warning indicates that the `match_font()` function from the `systemfonts` package has been deprecated. It suggests checking the installation details for more information.

```R
Found the following significant warnings:
  Warning: `match_font()` was deprecated in systemfonts 1.1.0.
See ‘/tmp/workdir/ggiraph/new/ggiraph.Rcheck/00install.out’ for details.
```

--------------------------------

### Get Glyph Raster (Recommended C API v2)

Source: https://context7.com/r-lib/systemfonts/llms.txt

Retrieves a rasterized representation (nativeRaster SEXP) of a glyph using the recommended v2 C API. Requires glyph index, FontSettings2, size, resolution, and color.

```c
// Get a raster (nativeRaster SEXP) for a glyph
SEXP raster = systemfonts::ver2::get_glyph_raster(
    glyph_index, fs2, 48.0, 300.0, -16777216 /*black*/
);
```

--------------------------------

### TransProR R Package Check Log (Devel)

Source: https://github.com/r-lib/systemfonts/blob/main/revdep/failures.md

This log captures the reverse dependency check for the TransProR package in its development version. It reports a '1 ERROR' due to a missing required package 'ggtree', which prevents successful installation or checking.

```log
* using log directory ‘/tmp/workdir/TransProR/new/TransProR.Rcheck’
* using R version 4.4.0 (2024-04-24)
* using platform: x86_64-pc-linux-gnu
* R was compiled by
    gcc (Ubuntu 13.3.0-6ubuntu2~24.04) 13.3.0
    GNU Fortran (Ubuntu 13.3.0-6ubuntu2~24.04) 13.3.0
* running under: Ubuntu 24.04.2 LTS
* using session charset: UTF-8
* using option ‘--no-manual’
* checking for file ‘TransProR/DESCRIPTION’ ... OK
... 
* checking package namespace information ... OK
* checking package dependencies ... ERROR
Package required but not available: ‘ggtree’

Package suggested but not available for checking: ‘ggtreeExtra’

See section ‘The DESCRIPTION file’ in the ‘Writing R Extensions’
manual.
* DONE
Status: 1 ERROR




```

--------------------------------

### Get Fallback Font (Legacy C API)

Source: https://context7.com/r-lib/systemfonts/llms.txt

Obtains a fallback font using the legacy C API, useful for characters like emoji that might not be present in the primary font. Returns a FontSettings struct.

```c
// Get a fallback font for a string (e.g. emoji)
FontSettings fb = get_fallback("\U0001f604", fs.file, fs.index);
```

--------------------------------

### reset_font_cache() — Invalidate the font list cache

Source: https://context7.com/r-lib/systemfonts/llms.txt

After installing new fonts on the system, the cached font list must be cleared so that subsequent calls to system_fonts() or match_fonts() reflect the new installation.

```APIDOC
## reset_font_cache()

### Description
Invalidates the font list cache. After installing new fonts on the system, the cached font list must be cleared so that subsequent calls to `system_fonts()` or `match_fonts()` reflect the new installation.

### Usage
```R
library(systemfonts)
reset_font_cache()
```

### Examples
```R
library(systemfonts)

before <- system_fonts()

# ... install a new font on the OS ...

# Without reset, still sees old list:
system_fonts()  # same as before

# Clear the cache:
reset_font_cache()

# Now picks up newly installed fonts:
after <- system_fonts()
nrow(after) > nrow(before)  # TRUE if a new font was installed
```
```

--------------------------------

### Download Web Fonts with get_from_google_fonts() / get_from_font_squirrel()

Source: https://context7.com/r-lib/systemfonts/llms.txt

Downloads a font family from Google Fonts or Font Squirrel to a local directory and adds it to the systemfonts lookup database.

```r
library(systemfonts)

# Download from Google Fonts (TTF by default, WOFF2 optional)
get_from_google_fonts("Merriweather", dir = "~/fonts", woff2 = FALSE)

# Download from Font Squirrel (returns a zip, extracts automatically)
get_from_font_squirrel("Chunk Five", dir = "~/fonts")

# Verify it is now available
system_fonts()[system_fonts()$family == "Merriweather", c("family", "style")]
```

--------------------------------

### register_variant()

Source: https://context7.com/r-lib/systemfonts/llms.txt

A convenience wrapper to register a weight, width, or feature variant of an existing system font without specifying file paths. It derives face files from an installed family.

```APIDOC
## `register_variant()` — Register a weight/width/feature variant of a system font

A convenience wrapper around `register_font()` that derives its face files from an existing installed family. Useful for exposing condensed widths, specific weights, or OpenType features without manually specifying file paths.

```r
library(systemfonts)

# Create a "semibold condensed" variant of a system font
register_variant(
  name   = "RobotoSemiCond",
  family = "Roboto",
  weight = c("semibold", "bold"),  # plain and bold weights
  width  = "condensed"
)
match_fonts("RobotoSemiCond")

# Attach discretionary ligatures to an existing font
register_variant(
  "GaramondLig",
  "EB Garamond",
  features = font_feature(ligatures = c("standard", "discretionary"))
)

# Clean up
clear_registry()
```
```

--------------------------------

### match_fonts() — Locate font files by family, weight, width, and italic

Source: https://context7.com/r-lib/systemfonts/llms.txt

Finds the best-matching font file(s) for the given family names and style parameters. Returns a list with `path`, `index`, and `features` fields. Matching priority: font registry → local fonts → system fonts. Always returns a result, falling back to "sans" if nothing matches.

```APIDOC
## match_fonts()

### Description
Locates font files by family, weight, width, and italic. Finds the best-matching font file(s) for the given family names and style parameters. Returns a list with `path`, `index`, and `features` fields. Matching priority: font registry → local fonts → system fonts. Always returns a result, falling back to "sans" if nothing matches.

### Usage
```R
library(systemfonts)
match_fonts(family, ..., italic = FALSE, weight = "normal", width = "normal", features = NULL, path = NULL, index = NULL)
```

### Parameters
* **family**: Font family name(s).
* **italic**: Logical, whether to match italic style.
* **weight**: Font weight (e.g., "normal", "bold", "semibold", or numeric).
* **width**: Font width (e.g., "normal", "condensed").
* **features**: OpenType features.
* **path**: Path to a font file.
* **index**: Index of the font face within the file.

### Examples
```R
# Match a single font
match_fonts("Arial")

# Match italic sans-serif system default
match_fonts("sans", italic = TRUE)

# Match multiple families at once (vectorised)
match_fonts(c("Helvetica", "Times New Roman", "Courier New"),
            weight = "bold", italic = FALSE)

# Match a condensed semibold variant
match_fonts("Arial", weight = "semibold", width = "condensed")

# Match using numeric weight (400 = normal, 700 = bold)
match_fonts("Arial", weight = 700)
```
```

--------------------------------

### Match Font Files by Properties with match_fonts()

Source: https://context7.com/r-lib/systemfonts/llms.txt

Locates the best-matching font file(s) based on family names, weight, width, and italic style. It prioritizes the font registry, then local fonts, and finally system fonts. Always returns a result, defaulting to 'sans' if no match is found.

```R
library(systemfonts)

# Match a single font
match_fonts("Arial")
# $path
# [1] "/usr/share/fonts/truetype/msttcorefonts/Arial.ttf"
# $index
# [1] 0

# Match italic sans-serif system default
match_fonts("sans", italic = TRUE)

# Match multiple families at once (vectorised)
match_fonts(c("Helvetica", "Times New Roman", "Courier New"),
            weight = "bold", italic = FALSE)

# Match a condensed semibold variant
match_fonts("Arial", weight = "semibold", width = "condensed")

# Match using numeric weight (400 = normal, 700 = bold)
match_fonts("Arial", weight = 700)
```

--------------------------------

### Search Online Font Repositories with search_web_fonts()

Source: https://context7.com/r-lib/systemfonts/llms.txt

Performs fuzzy name matching against Google Fonts, Bunny Fonts, and Font Squirrel catalogues. Requires an internet connection.

```r
library(systemfonts)

# Requires an internet connection
search_web_fonts("Spectral")
#          family               repository
# 1      Spectral Google Fonts/Bunny Fonts
# 2   Spectral SC Google Fonts/Bunny Fonts
# ...

# Find condensed sans fonts
search_web_fonts("Condensed Sans", n_max = 5)

# Then download the one you want
get_from_google_fonts("Spectral", dir = "~/fonts")
```

--------------------------------

### Invalidate Font Cache with reset_font_cache()

Source: https://context7.com/r-lib/systemfonts/llms.txt

Clears the internal font list cache. This is necessary after installing new fonts on the operating system to ensure subsequent calls to system_fonts() or match_fonts() recognize the updated list.

```R
library(systemfonts)

before <- system_fonts()

# ... install a new font on the OS ...

# Without reset, still sees old list:
system_fonts()  # same as before

# Clear the cache:
reset_font_cache()

# Now picks up newly installed fonts:
after <- system_fonts()
nrow(after) > nrow(before)  # TRUE if a new font was installed
```

--------------------------------

### as_font_weight() / as_font_width()

Source: https://context7.com/r-lib/systemfonts/llms.txt

Utility functions to convert human-readable font weight and width names into their corresponding numeric values used internally by systemfonts.

```APIDOC
## `as_font_weight()` / `as_font_width()` — Convert weight/width names to numeric values

Utility functions that translate human-readable weight/width names to the numeric values used internally by systemfonts (ISO-standard weight scale and width scale).

```r
library(systemfonts)

# Weight names → numeric (0, 100–900)
as_font_weight(c("thin", "light", "normal", "medium", "semibold", "bold", "heavy"))
# [1]   0 200 300 400 500 600 700 800
```
```

--------------------------------

### string_widths_dev() / string_metrics_dev()

Source: https://context7.com/r-lib/systemfonts/llms.txt

Measures string dimensions (width, ascent, descent) by querying the active R graphics device, providing a faster method than constructing grid grobs.

```APIDOC
## `string_widths_dev()` / `string_metrics_dev()` — Measure strings via the active graphics device

Queries the currently open R graphics device for string widths (and optionally ascent/descent) using the device's own font rendering. Faster than constructing grid grobs.

```r
library(systemfonts)

# Open a device first (e.g. ragg or the default pdf/screen device)
# pdf(tempfile())

# Widths in cm (default)
string_widths_dev(c("Hello", "World"), family = "sans", size = 12, cex = 1)

# Widths in inches
string_widths_dev("A test string", unit = "inches")

# Full metrics: width + ascent + descent
string_metrics_dev(
  c("Typography", "gjpqy descenders"),
  family = "serif", size = 14, unit = "cm"
)
# data.frame: width, ascent, descent

# dev.off()
```
```

--------------------------------

### Measure Strings via Graphics Device with string_widths_dev()

Source: https://context7.com/r-lib/systemfonts/llms.txt

string_widths_dev() and string_metrics_dev() query the active R graphics device for string metrics, offering faster performance than grid grobs. Specify units like 'cm' or 'inches'.

```r
library(systemfonts)

# Open a device first (e.g. ragg or the default pdf/screen device)
# pdf(tempfile())

# Widths in cm (default)
string_widths_dev(c("Hello", "World"), family = "sans", size = 12, cex = 1)
```

```r
# Widths in inches
string_widths_dev("A test string", unit = "inches")
```

```r
# Full metrics: width + ascent + descent
string_metrics_dev(
  c("Typography", "gjpqy descenders"),
  family = "serif", size = 14, unit = "cm"
)
# data.frame: width, ascent, descent

# dev.off()
```

--------------------------------

### Generate Web Font Import for HTML/SVG with fonts_as_import()

Source: https://context7.com/r-lib/systemfonts/llms.txt

Produces CSS @import statements, <link> tags, or stylesheet URLs for embedding fonts in web output. Supports various repositories and local embedding.

```r
library(systemfonts)

# Get a bare URL for a Google Fonts stylesheet
fonts_as_import("Fira Code", type = "url")
# [1] "https://fonts.bunny.net/css2?family=Fira+Code&display=swap"

# Get a CSS @import statement
fonts_as_import("Roboto", weight = c("normal", "bold"), type = "import")
# [1] "@import url('https://fonts.bunny.net/css2?...');"

# Get an HTML <link> tag
fonts_as_import("Noto Serif", italic = TRUE, type = "link")
# [1] "<link rel=\"stylesheet\" href=\"...\"/>"

# Multiple families at once
fonts_as_import(c("Lato", "Merriweather"), type = "link")

# Embed locally available font as data-URI (no external dependency)
fonts_as_import("MyLocalFont", repositories = NULL, may_embed = TRUE, type = "import")
```

--------------------------------

### List All Available System Fonts

Source: https://github.com/r-lib/systemfonts/blob/main/README.md

Retrieve a data frame containing information about all fonts available on the system. This includes path, index, name, family, style, weight, width, and italic properties.

```r
system_fonts()
#> # A tibble: 1,221 × 10
#>    path          index name  family style weight width italic monospace variable
#>    <chr>         <int> <chr> <chr>  <chr> <ord>  <ord> <lgl>  <lgl>     <lgl>   
#>  1 /Users/thoma…     0 Recu… Recur… Sans… medium norm… FALSE  FALSE     TRUE    
#>  2 /Users/thoma…     0 Syne… Syne   Regu… normal norm… FALSE  FALSE     FALSE   
#>  3 /Users/thoma…     0 Inpu… Input… Extr… light  cond… TRUE   TRUE      FALSE   
#>  4 /System/Libr…     1 Telu… Telug… Bold  bold   norm… FALSE  FALSE     FALSE   
#>  5 /Users/thoma…     0 Inpu… Input… Thin  light  semi… FALSE  FALSE     FALSE   
#>  6 /System/Libr…     0 Micr… Micro… Regu… normal norm… FALSE  FALSE     FALSE   
#>  7 /System/Libr…     0 Fira… Fira … Bold  bold   norm… FALSE  TRUE      FALSE   
#>  8 /System/Libr…     0 Sukh… Sukhu… Thin  ultra… semi… FALSE  FALSE     FALSE   
#>  9 /System/Libr…     0 Sathu Sathu  Regu… normal norm… FALSE  FALSE     FALSE   
#> 10 /Users/thoma…     0 IBMP… IBM P… Text… normal norm… TRUE   FALSE     FALSE   
#> # ℹ 1,211 more rows
```

--------------------------------

### Locate Font File (Legacy C API)

Source: https://context7.com/r-lib/systemfonts/llms.txt

Use the legacy C API to locate a font file by specifying family, italic, and bold attributes. The path is written to the provided buffer.

```c
#include <systemfonts.h>

// --- Legacy API (v1) ---

// Locate a font file by family/italic/bold
char path[PATH_MAX + 1];
int index = locate_font("Helvetica", 0 /*italic*/, 0 /*bold*/, path, PATH_MAX);
```

--------------------------------

### Convert Font Weight/Width Names to Numeric Values

Source: https://context7.com/r-lib/systemfonts/llms.txt

as_font_weight() and as_font_width() translate human-readable font style names into the numeric values used internally by systemfonts, following ISO standards.

```r
library(systemfonts)

# Weight names → numeric (0, 100–900)
as_font_weight(c("thin", "light", "normal", "medium", "semibold", "bold", "heavy"))
# [1]   0 200 300 400 500 600 700 800
```

--------------------------------

### `search_web_fonts()` — Search online font repositories by name

Source: https://context7.com/r-lib/systemfonts/llms.txt

Performs fuzzy name matching against Google Fonts / Bunny Fonts and Font Squirrel catalogues, returning the closest matches and their source repository.

```APIDOC
## `search_web_fonts()` — Search online font repositories by name

### Description
Performs fuzzy name matching against Google Fonts / Bunny Fonts and Font Squirrel catalogues, returning the closest matches and their source repository.

### Usage
```r
search_web_fonts(name, n_max = 10, repositories = c("Google Fonts/Bunny Fonts", "Font Squirrel"))
```

### Arguments
* `name` (character) - The name or part of the name of the font to search for.
* `n_max` (integer) - The maximum number of results to return. Defaults to 10.
* `repositories` (character vector) - The font repositories to search. Defaults to `c("Google Fonts/Bunny Fonts", "Font Squirrel")`.

### Examples
```r
library(systemfonts)

# Requires an internet connection
search_web_fonts("Spectral")
#          family               repository
# 1      Spectral Google Fonts/Bunny Fonts
# 2   Spectral SC Google Fonts/Bunny Fonts
# ...

# Find condensed sans fonts
search_web_fonts("Condensed Sans", n_max = 5)

# Then download the one you want
get_from_google_fonts("Spectral", dir = "~/fonts")
```
```

--------------------------------

### glyph_info() — Query per-glyph metrics

Source: https://context7.com/r-lib/systemfonts/llms.txt

Returns a data frame with width, height, x/y bearing, x/y advance, and bounding box for each glyph. Strings are automatically split into individual glyphs.

```APIDOC
## glyph_info()

### Description
Queries per-glyph metrics. Returns a data frame with width, height, x/y bearing, x/y advance, and bounding box for each glyph. Strings are automatically split into individual glyphs.

### Usage
```R
library(systemfonts)
glyph_info(string, family, ..., italic = FALSE, weight = "normal", width = "normal", size = 12, res = 72, path = NULL, index = NULL)
```

### Parameters
* **string**: The string to get glyph information for.
* **family**: Font family name(s).
* **italic**: Logical, whether to match italic style.
* **weight**: Font weight (e.g., "normal", "bold").
* **width**: Font width (e.g., "normal").
* **size**: Font size in points.
* **res**: Resolution in dots per inch (dpi).
* **path**: Path to a font file.
* **index**: Index of the font face within the file.

### Examples
```R
# Metrics for individual characters
glyph_info("Ag", family = "serif", size = 48, res = 96)

# Use a direct file path to skip lookup
font <- match_fonts("mono")
glyph_info("0123456789", path = font$path, index = font$index, size = 12, res = 72)
```
```

--------------------------------

### Shape String (Legacy C API)

Source: https://context7.com/r-lib/systemfonts/llms.txt

Calculates per-glyph x/y positions for a given string using the legacy C API. Requires font file, index, size, and resolution. Output arrays store positions.

```c
// Calculate per-glyph x/y positions for a string
double x[256], y[256];
int ok2 = string_shape("Hello", fs.file, fs.index, 12.0, 72.0, x, y, 256);
```

--------------------------------

### Query Per-Glyph Metrics with glyph_info()

Source: https://context7.com/r-lib/systemfonts/llms.txt

Returns metrics for individual glyphs within a font face, such as width, height, bearing, and advance. Strings are automatically split into glyphs. Can use direct file paths to bypass font lookup.

```R
library(systemfonts)

# Metrics for individual characters
glyph_info("Ag", family = "serif", size = 48, res = 96)
# glyph  index width height x_bearing y_bearing x_advance y_advance bbox
# A      ...   ...   ...    ...       ...       ...       0         list(...)
# g      ...   ...   ...    ...       ...       ...       0         list(...)

# Use a direct file path to skip lookup
font <- match_fonts("mono")
glyph_info("0123456789", path = font$path, index = font$index, size = 12, res = 72)
```

--------------------------------

### Locate Font with Features (Legacy C API)

Source: https://context7.com/r-lib/systemfonts/llms.txt

Locates a font using the legacy C API, considering OpenType features. Returns a FontSettings struct containing file path, index, and features.

```c
// Locate with registered OpenType features
FontSettings fs = locate_font_with_features("MyFont", 0, 1);
// fs.file, fs.index, fs.features, fs.n_features
```

--------------------------------

### Calculate String Widths with string_width()

Source: https://context7.com/r-lib/systemfonts/llms.txt

Use string_width() for fast pixel width measurements of pre-split lines. It's a lightweight alternative to shape_string() for measurement loops. Optionally exclude side-bearings for tighter layouts.

```r
library(systemfonts)

widths <- string_width(
  c("Short", "A much longer string", "Another one"),
  family = "serif", size = 14, res = 96
)
# Convert to inches: widths / 96
widths / 96
```

```r
# Exclude side-bearings for tight layout
string_width("Hello", family = "mono", size = 12, include_bearing = FALSE)
```

--------------------------------

### font_info() — Query detailed metrics for a font face

Source: https://context7.com/r-lib/systemfonts/llms.txt

Returns a data frame with comprehensive font-level metadata including ascender/descender heights, line height, underline position, bounding box, glyph count, kerning support, and more. Vectorised over all arguments.

```APIDOC
## font_info()

### Description
Queries detailed metrics for a font face. Returns a data frame with comprehensive font-level metadata including ascender/descender heights, line height, underline position, bounding box, glyph count, kerning support, and more. Vectorised over all arguments.

### Usage
```R
library(systemfonts)
font_info(family, ..., italic = FALSE, weight = "normal", width = "normal", size = 12, res = 72, path = NULL, index = NULL)
```

### Parameters
* **family**: Font family name(s).
* **italic**: Logical, whether to match italic style.
* **weight**: Font weight (e.g., "normal", "bold").
* **width**: Font width (e.g., "normal").
* **size**: Font size in points.
* **res**: Resolution in dots per inch (dpi).
* **path**: Path to a font file.
* **index**: Index of the font face within the file.

### Examples
```R
# Info for the default serif font at 12pt / 72 ppi
font_info("serif")

# Info for a specific font at display size
font_info("Georgia", italic = FALSE, weight = "bold", size = 24, res = 96)

# Skip lookup when the path is already known
sans <- match_fonts("sans")
fi <- font_info(path = sans$path, index = sans$index, size = 14, res = 96)
fi[, c("family", "style", "max_ascend", "max_descent", "lineheight", "n_glyphs")]

# Query multiple fonts at once
font_info(c("sans", "serif", "mono"), size = c(10, 12, 14))
```
```

--------------------------------

### Query Font Metrics with font_info()

Source: https://context7.com/r-lib/systemfonts/llms.txt

Retrieves detailed font-level metadata, including ascender/descender heights, line height, and glyph count. This function is vectorised over its arguments and can query specific font files directly.

```R
library(systemfonts)

# Info for the default serif font at 12pt / 72 ppi
font_info("serif")

# Info for a specific font at display size
font_info("Georgia", italic = FALSE, weight = "bold", size = 24, res = 96)

# Skip lookup when the path is already known
sans <- match_fonts("sans")
fi <- font_info(path = sans$path, index = sans$index, size = 14, res = 96)
fi[, c("family", "style", "max_ascend", "max_descent", "lineheight", "n_glyphs")]

# Query multiple fonts at once
font_info(c("sans", "serif", "mono"), size = c(10, 12, 14))
```

--------------------------------

### Declare Font Dependency with require_font()

Source: https://context7.com/r-lib/systemfonts/llms.txt

Ensures a font family is available by checking the system and searching online repositories. Can download if needed or use a fallback.

```r
library(systemfonts)

# Ensure "Fira Code" is available; download from Google Fonts if not
require_font("Fira Code")

# Use a fallback if unavailable and don't throw an error
require_font("Spectral SC", fallback = "Georgia", error = FALSE, verbose = TRUE)
# > Trying Google Fonts... Found! Downloading font to /tmp/...

# Download to a project-local fonts/ directory for portability
require_font("Lato", dir = "./fonts")

# Standard aliases always succeed immediately
require_font("sans")   # TRUE
require_font("mono")   # TRUE
```

--------------------------------

### Locate Font (Recommended C API v2)

Source: https://context7.com/r-lib/systemfonts/llms.txt

Uses the recommended v2 C API to locate a font, supporting variable fonts. Specify family, italic, weight, width, and optional variable axes.

```c
// --- Recommended API (v2, supports variable fonts) ---

// Locate font with weight/width/variation axes
FontSettings2 fs2 = systemfonts::ver2::locate_font(
    "Recursive",
    0.0,    // italic (0–1)
    700.0,  // weight (100–900)
    5.0,    // width (1–9)
    NULL, NULL, 0  // variable axes (tags, coords, count)
);
```

--------------------------------

### glyph_raster() / glyph_raster_grob()

Source: https://context7.com/r-lib/systemfonts/llms.txt

Renders glyphs into raster images suitable for base graphics or grid plotting, with options for size, resolution, and color.

```APIDOC
## `glyph_raster()` / `glyph_raster_grob()` — Render glyphs to raster images

Rasterizes a glyph to a `nativeRaster` object suitable for use with `graphics::rasterImage()` or `grid::grid.raster()`. `glyph_raster_grob()` wraps the result as a correctly-positioned `rasterGrob`.

```r
library(systemfonts)
library(grid)

font <- font_info()
gi   <- glyph_info("R", path = font$path, index = font$index)

# Render at 150pt, 300 ppi, in blue
rasters <- glyph_raster(gi$index, font$path, font$index,
                        size = 150, res = 300, col = "steelblue")

# Plot using base graphics
plot.new()
plot.window(c(0, 150), c(0, 150), asp = 1)
rasterImage(rasters[[1]], 0, 0,
            attr(rasters[[1]], "size")[2],
            attr(rasters[[1]], "size")[1])

# Or use grid with automatic offset handling
grob <- glyph_raster_grob(rasters[[1]], x = 75, y = 75)
grid.newpage()
grid.points(75, 75, default.units = "bigpts", pch = 19, size = unit(3, "pt"))
grid.draw(grob)
```
```

--------------------------------

### string_width()

Source: https://context7.com/r-lib/systemfonts/llms.txt

Calculates the width of strings in pixels for pre-split lines, offering a fast alternative to shape_string() for measurement loops.

```APIDOC
## `string_width()` — Calculate string width in pixels

A lightweight alternative to `shape_string()` that returns only pixel widths for pre-split lines (no newline handling). Useful for fast measurement loops.

```r
library(systemfonts)

widths <- string_width(
  c("Short", "A much longer string", "Another one"),
  family = "serif", size = 14, res = 96
)
# Convert to inches: widths / 96
widths / 96

# Exclude side-bearings for tight layout
string_width("Hello", family = "mono", size = 12, include_bearing = FALSE)
```
```

--------------------------------

### `get_from_google_fonts()` / `get_from_font_squirrel()` — Download web fonts

Source: https://context7.com/r-lib/systemfonts/llms.txt

Downloads a font family from Google Fonts or Font Squirrel to a local directory and adds the files to the systemfonts lookup database automatically.

```APIDOC
## `get_from_google_fonts()` / `get_from_font_squirrel()` — Download web fonts

### Description
Downloads a font family from Google Fonts or Font Squirrel to a local directory and adds the files to the systemfonts lookup database automatically.

### Usage
```r
get_from_google_fonts(family, dir = NULL, woff2 = FALSE)
get_from_font_squirrel(family, dir = NULL)
```

### Arguments
* `family` (character) - The name of the font family to download.
* `dir` (character, optional) - The directory to download the font files to. Defaults to `NULL`.
* `woff2` (logical) - If `TRUE`, attempts to download WOFF2 format from Google Fonts. Defaults to `FALSE`.

### Examples
```r
library(systemfonts)

# Download from Google Fonts (TTF by default, WOFF2 optional)
get_from_google_fonts("Merriweather", dir = "~/fonts", woff2 = FALSE)

# Download from Font Squirrel (returns a zip, extracts automatically)
get_from_font_squirrel("Chunk Five", dir = "~/fonts")

# Verify it is now available
system_fonts()[system_fonts()$family == "Merriweather", c("family", "style")]
```
```

--------------------------------

### Systemfonts C API Header

Source: https://github.com/r-lib/systemfonts/blob/main/README.md

Include the systemfonts header file in C/C++ code to access the package's C API for font locating functionalities.

```c
#include <systemfonts.h>
```

--------------------------------

### Register Custom Font Families with register_font()

Source: https://context7.com/r-lib/systemfonts/llms.txt

Register local font files under a new family name to ensure they are found first during font matching. This function can also override built-in aliases like 'sans' or 'serif'. Use registry_fonts() to list registered fonts and clear_registry() to remove them.

```r
library(systemfonts)

# Register four local TTF files as a complete family
register_font(
  name      = "MyBrand",
  plain     = "/path/to/MyBrand-Regular.ttf",
  bold      = "/path/to/MyBrand-Bold.ttf",
  italic    = list("/path/to/MyBrand-Italic.ttf", 0L),
  bolditalic = "/path/to/MyBrand-BoldItalic.ttf"
)

# Confirm it was registered
registry_fonts()[, c("family", "style", "path")]

# Now it resolves via match_fonts
match_fonts("MyBrand", italic = TRUE)

# Override the default "sans" mapping
register_font("sans", plain = "/path/to/FiraSans-Regular.ttf",
              bold = "/path/to/FiraSans-Bold.ttf")

# Remove all registrations
clear_registry()
```

--------------------------------

### Find Font File Path

Source: https://github.com/r-lib/systemfonts/blob/main/README.md

Locate the file path for a specific font family and style. Returns the path and index of the font within the file.

```r
library(systemfonts)

match_fonts('Avenir', italic = TRUE)
#>                               path index features variations
#> 1 /System/Library/Fonts/Avenir.ttc     1
```

--------------------------------

### Calculate Glyph Positions with shape_string()

Source: https://context7.com/r-lib/systemfonts/llms.txt

Performs low-level text shaping using FreeType, returning per-glyph offsets and string metrics. Supports word-wrapping, alignment, and mixed styles.

```r
library(systemfonts)

# Shape a simple multi-line string
result <- shape_string(
  "Hello, world!\nThis is line two.",
  family = "sans", size = 12, res = 96
)
result$shape    # glyph, index, x_offset, y_offset, x_mid per glyph
result$metrics  # width, height, left_bearing, right_bearing, …

# Word-wrap at 3 inches
shape_string("A long sentence that should wrap nicely onto the next line.",
             family = "Georgia", size = 12, res = 96,
             max_width = 3, align = "left")

# Mix font sizes within a single text run (same id)
shape_string(
  c("Normal text ", "BIG ", "normal again"),
  id   = c(1, 1, 1),
  size = c(12, 24, 12),
  family = "sans"
)
```

--------------------------------

### Register Font Variants with register_variant()

Source: https://context7.com/r-lib/systemfonts/llms.txt

Use register_variant() as a shortcut to register a specific weight, width, or feature variant of an existing system font without manually specifying file paths. This is useful for exposing condensed widths or specific OpenType features.

```r
library(systemfonts)

# Create a "semibold condensed" variant of a system font
register_variant(
  name   = "RobotoSemiCond",
  family = "Roboto",
  weight = c("semibold", "bold"),  # plain and bold weights
  width  = "condensed"
)
match_fonts("RobotoSemiCond")

# Attach discretionary ligatures to an existing font
register_variant(
  "GaramondLig",
  "EB Garamond",
  features = font_feature(ligatures = c("standard", "discretionary"))
)

# Clean up
clear_registry()
```

--------------------------------

### `require_font()` — Declare a font dependency in a script

Source: https://context7.com/r-lib/systemfonts/llms.txt

Ensures a font family is available by checking the system, searching online repositories (Google Fonts, Font Squirrel, Font Library), and downloading if necessary. It can throw an error or remap to a fallback family on failure.

```APIDOC
## `require_font()` — Declare a font dependency in a script

### Description
Ensures a font family is available: first checks the system, then searches online repositories (Google Fonts, Font Squirrel, Font Library) and downloads if needed. On failure, either throws an error or remaps to a fallback family.

### Usage
```r
require_font(family, dir = NULL, fallback = NULL, error = TRUE, verbose = FALSE)
```

### Arguments
* `family` (character) - The name of the font family to ensure is available.
* `dir` (character, optional) - Directory to download the font to if not found locally. Defaults to `NULL`.
* `fallback` (character, optional) - A fallback font family to use if the requested font is not found. Defaults to `NULL`.
* `error` (logical) - If `TRUE`, throws an error if the font cannot be found or downloaded. Defaults to `TRUE`.
* `verbose` (logical) - If `TRUE`, prints messages about the process. Defaults to `FALSE`.

### Examples
```r
library(systemfonts)

# Ensure "Fira Code" is available; download from Google Fonts if not
require_font("Fira Code")

# Use a fallback if unavailable and don't throw an error
require_font("Spectral SC", fallback = "Georgia", error = FALSE, verbose = TRUE)
# > Trying Google Fonts... Found! Downloading font to /tmp/...

# Download to a project-local fonts/ directory for portability
require_font("Lato", dir = "./fonts")

# Standard aliases always succeed immediately
require_font("sans")   # TRUE
require_font("mono")   # TRUE
```
```

--------------------------------

### Render Glyphs to Raster Images with glyph_raster()

Source: https://context7.com/r-lib/systemfonts/llms.txt

glyph_raster() and glyph_raster_grob() rasterize glyphs into nativeRaster objects for use with graphics::rasterImage() or grid::grid.raster(). Specify size, resolution, and color.

```r
library(systemfonts)
library(grid)

font <- font_info()
gi   <- glyph_info("R", path = font$path, index = font$index)

# Render at 150pt, 300 ppi, in blue
rasters <- glyph_raster(gi$index, font$path, font$index,
                        size = 150, res = 300, col = "steelblue")
```

```r
# Plot using base graphics
plot.new()
plot.window(c(0, 150), c(0, 150), asp = 1)
rasterImage(rasters[[1]], 0, 0,
            attr(rasters[[1]], "size")[2],
            attr(rasters[[1]], "size")[1])
```

```r
# Or use grid with automatic offset handling
grob <- glyph_raster_grob(rasters[[1]], x = 75, y = 75)
grid.newpage()
grid.points(75, 75, default.units = "bigpts", pch = 19, size = unit(3, "pt"))
grid.draw(grob)
```