@format.dev/fonts 0.0.0 → 0.1.0

package/README.md

@@ -1,32 +1,100 @@
 # @format.dev/fonts
 
-**This is a bootstrap placeholder. It reserves the package name and does nothing else.**
+Format's built-in font families — Sans, Serif, Mono, Emoji, Math, and Tofu — packaged as one source of truth. The previews (Studio, Engine Dyno) and the PDF renderer (press) load their `@font-face` definitions from here, so a document previews with the same typeface the PDF embeds. No metric or optical drift sits between what an author sees and what ships.
 
-Format is not released yet. Version `0.0.0` is not a usable version of this
-package: it contains no implementation, and installing it gets you an empty
-module.
+This README is the design record for the package; it replaces the earlier planning note.
 
-## Why it exists
+## Two ways to embed a variable font
 
-npm binds a package’s trusted publisher, and its staged-publishing flow, to a
-package that already exists. Creating these names ahead of the first release is
-what lets every real release go out through a reviewed, credential-free
-workflow rather than through a token somebody holds.
+The built-in families are **variable** fonts: each carries its full weight range along an axis, in a single file. A PDF embeds that font in one of two ways, and the two differ in size, optical sizing, and how consistently viewers draw the weight.
 
-This version is published deliberately and deprecated immediately.
+- **Variable master → Type 3.** The PDF engine cannot subset a variable font, so it re-expresses every glyph as a Type 3 drawing procedure. The result runs larger — roughly 100 KB across a typical six-face document — but keeps the variable's automatic optical sizing, and every glyph draws as a plain filled path, so the weight stays consistent from one viewer to the next.
+- **Static instance → CID subset.** Pinning the axis at one point produces an ordinary static font, which embeds as a compact, subset CID TrueType. The file shrinks, but the instance holds one fixed optical size, and CoreGraphics-based viewers (macOS Preview, Quick Look) stem-darken a real font — heavier strokes than the Type 3 path at the same outline.
 
-## Why a bare install resolves it
+No option is small, optically size-aware, _and_ identical across every viewer at once: only Type 3 escapes stem-darkening, and Type 3 is the larger embedding.
 
-npm creates a `latest` tag on a package’s first publish and will not remove it,
-so `latest` points at this placeholder until Format reaches general
-availability. That is why the deprecation warning is there.
+## Choosing a mode
 
-- Beta releases go out under the `beta` tag.
-- General availability is when `latest` moves to a real release.
+A document picks its strategy through the `fonts` prop, which the renderer maps to a variant:
 
-## Format
+```tsx
+<Document title="Q3 report">…</Document>                   // static instances → CID subset (default)
+<Document title="Q3 report" fonts="fidelity">…</Document>   // variable masters → Type 3
+```
 
-- https://format.dev
-- https://github.com/format-hq/format-js
+| `fonts` mode          | Embedding           | File size | Optical sizing      | Weight across viewers |
+| --------------------- | ------------------- | --------- | ------------------- | --------------------- |
+| `compact` _(default)_ | static → CID subset | small     | one fixed size      | varies by viewer      |
+| `fidelity`            | variable → Type 3   | larger    | exact (`opsz auto`) | consistent            |
 
-Licensed under (MIT AND OFL-1.1). The full text ships beside this file.
+Left unset, a document renders in `compact`: the platform defaults to small, deterministic files and accepts the fixed optical size. The `fidelity` mode is the opt-in for authors who need exact optical sizing and viewer-consistent weight and accept the larger file. Both modes share the same family names, so the choice changes the embedding alone — author markup never changes. The default lives in one place, `DEFAULT_FONT_MODE` in `src/mode.ts`.
+
+## Compact PDF text
+
+A static cut embeds as a CID subset, and Format writes its text in one of two ways. A run of glyphs becomes one drawing instruction when every glyph lands exactly where its advance width predicts. If a glyph lands even slightly off, the run closes and the writer starts a new one at a fresh position, so the output drifts toward one instruction per glyph and grows to several times its packed size.
+
+A glyph lands exactly only when its advance is exact in binary floating point. That advance is the glyph's stored width times the font size over the units-per-em, and the division is exact only when the units-per-em is a power of two and the size is a whole pixel. Mono's source, JetBrains Mono, carries a 1000-unit em, so the division leaves a remainder that accrues on every glyph, and Format writes a separate instruction for nearly every one.
+
+The build therefore re-ems any static face that isn't already on a power-of-two em onto a 2048-unit grid (`scale_upem` in `build-fonts.py`). Only the internal grid moves: outlines, advances, kerning, and vertical metrics all scale by the same ratio, so the face looks identical, and the largest coordinate shift lands a few thousandths of a pixel at reading size. The two 1000-em faces, Mono and the copied-through Math face, drop from one instruction per glyph to fully packed runs. Serif (1024) and Sans (2048) are already on a power-of-two em, so they pack as-is and pass through. Emoji and Tofu are colour faces the PDF draws per-glyph regardless, so they pass through too; Tofu is Format's own font, so its em is fixed on a power of two in the tofu package's generator, not here. The variable masters keep their source em, since the `fidelity` path embeds them as Type 3 and writes each glyph separately regardless of the em.
+
+## Families
+
+The package exposes seven canonical family names through `FONT_FAMILIES`. These names are the public contract: the source typeface behind a name can change; the name stays fixed. They must also match the engine's resolved-name table in `packages/engine/src/utils/fonts.rs`.
+
+Only Sans (Adwaita) carries an `opsz` axis, so the static variant ships it in two optical cuts — `Format Sans` for text and `Format Sans Display` for headings — and an author selects Display for large text. Serif (FMT Crimson Pro) and Mono (JetBrains Mono) vary by weight alone. Emoji, Math, and Tofu are already static and pass through unchanged.
+
+## Integrating the package
+
+`variantForMode()` maps a document's `fonts` value to the variant (it lives in the Node-free `@format.dev/fonts/mode`, so a browser preview can import it without the filesystem helpers), and `fontFaceCss()` builds the `@font-face` rules for a given variant and delivery. `documentFontCss()` does both in one call, for a server consumer that injects its own `<style>`:
+
+```ts
+import { documentFontCss, variantForMode } from '@format.dev/fonts'
+
+documentFontCss(doc.fonts, { delivery: 'local' }) // mode → @font-face CSS, in one call
+variantForMode(doc.fonts) // 'fidelity' → 'variable'; anything else (incl. unset) → 'static'
+```
+
+Delivery decides where the bytes come from:
+
+- The previews use `url` delivery — woff2 served over HTTP (`src: url(...)`) — because an end user's machine carries no Format fonts.
+- press uses `local` delivery — installed system fonts (`src: local("<PostScript>")`) — so the cuts ship in the image and one memory-mapped typeface serves every render with no per-request fetch or woff2 decode.
+
+```ts
+// a preview server that injects its own <style>: mode → CSS in one call
+documentFontCss(doc.fonts, { delivery: 'url', baseUrl: '/format-assets/fonts' })
+
+// press: cuts installed as system fonts in the image
+documentFontCss(doc.fonts, { delivery: 'local' })
+```
+
+For bundlers (Vite), the package also ships the two stylesheets prebuilt — `@format.dev/fonts/static.css` and `@format.dev/fonts/variable.css` — each with `url` delivery and relative paths. A bundler preview (the Engine Dyno) imports the one `variantForMode()` selects, and the bundler fingerprints the referenced woff2. A server preview that controls its own `<style>` (Studio) uses `documentFontCss()` instead, so it can swap the variant in place when a document's mode changes.
+
+## Layout
+
+```
+sources/        variable masters (Sans/Serif/Mono) + static Emoji/Math/Tofu — the inputs
+manifest.json   families, weight ranges and step, optical sizes, emoji unicode-ranges
+scripts/
+  build-fonts.py   instances, rebrands, re-ems any non-power-of-two face to 2048 (Mono; Math on copy-through), and compresses the masters to woff2 + ttf; copies the static families; writes fonts/fonts.json
+  emit-css.mjs     writes fonts/static.css and fonts/variable.css from fonts.json
+fonts/          generated, committed: woff2 + ttf, fonts.json descriptors, static.css, variable.css
+src/
+  mode.ts        FontMode, FontVariant, DEFAULT_FONT_MODE, variantForMode() — pure, no Node imports (the @format.dev/fonts/mode export)
+  css.ts         fontFaceCss(), documentFontCss(), loadDescriptors(), fontsDir — Node, reads fonts.json
+  index.ts       FONT_FAMILIES + the public re-exports
+```
+
+## Regenerating the fonts
+
+`fonts/` is committed, so an ordinary `pnpm build` (JavaScript only) needs no font toolchain. Regenerate after editing a master or the manifest:
+
+```
+pip install -r requirements.txt          # fonttools + brotli
+pnpm --filter "@format.dev/fonts" build:fonts  # rebuilds fonts/ and re-emits the stylesheets
+```
+
+CI runs `pnpm --filter @format.dev/fonts check:fonts`, which fails if `fonts/` is stale.
+
+## Future: demand-driven instancing
+
+The two modes force a choice between small files and exact optical sizing. A third path would remove it: the engine collects the exact `(opsz, wght)` coordinates a document uses, instances those into static subsets at render time, and embeds them as compact CID — small files _and_ per-document optical sizing in one mode. The same stem-darkening as any CID embedding still applies, and the approach needs runtime instancing in the engine, so it stays a future direction rather than a third `fonts` value for now.

package/dist/index.cjs

@@ -0,0 +1,82 @@
+const require_mode = require('./mode-DzsrOPvc.cjs');
+let node_fs = require("node:fs");
+let node_url = require("node:url");
+let node_path = require("node:path");
+
+//#region src/css.ts
+/** Absolute path to the generated font files. Serve this from a static server. */
+const fontsDir = (0, node_path.join)((0, node_path.dirname)((0, node_url.fileURLToPath)(require("url").pathToFileURL(__filename).href)), "..", "fonts");
+/** The descriptor list emitted by `scripts/build-fonts.py` — the single source the names/paths come from. */
+function loadDescriptors() {
+	return JSON.parse((0, node_fs.readFileSync)((0, node_path.join)(fontsDir, "fonts.json"), "utf8"));
+}
+/**
+* Generate the `@font-face` CSS for one variant + delivery.
+*
+* `static` emits `Format Sans` (text cuts) + `Format Sans Display` + the Serif/Mono
+* weight palettes; `variable` emits the variable masters (weight ranges, `opsz auto`).
+* Emoji/Math/Tofu are always included. `baseUrl` (the URL `fontsDir` is served under)
+* is required for `url` delivery and ignored for `local`.
+*/
+function fontFaceCss(opts) {
+	const variant = opts.variant ?? "static";
+	const delivery = opts.delivery ?? "url";
+	if (delivery === "url" && !opts.baseUrl) throw new Error("fontFaceCss: `baseUrl` is required for url delivery");
+	const base = (opts.baseUrl ?? "").replace(/\/+$/, "");
+	return loadDescriptors().filter((d) => d.variant === variant || d.variant === "shared").filter((d) => d.deliveries.includes(delivery)).map((d) => {
+		const weight = d.weightRange ? `${d.weightRange[0]} ${d.weightRange[1]}` : `${d.weight}`;
+		const range = d.unicodeRange ? `\n\tunicode-range: ${d.unicodeRange};` : "";
+		const src = delivery === "local" ? `local("${d.postscriptName}")` : `url('${base}/${d.woff2}') format('woff2')`;
+		return [
+			"@font-face {",
+			`\tfont-family: '${d.family}';`,
+			`\tfont-style: ${d.style};`,
+			`\tfont-weight: ${weight};`,
+			"	font-display: block;",
+			`\tsrc: ${src};${range}`,
+			"}"
+		].join("\n");
+	}).join("\n");
+}
+/**
+* Resolve a document's `fonts` mode straight to its `@font-face` CSS — the mode
+* mapping and the CSS generation in one call, so a consumer never composes them
+* itself. press uses `local` delivery (installed system fonts); a preview
+* server that injects its own `<style>` uses `url` delivery with the base URL
+* its woff2 are served under.
+*/
+function documentFontCss(mode, opts) {
+	return fontFaceCss({
+		variant: require_mode.variantForMode(mode),
+		...opts
+	});
+}
+
+//#endregion
+//#region src/index.ts
+/**
+* Canonical, durable family names. These are the public contract — the source
+* typeface behind each may change, the name does not. Must stay in sync with the
+* engine's resolved-name table (`packages/engine/src/utils/fonts.rs`).
+*
+* `sansDisplay` exists because Sans is the only family with an `opsz` axis; it is
+* a static-variant family (authors opt into it for large text).
+*/
+const FONT_FAMILIES = {
+	sans: "Format Sans",
+	sansDisplay: "Format Sans Display",
+	serif: "Format Serif",
+	mono: "Format Mono",
+	emoji: "Format Emoji",
+	math: "Format Math",
+	tofu: "Format Tofu"
+};
+
+//#endregion
+exports.DEFAULT_FONT_MODE = require_mode.DEFAULT_FONT_MODE;
+exports.FONT_FAMILIES = FONT_FAMILIES;
+exports.documentFontCss = documentFontCss;
+exports.fontFaceCss = fontFaceCss;
+exports.fontsDir = fontsDir;
+exports.loadDescriptors = loadDescriptors;
+exports.variantForMode = require_mode.variantForMode;

package/dist/index.d.cts

@@ -0,0 +1,84 @@
+import { i as variantForMode, n as FontMode, r as FontVariant, t as DEFAULT_FONT_MODE } from "./mode-BXEMdEsE.cjs";
+
+//#region src/css.d.ts
+/** Absolute path to the generated font files. Serve this from a static server. */
+declare const fontsDir: string;
+/**
+ * How the bytes reach the browser:
+ * - `url`   — served woff2, `src: url(...)`. For the previews (Studio/Dyno); the
+ *             end user's machine has no Format fonts installed.
+ * - `local` — system TTF, `src: local("<PostScript>")`. For press, where the
+ *             cuts are installed in the image — one mmap'd, process-shared typeface,
+ *             no per-request fetch/decode.
+ */
+type FontDelivery = 'url' | 'local';
+interface FontDescriptor {
+  /** `static`/`variable` are variant-specific; `shared` (emoji/math/tofu) belongs to both. */
+  variant: 'static' | 'variable' | 'shared';
+  family: string;
+  /** Single CSS weight (static/shared faces). */
+  weight?: number;
+  /** `[min, max]` weight range (variable faces). */
+  weightRange?: [number, number];
+  style: 'normal' | 'italic';
+  /** Sans-only optical cut; `null`/absent for weight-only families. */
+  optical?: 'text' | 'display' | null;
+  /** Which deliveries this face supports. */
+  deliveries: FontDelivery[];
+  /** woff2 path relative to `fontsDir` (present for `url` faces). */
+  woff2?: string;
+  /** ttf path relative to `fontsDir` (present for `local` faces; install these in the image). */
+  ttf?: string;
+  /** PostScript name for `src: local(...)` (present for `local` faces). */
+  postscriptName?: string;
+  unicodeRange?: string;
+}
+/** The descriptor list emitted by `scripts/build-fonts.py` — the single source the names/paths come from. */
+declare function loadDescriptors(): FontDescriptor[];
+/**
+ * Generate the `@font-face` CSS for one variant + delivery.
+ *
+ * `static` emits `Format Sans` (text cuts) + `Format Sans Display` + the Serif/Mono
+ * weight palettes; `variable` emits the variable masters (weight ranges, `opsz auto`).
+ * Emoji/Math/Tofu are always included. `baseUrl` (the URL `fontsDir` is served under)
+ * is required for `url` delivery and ignored for `local`.
+ */
+declare function fontFaceCss(opts: {
+  variant?: FontVariant;
+  delivery?: FontDelivery;
+  baseUrl?: string;
+}): string;
+/**
+ * Resolve a document's `fonts` mode straight to its `@font-face` CSS — the mode
+ * mapping and the CSS generation in one call, so a consumer never composes them
+ * itself. press uses `local` delivery (installed system fonts); a preview
+ * server that injects its own `<style>` uses `url` delivery with the base URL
+ * its woff2 are served under.
+ */
+declare function documentFontCss(mode: string | null | undefined, opts: {
+  delivery: FontDelivery;
+  baseUrl?: string;
+}): string;
+//#endregion
+//#region src/index.d.ts
+/**
+ * Canonical, durable family names. These are the public contract — the source
+ * typeface behind each may change, the name does not. Must stay in sync with the
+ * engine's resolved-name table (`packages/engine/src/utils/fonts.rs`).
+ *
+ * `sansDisplay` exists because Sans is the only family with an `opsz` axis; it is
+ * a static-variant family (authors opt into it for large text).
+ */
+declare const FONT_FAMILIES: {
+  readonly sans: "Format Sans";
+  readonly sansDisplay: "Format Sans Display";
+  readonly serif: "Format Serif";
+  readonly mono: "Format Mono";
+  readonly emoji: "Format Emoji";
+  readonly math: "Format Math";
+  readonly tofu: "Format Tofu";
+};
+type FontFamilyKey = keyof typeof FONT_FAMILIES;
+//#endregion
+export { DEFAULT_FONT_MODE, FONT_FAMILIES, type FontDelivery, type FontDescriptor, FontFamilyKey, type FontMode, type FontVariant, documentFontCss, fontFaceCss, fontsDir, loadDescriptors, variantForMode };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/css.ts","../src/index.ts"],"sourcesContent":[],"mappings":";;;;cAMa;AAAb;AAUA;AAEA;AAuBA;AAYA;AAuCA;;;KA5EY,YAAA;ACHC,UDKI,cAAA,CCGP;EAEE;;;;;;;;;;;cDOC;;;;;;;;;;iBAWG,eAAA,CAAA,GAAmB;;;;;;;;;iBAYnB,WAAA;YAA8B;aAAwB;;;;;;;;;;iBAuCtD,eAAA;YAEG;;;;;AA9EnB;AAEA;AAuBA;AAYA;AAuCA;;;;AC/Ea,cAAA,aAQH,EAAA;EAEE,SAAA,IAAA,EAAA,aAA6B;;;;;;;;KAA7B,aAAA,gBAA6B"}

package/dist/index.d.mts

@@ -0,0 +1,84 @@
+import { i as variantForMode, n as FontMode, r as FontVariant, t as DEFAULT_FONT_MODE } from "./mode-CtSoe83u.mjs";
+
+//#region src/css.d.ts
+/** Absolute path to the generated font files. Serve this from a static server. */
+declare const fontsDir: string;
+/**
+ * How the bytes reach the browser:
+ * - `url`   — served woff2, `src: url(...)`. For the previews (Studio/Dyno); the
+ *             end user's machine has no Format fonts installed.
+ * - `local` — system TTF, `src: local("<PostScript>")`. For press, where the
+ *             cuts are installed in the image — one mmap'd, process-shared typeface,
+ *             no per-request fetch/decode.
+ */
+type FontDelivery = 'url' | 'local';
+interface FontDescriptor {
+  /** `static`/`variable` are variant-specific; `shared` (emoji/math/tofu) belongs to both. */
+  variant: 'static' | 'variable' | 'shared';
+  family: string;
+  /** Single CSS weight (static/shared faces). */
+  weight?: number;
+  /** `[min, max]` weight range (variable faces). */
+  weightRange?: [number, number];
+  style: 'normal' | 'italic';
+  /** Sans-only optical cut; `null`/absent for weight-only families. */
+  optical?: 'text' | 'display' | null;
+  /** Which deliveries this face supports. */
+  deliveries: FontDelivery[];
+  /** woff2 path relative to `fontsDir` (present for `url` faces). */
+  woff2?: string;
+  /** ttf path relative to `fontsDir` (present for `local` faces; install these in the image). */
+  ttf?: string;
+  /** PostScript name for `src: local(...)` (present for `local` faces). */
+  postscriptName?: string;
+  unicodeRange?: string;
+}
+/** The descriptor list emitted by `scripts/build-fonts.py` — the single source the names/paths come from. */
+declare function loadDescriptors(): FontDescriptor[];
+/**
+ * Generate the `@font-face` CSS for one variant + delivery.
+ *
+ * `static` emits `Format Sans` (text cuts) + `Format Sans Display` + the Serif/Mono
+ * weight palettes; `variable` emits the variable masters (weight ranges, `opsz auto`).
+ * Emoji/Math/Tofu are always included. `baseUrl` (the URL `fontsDir` is served under)
+ * is required for `url` delivery and ignored for `local`.
+ */
+declare function fontFaceCss(opts: {
+  variant?: FontVariant;
+  delivery?: FontDelivery;
+  baseUrl?: string;
+}): string;
+/**
+ * Resolve a document's `fonts` mode straight to its `@font-face` CSS — the mode
+ * mapping and the CSS generation in one call, so a consumer never composes them
+ * itself. press uses `local` delivery (installed system fonts); a preview
+ * server that injects its own `<style>` uses `url` delivery with the base URL
+ * its woff2 are served under.
+ */
+declare function documentFontCss(mode: string | null | undefined, opts: {
+  delivery: FontDelivery;
+  baseUrl?: string;
+}): string;
+//#endregion
+//#region src/index.d.ts
+/**
+ * Canonical, durable family names. These are the public contract — the source
+ * typeface behind each may change, the name does not. Must stay in sync with the
+ * engine's resolved-name table (`packages/engine/src/utils/fonts.rs`).
+ *
+ * `sansDisplay` exists because Sans is the only family with an `opsz` axis; it is
+ * a static-variant family (authors opt into it for large text).
+ */
+declare const FONT_FAMILIES: {
+  readonly sans: "Format Sans";
+  readonly sansDisplay: "Format Sans Display";
+  readonly serif: "Format Serif";
+  readonly mono: "Format Mono";
+  readonly emoji: "Format Emoji";
+  readonly math: "Format Math";
+  readonly tofu: "Format Tofu";
+};
+type FontFamilyKey = keyof typeof FONT_FAMILIES;
+//#endregion
+export { DEFAULT_FONT_MODE, FONT_FAMILIES, type FontDelivery, type FontDescriptor, FontFamilyKey, type FontMode, type FontVariant, documentFontCss, fontFaceCss, fontsDir, loadDescriptors, variantForMode };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/css.ts","../src/index.ts"],"sourcesContent":[],"mappings":";;;;cAMa;AAAb;AAUA;AAEA;AAuBA;AAYA;AAuCA;;;KA5EY,YAAA;ACHC,UDKI,cAAA,CCGP;EAEE;;;;;;;;;;;cDOC;;;;;;;;;;iBAWG,eAAA,CAAA,GAAmB;;;;;;;;;iBAYnB,WAAA;YAA8B;aAAwB;;;;;;;;;;iBAuCtD,eAAA;YAEG;;;;;AA9EnB;AAEA;AAuBA;AAYA;AAuCA;;;;AC/Ea,cAAA,aAQH,EAAA;EAEE,SAAA,IAAA,EAAA,aAA6B;;;;;;;;KAA7B,aAAA,gBAA6B"}

package/dist/index.mjs

@@ -0,0 +1,77 @@
+import { n as variantForMode, t as DEFAULT_FONT_MODE } from "./mode-B8fVsgsV.mjs";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+//#region src/css.ts
+/** Absolute path to the generated font files. Serve this from a static server. */
+const fontsDir = join(dirname(fileURLToPath(import.meta.url)), "..", "fonts");
+/** The descriptor list emitted by `scripts/build-fonts.py` — the single source the names/paths come from. */
+function loadDescriptors() {
+	return JSON.parse(readFileSync(join(fontsDir, "fonts.json"), "utf8"));
+}
+/**
+* Generate the `@font-face` CSS for one variant + delivery.
+*
+* `static` emits `Format Sans` (text cuts) + `Format Sans Display` + the Serif/Mono
+* weight palettes; `variable` emits the variable masters (weight ranges, `opsz auto`).
+* Emoji/Math/Tofu are always included. `baseUrl` (the URL `fontsDir` is served under)
+* is required for `url` delivery and ignored for `local`.
+*/
+function fontFaceCss(opts) {
+	const variant = opts.variant ?? "static";
+	const delivery = opts.delivery ?? "url";
+	if (delivery === "url" && !opts.baseUrl) throw new Error("fontFaceCss: `baseUrl` is required for url delivery");
+	const base = (opts.baseUrl ?? "").replace(/\/+$/, "");
+	return loadDescriptors().filter((d) => d.variant === variant || d.variant === "shared").filter((d) => d.deliveries.includes(delivery)).map((d) => {
+		const weight = d.weightRange ? `${d.weightRange[0]} ${d.weightRange[1]}` : `${d.weight}`;
+		const range = d.unicodeRange ? `\n\tunicode-range: ${d.unicodeRange};` : "";
+		const src = delivery === "local" ? `local("${d.postscriptName}")` : `url('${base}/${d.woff2}') format('woff2')`;
+		return [
+			"@font-face {",
+			`\tfont-family: '${d.family}';`,
+			`\tfont-style: ${d.style};`,
+			`\tfont-weight: ${weight};`,
+			"	font-display: block;",
+			`\tsrc: ${src};${range}`,
+			"}"
+		].join("\n");
+	}).join("\n");
+}
+/**
+* Resolve a document's `fonts` mode straight to its `@font-face` CSS — the mode
+* mapping and the CSS generation in one call, so a consumer never composes them
+* itself. press uses `local` delivery (installed system fonts); a preview
+* server that injects its own `<style>` uses `url` delivery with the base URL
+* its woff2 are served under.
+*/
+function documentFontCss(mode, opts) {
+	return fontFaceCss({
+		variant: variantForMode(mode),
+		...opts
+	});
+}
+
+//#endregion
+//#region src/index.ts
+/**
+* Canonical, durable family names. These are the public contract — the source
+* typeface behind each may change, the name does not. Must stay in sync with the
+* engine's resolved-name table (`packages/engine/src/utils/fonts.rs`).
+*
+* `sansDisplay` exists because Sans is the only family with an `opsz` axis; it is
+* a static-variant family (authors opt into it for large text).
+*/
+const FONT_FAMILIES = {
+	sans: "Format Sans",
+	sansDisplay: "Format Sans Display",
+	serif: "Format Serif",
+	mono: "Format Mono",
+	emoji: "Format Emoji",
+	math: "Format Math",
+	tofu: "Format Tofu"
+};
+
+//#endregion
+export { DEFAULT_FONT_MODE, FONT_FAMILIES, documentFontCss, fontFaceCss, fontsDir, loadDescriptors, variantForMode };
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/css.ts","../src/index.ts"],"sourcesContent":["import { readFileSync } from 'node:fs'\nimport { fileURLToPath } from 'node:url'\nimport { dirname, join } from 'node:path'\nimport { variantForMode, type FontVariant } from './mode.js'\n\n/** Absolute path to the generated font files. Serve this from a static server. */\nexport const fontsDir = join(dirname(fileURLToPath(import.meta.url)), '..', 'fonts')\n\n/**\n * How the bytes reach the browser:\n * - `url`   — served woff2, `src: url(...)`. For the previews (Studio/Dyno); the\n *             end user's machine has no Format fonts installed.\n * - `local` — system TTF, `src: local(\"<PostScript>\")`. For press, where the\n *             cuts are installed in the image — one mmap'd, process-shared typeface,\n *             no per-request fetch/decode.\n */\nexport type FontDelivery = 'url' | 'local'\n\nexport interface FontDescriptor {\n\t/** `static`/`variable` are variant-specific; `shared` (emoji/math/tofu) belongs to both. */\n\tvariant: 'static' | 'variable' | 'shared'\n\tfamily: string\n\t/** Single CSS weight (static/shared faces). */\n\tweight?: number\n\t/** `[min, max]` weight range (variable faces). */\n\tweightRange?: [number, number]\n\tstyle: 'normal' | 'italic'\n\t/** Sans-only optical cut; `null`/absent for weight-only families. */\n\toptical?: 'text' | 'display' | null\n\t/** Which deliveries this face supports. */\n\tdeliveries: FontDelivery[]\n\t/** woff2 path relative to `fontsDir` (present for `url` faces). */\n\twoff2?: string\n\t/** ttf path relative to `fontsDir` (present for `local` faces; install these in the image). */\n\tttf?: string\n\t/** PostScript name for `src: local(...)` (present for `local` faces). */\n\tpostscriptName?: string\n\tunicodeRange?: string\n}\n\n/** The descriptor list emitted by `scripts/build-fonts.py` — the single source the names/paths come from. */\nexport function loadDescriptors(): FontDescriptor[] {\n\treturn JSON.parse(readFileSync(join(fontsDir, 'fonts.json'), 'utf8')) as FontDescriptor[]\n}\n\n/**\n * Generate the `@font-face` CSS for one variant + delivery.\n *\n * `static` emits `Format Sans` (text cuts) + `Format Sans Display` + the Serif/Mono\n * weight palettes; `variable` emits the variable masters (weight ranges, `opsz auto`).\n * Emoji/Math/Tofu are always included. `baseUrl` (the URL `fontsDir` is served under)\n * is required for `url` delivery and ignored for `local`.\n */\nexport function fontFaceCss(opts: { variant?: FontVariant; delivery?: FontDelivery; baseUrl?: string }): string {\n\tconst variant = opts.variant ?? 'static'\n\tconst delivery = opts.delivery ?? 'url'\n\n\tif (delivery === 'url' && !opts.baseUrl) {\n\t\tthrow new Error('fontFaceCss: `baseUrl` is required for url delivery')\n\t}\n\tconst base = (opts.baseUrl ?? '').replace(/\\/+$/, '')\n\n\tconst faces = loadDescriptors()\n\t\t.filter(d => d.variant === variant || d.variant === 'shared')\n\t\t.filter(d => d.deliveries.includes(delivery))\n\n\treturn faces\n\t\t.map(d => {\n\t\t\tconst weight = d.weightRange ? `${d.weightRange[0]} ${d.weightRange[1]}` : `${d.weight}`\n\t\t\tconst range = d.unicodeRange ? `\\n\\tunicode-range: ${d.unicodeRange};` : ''\n\t\t\tconst src = delivery === 'local' ? `local(\"${d.postscriptName}\")` : `url('${base}/${d.woff2}') format('woff2')`\n\n\t\t\treturn [\n\t\t\t\t'@font-face {',\n\t\t\t\t`\\tfont-family: '${d.family}';`,\n\t\t\t\t`\\tfont-style: ${d.style};`,\n\t\t\t\t`\\tfont-weight: ${weight};`,\n\t\t\t\t'\\tfont-display: block;',\n\t\t\t\t`\\tsrc: ${src};${range}`,\n\t\t\t\t'}'\n\t\t\t].join('\\n')\n\t\t})\n\t\t.join('\\n')\n}\n\n/**\n * Resolve a document's `fonts` mode straight to its `@font-face` CSS — the mode\n * mapping and the CSS generation in one call, so a consumer never composes them\n * itself. press uses `local` delivery (installed system fonts); a preview\n * server that injects its own `<style>` uses `url` delivery with the base URL\n * its woff2 are served under.\n */\nexport function documentFontCss(\n\tmode: string | null | undefined,\n\topts: { delivery: FontDelivery; baseUrl?: string }\n): string {\n\treturn fontFaceCss({ variant: variantForMode(mode), ...opts })\n}\n","export { fontFaceCss, documentFontCss, loadDescriptors, fontsDir } from './css.js'\nexport type { FontDelivery, FontDescriptor } from './css.js'\nexport { variantForMode, DEFAULT_FONT_MODE } from './mode.js'\nexport type { FontVariant, FontMode } from './mode.js'\n\n/**\n * Canonical, durable family names. These are the public contract — the source\n * typeface behind each may change, the name does not. Must stay in sync with the\n * engine's resolved-name table (`packages/engine/src/utils/fonts.rs`).\n *\n * `sansDisplay` exists because Sans is the only family with an `opsz` axis; it is\n * a static-variant family (authors opt into it for large text).\n */\nexport const FONT_FAMILIES = {\n\tsans: 'Format Sans',\n\tsansDisplay: 'Format Sans Display',\n\tserif: 'Format Serif',\n\tmono: 'Format Mono',\n\temoji: 'Format Emoji',\n\tmath: 'Format Math',\n\ttofu: 'Format Tofu'\n} as const\n\nexport type FontFamilyKey = keyof typeof FONT_FAMILIES\n"],"mappings":";;;;;;;AAMA,MAAa,WAAW,KAAK,QAAQ,cAAc,OAAO,KAAK,IAAI,CAAC,EAAE,MAAM,QAAQ;;AAmCpF,SAAgB,kBAAoC;AACnD,QAAO,KAAK,MAAM,aAAa,KAAK,UAAU,aAAa,EAAE,OAAO,CAAC;;;;;;;;;;AAWtE,SAAgB,YAAY,MAAoF;CAC/G,MAAM,UAAU,KAAK,WAAW;CAChC,MAAM,WAAW,KAAK,YAAY;AAElC,KAAI,aAAa,SAAS,CAAC,KAAK,QAC/B,OAAM,IAAI,MAAM,sDAAsD;CAEvE,MAAM,QAAQ,KAAK,WAAW,IAAI,QAAQ,QAAQ,GAAG;AAMrD,QAJc,iBAAiB,CAC7B,QAAO,MAAK,EAAE,YAAY,WAAW,EAAE,YAAY,SAAS,CAC5D,QAAO,MAAK,EAAE,WAAW,SAAS,SAAS,CAAC,CAG5C,KAAI,MAAK;EACT,MAAM,SAAS,EAAE,cAAc,GAAG,EAAE,YAAY,GAAG,GAAG,EAAE,YAAY,OAAO,GAAG,EAAE;EAChF,MAAM,QAAQ,EAAE,eAAe,sBAAsB,EAAE,aAAa,KAAK;EACzE,MAAM,MAAM,aAAa,UAAU,UAAU,EAAE,eAAe,MAAM,QAAQ,KAAK,GAAG,EAAE,MAAM;AAE5F,SAAO;GACN;GACA,mBAAmB,EAAE,OAAO;GAC5B,iBAAiB,EAAE,MAAM;GACzB,kBAAkB,OAAO;GACzB;GACA,UAAU,IAAI,GAAG;GACjB;GACA,CAAC,KAAK,KAAK;GACX,CACD,KAAK,KAAK;;;;;;;;;AAUb,SAAgB,gBACf,MACA,MACS;AACT,QAAO,YAAY;EAAE,SAAS,eAAe,KAAK;EAAE,GAAG;EAAM,CAAC;;;;;;;;;;;;;ACnF/D,MAAa,gBAAgB;CAC5B,MAAM;CACN,aAAa;CACb,OAAO;CACP,MAAM;CACN,OAAO;CACP,MAAM;CACN,MAAM;CACN"}

package/dist/mode-B8fVsgsV.mjs

@@ -0,0 +1,26 @@
+//#region src/mode.ts
+/**
+* The mode an unset or unrecognised `fonts` value resolves to. Compact embeds
+* static instances (CID subset): smaller files, one fixed optical size. Most
+* documents take this default. Fidelity is the opt-in for exact optical sizing
+* and viewer-consistent weight, at a larger file.
+*/
+const DEFAULT_FONT_MODE = "compact";
+/**
+* Resolve the author-facing mode to an embedding variant. Fidelity embeds the
+* variable masters (Type 3: exact optical sizing, identical weight in every
+* viewer); compact embeds static instances (CID subset: smaller files, fixed
+* optical size). An absent or unknown value resolves to DEFAULT_FONT_MODE.
+*
+* This is the one definition of the mapping and the default, so the previews,
+* press, and Studio can never disagree on either. It has no Node imports, so
+* a browser preview can call it without pulling the filesystem-backed helpers in
+* `css.ts`.
+*/
+function variantForMode(mode) {
+	return (mode === "fidelity" || mode === "compact" ? mode : DEFAULT_FONT_MODE) === "fidelity" ? "variable" : "static";
+}
+
+//#endregion
+export { variantForMode as n, DEFAULT_FONT_MODE as t };
+//# sourceMappingURL=mode-B8fVsgsV.mjs.map

package/dist/mode-B8fVsgsV.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"mode-B8fVsgsV.mjs","names":["DEFAULT_FONT_MODE: FontMode"],"sources":["../src/mode.ts"],"sourcesContent":["export type FontVariant = 'static' | 'variable'\n\n/** Author-facing font strategy, set on `<Document fonts>`. */\nexport type FontMode = 'fidelity' | 'compact'\n\n/**\n * The mode an unset or unrecognised `fonts` value resolves to. Compact embeds\n * static instances (CID subset): smaller files, one fixed optical size. Most\n * documents take this default. Fidelity is the opt-in for exact optical sizing\n * and viewer-consistent weight, at a larger file.\n */\nexport const DEFAULT_FONT_MODE: FontMode = 'compact'\n\n/**\n * Resolve the author-facing mode to an embedding variant. Fidelity embeds the\n * variable masters (Type 3: exact optical sizing, identical weight in every\n * viewer); compact embeds static instances (CID subset: smaller files, fixed\n * optical size). An absent or unknown value resolves to DEFAULT_FONT_MODE.\n *\n * This is the one definition of the mapping and the default, so the previews,\n * press, and Studio can never disagree on either. It has no Node imports, so\n * a browser preview can call it without pulling the filesystem-backed helpers in\n * `css.ts`.\n */\nexport function variantForMode(mode?: string | null): FontVariant {\n\tconst resolved = mode === 'fidelity' || mode === 'compact' ? mode : DEFAULT_FONT_MODE\n\treturn resolved === 'fidelity' ? 'variable' : 'static'\n}\n"],"mappings":";;;;;;;AAWA,MAAaA,oBAA8B;;;;;;;;;;;;AAa3C,SAAgB,eAAe,MAAmC;AAEjE,SADiB,SAAS,cAAc,SAAS,YAAY,OAAO,uBAChD,aAAa,aAAa"}

package/dist/mode-BXEMdEsE.d.cts

@@ -0,0 +1,26 @@
+//#region src/mode.d.ts
+type FontVariant = 'static' | 'variable';
+/** Author-facing font strategy, set on `<Document fonts>`. */
+type FontMode = 'fidelity' | 'compact';
+/**
+ * The mode an unset or unrecognised `fonts` value resolves to. Compact embeds
+ * static instances (CID subset): smaller files, one fixed optical size. Most
+ * documents take this default. Fidelity is the opt-in for exact optical sizing
+ * and viewer-consistent weight, at a larger file.
+ */
+declare const DEFAULT_FONT_MODE: FontMode;
+/**
+ * Resolve the author-facing mode to an embedding variant. Fidelity embeds the
+ * variable masters (Type 3: exact optical sizing, identical weight in every
+ * viewer); compact embeds static instances (CID subset: smaller files, fixed
+ * optical size). An absent or unknown value resolves to DEFAULT_FONT_MODE.
+ *
+ * This is the one definition of the mapping and the default, so the previews,
+ * press, and Studio can never disagree on either. It has no Node imports, so
+ * a browser preview can call it without pulling the filesystem-backed helpers in
+ * `css.ts`.
+ */
+declare function variantForMode(mode?: string | null): FontVariant;
+//#endregion
+export { variantForMode as i, FontMode as n, FontVariant as r, DEFAULT_FONT_MODE as t };
+//# sourceMappingURL=mode-BXEMdEsE.d.cts.map

package/dist/mode-BXEMdEsE.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mode-BXEMdEsE.d.cts","names":[],"sources":["../src/mode.ts"],"sourcesContent":[],"mappings":";KAAY,WAAA;AAAZ;AAGY,KAAA,QAAA,GAAQ,UAAA,GAAA,SAAA;AAQpB;AAaA;;;;;cAba,mBAAmB;;;;;;;;;;;;iBAahB,cAAA,wBAAsC"}

package/dist/mode-CtSoe83u.d.mts

@@ -0,0 +1,26 @@
+//#region src/mode.d.ts
+type FontVariant = 'static' | 'variable';
+/** Author-facing font strategy, set on `<Document fonts>`. */
+type FontMode = 'fidelity' | 'compact';
+/**
+ * The mode an unset or unrecognised `fonts` value resolves to. Compact embeds
+ * static instances (CID subset): smaller files, one fixed optical size. Most
+ * documents take this default. Fidelity is the opt-in for exact optical sizing
+ * and viewer-consistent weight, at a larger file.
+ */
+declare const DEFAULT_FONT_MODE: FontMode;
+/**
+ * Resolve the author-facing mode to an embedding variant. Fidelity embeds the
+ * variable masters (Type 3: exact optical sizing, identical weight in every
+ * viewer); compact embeds static instances (CID subset: smaller files, fixed
+ * optical size). An absent or unknown value resolves to DEFAULT_FONT_MODE.
+ *
+ * This is the one definition of the mapping and the default, so the previews,
+ * press, and Studio can never disagree on either. It has no Node imports, so
+ * a browser preview can call it without pulling the filesystem-backed helpers in
+ * `css.ts`.
+ */
+declare function variantForMode(mode?: string | null): FontVariant;
+//#endregion
+export { variantForMode as i, FontMode as n, FontVariant as r, DEFAULT_FONT_MODE as t };
+//# sourceMappingURL=mode-CtSoe83u.d.mts.map

package/dist/mode-CtSoe83u.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mode-CtSoe83u.d.mts","names":[],"sources":["../src/mode.ts"],"sourcesContent":[],"mappings":";KAAY,WAAA;AAAZ;AAGY,KAAA,QAAA,GAAQ,UAAA,GAAA,SAAA;AAQpB;AAaA;;;;;cAba,mBAAmB;;;;;;;;;;;;iBAahB,cAAA,wBAAsC"}

package/dist/mode-DzsrOPvc.cjs

@@ -0,0 +1,37 @@
+
+//#region src/mode.ts
+/**
+* The mode an unset or unrecognised `fonts` value resolves to. Compact embeds
+* static instances (CID subset): smaller files, one fixed optical size. Most
+* documents take this default. Fidelity is the opt-in for exact optical sizing
+* and viewer-consistent weight, at a larger file.
+*/
+const DEFAULT_FONT_MODE = "compact";
+/**
+* Resolve the author-facing mode to an embedding variant. Fidelity embeds the
+* variable masters (Type 3: exact optical sizing, identical weight in every
+* viewer); compact embeds static instances (CID subset: smaller files, fixed
+* optical size). An absent or unknown value resolves to DEFAULT_FONT_MODE.
+*
+* This is the one definition of the mapping and the default, so the previews,
+* press, and Studio can never disagree on either. It has no Node imports, so
+* a browser preview can call it without pulling the filesystem-backed helpers in
+* `css.ts`.
+*/
+function variantForMode(mode) {
+	return (mode === "fidelity" || mode === "compact" ? mode : DEFAULT_FONT_MODE) === "fidelity" ? "variable" : "static";
+}
+
+//#endregion
+Object.defineProperty(exports, 'DEFAULT_FONT_MODE', {
+  enumerable: true,
+  get: function () {
+    return DEFAULT_FONT_MODE;
+  }
+});
+Object.defineProperty(exports, 'variantForMode', {
+  enumerable: true,
+  get: function () {
+    return variantForMode;
+  }
+});

package/dist/mode.cjs

@@ -0,0 +1,4 @@
+const require_mode = require('./mode-DzsrOPvc.cjs');
+
+exports.DEFAULT_FONT_MODE = require_mode.DEFAULT_FONT_MODE;
+exports.variantForMode = require_mode.variantForMode;

package/dist/mode.d.cts

@@ -0,0 +1,2 @@
+import { i as variantForMode, n as FontMode, r as FontVariant, t as DEFAULT_FONT_MODE } from "./mode-BXEMdEsE.cjs";
+export { DEFAULT_FONT_MODE, FontMode, FontVariant, variantForMode };

package/dist/mode.d.mts

@@ -0,0 +1,2 @@
+import { i as variantForMode, n as FontMode, r as FontVariant, t as DEFAULT_FONT_MODE } from "./mode-CtSoe83u.mjs";
+export { DEFAULT_FONT_MODE, FontMode, FontVariant, variantForMode };

package/dist/mode.mjs

@@ -0,0 +1,3 @@
+import { n as variantForMode, t as DEFAULT_FONT_MODE } from "./mode-B8fVsgsV.mjs";
+
+export { DEFAULT_FONT_MODE, variantForMode };