fontisan 0.2.16 → 0.2.22

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 356bd0157b272462910d8822c6b77a6c768e12a45f4c56b2646d6bc683413239
-  data.tar.gz: 981dca0c122d3d3e2dab683c6a7962bc2bcc1be35fb5c0818857d6c55ff7bbbf
+  metadata.gz: 215de38977d0c94ac54def7b0aef0cc200e326172fd71b30912f6484ae122320
+  data.tar.gz: da89a4c238f617179e0da73377b83ae088d292c9e337cbc5c18832308864d970
 SHA512:
-  metadata.gz: '0852e6bc36559c125cab91cf4fe4d65256628df2e8c873bc52b4f291b2adc944126ed2a0e26d6daafbe7d568934a9788677cb47c8b70982097320addbc93365a'
-  data.tar.gz: dc9d8fdacf95fc0761bb62cfec0f56e7a7da1a78986915db76243461cf2434d3f8142a0547e153d6746e242aa4a3a5dc33b5b505e8ac073e467e9b9c269d97bf
+  metadata.gz: 5e18eef08d7be3ddd02e465497971cc020c7c5b03f40e4d92f02cf1c696d6553c9aa75b75cbea5ce4a5e43f0a7d683e57d7f1efada42b8d02b0b55da91837221
+  data.tar.gz: '02830dec034211c50cad0d5ebef7c771276808f815e5487e0a012bf08cd0b820eac0570befc0eb5a1b0bc518f5f906b5bfa3012de5d13ebe20a67cd42fb79a7c'

data/.rubocop_todo.yml

@@ -1,68 +1,27 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2026-05-02 04:07:39 UTC using RuboCop version 1.86.1.
+# on 2026-06-24 11:12:20 UTC using RuboCop version 1.86.1.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
 # versions of RuboCop, may require this file to be generated again.
 
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-Gemspec/RequireMFA:
-  Exclude:
-    - 'docs/node_modules/speakingurl/speakingurl-rails.gemspec'
-
 # Offense count: 2
 Gemspec/RequiredRubyVersion:
   Exclude:
     - 'docs/node_modules/speakingurl/speakingurl-rails.gemspec'
     - 'fontisan.gemspec'
 
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-Layout/EmptyLines:
-  Exclude:
-    - 'lib/fontisan/loading_modes.rb'
-
-# Offense count: 4
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: AllowForAlignment, AllowBeforeTrailingComments, ForceEqualSignAlignment.
-Layout/ExtraSpacing:
-  Exclude:
-    - 'docs/node_modules/speakingurl/lib/speakingurl-rails.rb'
-    - 'docs/node_modules/speakingurl/speakingurl-rails.gemspec'
-
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: AllowMultipleStyles, EnforcedHashRocketStyle, EnforcedColonStyle, EnforcedLastArgumentHashStyle.
-# SupportedHashRocketStyles: key, separator, table
-# SupportedColonStyles: key, separator, table
-# SupportedLastArgumentHashStyles: always_inspect, always_ignore, ignore_implicit, ignore_explicit
-Layout/HashAlignment:
-  Exclude:
-    - 'docs/node_modules/speakingurl/speakingurl-rails.gemspec'
-
-# Offense count: 1585
+# Offense count: 1606
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, AllowRBSInlineAnnotation, AllowCopDirectives, AllowedPatterns, SplitStrings.
 # URISchemes: http, https
 Layout/LineLength:
   Enabled: false
 
-# Offense count: 5
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: AllowForAlignment, EnforcedStyleForExponentOperator, EnforcedStyleForRationalLiterals.
-# SupportedStylesForExponentOperator: space, no_space
-# SupportedStylesForRationalLiterals: space, no_space
-Layout/SpaceAroundOperators:
-  Exclude:
-    - 'docs/node_modules/speakingurl/lib/speakingurl-rails.rb'
-    - 'docs/node_modules/speakingurl/speakingurl-rails.gemspec'
-
-# Offense count: 3
+# Offense count: 2
 Lint/CopDirectiveSyntax:
   Exclude:
-    - 'lib/fontisan/converters/woff_writer.rb'
     - 'lib/fontisan/woff2_font.rb'
     - 'spec/fontisan/variation/cache_spec.rb'
 
@@ -114,28 +73,18 @@ Lint/MissingSuper:
     - 'lib/fontisan/commands/validate_command.rb'
     - 'lib/fontisan/tables/cff2/table_builder.rb'
 
-# Offense count: 4
-# This cop supports safe autocorrection (--autocorrect).
-Lint/RedundantRequireStatement:
-  Exclude:
-    - 'lib/fontisan/commands/features_command.rb'
-    - 'lib/fontisan/commands/scripts_command.rb'
-    - 'lib/fontisan/loading_modes.rb'
-    - 'lib/fontisan/variation/optimizer.rb'
-
 # Offense count: 1
 Lint/StructNewOverride:
   Exclude:
     - 'lib/fontisan/optimizers/pattern_analyzer.rb'
 
-# Offense count: 8
+# Offense count: 7
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: AllowUnusedKeywordArguments, IgnoreEmptyMethods, IgnoreNotImplementedMethods, NotImplementedExceptions.
 # NotImplementedExceptions: NotImplementedError
 Lint/UnusedMethodArgument:
   Exclude:
     - 'lib/fontisan.rb'
-    - 'lib/fontisan/font_loader.rb'
     - 'lib/fontisan/tables/cff2/private_dict_blend_handler.rb'
     - 'lib/fontisan/utilities/brotli_wrapper.rb'
     - 'lib/fontisan/variation/table_accessor.rb'
@@ -148,12 +97,12 @@ Lint/UselessConstantScoping:
     - 'lib/fontisan/conversion_options.rb'
     - 'lib/fontisan/type1/charstrings.rb'
 
-# Offense count: 549
+# Offense count: 552
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
 Metrics/AbcSize:
   Enabled: false
 
-# Offense count: 33
+# Offense count: 31
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns, inherit_mode.
 # AllowedMethods: refine
 Metrics/BlockLength:
@@ -171,17 +120,17 @@ Metrics/CollectionLiteralLength:
     - 'lib/fontisan/type1/agl.rb'
     - 'lib/fontisan/type1/encodings.rb'
 
-# Offense count: 301
+# Offense count: 304
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/CyclomaticComplexity:
   Enabled: false
 
-# Offense count: 842
+# Offense count: 844
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
   Max: 135
 
-# Offense count: 22
+# Offense count: 24
 # Configuration parameters: CountKeywordArgs.
 Metrics/ParameterLists:
   Max: 39
@@ -241,7 +190,7 @@ Naming/VariableName:
     - 'lib/fontisan/type1/pfm_generator.rb'
     - 'lib/fontisan/type1/pfm_parser.rb'
 
-# Offense count: 113
+# Offense count: 111
 # Configuration parameters: EnforcedStyle, CheckMethodNames, CheckSymbols, AllowedIdentifiers, AllowedPatterns.
 # SupportedStyles: snake_case, normalcase, non_integer
 # AllowedIdentifiers: TLS1_1, TLS1_2, capture3, iso8601, rfc1123_date, rfc822, rfc2822, rfc3339, x86_64
@@ -264,7 +213,7 @@ RSpec/AnyInstance:
 RSpec/ContextWording:
   Enabled: false
 
-# Offense count: 27
+# Offense count: 28
 # Configuration parameters: IgnoredMetadata.
 RSpec/DescribeClass:
   Enabled: false
@@ -280,7 +229,7 @@ RSpec/DescribeMethod:
     - 'spec/fontisan/type1/seac_expander_spec.rb'
     - 'spec/fontisan/type1_real_fonts_spec.rb'
 
-# Offense count: 1428
+# Offense count: 1446
 # Configuration parameters: CountAsOne.
 RSpec/ExampleLength:
   Max: 66
@@ -357,11 +306,11 @@ RSpec/MultipleDescribes:
     - 'spec/fontisan/utils/thread_pool_spec.rb'
     - 'spec/fontisan/variation/cache_spec.rb'
 
-# Offense count: 1855
+# Offense count: 1868
 RSpec/MultipleExpectations:
   Max: 19
 
-# Offense count: 152
+# Offense count: 154
 # Configuration parameters: AllowSubject.
 RSpec/MultipleMemoizedHelpers:
   Max: 13
@@ -442,13 +391,6 @@ Style/EmptyElse:
   Exclude:
     - 'lib/fontisan/type1/seac_expander.rb'
 
-# Offense count: 2
-# This cop supports safe autocorrection (--autocorrect).
-Style/ExpandPathArguments:
-  Exclude:
-    - 'docs/node_modules/speakingurl/lib/speakingurl-rails.rb'
-    - 'docs/node_modules/speakingurl/speakingurl-rails.gemspec'
-
 # Offense count: 11
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: EnforcedStyle, MaxUnannotatedPlaceholdersAllowed, Mode, AllowedMethods, AllowedPatterns.
@@ -466,27 +408,9 @@ Style/HashLikeCase:
     - 'lib/fontisan/commands/unpack_command.rb'
     - 'lib/fontisan/models/validation_report.rb'
 
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle, EnforcedShorthandSyntax, UseHashRocketsWithSymbolValues, PreferHashRocketsForNonAlnumEndingSymbols.
-# SupportedStyles: ruby19, hash_rockets, no_mixed_keys, ruby19_no_mixed_keys
-# SupportedShorthandSyntax: always, never, either, consistent, either_consistent
-Style/HashSyntax:
-  Exclude:
-    - 'docs/node_modules/speakingurl/lib/speakingurl-rails.rb'
-
 # Offense count: 1
 # Configuration parameters: AllowedMethods.
 # AllowedMethods: respond_to_missing?
 Style/OptionalBooleanParameter:
   Exclude:
     - 'lib/fontisan/conversion_options.rb'
-
-# Offense count: 7
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle, ConsistentQuotesInMultiline.
-# SupportedStyles: single_quotes, double_quotes
-Style/StringLiterals:
-  Exclude:
-    - 'docs/node_modules/speakingurl/lib/speakingurl-rails.rb'
-    - 'docs/node_modules/speakingurl/speakingurl-rails.gemspec'

data/Gemfile

@@ -5,12 +5,12 @@ source "https://rubygems.org"
 # Specify your gem's dependencies in fontisan.gemspec
 gemspec
 
-gem "canon", "~> 0.1.3"
-gem "get_process_mem", "~> 0.2"
+gem "benchmark"
 # bigdecimal is required by get_process_mem for Ruby 3.4+ compatibility
 gem "bigdecimal"
+gem "canon", "~> 0.1.3"
+gem "get_process_mem", "~> 0.2"
 gem "openssl", "~> 3.0"
-# sys-proctable is required by get_process_mem on Windows
 gem "rake"
 gem "rspec"
 gem "rubocop"
@@ -18,4 +18,7 @@ gem "rubocop-performance"
 gem "rubocop-rake"
 gem "rubocop-rspec"
 gem "rubyzip"
+# sys-proctable is required by get_process_mem on Windows
 gem "sys-proctable", platforms: %i[mswin mingw mswin64]
+# win32ole was a default gem until Ruby 4.0 — pin it for Windows runners
+gem "win32ole", platforms: %i[mswin mingw mswin64]

data/README.adoc

@@ -61,6 +61,7 @@ Color fonts and collections::
 * Font collection validation with per-font reporting (see link:docs/COLLECTION_VALIDATION.adoc[Collection Validation Guide])
 
 Font analysis and information::
+* Comprehensive per-face font audit (replaces `otfinfo`) covering identity, style, metrics, codepoint coverage, licensing, hinting, color capabilities, variable-font detail, OpenType layout features, UCD block/script aggregation, and CLDR language coverage — plus `--compare` mode and whole-library `--recursive --summary` mode
 * Bidirectional font hint conversion (see link:docs/FONT_HINTING.adoc[Font Hinting Guide])
 * Extract comprehensive font metadata (name, version, designer, license, etc.)
 * Brief mode for fast font indexing (5x faster, metadata-only loading)
@@ -99,11 +100,224 @@ Font engineering::
 
 Export and interfaces::
 * TTX/YAML/JSON export (complete)
-* Command-line interface with 18 commands
+* Command-line interface with 19 commands
 * Ruby library API for programmatic access
 * Structured output in YAML, JSON, and text formats
 
 
+== Font audit
+
+=== General
+
+The `audit` command produces a complete per-face font audit report —
+the successor to `otfinfo`, covering everything `otfinfo` reports plus
+codepoint coverage, licensing, hinting, color capabilities, variable-font
+detail, OpenType layout, UCD block/script aggregation, and CLDR language
+coverage. It also supports collections, `--compare` mode, and whole-
+library `--recursive --summary` mode.
+
+For each face, audit reports:
+
+Identity & provenance:: `family_name`, `subfamily_name`, `full_name`,
+  `postscript_name`, `version`, `font_revision`, `source_sha256`,
+  `source_format`, `fontisan_version`, `generated_at`.
+Style:: `weight_class` (+ human label), `width_class`, `bold`, `italic`,
+  `panose`, `fs_selection_flags`.
+Coverage:: `total_codepoints`, `total_glyphs`, `cmap_subtables`,
+  `codepoint_ranges` (compact by default; `--all-codepoints` for the
+  flat list).
+Licensing:: `license_url`, `license_description`, `embedding_type`
+  (decoded `fsType`).
+Metrics:: `units_per_em`, ascender/descender/etc., x-height, cap height,
+  `metrics_consistent?` flag.
+Hinting:: `has_fpgm`, `has_prep`, `gasp_ranges`, TrueType vs PostScript
+  hint presence.
+Color capabilities:: COLR/CPAL, sbix, CBDT/CBLC, SVG table presence.
+Variable-font detail:: axes (`fvar`), named instances.
+OpenType layout:: scripts/features in GSUB and GPOS.
+Aggregations (UCD):: per-block coverage rows, per-script roll-up.
+Language coverage (opt-in via `--with-language-coverage`):: per-language
+  coverage % using CLDR exemplar sets.
+
+[source,shell]
+----
+$ fontisan audit PATH [--compare LEFT RIGHT] [--recursive] [--summary]
+                     [--brief] [--all-codepoints]
+                     [--ucd-version VERSION] [--with-language-coverage]
+                     [--cldr-version VERSION]
+                     [--font-index N] [--output PATH] [--format FORMAT]
+----
+
+Where,
+
+`PATH`:: Path to a font file (single-face audit), collection
+  (`TTC`/`OTC`/`dfont` — one report per face), or directory
+  (library mode with `--recursive`/`--summary`).
+`--compare`:: Diff two inputs (each is a font file or a saved
+  `.yaml`/`.yml`/`.json` audit report). Requires exactly two paths.
+`--recursive`:: Library mode: walk subdirectories.
+`--summary`:: Library mode: produce a `LibrarySummary`.
+`--brief`:: Fast inventory: skip metrics, hinting, color, variation,
+  OpenType layout, and UCD/CLDR aggregation. Note: distinct from
+  `info --brief` — `audit --brief` still loads the full font.
+`--all-codepoints`:: Include the full per-codepoint list (default is a
+  compact range view).
+`--ucd-version VERSION`:: Aggregate against this UCD version
+  (`latest` probes upstream).
+`--with-language-coverage`:: Compute CLDR per-language coverage %
+  (auto-downloads CLDR on first use).
+`--cldr-version VERSION`:: CLDR version (`latest` probes upstream).
+`--font-index N`:: Audit only face N of a collection.
+`--output PATH`:: Write to a directory (collection/library), file
+  (single/compare), or stdout.
+`--format FORMAT`:: `text` (default), `yaml`, or `json`.
+
+=== Command-line usage
+
+Single face:
+
+[source,shell]
+----
+$ fontisan audit NotoSans-Regular.ttf
+$ fontisan audit NotoSans-Regular.ttf --format yaml
+$ fontisan audit NotoSans-Regular.ttf --brief
+$ fontisan audit NotoSans-Regular.ttf --with-language-coverage
+----
+
+Collection (one report per face):
+
+[source,shell]
+----
+$ fontisan audit Family.ttc
+$ fontisan audit Family.ttc --font-index 2
+$ fontisan audit Family.ttc --output reports/
+----
+
+Compare two fonts or saved reports:
+
+[source,shell]
+----
+$ fontisan audit --compare a.ttf b.ttf
+$ fontisan audit --compare baseline.yaml new.ttf
+$ fontisan audit --compare v1.yaml v2.yaml --output diff.yaml
+----
+
+Library summary:
+
+[source,shell]
+----
+$ fontisan audit lib/ --summary
+$ fontisan audit lib/ --recursive --summary
+$ fontisan audit lib/ --recursive --summary --format yaml --output library.yaml
+----
+
+The library summary includes:
+
+* `root_path`, `total_files`, `total_faces`, `scanned_extensions`
+* `aggregate_metrics` — summed codepoints/glyphs/bytes
+* `script_coverage` — per-script face counts and face lists
+* `duplicate_groups` — files grouped by `source_sha256` (size > 1)
+* `license_distribution` — face counts per `license_url`
+* `per_face_reports` — the full per-face reports
+
+Files that fail to load (corrupt, unsupported) are reported on stderr
+as `skipped <path>` and excluded from the summary.
+
+UCD/CLDR cache management:
+
+[source,shell]
+----
+$ fontisan ucd status
+$ fontisan ucd list
+$ fontisan ucd download 17.0.0
+$ fontisan cldr status
+$ fontisan cldr list
+$ fontisan cldr download 45
+----
+
+=== Ruby API usage
+
+Single face:
+
+[source,ruby]
+----
+require "fontisan"
+
+# Returns an AuditReport for a single font, or an Array<AuditReport>
+# for a collection (one per face, in source order).
+report = Fontisan::Commands::AuditCommand.new(
+  "NotoSans-Regular.ttf", ucd_version: "17.0.0"
+).run
+
+report.family_name                # => "Noto Sans"
+report.licensing.license_url      # => "https://scripts.sil.org/OFL"
+report.blocks.first.fill_ratio    # => 0.742
+report.opentype_layout.features   # => ["c2sc", "calt", "case", ...]
+----
+
+Compare:
+
+[source,ruby]
+----
+diff = Fontisan::Commands::AuditCompareCommand.new(
+  "baseline.yaml", "new.ttf", ucd_version: "17.0.0"
+).run
+
+diff.field_changes.each { |c| puts "#{c.field}: #{c.left} -> #{c.right}" }
+puts "added codepoints: #{diff.codepoints.added_count}"
+----
+
+Library summary:
+
+[source,ruby]
+----
+cmd = Fontisan::Commands::AuditLibraryCommand.new(
+  "lib/", recursive: true, options: { ucd_version: "17.0.0" }
+)
+summary = cmd.run
+cmd.skipped.each { |path| warn "skipped #{path}" }
+
+summary.script_coverage.each do |row|
+  puts "#{row.script}: #{row.face_count} faces"
+end
+
+summary.duplicate_groups.each do |group|
+  puts "duplicate #{group.source_sha256[0, 8]}: #{group.files.join(', ')}"
+end
+----
+
+Brief mode (note the `audit_brief:` key — `brief:` would trigger
+metadata-only font loading via `BaseCommand`):
+
+[source,ruby]
+----
+report = Fontisan::Commands::AuditCommand.new(
+  "NotoSans-Regular.ttf", audit_brief: true, ucd_version: "17.0.0"
+).run
+----
+
+=== Architecture
+
+Each audit concern is implemented as a small extractor class
+registered in `Fontisan::Audit::Registry`. `AuditCommand` builds an
+`Audit::Context` and iterates the registry, merging each extractor's
+output into a single `Models::Audit::AuditReport`. Adding a new field
+group means adding one extractor class and one line in the registry —
+`AuditCommand` itself never changes (open/closed).
+
+Two extractor sets are defined:
+
+* `ORDERED_EXTRACTORS` — the full set (default).
+* `BRIEF_EXTRACTORS` — a cheap subset for `--brief` (provenance,
+  identity, style, licensing, coverage).
+
+Sub-models (`Licensing`, `Metrics`, `Hinting`, `ColorCapabilities`,
+`VariationDetail`, `OpenTypeLayout`, `CodepointRange`, `AuditBlock`,
+`NamedInstance`, `AuditAxis`, `ScriptFeatures`) group related fields
+on `AuditReport` (MECE). Compare mode produces an `AuditDiff`; library
+mode produces a `LibrarySummary`.
+
+
 == Font information
 
 === General
@@ -2133,11 +2347,33 @@ Generating options (control how the output font is written):
 * `--optimize-tables` - Enable table optimization
 * `--decompose-on-output` - Decompose composites in output
 
+WOFF compression knobs (apply to `--to woff` only):
+
+* `--zlib-level=N` - zlib level (0–9, default 6)
+* `--uncompressed` - store tables uncompressed (legal per WOFF 1.0 §5.1)
+* `--compression-threshold=N` - skip compression for tables smaller than N bytes
+
+WOFF2 compression knobs (apply to `--to woff2` only):
+
+* `--brotli-quality=N` - Brotli quality (0–11, default 11)
+* `--transform-tables` / `--no-transform-tables` - apply glyf/loca + hmtx transformations
+
+The format selection (`--to woff` vs `--to woff2`) **is** the algorithm
+choice: WOFF mandates zlib, WOFF2 mandates Brotli. Passing a knob that
+doesn't apply to the requested target exits 1 with a clear error.
+
 [source,shell]
 ----
 # Convert with autohinting and optimization
 fontisan convert font.ttf --to otf --output font.otf \
   --autohint --hinting-mode auto --optimize-tables
+
+# Smallest WOFF2 (max Brotli + table transforms)
+fontisan convert font.ttf --to woff2 --output font.woff2 \
+  --brotli-quality 11 --transform-tables
+
+# WOFF for IE 9+ legacy reach (max zlib)
+fontisan convert font.ttf --to woff --output font.woff --zlib-level 9
 ----
 
 For detailed information on all available options and conversion scenarios,
@@ -2206,6 +2442,26 @@ tables = converter.convert(font, options: options)
 ====
 
 
+.One-shot conversion via Fontisan.convert
+[example]
+====
+[source,ruby]
+----
+require 'fontisan'
+
+# TTF → WOFF2 (modern browsers)
+Fontisan.convert('font.ttf', to: :woff2, output: 'font.woff2',
+                 brotli_quality: 11, transform_tables: true)
+
+# TTF → WOFF (IE 9+ legacy reach, max zlib)
+Fontisan.convert('font.ttf', to: :woff, output: 'font.woff', zlib_level: 9)
+
+# WOFF stored uncompressed (legal per WOFF 1.0 §5.1; useful for tooling)
+Fontisan.convert('font.ttf', to: :woff, output: 'font.woff', uncompressed: true)
+----
+====
+
+
 == Round-Trip validation
 
 === General

data/docs/.vitepress/config.ts

@@ -1,4 +1,19 @@
-import { defineConfig } from "vitepress";
+import { defineConfig, type HeadConfig } from "vitepress";
+
+const SITE_ORIGIN = "https://www.fontist.org";
+const BASE_PATH = "/fontisan/";
+const DEFAULT_DESCRIPTION =
+  "The most comprehensive font processing library for Ruby — 100% Pure Ruby, no Python, no C++, no C# dependencies.";
+const DEFAULT_OG_IMAGE = `${SITE_ORIGIN}/og-image.png`;
+
+// Map a page's source path to its canonical public URL (origin + base + clean path).
+function pathToUrl(relativePath: string): string {
+  const bare = relativePath.replace(/\.md$/, "").replace(/\\/g, "/");
+  if (bare === "index") return `${SITE_ORIGIN}${BASE_PATH}`;
+  if (bare.endsWith("/index"))
+    return `${SITE_ORIGIN}${BASE_PATH}${bare.slice(0, -6)}/`;
+  return `${SITE_ORIGIN}${BASE_PATH}${bare}`;
+}
 
 // https://vitepress.dev/reference/site-config
 export default defineConfig({
@@ -7,12 +22,29 @@ export default defineConfig({
   // https://vitepress.dev/guide/routing#generating-clean-url
   cleanUrls: true,
 
+  // Exclude standalone guide stubs that collide with directory routes.
+  // Both guide/<name>.md and guide/<name>/index.md exist for these three
+  // (hinting, validation, conversion); the directory version is the canonical
+  // one (sidebar-linked, richer content). Excluding the standalone stub from
+  // the build resolves the duplicate-route collision while keeping the source
+  // files in the repo.
+  srcExclude: [
+    "guide/hinting.md",
+    "guide/validation.md",
+    "guide/conversion.md",
+  ],
+
   title: "Fontisan",
   description:
     "The most comprehensive font processing library for Ruby — 100% Pure Ruby, no Python, no C++, no C# dependencies.",
 
   lastUpdated: true,
 
+  // https://vitepress.dev/reference/site-config#sitemap
+  sitemap: {
+    hostname: SITE_ORIGIN,
+  },
+
   // Base path for deployment (e.g., /fontisan/ for fontist.org/fontisan/)
   base: process.env.BASE_PATH || "/fontisan/",
 
@@ -29,19 +61,40 @@ export default defineConfig({
     ],
     ["link", { rel: "manifest", href: "/site.webmanifest" }],
     ["meta", { property: "og:type", content: "website" }],
-    ["meta", { property: "og:title", content: "Fontisan" }],
+    ["link", { rel: "preconnect", href: "https://fonts.googleapis.com" }],
+    ["link", { rel: "preconnect", href: "https://fonts.gstatic.com", crossorigin: "" }],
     [
-      "meta",
+      "link",
       {
-        property: "og:description",
-        content:
-          "The most comprehensive font processing library for Ruby — 100% Pure Ruby.",
+        rel: "stylesheet",
+        href: "https://fonts.googleapis.com/css2?family=Spectral:ital,opsz,wght@0,7..72,200..800;1,7..72,200..800&family=IBM+Plex+Mono:wght@400;500&family=IBM+Plex+Sans:wght@300;400;500;600&display=swap",
       },
     ],
-    ["meta", { property: "og:image", content: "/logo-full.svg" }],
-    ["meta", { name: "twitter:card", content: "summary_large_image" }],
   ],
 
+  // Per-page og:* and twitter:* tags are derived from each page's frontmatter.
+  // https://vitepress.dev/reference/site-config#transformhead
+  transformHead(ctx) {
+    const { pageData } = ctx;
+    const url = pathToUrl(pageData.relativePath);
+    const title = pageData.title || "Fontisan";
+    const description = pageData.description || DEFAULT_DESCRIPTION;
+    const image = pageData.frontmatter.image || DEFAULT_OG_IMAGE;
+
+    const tags: HeadConfig[] = [
+      ["meta", { property: "og:title", content: title }],
+      ["meta", { property: "og:description", content: description }],
+      ["meta", { property: "og:url", content: url }],
+      ["meta", { property: "og:image", content: image }],
+      ["meta", { name: "twitter:card", content: "summary_large_image" }],
+      ["meta", { name: "twitter:title", content: title }],
+      ["meta", { name: "twitter:description", content: description }],
+      ["meta", { name: "twitter:image", content: image }],
+    ];
+
+    return tags;
+  },
+
   // https://vitepress.dev/reference/default-theme-config
   themeConfig: {
     logo: "/logo-full.svg",
@@ -210,6 +263,13 @@ export default defineConfig({
             { text: "Overview", link: "/cli/" },
           ],
         },
+        {
+          text: "Font Audit",
+          collapsed: true,
+          items: [
+            { text: "audit", link: "/cli/audit" },
+          ],
+        },
         {
           text: "Font Information",
           collapsed: true,