fontisan 0.2.17 → 0.2.22

data/docs/guide/conversion/options.md

@@ -40,13 +40,22 @@ Generating options control how the output font is written.
 | `optimize_tables` | Boolean | Enable table optimization | Reduce file size |
 | `reencode_first_256` | Boolean | Reencode first 256 glyphs | Type 1 output |
 | `encoding_vector` | String | Custom encoding vector | Type 1 output |
-| `compression` | String | Compression: zlib, brotli, none | Web font output |
-| `transform_tables` | Boolean | Transform tables for output | Format-specific |
+| `zlib_level` | Integer (0–9) | zlib compression level for WOFF | WOFF output (default 6) |
+| `uncompressed` | Boolean | Store WOFF tables uncompressed (legal per WOFF 1.0 §5.1) | Tooling pipelines |
+| `compression_threshold` | Integer | Skip compression for tables smaller than N bytes | Tiny-table edge cases |
+| `brotli_quality` | Integer (0–11) | Brotli quality for WOFF2 | WOFF2 output (default 11) |
+| `transform_tables` | Boolean | Apply WOFF2 glyf/loca + hmtx transformations | Smaller WOFF2 output |
+| `metadata_xml` | String | Optional WOFF metadata XML block | WOFF metadata block |
+| `private_data` | String | Optional WOFF private data block | WOFF private block |
 | `preserve_metadata` | Boolean | Preserve copyright/license metadata | Maintain metadata |
 | `strip_metadata` | Boolean | Remove metadata | Reduce file size |
 | `target_format` | String | Collection target format | Collection conversions |
 | `curve_tolerance` | Float | Curve approximation tolerance | OTF → TTF |
 
+Compression knobs come from each strategy's `ConversionStrategy` DSL
+declarations. Knobs that don't apply to the requested target format are
+rejected by `FormatConverter.validate_options_for_target!`.
+
 ## CLI Option Mapping
 
 ### Opening Options
@@ -103,6 +112,16 @@ Generating options control how the output font is written.
 
 # Curves
 --curve-tolerance N   # Approximation tolerance (0.1-2.0)
+
+# WOFF only (zlib)
+--zlib-level=N              # 0–9, default 6
+--uncompressed              # Store tables uncompressed (legal per WOFF 1.0 §5.1)
+--compression-threshold=N   # Skip compression for tables < N bytes (default 100)
+
+# WOFF2 only (Brotli)
+--brotli-quality=N          # 0–11, default 11
+--transform-tables          # Apply glyf/loca + hmtx transformations
+--no-transform-tables       # Disable transformations (default)
 ```
 
 ### Preset Option
@@ -194,10 +213,20 @@ Fonts optimized for web delivery.
 Fontisan::ConversionOptions.from_preset(:web_optimized)
 # From: :otf, To: :woff2
 # opening: {}
-# generating: { compression: "brotli", transform_tables: true,
+# generating: { brotli_quality: 11, transform_tables: true,
 #              optimize_tables: true, preserve_metadata: true }
 ```
 
+### legacy_web
+
+WOFF with maximum zlib compression for legacy browser reach (IE 9+).
+
+```ruby
+Fontisan::ConversionOptions.from_preset(:legacy_web)
+# From: :otf, To: :woff
+# generating: { zlib_level: 9, optimize_tables: true, preserve_metadata: true }
+```
+
 ### archive_to_modern
 
 Collection extraction and modernization.

data/docs/guide/conversion/ttf-otf.md

@@ -157,7 +157,7 @@ Result: Some precision loss unavoidable.
 # Convert all TTF files in a directory
 Dir.glob('fonts/*.ttf').each do |input|
   output = input.sub('.ttf', '.otf')
-  Fontisan.convert(input, output_format: :otf, output_path: output)
+  Fontisan.convert(input, to: :otf, output: output)
 end
 ```
 

data/docs/guide/conversion/type1.md

@@ -203,6 +203,6 @@ fontisan convert font.pfb --to woff2 --output font.woff2 \
 ```ruby
 Dir.glob('legacy/*.pfb').each do |input|
   output = input.sub('.pfb', '.otf').sub('legacy/', 'modern/')
-  Fontisan.convert(input, output_format: :otf, output_path: output)
+  Fontisan.convert(input, to: :otf, output: output)
 end
 ```

data/docs/guide/conversion/web.md

@@ -10,8 +10,13 @@ Fontisan supports conversion to web-optimized formats (WOFF and WOFF2) for optim
 
 | Format | Compression | Browser Support | Use Case |
 |--------|-------------|-----------------|----------|
-| WOFF | zlib | All modern browsers | Wide compatibility |
-| WOFF2 | brotli | Modern browsers | Smallest size |
+| WOFF | zlib | All modern browsers (IE 9+) | Wide compatibility |
+| WOFF2 | Brotli | Modern browsers | Smallest size |
+
+The format you pick **is** the algorithm choice — WOFF 1.0 mandates zlib,
+WOFF2 mandates Brotli. There is no separate `--compression` flag. Each
+format exposes its algorithm's tunable parameters instead (level, quality,
+threshold, transform).
 
 ## WOFF2
 
@@ -34,7 +39,7 @@ fontisan convert font.pfb --to woff2 --output font.woff2
 Fontisan::ConversionOptions.from_preset(:web_optimized)
 # From: :otf, To: :woff2
 # opening: {}
-# generating: { compression: "brotli", transform_tables: true,
+# generating: { brotli_quality: 11, transform_tables: true,
 #              optimize_tables: true, preserve_metadata: true }
 ```
 
@@ -61,13 +66,20 @@ fontisan convert font.ttf --to woff --output font.woff
 options = Fontisan::ConversionOptions.new(
   to: :woff,
   generating: {
-    compression: "zlib",
-    preserve_metadata: true,
-    add_private_data: false
+    zlib_level: 9,           # max zlib compression
+    preserve_metadata: true
   }
 )
 ```
 
+For maximum legacy reach use the `:legacy_web` preset:
+
+```ruby
+Fontisan::ConversionOptions.from_preset(:legacy_web)
+# From: :otf, To: :woff
+# generating: { zlib_level: 9, optimize_tables: true, preserve_metadata: true }
+```
+
 ## web_optimized Preset
 
 Optimize fonts for web delivery:
@@ -76,7 +88,7 @@ Optimize fonts for web delivery:
 Fontisan::ConversionOptions.from_preset(:web_optimized)
 # From: :otf, To: :woff2
 # opening: {}
-# generating: { compression: "brotli", transform_tables: true,
+# generating: { brotli_quality: 11, transform_tables: true,
 #              optimize_tables: true, preserve_metadata: true }
 ```
 
@@ -113,43 +125,72 @@ fontisan convert font.otf --to woff2 --output font.woff2
 # Via OTF intermediate
 options = Fontisan::ConversionOptions.new(
   opening: { decompose_composites: false, generate_unicode: true },
-  generating: { compression: "brotli" }  # WOFF2
-  # OR: generating: { compression: "zlib" }    # WOFF
+  generating: {
+    brotli_quality: 11     # WOFF2
+    # For WOFF instead, use: zlib_level: 9
+  }
 )
 ```
 
-## Compression Options
+## Compression Knobs
+
+Each web format exposes its algorithm's parameters. Knobs that don't apply
+to the requested target are rejected up-front with a clear error.
 
-### brotli (WOFF2)
+### WOFF (zlib)
+
+| Option | CLI | Range | Default | Notes |
+|--------|-----|-------|---------|-------|
+| `zlib_level` | `--zlib-level=N` | 0–9 | 6 | 0 = no compression, 9 = smallest |
+| `uncompressed` | `--uncompressed` | bool | false | Store tables uncompressed (legal per WOFF 1.0 §5.1; `compLength == origLength`) |
+| `compression_threshold` | `--compression-threshold=N` | bytes | 100 | Skip compression for tables smaller than N |
 
 ```ruby
-generating: { compression: "brotli" }
+# Max zlib compression
+options = Fontisan::ConversionOptions.new(
+  to: :woff,
+  generating: { zlib_level: 9 }
+)
+
+# No compression (legal per spec; useful for tooling pipelines)
+options = Fontisan::ConversionOptions.new(
+  to: :woff,
+  generating: { uncompressed: true }
+)
 ```
 
-- Best compression ratio
-- Requires modern browsers
-- Transforms tables for better compression
+### WOFF2 (Brotli)
 
-### zlib (WOFF)
+| Option | CLI | Range | Default | Notes |
+|--------|-----|-------|---------|-------|
+| `brotli_quality` | `--brotli-quality=N` | 0–11 | 11 | 0 = fastest, 11 = smallest |
+| `transform_tables` | `--[no-]transform-tables` | bool | false | Apply glyf/loca and hmtx transformations |
 
 ```ruby
-generating: { compression: "zlib" }
+# Smallest possible WOFF2
+options = Fontisan::ConversionOptions.new(
+  to: :woff2,
+  generating: { brotli_quality: 11, transform_tables: true }
+)
 ```
 
-- Good compression
-- Wide browser support
-- No table transforms
+### Cross-format validation
 
-### none
+Passing a WOFF knob to a WOFF2 target (or vice versa) is rejected at
+conversion time by `FormatConverter.validate_options_for_target!`:
 
 ```ruby
-generating: { compression: "none" }
+# Rejected at convert time: brotli_quality does not apply to woff
+Fontisan.convert('font.ttf', to: :woff, output: 'font.woff',
+                 brotli_quality: 11)
+# => Fontisan::Error: ... Option(s) :brotli_quality do not apply to --to woff.
+#    Accepted for woff: zlib_level, uncompressed, compression_threshold,
+#                       metadata_xml, private_data
 ```
 
-- No compression
-- For debugging
+The CLI equivalent exits 1 with the same message.
 
-## Table Transforms
+## Table Transforms (WOFF2)
 
 WOFF2 supports table transformations for better compression:
 
@@ -166,6 +207,12 @@ options = Fontisan::ConversionOptions.new(
 )
 ```
 
+CLI equivalent:
+
+```bash
+fontisan convert font.ttf --to woff2 --output font.woff2 --transform-tables
+```
+
 ## Metadata Handling
 
 ### Preserve Metadata
@@ -198,20 +245,32 @@ font = Fontisan::FontLoader.load('source.ttf')
 woff2_options = Fontisan::ConversionOptions.from_preset(:web_optimized)
 Fontisan::FontWriter.write(font, 'font.woff2', options: woff2_options)
 
-# Create WOFF for older browsers
-woff_options = Fontisan::ConversionOptions.new(
-  to: :woff,
-  generating: { compression: "zlib", preserve_metadata: true }
-)
+# Create WOFF for older browsers (max zlib)
+woff_options = Fontisan::ConversionOptions.from_preset(:legacy_web)
 Fontisan::FontWriter.write(font, 'font.woff', options: woff_options)
 ```
 
+### Top-level Fontisan.convert
+
+```ruby
+# WOFF2 with max Brotli
+Fontisan.convert('font.ttf', to: :woff2, output: 'font.woff2',
+                 brotli_quality: 11, transform_tables: true)
+
+# WOFF with max zlib (for IE / older browsers)
+Fontisan.convert('font.ttf', to: :woff, output: 'font.woff', zlib_level: 9)
+
+# WOFF stored uncompressed (legal per WOFF 1.0 §5.1)
+Fontisan.convert('font.ttf', to: :woff, output: 'font.woff', uncompressed: true)
+```
+
 ### Batch Web Conversion
 
 ```bash
-# Convert all TTF files to WOFF2
+# Convert all TTF files to WOFF2 with max Brotli
 for f in fonts/*.ttf; do
-  fontisan convert "$f" --to woff2 --output "web/$(basename "${f%.ttf}.woff2")"
+  fontisan convert "$f" --to woff2 --output "web/$(basename "${f%.ttf}.woff2")" \
+    --brotli-quality 11 --transform-tables
 done
 ```
 

data/docs/guide/conversion.md

@@ -18,10 +18,10 @@ Fontisan supports conversion between various font formats.
 require 'fontisan'
 
 # Convert TTF to WOFF2
-Fontisan.convert('font.ttf', output_format: :woff2)
+Fontisan.convert('font.ttf', to: :woff2, output: 'font.woff2')
 
-# Convert with custom output path
-Fontisan.convert('font.ttf', output_path: 'output/font.woff2')
+# Convert TTF to OTF
+Fontisan.convert('font.ttf', to: :otf, output: 'font.otf')
 ```
 
 ## Batch Conversion
@@ -30,10 +30,11 @@ Fontisan.convert('font.ttf', output_path: 'output/font.woff2')
 # Convert multiple files
 fonts = Dir.glob('fonts/*.ttf')
 fonts.each do |font|
-  Fontisan.convert(font, output_format: :otf)
+  out = font.sub(/\.ttf$/, '.otf')
+  Fontisan.convert(font, to: :otf, output: out)
 end
 ```
 
 ## Related
 
-- [WOFF/WOFF2 Formats](/guide/woff) - Details on web font formats
+- [WOFF/WOFF2 Formats](/guide/conversion/web) - Details on web font formats

data/docs/guide/formats/woff.md

@@ -10,8 +10,13 @@ Web Open Font Format (WOFF and WOFF2) are optimized for web delivery.
 
 | Format | Compression | Browser Support |
 |--------|-------------|-----------------|
-| WOFF | zlib | All modern browsers |
-| WOFF2 | brotli | Modern browsers |
+| WOFF | zlib | All modern browsers (IE 9+) |
+| WOFF2 | Brotli | Modern browsers |
+
+The format you pick **is** the algorithm choice — WOFF 1.0 mandates zlib,
+WOFF2 mandates Brotli. Each format exposes its algorithm's parameters
+(level, quality, transform) rather than offering a separate algorithm
+selector.
 
 ## WOFF2 Benefits
 
@@ -27,6 +32,9 @@ fontisan convert font.ttf --to woff --output font.woff
 
 # From OTF
 fontisan convert font.otf --to woff --output font.woff
+
+# Max zlib compression
+fontisan convert font.ttf --to woff --output font.woff --zlib-level 9
 ```
 
 ## Converting to WOFF2
@@ -40,6 +48,10 @@ fontisan convert font.otf --to woff2 --output font.woff2
 
 # From Type 1
 fontisan convert font.pfb --to woff2 --output font.woff2
+
+# Smallest possible output (max Brotli + table transforms)
+fontisan convert font.ttf --to woff2 --output font.woff2 \
+  --brotli-quality 11 --transform-tables
 ```
 
 ## API Usage
@@ -47,28 +59,40 @@ fontisan convert font.pfb --to woff2 --output font.woff2
 ```ruby
 options = Fontisan::ConversionOptions.from_preset(:web_optimized)
 # From: :otf, To: :woff2
-# generating: { compression: "brotli", transform_tables: true }
+# generating: { brotli_quality: 11, transform_tables: true,
+#              optimize_tables: true, preserve_metadata: true }
 
 Fontisan::FontWriter.write(font, 'font.woff2', options: options)
 ```
 
-## Compression Options
+## Compression Knobs
+
+### WOFF (zlib)
 
-### brotli (WOFF2)
+| Option | CLI | Range | Default |
+|--------|-----|-------|---------|
+| `zlib_level` | `--zlib-level=N` | 0–9 | 6 |
+| `uncompressed` | `--uncompressed` | bool | false |
+| `compression_threshold` | `--compression-threshold=N` | bytes | 100 |
 
 ```ruby
-generating: { compression: "brotli" }
+generating: { zlib_level: 9 }           # max zlib
+generating: { uncompressed: true }      # legal per WOFF 1.0 §5.1
 ```
 
-Best compression ratio.
+### WOFF2 (Brotli)
 
-### zlib (WOFF)
+| Option | CLI | Range | Default |
+|--------|-----|-------|---------|
+| `brotli_quality` | `--brotli-quality=N` | 0–11 | 11 |
+| `transform_tables` | `--[no-]transform-tables` | bool | false |
 
 ```ruby
-generating: { compression: "zlib" }
+generating: { brotli_quality: 11, transform_tables: true }
 ```
 
-Wide compatibility.
+Cross-format misuse (e.g. `brotli_quality` on `:woff`) raises
+`ArgumentError` from `FormatConverter.validate_options_for_target!`.
 
 ## Table Transforms
 
@@ -110,6 +134,6 @@ fontisan convert font.woff2 --to otf --output font.otf
 ## Best Practices
 
 1. **Use WOFF2 primarily** — Best compression
-2. **Provide WOFF fallback** — For older browsers
+2. **Provide WOFF fallback** — For older browsers (IE 9+)
 3. **Keep original** — For editing
 4. **Preserve metadata** — Unless stripping for size

data/docs/guide/index.md

@@ -86,7 +86,7 @@ puts tables.keys
 
 ```ruby
 # Simple conversion
-Fontisan.convert('input.ttf', output_format: :woff2)
+Fontisan.convert('input.ttf', to: :woff2, output: 'output.woff2')
 
 # With custom options
 options = Fontisan::ConversionOptions.new(
@@ -94,7 +94,7 @@ options = Fontisan::ConversionOptions.new(
   to: :otf,
   opening: { autohint: true, convert_curves: true }
 )
-Fontisan.convert('input.ttf', output_format: :otf, options: options)
+Fontisan.convert('input.ttf', to: :otf, output: 'output.otf', options: options)
 ```
 
 ### Validate Fonts

data/docs/guide/migrations/extract-ttc.md

@@ -246,7 +246,7 @@ fontisan maintains 100% backward compatibility:
 
 = ExtractTTC to Fontisan Migration Guide
 
-This guide helps users migrate from https://github.com/fontist/extract_ttc[ExtractTTC] to Fontisan.
+This guide helps users migrate from [ExtractTTC](https://github.com/fontist/extract_ttc) to Fontisan.
 
 Fontisan provides complete compatibility with all ExtractTTC functionality while adding comprehensive font analysis, subsetting, validation, and format conversion capabilities.
 

data/docs/guide/quick-start.md

@@ -70,13 +70,13 @@ fontisan info font.ttf --format json
 
 ```ruby
 # TTF to OTF
-Fontisan.convert('input.ttf', output_format: :otf)
+Fontisan.convert('input.ttf', to: :otf, output: 'output.otf')
 
 # OTF to WOFF2
-Fontisan.convert('input.otf', output_format: :woff2)
+Fontisan.convert('input.otf', to: :woff2, output: 'output.woff2')
 
 # Type 1 to OTF
-Fontisan.convert('input.pfb', output_format: :otf)
+Fontisan.convert('input.pfb', to: :otf, output: 'output.otf')
 ```
 
 ### With Options
@@ -89,7 +89,7 @@ options = Fontisan::ConversionOptions.new(
   generating: { hinting_mode: 'auto' }
 )
 
-Fontisan.convert('input.ttf', output_format: :otf, options: options)
+Fontisan.convert('input.ttf', to: :otf, output: 'output.otf', options: options)
 ```
 
 ### Using CLI

data/docs/guide/type1.md

@@ -28,13 +28,13 @@ puts font.num_glyphs
 
 ```ruby
 # Convert to TrueType
-Fontisan.convert('font.pfb', output_format: :ttf)
+Fontisan.convert('font.pfb', to: :ttf, output: 'font.ttf')
 
 # Convert to OpenType
-Fontisan.convert('font.pfb', output_format: :otf)
+Fontisan.convert('font.pfb', to: :otf, output: 'font.otf')
 
 # Convert to WOFF2
-Fontisan.convert('font.pfb', output_format: :woff2)
+Fontisan.convert('font.pfb', to: :woff2, output: 'font.woff2')
 ```
 
 ## Handling Encodings
@@ -55,4 +55,4 @@ end
 
 ## Related
 
-- [Font Conversion](/guide/conversion) - General conversion guide
+- [Font Conversion](/guide/conversion/) - General conversion guide

data/docs/guide/woff.md

@@ -9,41 +9,42 @@ WOFF and WOFF2 are web font formats optimized for use on websites:
 - **WOFF** - Compressed version of TrueType/OpenType with metadata support
 - **WOFF2** - Improved compression using Brotli algorithm (typically 30% smaller than WOFF)
 
+The format you pick (`--to woff` vs `--to woff2`) **is** the algorithm
+choice: WOFF mandates zlib, WOFF2 mandates Brotli. Each format exposes
+its algorithm's parameters (level, quality, transform) rather than
+offering a separate algorithm selector.
+
 ## Converting to WOFF
 
 ```ruby
 require 'fontisan'
 
-# Convert to WOFF
-Fontisan.convert('font.ttf', output_format: :woff)
+# Convert to WOFF (max zlib for legacy browser reach)
+Fontisan.convert('font.ttf', to: :woff, output: 'font.woff', zlib_level: 9)
 
-# Convert to WOFF2 (recommended for web)
-Fontisan.convert('font.ttf', output_format: :woff2)
+# Convert to WOFF2 (recommended for modern browsers)
+Fontisan.convert('font.ttf', to: :woff2, output: 'font.woff2',
+                 brotli_quality: 11, transform_tables: true)
 ```
 
 ## Metadata
 
-WOFF files can contain extended metadata:
+WOFF files can carry an extended metadata block:
 
 ```ruby
-# Add metadata when converting
+# Add WOFF metadata when converting
 Fontisan.convert('font.ttf',
-  output_format: :woff2,
-  metadata: {
-    unique_id: 'my-font-1.0',
-    license: 'OFL',
-    license_url: 'https://scripts.sil.org/OFL',
-    description: 'My custom font'
-  }
-)
+  to: :woff,
+  output: 'font.woff',
+  metadata_xml: '<metadata>...</metadata>')
 ```
 
 ## Extracting from WOFF
 
 ```ruby
 # Extract original font from WOFF
-Fontisan.convert('font.woff', output_format: :ttf)
-Fontisan.convert('font.woff2', output_format: :otf)
+Fontisan.convert('font.woff', to: :ttf, output: 'font.ttf')
+Fontisan.convert('font.woff2', to: :otf, output: 'font.otf')
 ```
 
 ## Compression Comparison
@@ -56,4 +57,5 @@ Fontisan.convert('font.woff2', output_format: :otf)
 
 ## Related
 
-- [Font Conversion](/guide/conversion) - General conversion guide
+- [Web Font Formats](/guide/conversion/web) - Detailed WOFF/WOFF2 guide with all compression knobs
+- [Font Conversion](/guide/conversion/) - General conversion guide

data/docs/index.md

@@ -18,6 +18,8 @@ hero:
       link: /guide/migrations/fonttools
 
 features:
+  - title: "🔍 Font Audit"
+    details: Comprehensive per-face audit (replaces otfinfo) — identity, style, metrics, coverage, licensing, hinting, color, variation, OpenType layout, UCD/CLDR aggregation, compare, and library-summary modes.
   - title: "🔄 Font Conversion"
     details: Convert between TTF, OTF, WOFF, WOFF2, Type 1 (PFB/PFA), and SVG formats with curve conversion and optimization.
   - title: "✅ Font Validation"

data/docs/lychee.toml

@@ -23,7 +23,11 @@ include_verbatim = true
 # Exclude URLs (regex patterns)
 exclude = [
   'github\.com/fontist/fontisan/issues',
-  'github\.com/fontist/extract_ttc',
+  'github\.com/extract_ttc',
+  # Exclude internal /fontisan/ links — these are deployment base paths that
+  # resolve correctly when deployed but fail lychee's local file:// checks
+  # (the built HTML has /fontisan/<path>; the file lives at dist/<path>).
+  '^file://.*/fontisan/',
 ]
 
 # Exclude paths from checking (regex patterns)

data/docs/package.json

@@ -1,7 +1,7 @@
 {
   "scripts": {
     "dev": "vitepress dev",
-    "build": "vitepress build",
+    "build": "vitepress build && node scripts/post-build.mjs",
     "preview": "vitepress preview",
     "format": "prettier -w ."
   },

data/docs/public/robots.txt

@@ -0,0 +1,4 @@
+User-agent: *
+Allow: /
+
+Sitemap: https://www.fontist.org/fontisan/sitemap.xml

data/docs/scripts/post-build.mjs

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+// Post-build fixes for GitHub Pages subpath deployment.
+//
+// 1. Dirify: convert VitePress file-style output (foo.html) to directory-style
+//    (foo/index.html) so GitHub Pages resolves BOTH /foo and /foo/. Without
+//    this, /foo/ 404s because foo.html is a file, not a directory.
+//
+// 2. Sitemap base: insert the deployment base path into sitemap.xml URLs.
+//    VitePress omits `base` from sitemap route paths (and ignores the path
+//    portion of `sitemap.hostname`), so the generated URLs point at the origin
+//    root instead of the subsite. We rewrite each <loc> to include the base.
+//
+// Idempotent. Kept at the dist root: index.html (site root), 404.html (GHP 404 page).
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+
+const DIST = ".vitepress/dist";
+const HTML = ".html";
+const KEEP_AT_ROOT = new Set(["index.html", "404.html"]);
+// Subsite identity — must match config.ts base and the real deployment URL.
+const ORIGIN = "https://www.fontist.org";
+const BASE = "fontisan"; // path segment under ORIGIN (no slashes)
+
+let moved = 0;
+let skipped = 0;
+
+function dirify(dir) {
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) {
+      dirify(full);
+      continue;
+    }
+    if (!entry.endsWith(HTML)) continue;
+    if (entry === "index.html") continue; // already directory-style
+    if (dir === DIST && KEEP_AT_ROOT.has(entry)) {
+      skipped++; // root index.html / 404.html stay put
+      continue;
+    }
+    const name = entry.slice(0, -HTML.length);
+    const targetDir = join(dir, name);
+    const targetIndex = join(targetDir, "index.html");
+    if (existsSync(targetIndex)) {
+      console.warn(`[post-build] skip ${full.replace(DIST + "/", "")}: target exists`);
+      skipped++;
+      continue;
+    }
+    mkdirSync(targetDir, { recursive: true });
+    renameSync(full, targetIndex);
+    moved++;
+  }
+}
+
+function fixSitemapBase() {
+  const sitemap = `${DIST}/sitemap.xml`;
+  if (!existsSync(sitemap)) return false;
+  let xml = readFileSync(sitemap, "utf8");
+  // Insert BASE after the origin unless the path already starts with BASE
+  // (VitePress emits the homepage route as "/<base>"; other routes omit it).
+  const originPattern = new RegExp(
+    `(<loc>${ORIGIN.replaceAll("/", "\\/")}\\/)(?!${BASE}(\\/|$))`,
+    "g",
+  );
+  xml = xml.replace(originPattern, `$1${BASE}/`);
+  writeFileSync(sitemap, xml);
+  return true;
+}
+
+dirify(DIST);
+const sitemapFixed = fixSitemapBase();
+console.log(
+  `[post-build] dirified ${moved} route(s), kept ${skipped} at root; sitemap ${sitemapFixed ? "rewritten with /" + BASE + "/" : "absent (skipped)"}`,
+);