@nowline/export-core 0.2.0

package/src/fonts/probe-list.ts

@@ -0,0 +1,143 @@
+// Per-platform candidate-font tables walked by `resolveFonts()`.
+//
+// Spec: specs/handoffs/m2c.md § 10 "Platform probe list".
+//
+// `path` segments use forward slashes; the resolver normalizes via
+// `path.normalize()` at lookup time so Windows paths work correctly.
+// `face` is set for `.ttc` collections — the resolver loads the TTC and
+// hands the face PostScript name to PDFKit / resvg via `ResolvedFont.face`.
+
+// Use platform-specific path joiners so Windows paths render with backslashes
+// even when the resolver runs on a non-Windows host (e.g. test mocks on macOS
+// CI exercising the win32 probe list).
+import * as path from 'node:path';
+
+export interface FontCandidate {
+    path: string;
+    face?: string;
+    /** Friendly family name surfaced in `ResolvedFont.name`. */
+    name: string;
+}
+
+export interface PlatformProbe {
+    sans: readonly FontCandidate[];
+    mono: readonly FontCandidate[];
+}
+
+const MACOS: PlatformProbe = {
+    sans: [
+        { path: '/System/Library/Fonts/SFNS.ttf', name: 'SF Pro' },
+        { path: '/System/Library/Fonts/Helvetica.ttc', face: 'Helvetica', name: 'Helvetica' },
+        { path: '/System/Library/Fonts/Supplemental/Arial.ttf', name: 'Arial' },
+    ],
+    mono: [
+        { path: '/System/Library/Fonts/SFNSMono.ttf', name: 'SF Mono' },
+        { path: '/System/Library/Fonts/Menlo.ttc', face: 'Menlo-Regular', name: 'Menlo' },
+        { path: '/System/Library/Fonts/Monaco.ttf', name: 'Monaco' },
+    ],
+};
+
+function windowsCandidate(fontsDir: string, file: string, name: string): FontCandidate {
+    return { path: path.win32.join(fontsDir, file), name };
+}
+
+function windowsProbe(fontsDir: string): PlatformProbe {
+    return {
+        sans: [
+            windowsCandidate(fontsDir, 'segoeui.ttf', 'Segoe UI'),
+            windowsCandidate(fontsDir, 'arial.ttf', 'Arial'),
+            windowsCandidate(fontsDir, 'tahoma.ttf', 'Tahoma'),
+            windowsCandidate(fontsDir, 'verdana.ttf', 'Verdana'),
+        ],
+        mono: [
+            windowsCandidate(fontsDir, 'consola.ttf', 'Consolas'),
+            windowsCandidate(fontsDir, 'cour.ttf', 'Courier New'),
+        ],
+    };
+}
+
+const LINUX: PlatformProbe = {
+    sans: [
+        { path: '/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf', name: 'DejaVu Sans' },
+        { path: '/usr/share/fonts/dejavu/DejaVuSans.ttf', name: 'DejaVu Sans' },
+        { path: '/usr/share/fonts/TTF/DejaVuSans.ttf', name: 'DejaVu Sans' },
+        { path: '/usr/share/fonts/liberation/LiberationSans-Regular.ttf', name: 'Liberation Sans' },
+        {
+            path: '/usr/share/fonts/truetype/liberation/LiberationSans-Regular.ttf',
+            name: 'Liberation Sans',
+        },
+        { path: '/usr/share/fonts/truetype/noto/NotoSans-Regular.ttf', name: 'Noto Sans' },
+        { path: '/usr/share/fonts/ubuntu/Ubuntu-R.ttf', name: 'Ubuntu' },
+        { path: '/usr/share/fonts/cantarell/Cantarell-Regular.otf', name: 'Cantarell' },
+    ],
+    mono: [
+        { path: '/usr/share/fonts/truetype/dejavu/DejaVuSansMono.ttf', name: 'DejaVu Sans Mono' },
+        { path: '/usr/share/fonts/dejavu/DejaVuSansMono.ttf', name: 'DejaVu Sans Mono' },
+        { path: '/usr/share/fonts/TTF/DejaVuSansMono.ttf', name: 'DejaVu Sans Mono' },
+        { path: '/usr/share/fonts/liberation/LiberationMono-Regular.ttf', name: 'Liberation Mono' },
+        {
+            path: '/usr/share/fonts/truetype/liberation/LiberationMono-Regular.ttf',
+            name: 'Liberation Mono',
+        },
+        { path: '/usr/share/fonts/ubuntu/UbuntuMono-R.ttf', name: 'Ubuntu Mono' },
+        { path: '/usr/share/fonts/truetype/noto/NotoSansMono-Regular.ttf', name: 'Noto Sans Mono' },
+    ],
+};
+
+export function probeListFor(
+    platform: NodeJS.Platform,
+    env: NodeJS.ProcessEnv = process.env,
+): PlatformProbe {
+    if (platform === 'darwin') return MACOS;
+    if (platform === 'win32') {
+        const fontsDir = path.win32.join(env.WINDIR ?? 'C:\\Windows', 'Fonts');
+        return windowsProbe(fontsDir);
+    }
+    return LINUX;
+}
+
+/**
+ * Aliases for `--font-sans` / `--font-mono`. Resolves to the platform-default
+ * candidate for that family. `dejavu` always resolves to the bundled fallback
+ * regardless of platform — handled in resolver.ts.
+ */
+export const ALIASES: Readonly<Record<string, { sans?: string; mono?: string }>> = {
+    sf: { sans: 'SF Pro', mono: 'SF Mono' },
+    segoe: { sans: 'Segoe UI', mono: 'Consolas' },
+    dejavu: { sans: 'DejaVu Sans', mono: 'DejaVu Sans Mono' },
+    helvetica: { sans: 'Helvetica' },
+    arial: { sans: 'Arial' },
+    tahoma: { sans: 'Tahoma' },
+    verdana: { sans: 'Verdana' },
+    liberation: { sans: 'Liberation Sans', mono: 'Liberation Mono' },
+    noto: { sans: 'Noto Sans', mono: 'Noto Sans Mono' },
+    ubuntu: { sans: 'Ubuntu', mono: 'Ubuntu Mono' },
+    cantarell: { sans: 'Cantarell' },
+    menlo: { mono: 'Menlo' },
+    consolas: { mono: 'Consolas' },
+    monaco: { mono: 'Monaco' },
+    courier: { mono: 'Courier New' },
+};
+
+export function isAlias(value: string): boolean {
+    return Object.hasOwn(ALIASES, value.toLowerCase());
+}
+
+/**
+ * Look up the candidate corresponding to an alias for the given role.
+ *
+ * Returns `undefined` if the alias doesn't have an entry for that role
+ * (e.g. `--font-sans menlo` makes no sense — menlo is a mono family).
+ */
+export function aliasCandidate(
+    alias: string,
+    role: 'sans' | 'mono',
+    probe: PlatformProbe,
+): FontCandidate | undefined {
+    const entry = ALIASES[alias.toLowerCase()];
+    if (!entry) return undefined;
+    const target = entry[role];
+    if (!target) return undefined;
+    const list = probe[role];
+    return list.find((c) => c.name === target);
+}

package/src/fonts/resolve.ts

@@ -0,0 +1,228 @@
+// 5-step font resolver shared by PDF and PNG.
+//
+// Spec: specs/handoffs/m2c.md § 10 "Font strategy — system first, one
+// bundled headless fallback".
+//
+// Resolution order (run independently for sans / mono — first hit wins):
+//   1. Explicit flag    — `--font-sans <path|alias>` / `--font-mono <path|alias>`
+//   2. Environment      — NOWLINE_FONT_SANS / NOWLINE_FONT_MONO
+//   3. Headless override — `--headless`, NOWLINE_HEADLESS=1, or auto in CI
+//                          without a TTY
+//   4. Platform probe   — first existing entry from `probe-list.ts`
+//   5. Bundled fallback — DejaVuSans.ttf / DejaVuSansMono.ttf
+
+import { existsSync as defaultExistsSync, promises as fs } from 'node:fs';
+import * as path from 'node:path';
+
+import type { FontRole, FontSource, ResolvedFont } from '../types.js';
+import { loadBundledMono, loadBundledSans } from './bundled.js';
+import { aliasCandidate, isAlias, type PlatformProbe, probeListFor } from './probe-list.js';
+import { isVariableFontBytes } from './sfns.js';
+
+export interface ResolveOptions {
+    /** Path or alias for the sans role. Wins over env / probe / bundled. */
+    fontSans?: string;
+    /** Path or alias for the mono role. */
+    fontMono?: string;
+    /**
+     * Skip steps 4–5; go straight to step 5 (bundled DejaVu pair). Implied by
+     * `NOWLINE_HEADLESS=1` and by `CI=true` without a TTY (unless
+     * `disableAutoHeadless` is set).
+     */
+    headless?: boolean;
+    /** Disable the CI-no-TTY auto-headless heuristic. Defaults to false. */
+    disableAutoHeadless?: boolean;
+    // Test seams — defaults wire to real `node:fs` / `node:process`.
+    platform?: NodeJS.Platform;
+    fileExists?: (p: string) => boolean;
+    readFileBytes?: (p: string) => Promise<Uint8Array>;
+    env?: NodeJS.ProcessEnv;
+    isStdoutTty?: boolean;
+}
+
+export interface ResolveResult {
+    sans: ResolvedFont;
+    mono: ResolvedFont;
+    /**
+     * True when EITHER role landed at step 5 without explicit `--headless`.
+     * Callers (CLI) emit a `--strict` warning on this.
+     */
+    sansFellBackToBundled: boolean;
+    monoFellBackToBundled: boolean;
+}
+
+export async function resolveFonts(options: ResolveOptions = {}): Promise<ResolveResult> {
+    const env = options.env ?? process.env;
+    const platform = options.platform ?? process.platform;
+    const fileExists = options.fileExists ?? defaultExistsSync;
+    const readFileBytes = options.readFileBytes ?? defaultReadFileBytes;
+    const probe = probeListFor(platform, env);
+
+    const headlessRequested = isHeadlessRequested(options, env);
+    const sans = await resolveRole({
+        role: 'sans',
+        flag: options.fontSans,
+        envValue: env.NOWLINE_FONT_SANS,
+        headless: headlessRequested,
+        probe,
+        fileExists,
+        readFileBytes,
+    });
+    const mono = await resolveRole({
+        role: 'mono',
+        flag: options.fontMono,
+        envValue: env.NOWLINE_FONT_MONO,
+        headless: headlessRequested,
+        probe,
+        fileExists,
+        readFileBytes,
+    });
+    return {
+        sans,
+        mono,
+        sansFellBackToBundled: sans.source === 'bundled' && !headlessRequested,
+        monoFellBackToBundled: mono.source === 'bundled' && !headlessRequested,
+    };
+}
+
+function isHeadlessRequested(options: ResolveOptions, env: NodeJS.ProcessEnv): boolean {
+    if (options.headless) return true;
+    if (env.NOWLINE_HEADLESS === '1' || env.NOWLINE_HEADLESS === 'true') return true;
+    if (options.disableAutoHeadless) return false;
+    const inCI = env.CI === 'true' || env.CI === '1';
+    const stdoutIsTty = options.isStdoutTty ?? Boolean(process.stdout.isTTY);
+    return inCI && !stdoutIsTty;
+}
+
+interface RoleArgs {
+    role: FontRole;
+    flag?: string;
+    envValue?: string;
+    headless: boolean;
+    probe: PlatformProbe;
+    fileExists: (p: string) => boolean;
+    readFileBytes: (p: string) => Promise<Uint8Array>;
+}
+
+async function resolveRole(args: RoleArgs): Promise<ResolvedFont> {
+    // Step 1 — flag (path or alias)
+    if (args.flag) {
+        return loadFlag(args.flag, args.role, 'flag', args);
+    }
+    // Step 2 — environment
+    if (args.envValue) {
+        return loadFlag(args.envValue, args.role, 'env', args);
+    }
+    // Step 3 — headless: skip probe, go to bundled
+    if (args.headless) {
+        return loadBundled(args.role, 'headless');
+    }
+    // Step 4 — platform probe
+    for (const candidate of args.probe[args.role]) {
+        if (args.fileExists(candidate.path)) {
+            const bytes = await args.readFileBytes(candidate.path);
+            return decorate(bytes, {
+                name: candidate.name,
+                source: 'probe',
+                path: candidate.path,
+                face: candidate.face,
+            });
+        }
+    }
+    // Step 5 — bundled fallback
+    return loadBundled(args.role, 'bundled');
+}
+
+async function loadFlag(
+    raw: string,
+    role: FontRole,
+    source: 'flag' | 'env',
+    args: RoleArgs,
+): Promise<ResolvedFont> {
+    if (
+        path.isAbsolute(raw) ||
+        raw.startsWith('.') ||
+        raw.includes(path.sep) ||
+        raw.endsWith('.ttf') ||
+        raw.endsWith('.otf') ||
+        raw.endsWith('.ttc')
+    ) {
+        const abs = path.resolve(raw);
+        if (!args.fileExists(abs)) {
+            throw new FontResolveError(`font path does not exist: ${raw} (resolved to ${abs})`);
+        }
+        const bytes = await args.readFileBytes(abs);
+        return decorate(bytes, {
+            name: deriveDisplayName(abs),
+            source,
+            path: abs,
+        });
+    }
+
+    if (isAlias(raw)) {
+        const candidate = aliasCandidate(raw, role, args.probe);
+        if (!candidate) {
+            throw new FontResolveError(`alias "${raw}" has no ${role} mapping on this platform`);
+        }
+        if (!args.fileExists(candidate.path)) {
+            // Alias is known but the underlying file is missing — fall through
+            // to bundled with the original source preserved is wrong; surface
+            // the missing-file error so the user knows their alias didn't land.
+            throw new FontResolveError(
+                `alias "${raw}" maps to ${candidate.path} which does not exist on this system`,
+            );
+        }
+        const bytes = await args.readFileBytes(candidate.path);
+        return decorate(bytes, {
+            name: candidate.name,
+            source,
+            path: candidate.path,
+            face: candidate.face,
+        });
+    }
+
+    throw new FontResolveError(`font value "${raw}" is neither a path nor a known alias`);
+}
+
+async function loadBundled(role: FontRole, source: FontSource): Promise<ResolvedFont> {
+    const bytes = role === 'sans' ? await loadBundledSans() : await loadBundledMono();
+    return decorate(bytes, {
+        name: role === 'sans' ? 'DejaVu Sans' : 'DejaVu Sans Mono',
+        source,
+    });
+}
+
+interface DecorateMeta {
+    name: string;
+    source: FontSource;
+    path?: string;
+    face?: string;
+}
+
+function decorate(bytes: Uint8Array, meta: DecorateMeta): ResolvedFont {
+    return {
+        name: meta.name,
+        bytes,
+        source: meta.source,
+        path: meta.path,
+        face: meta.face,
+        isVariableFont: isVariableFontBytes(bytes),
+    };
+}
+
+function deriveDisplayName(absPath: string): string {
+    const base = path.basename(absPath, path.extname(absPath));
+    return base.replace(/-Regular$/, '').replace(/[_-]/g, ' ');
+}
+
+async function defaultReadFileBytes(p: string): Promise<Uint8Array> {
+    const buf = await fs.readFile(p);
+    return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+}
+
+export class FontResolveError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = 'FontResolveError';
+    }
+}

package/src/fonts/sfns.ts

@@ -0,0 +1,34 @@
+// SF Pro variable-font handling.
+//
+// Spec: specs/handoffs/m2c.md § 10 "Variable-font handling (SFNS.ttf)".
+//
+// Detection only — actual VF instancing for PDF embedding lives in
+// @nowline/export-pdf, which depends on fontkit directly. The resolver
+// surfaces `isVariableFont: true` so consumers know they may need to
+// pre-instance.
+
+const FVAR_TAG = 0x66766172; // 'fvar'
+
+/**
+ * Returns true when the given TTF/OTF byte buffer carries an `fvar` table —
+ * i.e. it is an OpenType variable font with continuous axes.
+ */
+export function isVariableFontBytes(bytes: Uint8Array): boolean {
+    if (bytes.byteLength < 12) return false;
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const sfntVersion = view.getUint32(0);
+    // Accept both TrueType ('\x00\x01\x00\x00') and OpenType/CFF ('OTTO').
+    const isSfnt = sfntVersion === 0x00010000 || sfntVersion === 0x4f54544f;
+    const isCollection = sfntVersion === 0x74746366; // 'ttcf' — handled separately
+    if (!isSfnt && !isCollection) return false;
+    if (isCollection) return false; // collection: caller should index by face first
+
+    const numTables = view.getUint16(4);
+    for (let i = 0; i < numTables; i++) {
+        const recordOffset = 12 + i * 16;
+        if (recordOffset + 16 > bytes.byteLength) return false;
+        const tag = view.getUint32(recordOffset);
+        if (tag === FVAR_TAG) return true;
+    }
+    return false;
+}