Skip to content

Latest commit

 

History

History
287 lines (206 loc) · 27.3 KB

plan.md

File metadata and controls

287 lines (206 loc) · 27.3 KB

fontstay.dev — Implementation Plan

Static Astro site that generates metric-adjusted fallback font stacks for web fonts, per target OS/browser audience, with live preview and live layout-shift (CLS) estimation.

Inspired by:

1. Product scope

1.1 Inputs (web fonts)

The default entry point is choosing fonts (upload / catalog). Arriving from the bookmarklet is a secondary path and is not emphasized on the first screen.

Delivered incrementally:

  1. File upload (woff2/woff/ttf/otf) — fully local, no network. First to ship.
  2. Google Fonts picker — catalog JSON generated by pnpm google-fonts:catalog and committed (lazy-loaded chunk); font files fetched from fonts.gstatic.com (CORS-enabled). The site import (#34) is documented in docs/security.md and extension/README.md. The Fontsource picker (#44) adds the non-Google open fonts (pnpm fontsource:catalog), files from cdn.jsdelivr.net.
  3. Site import — hosting is static (no proxy), so:
    • Bookmarklet run on the user's site: collects @font-face rules, document.fonts, computed font-family of key elements (body, h1–h3, buttons), element boxes, fetches same-origin font files, then opens the generator in a new tab and hands the payload over (window.open + postMessage handshake; clipboard JSON as a fallback). The user lands directly in the tuning UI with their site's fonts preloaded; the preview and CLS simulation keep the sample article until #173 brings the site structure.
    • Direct URL fetch attempted from the browser; works only when the site sends CORS headers (font files usually do, HTML/CSS usually don't). Failure falls back to the bookmarklet or the extension with a clear explanation. Implemented in site-import/lib/direct-fetch.ts; limits and the connect-src exception are in docs/security.md.
    • Paste CSS (@font-face blocks / Google Fonts <link> URL).

1.2 Audience (OS & browsers)

  • Browserslist tag editor in the browser: quick-add tags (baseline widely available, baseline newly available, baseline 20XX, defaults, > 0.5%, last 2 versions, mobile-only, desktop-only, browsers, operating systems) with a hover not action, typed or pasted queries, .browserslist drop, validation and live resolved list.
  • Resolved browsers are mapped to OS groups: ios_saf → iOS, safari → macOS, and_chr/samsung/and_ff/and_uc → Android, chrome/edge/firefox/opera → Windows/macOS/Linux/ChromeOS (desktop split is configurable).
  • My stats: load browserslist-stats.json from the user's analytics (see 2.3) to use in my stats queries and traffic-weighted coverage.
  • Manual mode: user adds/removes OS groups and versions directly, ignoring browserslist.
  • The audience drives: which per-OS fallback selectors are shown, descriptor support warnings, and coverage estimates.

1.3 Per-OS fallback selection

  • One column/selector per OS group. Each lists fonts preinstalled on that OS (from our dataset), ranked by metric similarity to the web font (x-width avg, cap height, x-height, ascent/descent ratios) with an "auto-pick best" default.
  • Multiple fallbacks per OS allowed (ordered).
  • Stack resolver: simulates, per OS, which local() face wins given the final font-family order (e.g. Arial also exists on macOS, so the macOS pick must come before Arial). Shows conflicts and proposes a reordering.
  • local() name variants (full name + PostScript name) emitted per font, since naming differs across OSes.

1.4 Auto-fit (every number has auto + manual override)

Every numeric control = slider + number input + "auto" toggle. Auto values recompute when inputs change; manual edits pin the value until reset.

Value Auto-fit method
size-adjust Ratio of weighted average glyph width (language-specific letter frequencies, per script) of web font vs fallback; optional exact fit against the preview text by measuring rendered width.
ascent-override / descent-override / line-gap-override Web font vertical metrics (hhea/OS2 selected by an explicit engine policy) divided by the web font's own unitsPerEm and size-adjust.
letter-spacing / word-spacing Numeric optimizer minimizing line-break mismatches and block height delta on sample text across chosen viewports. Emitted as a "fonts loading" CSS class + Font Loading API snippet (these are not @font-face descriptors).
font-size-adjust Computed from x-height/cap-height ratio; offered as the Safari strategy (see 1.6).
Automatic CLS fit Runs the solver on every chosen fallback whenever inputs change; values pinned by hand stay and the rest are optimized to minimize the estimated CLS.

1.5 unicode-range

Both modes:

  • (a) Coverage-limited fallback: extract the web font's cmap, emit a compact unicode-range for each adjusted fallback @font-face, so metric overrides apply only to characters the web font actually covers.
  • (b) Per-script fallback chains: Latin / Cyrillic / Greek / CJK / Arabic / … each get their own fallback font per OS and their own adjusted @font-face with the script's range and per-script fit (Capsize-style per-subset x-width).
  • Range compaction (merge adjacent code points, named presets matching Google Fonts subsets).

1.6 Impact & diagnostics (shown live, included in export)

  • Layout shift (CLS) simulation, updated live while sliders move (debounced to animation frames):
    • Preview document rendered in hidden same-origin iframes at preset viewports (412 / 1350, the Lighthouse mobile and desktop sizes).
    • Element boxes collected with fallback vs web font, layout shift score computed per the Layout Instability spec (impact fraction × distance fraction).
    • Shows score per viewport with Good / Needs improvement / Poor rating (0.1 / 0.25 thresholds), plus line-count delta, block height delta, width delta %, line-break mismatches.
    • The sample article, or the element boxes of an imported page when the bookmarklet or extension collected them (#173); a direct URL import and the per-OS ranking still use the sample article.
    • Device picker in the preview toolbar (Responsive, phones, foldables, tablets, laptops and displays; list generated from Chrome DevTools' emulated devices by pnpm devices:import). A chosen device or a dragged preview width sets the frame width and the score is recomputed at that width; the page width is measured too when the preview is not constrained.
  • Descriptor support matrix for the selected audience (MDN BCD data). Notably Safari/iOS do not support ascent-override / descent-override / line-gap-override (only size-adjust from 17), so the tool shows the expected residual shift there and offers the font-size-adjust + fixed line-height strategy.
  • Coverage estimate: share of the audience whose OS has each fallback preinstalled (usage from browserslist/caniuse data × OS availability dataset).
  • Loading strategy guidance: font-display choice and its effect on CLS (optional = no swap shift), <link rel="preload" … crossorigin>, font file size, FOUT/FOIT trade-offs.

1.7 Outputs

  • Plain CSS (@font-face + font-family), CSS custom properties variant.
  • Tailwind v4 @theme, Next.js next/font/local (declarations, adjustFontFallback: false + manual fallback), Fontaine / Nuxt Fonts config, Astro Fonts config.
  • Font Loading API snippet for the "fonts loading" class.
  • Preload <link> tags.
  • Machine-readable JSON (all inputs, computed metrics, outputs).
  • Impact report (Markdown): CLS per viewport, support matrix, coverage, warnings.
  • Share link: only the difference from the app defaults is serialized into the URL hash, including the open dock panel and the preview modes (uploaded font files are kept in IndexedDB locally; link warns they are not shared; fonts picked from Google Fonts or Fontsource travel as sources and are downloaded again after the recipient confirms).
    • The link carries a short fingerprint of the preset picks over the bundled OS font dataset (data). If it differs from the recipient's, only the picks whose fonts still exist in the recipient's dataset are restored (the rest fall back to the preset) and a dismissable notice is shown; the other settings are applied. Settings saved in the browser carry the same fingerprint and raise the same notice. Opening a link does not overwrite the recipient's saved dock layout. The preview heading and body families travel in the view diff (headingFont, bodyFont); page text is never carried.
    • Auto-fit values are recomputed by the recipient from a browser-dependent calibration, so the numbers can differ slightly between browsers. The opt-in "Pin auto-fit values" checkbox next to Share writes the selected font's current fit numbers (size-adjust, ascent, descent, line gap; percent, two decimals) into the link as manual values; they stay fixed instead of recalculating when the recipient changes the font. Other fonts of a multi-font link are not pinned, and a pinned link over the hash limit is copied unpinned with a notice.

1.8 Other pages

  • Font catalog (cssfontstack analog): table of system fonts × OS/versions with availability and estimated audience coverage; static page per font with metrics and specimen.
  • Presets (abacktools analog): curated stacks per category (sans, serif, mono, display, handwriting, system-ui, modern-font-stacks families), each openable in the generator.
    • Model (#510): a preset is not a CSS stack that is copied into the output. It sets the font type and preselects, per system, the stack fonts that the OS fonts dataset lists as preinstalled and that have metrics; the fitted @font-face fallbacks (size-adjust, overrides) are then computed for those picks like for any other pick, and flow into every export format, the preview and the share link. Stack fonts without dataset entries or metrics (for example Rockwell, Charter, Menlo) cannot be fitted and are skipped (as is any stack font beyond two per system); the Fine-tuning panel lists them, or says that the preset only sets the font type when none of the selected systems has a usable pick.
  • Guide: how descriptors, unicode-range and CLS interact.
  • Footer links: Credits page, source repository (fogrew/fontstay.dev).

1.9 Later (backlog)

  • More OFL font sources besides Google Fonts (Fontsource, Bunny Fonts, independent foundries).

2. Data

2.1 Fallback font metrics

  • @capsizecss/metrics (MIT): used as a cross-check for Google Fonts and a few system fonts only. It has just latin/thai subsets and ~20 system fonts (spike).
  • Own metrics format: per face, advances of every code point in supported scripts (Latin, Cyrillic, Greek first) plus vertical metrics, produced by scripts/extract-metrics.ts from installed font files. Only metrics are committed, never font files.
  • Optional in-browser enhancement: Local Font Access API (Chromium) to read the user's actual installed fallback fonts.

2.2 OS availability dataset (own JSON, MIT)

fonts/<font-id>.json: names (family, full, PostScript per OS), category, scripts covered, and availability[os][version] = preinstalled | on-demand | optional-feature | absent, each entry with a source link.

Seeds:

  • Official vendor lists: Microsoft Learn Windows font lists, Apple "Fonts included with macOS / iOS" pages, AOSP fonts.xml (Apache-2.0), default font packages of Ubuntu/Fedora, ChromeOS.
  • adrg/os-font-list (MIT, unmaintained since Nov 2021) — one-time import for older Windows/macOS/Linux versions, with attribution; not a dependency.
  • modern-font-stacks (CC0, active) — preset stacks and cross-check of availability.
  • Validated by a schema (Valibot/Zod) and unit tests (every entry has a source, no unknown OS ids).

2.3 Usage data

  • Browser version usage: caniuse-lite via browserslist (CC BY 4.0).
  • Own traffic stats: the user can load a browserslist-stats.json (custom usage data schema) produced by browserslist-plausible, browserslist-ga, browserslist-ga-export or by hand. Enables > N% in my stats queries and weights all coverage estimates by the user's real traffic. Parsed and validated locally, never uploaded.
  • Desktop OS split for desktop browsers: default from StatCounter (CC BY-SA 3.0, attributed), user-editable.
  • Descriptor support: @mdn/browser-compat-data (CC0), compiled to a small JSON at build time.

3. Architecture

3.1 Stack

  • Astro (static output, no adapter, no server), TypeScript strict.
  • Hosting: Cloudflare Workers with static assets only (no Worker script), deployed by Workers Builds from GitHub.
  • Preact + @preact/signals for the interactive generator island (client:load for generator, client:visible elsewhere).
  • Font parsing: fontkitten (MIT, ~93 KB gzip, woff2 included) in a Web Worker; we compute metrics ourselves from cmap + glyph advances (spike).
  • browserslist + baseline-browser-mapping bundled for the browser (lazy-loaded chunk).
  • i18n: Astro i18n routing (/en/, /ru/, default locale redirect) + Paraglide JS 2 for the typed message keys and the locale runtime; the texts themselves are the per-locale JSON files (messages/<locale>.json), which messagesFor fills in {name} placeholders from. A page fetches only the file of its own locale (preloaded from the head, read before the islands hydrate); prerendering reads all of them.

3.2 FEOD layout

FEOD levels: app, pages, modules, common, global. Imports only through each entity's root index.ts; direction per the import matrix.

Astro routes live in src/app/pages (srcDir: ./src/app), which frees src/pages for the FEOD pages level; route files are thin and render page entities.

src/
  app/                    # Astro srcDir: routes, layouts, global styles, i18n wiring, head/meta, theme
    pages/                # thin Astro routes ([locale]/index.astro, fonts/[slug].astro, …)
    layouts/
    styles/
  pages/                  # FEOD pages level: page entities with root index.ts
    generator/            # composition of modules for the generator page
    catalog/
    presets/
    guide/
  modules/
    font-source/          # web font inputs
      upload/  google-fonts/  site-import/   # submodules
    font-metrics/         # parsing worker, metrics, cmap, script detection
    system-fonts/         # dataset access, similarity ranking, local() names
    audience/             # browserslist tag editor, OS mapping, support matrix, coverage
    fallback-fit/         # fit math, solver, unicode-range builder, stack resolver
    layout-shift/         # CLS simulation (iframes, box diff, scoring)
    preview/              # overlay/side-by-side preview, toggles
    export/               # CSS/Tailwind/Next/Fontaine/Astro/JSON/report generators
    presets/              # curated stacks
    project-state/        # signals store, URL hash + IndexedDB persistence
  common/
    ui/                   # Button, FitField (slider+number+auto), Select, Tabs, CodeBlock, Disclosure, LiveRegion
    i18n/                 # Paraglide runtime re-exports, locale helpers
    lib/                  # math, debounce, typed worker RPC
  global/                 # env.d.ts, polyfills
data/                     # fonts/*.json, metrics/*.json, presets.json (+ schemas)
scripts/                  # extract-metrics, google-fonts/import-catalog, build-bcd-subset, i18n-add-locale
tests/e2e/

Pure logic (fallback-fit, font-metrics, audience, layout-shift scoring, export) has no UI dependency and is unit-tested in isolation.

3.3 i18n workflow

  • messages/en.json is the source of truth; ru.json etc. typed against it by Paraglide (missing key = type error).
  • pnpm i18n:add <locale> scaffolds the messages file, registers the locale in Paraglide settings and Astro i18n config.
  • Unit test checks key parity and ICU plural forms; e2e smoke runs per locale.
  • Language switcher keeps the current state (URL hash survives).

3.4 Accessibility (WCAG 2.2 AA)

  • Native inputs (<input type="range"> + linked <input type="number">), visible labels, units in accessible names.
  • Full keyboard operation, visible focus, logical order, skip link.
  • Live CLS value announced via throttled polite aria-live region (only on settle, not every frame).
  • Light/dark via light-dark() and prefers-color-scheme, respects prefers-reduced-motion and forced-colors.
  • Preview overlay is not color-only: outline/dash patterns distinguish fallback vs web font.
  • @axe-core/playwright checks on every page in both locales and themes.

4. Tooling & CI

  • pnpm, Biome (lint + format), lefthook pre-commit:

    • biome check --staged --write (fixes re-staged),
    • astro check (typecheck incl. .astro),
    • feod-analyzer analyze . --fail-on warning (@feod/analyzer, MIT) + Biome noRestrictedImports patterns for deep imports.
  • Vitest (unit + fast-check property tests for the solver and range compaction).

  • Playwright e2e against astro preview (Chromium; WebKit/Firefox if available in CI image).

  • lefthook commit-msg: commitlint (Conventional Commits). Changelog generated from commits by git-cliff into Keep a Changelog format.

  • Cloudflare Workers Builds (no GitHub Actions): the build command runs everything, so every PR gets a check run + preview URL, and a failing check fails the deployment:

    pnpm run verify   # biome ci → astro check → feod-analyzer → vitest run → astro build → playwright test
    

    Deploy: wrangler deploy on main, wrangler versions upload (preview URL) on other branches. wrangler.jsonc serves dist/ as static assets. Node pinned via .node-version, pnpm via the PNPM_VERSION build variable (the build image default may be older than packageManager).

5. Phases

Each phase ends deployable with a green PR check.

Phase 0 — Bootstrap & spikes

  • Astro + Preact + TS strict, Biome, lefthook, Vitest, Playwright, Paraglide (EN/RU), FEOD skeleton with index.ts per entity.
  • Cloudflare Workers Builds connected; verify pipeline running on PRs.
  • Spikes (go/no-go):
    • @feod/analyzer (0.1.x): parses .ts/.tsx only, not .astro (see issues).
    • Done: font parsing in a worker (fontkitten, own metrics format) and @capsizecss/metrics coverage; results in docs/spikes/.

Phase 1 — Core engine (no UI)

  • Font parsing worker, metrics model, fit math, @font-face/CSS generator, stack resolver.
  • Unit tests against known reference outputs (Capsize/Fontaine results for e.g. Inter→Arial, Roboto→Arial).

Phase 2 — MVP generator

  • Upload input, one fallback, FitFields with auto, overlay + side-by-side preview, CSS output, copy button, EN/RU, a11y baseline.

Phase 3 — Audience & per-OS fallbacks

  • Browserslist tag editor with Baseline tags, browserslist-stats.json import, OS mapping, manual mode, per-OS selectors with similarity ranking, stack resolver UI, descriptor support warnings, Safari strategy.

Phase 4 — Layout shift

  • CLS simulator, live metric per viewport, letter/word-spacing fit, "Optimize for CLS".

Phase 5 — unicode-range

  • cmap extraction, coverage-limited ranges, per-script fallback chains with per-script fit.
  • Unicode map and glyph coverage per Unicode block, with counts of covered code points (#100).

Phase 6 — Data & catalog

  • OS availability dataset + schema + sources, metrics extraction script, catalog pages, coverage estimates.

Phase 7 — More inputs

  • Google Fonts picker, site import (bookmarklet, extension, direct CORS fetch, paste CSS).
  • Font collections (.ttc, .otc): list the members, let the user pick one (#99).
  • Preview of text the font cannot render: substitute missing glyphs explicitly and offer per-glyph fallback fonts (#84).

Phase 8 — Presets, exports, sharing

  • Presets page, all export formats, impact report, share links, persistence.

Phase 9 — Polish

  • Full a11y audit, performance (lazy chunks, worker), SEO/meta/OG, guide page, Credits page, README. The guide also covers @font-face syntax, descriptor and format support, font licenses and specification links (#102).
  • Split web font audit of imported and pasted @font-face rules in the generator, CLI and MCP server (#418).
  • Spike: Playwright in the Cloudflare build container (gVisor, Ubuntu 22.04, no root for apt deps), to decide whether e2e can run in the build (#7).
  • More UI languages (the set is chosen after researching the target markets) and a language dropdown instead of the link list in the header (#126).

Backlog

  • Font inspector in the style of everythingfonts.com: colour and background previews (the image background landed in #483), a size waterfall, a glyph viewer with bounding boxes and line metrics, name-table attributes (#101).
  • Offline use and a service-worker update flow: an "Update" toast with a changelog link while the app is open, the new version downloaded in the background, and a toast after an automatic update linking to the combined changelog of all applied versions (#78).
  • Right-to-left interface and an Arabic locale (#221): all layout uses logical properties (inline and block), direction-dependent geometry (the slider, the X-ray lens, the width handle, disclosure glyphs) is mirrored, and the Arabic messages need a native review before the locale ships.

6. Risks

Risk Mitigation
Playwright browsers may not run in Cloudflare's build container (Workers Builds) Spike in Phase 0; options: headless shell only, Chromium-only e2e, or a separate e2e check (needs a decision).
Build time limit / monthly build quota Cache node_modules and Playwright browsers; keep e2e suite focused.
@feod/analyzer is early (0.1.x), single maintainer, prebuilt binaries without provenance, no .astro parsing Kept with mitigations (#50): exact version pin, sha256 verification of the platform binary against scripts/feod-analyzer.sha256.json, execution with a scrubbed environment (it keeps secrets from the analyzer binary, not from the rest of the build command), own relative-path-literal check for .astro, Biome import restrictions as a second line. Revisit if upstream adds provenance or .astro support.
System font metrics vary by OS version Store metrics per OS version where they differ; show "measured on" source.
Safari lacks vertical overrides Explicit residual-shift estimate + font-size-adjust strategy.
No precise "% of users have font X" data exists Estimate from OS availability × browser/OS usage; label as estimate.

7. Credits

Every external source (data, libraries with notable data, inspiration sites, specs) is listed in CREDITS.md with its license, and rendered on a Credits page of the site (linked from the footer).

8. Open questions

  1. If Playwright cannot run in the Cloudflare build: allow a single GitHub Actions job for e2e only, or run e2e Chromium-only / locally? (decided by the spike in Phase 9, #7)