@nowline/export-core 0.2.0

package/src/index.ts

@@ -0,0 +1,62 @@
+export {
+    displayLabel,
+    getProp,
+    getProps,
+    hasProp,
+    type PropertyHost,
+    roadmapTitle,
+} from './ast-helpers.js';
+export {
+    BUNDLED_MONO_PATH,
+    BUNDLED_SANS_PATH,
+    clearBundledCache,
+    loadBundledMono,
+    loadBundledSans,
+} from './fonts/bundled.js';
+export {
+    ALIASES,
+    aliasCandidate,
+    type FontCandidate,
+    isAlias,
+    type PlatformProbe,
+    probeListFor,
+} from './fonts/probe-list.js';
+
+export {
+    FontResolveError,
+    type ResolveOptions,
+    type ResolveResult,
+    resolveFonts,
+} from './fonts/resolve.js';
+
+export { isVariableFontBytes } from './fonts/sfns.js';
+export {
+    type ContentScale,
+    fitContent,
+    isPdfPresetName,
+    PageSizeParseError,
+    parsePageSize,
+    presetDimensions,
+    presetNames,
+    type ResolvedPage,
+    resolvePage,
+    validateMargin,
+} from './pdf-page.js';
+export type {
+    ExportInputs,
+    FontRole,
+    FontSource,
+    PdfLength,
+    PdfLengthUnit,
+    PdfOrientation,
+    PdfPageSize,
+    PdfPresetName,
+    ResolvedFont,
+    ResolvedFontPair,
+} from './types.js';
+export {
+    LengthParseError,
+    lengthToPoints,
+    parseLength,
+    pointsToLength,
+} from './units.js';

package/src/pdf-page.ts

@@ -0,0 +1,224 @@
+// PDF page-size parsing, preset table, and orientation/margin resolution.
+//
+// Spec: specs/handoffs/m2c.md § 4 "PDF — vector PDF via PDFKit"
+//   - Default: US Letter (8.5 × 11 in) portrait.
+//   - Presets: imperial (letter, legal, tabloid, ledger) + ISO 216 (a5–a1, b5–b3).
+//   - Custom: WxHunit (mixed units rejected).
+//   - "content": page = content dimensions, no scaling, no upper bound.
+
+import type { PdfLength, PdfOrientation, PdfPageSize, PdfPresetName } from './types.js';
+import { LengthParseError, lengthToPoints, parseLength } from './units.js';
+
+interface PresetDimensions {
+    widthPt: number;
+    heightPt: number;
+}
+
+function fromMm(widthMm: number, heightMm: number): PresetDimensions {
+    const factor = 72 / 25.4;
+    return {
+        widthPt: roundToMicropoint(widthMm * factor),
+        heightPt: roundToMicropoint(heightMm * factor),
+    };
+}
+
+function roundToMicropoint(n: number): number {
+    return Math.round(n * 1000) / 1000;
+}
+
+const PRESETS: Readonly<Record<PdfPresetName, PresetDimensions>> = {
+    letter: { widthPt: 612, heightPt: 792 },
+    legal: { widthPt: 612, heightPt: 1008 },
+    tabloid: { widthPt: 792, heightPt: 1224 },
+    ledger: { widthPt: 1224, heightPt: 792 },
+    a1: fromMm(594, 841),
+    a2: fromMm(420, 594),
+    a3: fromMm(297, 420),
+    a4: fromMm(210, 297),
+    a5: fromMm(148, 210),
+    b3: fromMm(353, 500),
+    b4: fromMm(250, 353),
+    b5: fromMm(176, 250),
+};
+
+const PRESET_NAMES = Object.keys(PRESETS) as readonly PdfPresetName[];
+
+export class PageSizeParseError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = 'PageSizeParseError';
+    }
+}
+
+export function isPdfPresetName(value: string): value is PdfPresetName {
+    return (PRESET_NAMES as readonly string[]).includes(value.toLowerCase());
+}
+
+export function presetNames(): readonly PdfPresetName[] {
+    return PRESET_NAMES;
+}
+
+export function presetDimensions(name: PdfPresetName): PresetDimensions {
+    return PRESETS[name];
+}
+
+// Canonical form: `<W>x<H><unit>` — single trailing unit applies to both
+// (e.g. `8.5x11in`).
+// Explicit form: `<W><unit>x<H><unit>` — both dimensions tagged. Same unit
+// required; mismatch is rejected as "mixed units".
+const CUSTOM_RE = /^(\d+(?:\.\d+)?)([a-z]+)?x(\d+(?:\.\d+)?)([a-z]+)$/i;
+
+/**
+ * Parse a `--page-size` value: preset name, custom `WxHunit`, or `content`.
+ * Case-insensitive.
+ */
+export function parsePageSize(input: string): PdfPageSize {
+    const lower = input.trim().toLowerCase();
+    if (!lower) throw new PageSizeParseError('empty page size');
+    if (lower === 'content') return { kind: 'content' };
+    if (isPdfPresetName(lower)) {
+        return { kind: 'preset', name: lower as PdfPresetName };
+    }
+
+    const match = CUSTOM_RE.exec(lower);
+    if (!match) {
+        throw new PageSizeParseError(
+            `invalid page size "${input}": expected preset (${PRESET_NAMES.join(', ')}), "content", or <W>x<H><unit> (e.g. 8.5x11in)`,
+        );
+    }
+    const [, wRaw, wUnitMaybe, hRaw, hUnit] = match;
+    if (wUnitMaybe !== undefined && wUnitMaybe !== hUnit) {
+        throw new PageSizeParseError(
+            `invalid page size "${input}": mixed units (${wUnitMaybe} vs ${hUnit}); use the same unit for width and height`,
+        );
+    }
+
+    let width: PdfLength;
+    let height: PdfLength;
+    try {
+        width = parseLength(`${wRaw}${hUnit}`);
+        height = parseLength(`${hRaw}${hUnit}`);
+    } catch (err) {
+        if (err instanceof LengthParseError) {
+            throw new PageSizeParseError(`invalid page size "${input}": ${err.message}`);
+        }
+        throw err;
+    }
+    return { kind: 'custom', width, height };
+}
+
+export interface ResolvedPage {
+    widthPt: number;
+    heightPt: number;
+    orientation: 'portrait' | 'landscape';
+    isContentSized: boolean;
+}
+
+/**
+ * Resolve the final page rectangle (in points) from page size, orientation,
+ * and content dimensions.
+ *
+ * Rules per § 4 "Orientation" / "Scaling":
+ *  - `--page-size content` → page = content + 2 × margin; orientation derived from
+ *    the resulting aspect; `orientation` argument is ignored.
+ *  - Fixed page (preset or custom):
+ *      `auto` → portrait if content taller-than-wide, landscape otherwise.
+ *      `portrait` / `landscape` → swap the preset W/H if the preset is in the
+ *      opposite orientation.
+ */
+export function resolvePage(args: {
+    pageSize: PdfPageSize;
+    orientation: PdfOrientation;
+    contentWidthPt: number;
+    contentHeightPt: number;
+    marginPt: number;
+}): ResolvedPage {
+    const { pageSize, orientation, contentWidthPt, contentHeightPt, marginPt } = args;
+
+    if (pageSize.kind === 'content') {
+        const widthPt = contentWidthPt + 2 * marginPt;
+        const heightPt = contentHeightPt + 2 * marginPt;
+        return {
+            widthPt,
+            heightPt,
+            orientation: widthPt >= heightPt ? 'landscape' : 'portrait',
+            isContentSized: true,
+        };
+    }
+
+    let widthPt: number;
+    let heightPt: number;
+    if (pageSize.kind === 'preset') {
+        ({ widthPt, heightPt } = PRESETS[pageSize.name]);
+    } else {
+        widthPt = lengthToPoints(pageSize.width);
+        heightPt = lengthToPoints(pageSize.height);
+    }
+
+    const resolvedOrientation: 'portrait' | 'landscape' =
+        orientation === 'auto'
+            ? contentWidthPt > contentHeightPt
+                ? 'landscape'
+                : 'portrait'
+            : orientation;
+
+    if (resolvedOrientation === 'landscape' && widthPt < heightPt) {
+        [widthPt, heightPt] = [heightPt, widthPt];
+    } else if (resolvedOrientation === 'portrait' && widthPt > heightPt) {
+        [widthPt, heightPt] = [heightPt, widthPt];
+    }
+
+    return { widthPt, heightPt, orientation: resolvedOrientation, isContentSized: false };
+}
+
+/**
+ * Validate a margin against the resolved page. `margin × 2 ≥ either dim`
+ * means the printable area collapses; throw with a pointer at `--margin`.
+ */
+export function validateMargin(marginPt: number, page: ResolvedPage): void {
+    if (!Number.isFinite(marginPt) || marginPt < 0) {
+        throw new PageSizeParseError('invalid margin: must be a non-negative number of points');
+    }
+    if (marginPt * 2 >= page.widthPt || marginPt * 2 >= page.heightPt) {
+        throw new PageSizeParseError(
+            `margin ${marginPt}pt consumes the entire ${page.widthPt}x${page.heightPt}pt page`,
+        );
+    }
+}
+
+export interface ContentScale {
+    /** Factor applied to content; 1 = native, < 1 = shrink to fit. */
+    factor: number;
+    /** Top-left of where the (scaled) content begins inside the page. */
+    offsetX: number;
+    offsetY: number;
+}
+
+/**
+ * For fixed-page mode, fit (centered, never up-scaled) the content rectangle
+ * inside the printable area `(page − 2 × margin)`. For content-sized pages,
+ * the factor is always 1 and the offset is just the margin.
+ */
+export function fitContent(args: {
+    page: ResolvedPage;
+    contentWidthPt: number;
+    contentHeightPt: number;
+    marginPt: number;
+}): ContentScale {
+    const { page, contentWidthPt, contentHeightPt, marginPt } = args;
+    if (page.isContentSized) {
+        return { factor: 1, offsetX: marginPt, offsetY: marginPt };
+    }
+    const printableW = page.widthPt - 2 * marginPt;
+    const printableH = page.heightPt - 2 * marginPt;
+    const scaleX = printableW / contentWidthPt;
+    const scaleY = printableH / contentHeightPt;
+    const factor = Math.min(scaleX, scaleY, 1);
+    const scaledW = contentWidthPt * factor;
+    const scaledH = contentHeightPt * factor;
+    return {
+        factor,
+        offsetX: marginPt + (printableW - scaledW) / 2,
+        offsetY: marginPt + (printableH - scaledH) / 2,
+    };
+}

package/src/types.ts

@@ -0,0 +1,88 @@
+// Shared types consumed by every @nowline/export-* package.
+//
+// Heavy deps (resvg, pdfkit, exceljs) live in the format packages, never
+// here — see specs/handoffs/m2c.md § 1.
+
+import type { NowlineFile, ResolveResult } from '@nowline/core';
+import type { PositionedRoadmap } from '@nowline/layout';
+
+/** Bundle of inputs every export function consumes. */
+export interface ExportInputs {
+    /** Positioned model produced by `layoutRoadmap()`. */
+    model: PositionedRoadmap;
+    /** Original AST — needed for XLSX / Mermaid / MS Project. */
+    ast: NowlineFile;
+    /** Include-resolved data — needed for XLSX joins. */
+    resolved: ResolveResult;
+    /**
+     * Display path for the source. Use `'<stdin>'` when piped. Used in
+     * footers / metadata; never for filesystem reads.
+     */
+    sourcePath: string;
+    /**
+     * Optional pinned timestamp. Exporters that would otherwise call
+     * `new Date()` (PDF CreationDate, XLSX Created) MUST take this from
+     * `ast.generated` first, then `today`, never `new Date()`.
+     */
+    today?: Date;
+}
+
+// PDF page sizing -----------------------------------------------------------
+
+export type PdfPresetName =
+    // Imperial / ANSI
+    | 'letter' //  8.5 x 11    in   (default)
+    | 'legal' //  8.5 x 14    in
+    | 'tabloid' // 11   x 17    in   (ANSI B portrait)
+    | 'ledger' // 17   x 11    in   (ANSI B landscape)
+    // Metric / ISO 216 — A series
+    | 'a5'
+    | 'a4'
+    | 'a3'
+    | 'a2'
+    | 'a1'
+    // Metric / ISO 216 — B series
+    | 'b5'
+    | 'b4'
+    | 'b3';
+
+export type PdfLengthUnit = 'pt' | 'in' | 'mm' | 'cm';
+
+export interface PdfLength {
+    value: number;
+    unit: PdfLengthUnit;
+}
+
+export type PdfPageSize =
+    | { kind: 'preset'; name: PdfPresetName }
+    | { kind: 'custom'; width: PdfLength; height: PdfLength }
+    | { kind: 'content' };
+
+export type PdfOrientation = 'portrait' | 'landscape' | 'auto';
+
+// Font resolver -------------------------------------------------------------
+
+/** Where the resolver landed when it stopped. */
+export type FontSource = 'flag' | 'env' | 'headless' | 'probe' | 'bundled';
+
+export type FontRole = 'sans' | 'mono';
+
+export interface ResolvedFont {
+    /** Friendly family name, e.g. 'DejaVu Sans', 'SF Pro'. */
+    name: string;
+    /** Full TTF/OTF bytes, ready for PDFKit / resvg consumption. */
+    bytes: Uint8Array;
+    /** Where in the resolver chain this font came from. */
+    source: FontSource;
+    /** Filesystem path; undefined for bundled / synthesized bytes. */
+    path?: string;
+    /** Face inside a `.ttc` collection, if applicable. */
+    face?: string;
+    /** True when the loaded font is an OpenType variable font (axes, no fixed instance). */
+    isVariableFont?: boolean;
+}
+
+export interface ResolvedFontPair {
+    sans: ResolvedFont;
+    mono: ResolvedFont;
+}

package/src/units.ts

@@ -0,0 +1,60 @@
+// Length conversions and parsing for PDF page sizing.
+//
+// PDF native unit is the "PostScript point": 1 pt = 1/72 in. Every length
+// resolves to points before the page is laid out — see specs/handoffs/m2c.md
+// § 4 "Unit conversion".
+
+import type { PdfLength, PdfLengthUnit } from './types.js';
+
+const POINTS_PER_UNIT: Readonly<Record<PdfLengthUnit, number>> = {
+    pt: 1,
+    in: 72,
+    mm: 72 / 25.4, // ≈ 2.83464567
+    cm: 72 / 2.54, // ≈ 28.3464567
+};
+
+/** Convert a tagged length to PDF points. */
+export function lengthToPoints(length: PdfLength): number {
+    return length.value * POINTS_PER_UNIT[length.unit];
+}
+
+/** Convert a raw point count back to a tagged length in the requested unit. */
+export function pointsToLength(points: number, unit: PdfLengthUnit): PdfLength {
+    return { value: points / POINTS_PER_UNIT[unit], unit };
+}
+
+export class LengthParseError extends Error {
+    constructor(input: string, reason: string) {
+        super(`invalid length "${input}": ${reason}`);
+        this.name = 'LengthParseError';
+    }
+}
+
+const LENGTH_RE = /^(-?\d+(?:\.\d+)?)([a-z]+)$/i;
+const KNOWN_UNITS = new Set<PdfLengthUnit>(['pt', 'in', 'mm', 'cm']);
+
+/**
+ * Parse a unit-tagged length like `36pt`, `0.5in`, `10mm`, `1cm`.
+ *
+ * Throws `LengthParseError` on missing unit, unknown unit, non-numeric, zero,
+ * or negative values.
+ */
+export function parseLength(input: string): PdfLength {
+    const trimmed = input.trim();
+    if (!trimmed) throw new LengthParseError(input, 'empty');
+    const match = LENGTH_RE.exec(trimmed);
+    if (!match) {
+        if (/^-?\d+(?:\.\d+)?$/.test(trimmed)) {
+            throw new LengthParseError(input, 'missing unit (expected pt, in, mm, or cm)');
+        }
+        throw new LengthParseError(input, 'expected <number><unit>');
+    }
+    const unit = match[2].toLowerCase();
+    if (!KNOWN_UNITS.has(unit as PdfLengthUnit)) {
+        throw new LengthParseError(input, `unknown unit "${unit}"; expected one of pt, in, mm, cm`);
+    }
+    const value = Number(match[1]);
+    if (!Number.isFinite(value)) throw new LengthParseError(input, 'non-numeric value');
+    if (value <= 0) throw new LengthParseError(input, 'must be positive');
+    return { value, unit: unit as PdfLengthUnit };
+}