cli

interface Streams {
  readonly out: (text: string) => void;
  readonly err: (text: string) => void;
}

function main(argv: readonly string[], streams?: Streams): number;

interface InspectOptions {
  readonly json: boolean;
  readonly parts: boolean;
  readonly namespaces: boolean;
  readonly top: number;
  /** Write to this path instead of stdout. */
  readonly out: string | null;
}

const INSPECT_DEFAULTS: InspectOptions;

interface InspectResult {
  readonly census: PackageCensus;
  readonly output: string;
  /**
   * Process exit code.
   *
   * `1` when the census found something it classes as an error, `0` otherwise -
   * a warning or a note never fails the command. That distinction is what makes
   * `inspect` usable in a script: "did this deck load, and is anything in it
   * structurally broken" is a yes/no question, while "is anything in it
   * unusual" is not.
   */
  readonly exitCode: number;
}

function inspectFile(path: string, options?: InspectOptions): InspectResult;

function runInspect(path: string, options: InspectOptions, write: (text: string) => void): number;

type FontBackend = 'directwrite' | 'freetype' | 'coretext';

function backendFor(platform: string): FontBackend;

interface Face {
  /** `name` ID 1, which is what PowerPoint matches a typeface on. */
  readonly family: string;
  /** `name` ID 2: `Regular`, `Bold`, `Italic`, `Bold Italic`, or a style name. */
  readonly subfamily: string;
  /** `name` ID 16, present when the family splits into more than four styles. */
  readonly typographicFamily: string | undefined;
  readonly metrics: FaceMetrics;
  readonly bold: boolean;
  readonly italic: boolean;
  /** Code point to advance, in font units. */
  advanceOf(codePoint: number): number | undefined;
  /** The adjustment between two code points, in font units. Usually zero. */
  kernBetween(left: number, right: number): number;
}

function facesIn(bytes: Uint8Array, subject: string, backend: FontBackend): readonly Face[];

function systemFontDirectories(platform?: string): readonly string[];

interface FontLibrary {
  /** Every face found, for the diagnostics and for a test to count. */
  readonly indexed: readonly IndexedFace[];
  /** The directories that were scanned, in order. */
  readonly directories: readonly string[];
  resolve(family: string, bold: boolean, italic: boolean): Resolved | undefined;
}

function indexFonts(options?: IndexOptions): FontLibrary;

interface FaceUse {
  readonly asked: string;
  readonly drawn: string;
  readonly file: string;
  readonly substituted: boolean;
}

interface FontMeasurer {
  readonly measurer: TextMeasurer;
  readonly faceBox: FaceBoxProbe;
  /** The CSS family list a run is drawn in: the face that measured it, then the deck's own stack. */
  readonly cssFamilyFor: (font: RunFont) => string;
  /** Every typeface asked for, and what it was drawn in. */
  used(): readonly FaceUse[];
  /** Code points no face in the library could draw. */
  missing(): readonly number[];
}

function createFontMeasurer(library: FontLibrary): FontMeasurer;

const DEFAULT_WIDTH = 1920;

interface RenderDeckOptions {
  /** 1-based. Omitted, or `null`, is every slide. */
  readonly slide?: number | null;
  /** The `width` attribute in CSS pixels; the height follows the deck's aspect. */
  readonly width?: number;
  /** Searched before the platform's own, so a face can be overridden without installing it. */
  readonly fontDirs?: readonly string[];
  /** Also look in this platform's font directories. Default true. */
  readonly systemFonts?: boolean;
  /** Draw text. `false` draws geometry only and asks no font questions. Default true. */
  readonly text?: boolean;
}

interface RenderOptions extends RenderDeckOptions {
  /** A directory for many slides, a file for one, or `null` for stdout. */
  readonly out: string | null;
  readonly json: boolean;
  readonly quiet: boolean;
}

interface RenderedSlide {
  /** 1-based, as the flag and the file name spell it. */
  readonly number: number;
  readonly svg: string;
}

interface RenderResult {
  readonly slides: readonly RenderedSlide[];
  readonly width: number;
  readonly height: number;
  /** Every typeface the deck asked for, and what drew it. Empty with `--no-text`. */
  readonly fonts: readonly FaceUse[];
  /** Code points no indexed face could draw. */
  readonly missing: readonly number[];
  readonly fontDirectories: readonly string[];
  readonly facesIndexed: number;
}

function renderDeck(bytes: Uint8Array, options?: RenderDeckOptions): RenderResult;

function runRender(file: string, options: RenderOptions, out: (text: string) => void): number;

type RenderErrorCode =
/** Bytes that are not an SFNT font, or a table the reader needs is absent. */
'CLI_FONT_UNREADABLE' |
/** A font directory that was named on the command line and does not exist. */
'CLI_FONT_DIR' |
/** No face on this machine can stand in for a typeface the deck names. */
'CLI_NO_FACE' |
/** A run whose resolved size is not a positive number of hundredths of a point. */
'CLI_FONT_SIZE' |
/** A slide index outside the deck. */
'CLI_NO_SLIDE' |
/** A width that is not a positive whole number of pixels. */
'CLI_WIDTH' |
/** An output path that names no directory, or a directory that is a file. */
'CLI_OUTPUT_PATH';

const RENDER_ERROR_CODES: readonly RenderErrorCode[];

class RenderError extends Error {
  readonly name = "RenderError";
  readonly code: RenderErrorCode;
  /** The font file, deck path or typeface the failure is about. */
  readonly subject: string;
  constructor(code: RenderErrorCode, message: string, subject: string);
}

function isRenderError(error: unknown): error is RenderError;