@pptx-studio/cli 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,232 @@
+import { PackageCensus } from "@pptx-studio/census";
+import { FaceBoxProbe, TextMeasurer } from "@pptx-studio/text";
+//#region src/main.d.ts
+interface Streams {
+  readonly out: (text: string) => void;
+  readonly err: (text: string) => void;
+}
+/** Parse, dispatch, and return an exit code. Never calls `process.exit`. */
+declare function main(argv: readonly string[], streams?: Streams): number;
+//#endregion
+//#region src/inspect.d.ts
+/**
+ * `pptx-studio inspect deck.pptx`
+ *
+ * Everything this command knows about `.pptx` lives in `@pptx-studio/census`,
+ * which is a browser package with no Node in it. That split is deliberate and
+ * it is the reason the census exists as a package at all: the browser explorer
+ * in `apps/studio` computes exactly the same object in a Web Worker, so a
+ * question answered here and a question answered in a tab cannot drift.
+ *
+ * What is left for this file is the two things a browser cannot do - read a
+ * path off the filesystem, and write to a stream - plus argument handling.
+ */
+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;
+}
+declare 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;
+}
+/** Run a census over one file and render it. Does no I/O of its own beyond the read. */
+declare function inspectFile(path: string, options?: InspectOptions): InspectResult;
+/** Run `inspectFile` and put the result where the options say. */
+declare function runInspect(path: string, options: InspectOptions, write: (text: string) => void): number;
+//#endregion
+//#region src/render/sfnt.d.ts
+/**
+ * The four tables a measurement needs, read out of a font file.
+ *
+ * Not a font library: nothing here decodes an outline, and a CFF font is read
+ * as happily as a glyf one because advances live in `hmtx` either way. What it
+ * answers is the question the browser answers with `measureText`, which is the
+ * one thing `render-svg` cannot get in Node. Every reading below was measured
+ * against Chromium in experiment T13 rather than taken from the specification.
+ * ADR 0042.
+ */
+interface FaceMetrics {
+  /** `head.unitsPerEm`, the denominator of every number here. */
+  readonly unitsPerEm: number;
+  /** Above the baseline, in font units. */
+  readonly ascent: number;
+  /** Below the baseline, in font units, positive. */
+  readonly descent: number;
+  /** Which table `ascent` and `descent` came out of, for the diagnostics. */
+  readonly source: 'usWin' | 'sTypo';
+}
+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;
+}
+/** Every face in a file, which is one unless the file is a collection. */
+declare function facesIn(bytes: Uint8Array, subject: string): readonly Face[];
+//#endregion
+//#region src/render/faces.d.ts
+/** Where fonts live on this platform, whether or not the directories exist. */
+declare function systemFontDirectories(platform?: string): readonly string[];
+interface IndexedFace {
+  readonly face: Face;
+  readonly file: string;
+}
+/** What the library found for a typeface the deck named. */
+interface Resolved {
+  readonly face: Face;
+  /** The typeface the deck asked for. */
+  readonly asked: string;
+  /** The family actually drawn in, which differs when a substitute was used. */
+  readonly drawn: string;
+  readonly file: string;
+  readonly substituted: boolean;
+}
+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;
+}
+interface IndexOptions {
+  /** Directories to scan before the system ones. Each must exist. */
+  readonly extra?: readonly string[];
+  /** Whether to scan this platform's own font directories. Default true. */
+  readonly system?: boolean;
+  readonly platform?: string;
+}
+/**
+ * Read every font file under the given directories, once.
+ *
+ * A file that will not parse is skipped rather than fatal: a font directory on
+ * a real machine holds `.ttf` files that are bitmap-only, damaged, or not fonts
+ * at all, and one of them must not stop a deck from rendering.
+ */
+declare function indexFonts(options?: IndexOptions): FontLibrary;
+//#endregion
+//#region src/render/measure.d.ts
+interface FaceUse {
+  readonly asked: string;
+  readonly drawn: string;
+  readonly file: string;
+  readonly substituted: boolean;
+}
+interface FontMeasurer {
+  readonly measurer: TextMeasurer;
+  readonly faceBox: FaceBoxProbe;
+  /** 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[];
+}
+/**
+ * A measurer bound to one library.
+ *
+ * Both probes cache by family, because a slide asks for the same handful of
+ * typefaces thousands of times and nothing can change between two asks.
+ */
+declare function createFontMeasurer(library: FontLibrary): FontMeasurer;
+//#endregion
+//#region src/render/render.d.ts
+/** What a slide is drawn at when the caller says nothing. PowerPoint's own. */
+declare const DEFAULT_WIDTH = 1920;
+interface RenderOptions {
+  /** 1-based, or `null` for every slide. */
+  readonly slide: number | null;
+  readonly width: number;
+  /** A directory for many slides, a file for one, or `null` for stdout. */
+  readonly out: string | null;
+  readonly fontDirs: readonly string[];
+  readonly systemFonts: boolean;
+  readonly text: boolean;
+  readonly json: boolean;
+  readonly quiet: boolean;
+}
+declare const RENDER_DEFAULTS: {
+  readonly width: 1920;
+  readonly systemFonts: true;
+  readonly text: true;
+};
+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;
+}
+/**
+ * Render a deck that is already in memory.
+ *
+ * Separate from `runRender` so that the whole pipeline is exercised by the test
+ * suite without a file system, a process or a captured stdout.
+ */
+declare function renderDeck(bytes: Uint8Array, options: RenderOptions): RenderResult;
+/** Read, render, write, and return an exit code. Never calls `process.exit`. */
+declare function runRender(file: string, options: RenderOptions, out: (text: string) => void): number;
+//#endregion
+//#region src/render/errors.d.ts
+/**
+ * Typed failures for rendering outside a browser.
+ *
+ * The browser renderer cannot produce any of these: it is handed a measuring
+ * canvas and a font stack, and the platform answers. In Node both of those are
+ * ours to find, so both are ours to fail at. ADR 0042.
+ */
+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' |
+/** An output path that names no directory, or a directory that is a file. */
+'CLI_OUTPUT_PATH';
+declare const RENDER_ERROR_CODES: readonly RenderErrorCode[];
+declare 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);
+}
+declare function isRenderError(error: unknown): error is RenderError;
+//#endregion
+export { DEFAULT_WIDTH, type Face, type FaceUse, type FontLibrary, type FontMeasurer, INSPECT_DEFAULTS, type InspectOptions, type InspectResult, RENDER_DEFAULTS, RENDER_ERROR_CODES, RenderError, type RenderErrorCode, type RenderOptions, type RenderResult, type RenderedSlide, type Streams, createFontMeasurer, facesIn, indexFonts, inspectFile, isRenderError, main, renderDeck, runInspect, runRender, systemFontDirectories };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/main.ts","../src/inspect.ts","../src/render/sfnt.ts","../src/render/faces.ts","../src/render/measure.ts","../src/render/render.ts","../src/render/errors.ts"],"mappings":";;;UA0HiB;WACN,MAAM;WACN,MAAM;;;iBASD,KAAK,yBAAyB,UAAS;;;;;;;;;;;;;;;UCrHtC;WACN;WACA;WACA;WACA;;WAEA;;cAGE,kBAAkB;UAQd;WACN,QAAQ;WACR;;;;;;;;;;WAUA;;;iBAIK,YACd,cACA,UAAS,iBACR;;iBAiBa,WACd,cACA,SAAS,gBACT,QAAQ;;;;;;;;;;;;;UCpDO;;WAEN;;WAEA;;WAEA;;WAEA;;UAGM;;WAEN;;WAEA;;WAEA;WACA,SAAS;WACT;WACA;;EAET,UAAU;;EAEV,YAAY,cAAc;;;iBAqdZ,QAAQ,OAAO,YAAY,2BAA2B;;;;iBCnetD,sBAAsB;UAuCrB;WACN,MAAM;WACN;;;UAIM;WACN,MAAM;;WAEN;;WAEA;WACA;WACA;;UAGM;;WAEN,kBAAkB;;WAElB;EACT,QAAQ,gBAAgB,eAAe,kBAAkB;;UAG1C;;WAEN;;WAEA;WACA;;;;;;;;;iBAoBK,WAAW,UAAS,eAAoB;;;UCxEvC;WACN;WACA;WACA;WACA;;UAGM;WACN,UAAU;WACV,SAAS;;EAElB,iBAAiB;;EAEjB;;;;;;;;iBASc,mBAAmB,SAAS,cAAc;;;;cC9C7C;UAEI;;WAEN;WACA;;WAEA;WACA;WACA;WACA;WACA;WACA;;cAGE;;;;;UAMI;;WAEN;WACA;;UAGM;WACN,iBAAiB;WACjB;WACA;;WAEA,gBAAgB;;WAEhB;WACA;WACA;;;;;;;;iBAoBK,WAAW,OAAO,YAAY,SAAS,gBAAgB;;iBAuIvD,UACd,cACA,SAAS,eACT,MAAM;;;;;;;;;;KCjNI;;;;;;;;;;;;;cAcC,6BAA6B;cAS7B,oBAAoB;WACb;WACT,MAAM;;WAEN;EAEG,YAAA,MAAM,iBAAiB,iBAAiB;;iBAOtC,cAAc,iBAAiB,SAAS"}

package/dist/index.js

@@ -0,0 +1,2 @@
+import { a as runRender, c as systemFontDirectories, d as RenderError, f as isRenderError, h as runInspect, i as renderDeck, l as facesIn, m as inspectFile, n as DEFAULT_WIDTH, o as createFontMeasurer, p as INSPECT_DEFAULTS, r as RENDER_DEFAULTS, s as indexFonts, t as main, u as RENDER_ERROR_CODES } from "./main-DLx2onii.js";
+export { DEFAULT_WIDTH, INSPECT_DEFAULTS, RENDER_DEFAULTS, RENDER_ERROR_CODES, RenderError, createFontMeasurer, facesIn, indexFonts, inspectFile, isRenderError, main, renderDeck, runInspect, runRender, systemFontDirectories };