pptx-ts 3.7.0 → 4.0.0

package/dist/font-metrics-v5fn7s7e.d.ts

@@ -0,0 +1,613 @@
+import { c as PLACEHOLDER_TYPE, d as SHAPE_NAME, g as TextAnchor, i as CHART_NAME, m as SlideObjectType, o as ChartType, t as AlignH } from "./enums-BUKTUB6V.js";
+import { A as TextVertType, Ht as TextPropsOptions, Jt as MediaType, K as ChartErrorBarOptions, Nt as SlideComment, Q as ChartOpts, R as HyperlinkProps, T as Margin, Vt as TextProps, Z as ChartMulti, a as PresentationProps, f as BackgroundOption, i as PresLayout, o as SectionProps, qt as MediaProps, xn as TextShapeType, xt as OptsChartData } from "./pres-C6qgOFAa.js";
+import { O as TableCell, S as AnimationProps, _ as MasterTextStyleProps, a as Slide, i as ObjectOptions, o as SlideLayout, x as SlideNumberProps } from "./slide-Dx2ZeVZ6.js";
+import { t as EmbeddedFont } from "./embedded-fonts-DarT9aoa.js";
+//#region src/types/internal.d.ts
+/** The keys of `T` that are declared optional. */
+type OptionalKeysOf<T> = { [K in keyof T]-?: {} extends Pick<T, K> ? K : never; }[keyof T];
+/**
+ * `T`, but every *optional* property may also be spelled as a present `undefined`.
+ *
+ * Under `exactOptionalPropertyTypes` a `foo?: T` says the key is either absent or holds a `T`.
+ * That distinction is real for a bag that is **stored, spread or enumerated** — `{ ...defaults,
+ * ...options }` inherits from an absent key and is overridden by a present `undefined` — and
+ * those bags keep the strict declaration, with `delete` as their one spelling of absent (the
+ * write-side twin of `compact()` in `script/from-read/values.ts`).
+ *
+ * It is noise for a bag that is only ever **read**: typically a function parameter its call sites
+ * assemble inline out of values that may be unset (`{ color: opts.titleColor, … }`), where the
+ * reader cannot tell the two states apart in the first place. Those parameters take this instead
+ * of forcing every call site to build the object key by key.
+ *
+ * Required properties are left alone, so this never quietly makes a mandatory field optional.
+ */
+type MaybeUndefined<T> = Omit<T, OptionalKeysOf<T>> & { [K in OptionalKeysOf<T>]?: T[K] | undefined; };
+/**
+ * Text options carrying the two members the emitters write onto them.
+ *
+ * `_bodyProp` is the normalized `a:bodyPr` the definer builds out of the caller's `align`,
+ * `valign`, `margin`, `columns`, `textDirection` and `textWarp` — a *derived* shape, not an
+ * input, which is what made its presence on the public interface a de-facto API nobody
+ * intended. `_lineIdx` is the paragraph index the run emitter stamps while walking an array
+ * of runs.
+ */
+interface TextPropsOptionsInternal extends TextPropsOptions {
+  _bodyProp?: {
+    align?: AlignH;
+    /**
+     * The resolved `a:bodyPr/@anchor` token. The enum's *values* rather than the enum, so
+     * that both spellings of the same three tokens are accepted: the definer writes
+     * `TextAnchor.ctr` for its own default, while `resolveTextAnchor` answers with the
+     * schema token from the shared `valign` table, which cannot name the enum (it lives in
+     * `ooxml/`, which holds no runtime imports).
+     */
+    anchor?: `${TextAnchor}`;
+    lIns?: number;
+    rIns?: number;
+    tIns?: number;
+    bIns?: number;
+    numCol?: number;
+    spcCol?: number;
+    vert?: TextVertType;
+    wrap?: boolean;
+    prstTxWarp?: TextShapeType;
+  };
+  _lineIdx?: number;
+}
+/**
+ * A slide object's options carrying the six members the definers and emitters write onto them.
+ *
+ * All six are *derived* rather than authored: a placeholder's resolved index and type, the
+ * adjust guides and connection-site bindings a connector resolves at serialize time, and the
+ * flags recording which image dimension has to be backfilled from the natural pixel size once
+ * the bytes have loaded. They were on the public {@link ObjectOptions}, where the two `Cxn`
+ * ones in particular read as a supported way to bind a connector -- the supported way is
+ * `startShape`/`startShapeIdx`.
+ */
+interface ObjectOptionsInternal extends ObjectOptions, TextPropsOptionsInternal {
+  _placeholderIdx?: number;
+  _placeholderType?: PLACEHOLDER_TYPE;
+  /** Connector adjust-guide values (OOXML 1000ths-of-a-percent), one per bend; emitted as `<a:gd name="adjN">` */
+  _connectorAdj?: number[];
+  /** Connector start-point binding: target shape `objectName` (raw, as the caller spelled it) + connection-site index; resolved to `<a:stCxn>` at serialize time */
+  _startCxn?: {
+    name: string;
+    idx: number;
+  };
+  /** Connector end-point binding: target shape `objectName` (raw, as the caller spelled it) + connection-site index; resolved to `<a:endCxn>` at serialize time */
+  _endCxn?: {
+    name: string;
+    idx: number;
+  };
+  /**
+   * Image: which dimensions were omitted by the user and should be derived from the image's
+   * natural pixel size at serialize time. Path-based images can't be measured synchronously in
+   * `addImage()` (bytes are loaded async during export), so the missing extent is backfilled
+   * once `_relsMedia[].data` is populated. `{ w, h }` true means "derive this side from the
+   * natural ratio". Base64 `data` images are measured eagerly in `addImage()` and never set this.
+   */
+  _szAuto?: {
+    w: boolean;
+    h: boolean;
+  };
+}
+/**
+ * One error bar as `addChartDefinition` vetted it: the three enumerations checked, `value` finite,
+ * and the width, stated as `width` or the deprecated `size`, converted to EMU and clamped into
+ * `ST_LineWidth`. The emitter writes what it reads.
+ */
+interface ChartErrorBarInternal extends Omit<ChartErrorBarOptions, 'width' | 'size'> {
+  widthEmu?: number;
+}
+interface OptsChartDataInternal extends OptsChartData {
+  labels?: string[][];
+  /** Always an array here, whichever of the two shapes the caller passed. */
+  errorBars?: ChartErrorBarInternal[];
+  /** Series index; always assigned by addChartDefinition() before this internal shape is built. */
+  _dataIndex: number;
+}
+interface ChartOptsInternal extends ChartOpts {
+  _type?: ChartType | ChartMultiInternal[];
+}
+/**
+ * A combo subchart's option overrides after `addChartDefinition` vetted them — the one bag in the
+ * generator where a key may be *present* and hold `undefined`.
+ *
+ * Everywhere else "unset" has exactly one spelling, an absent key: `compact()` enforces it on the
+ * read side (`script/from-read/values.ts`) and the `delete` idiom does on the write side
+ * (`gen/define/chart.ts`). This bag needs the third state because it is merged *over* the
+ * chart-level options at emit time (`{ ...rel.opts, ...type.options }` in `gen/chart/chart-xml.ts`),
+ * where a present `undefined` suppresses the chart-level value and an absent key inherits it.
+ * Suppressing is the intent: the subchart supplied an override the schema rejects, and the
+ * chart-level value is one it never asked for — inheriting it would be a different chart than
+ * either party described. For a combo chart the chart-level pass cannot vet these itself, since
+ * `_type` is an array there and every type-keyed correction matches no branch.
+ */
+type ChartOptsOverrides = MaybeUndefined<ChartOptsInternal>;
+/**
+ * One subchart of a combo chart, as `addChartDefinition` rebuilt it: series normalized onto
+ * {@link OptsChartDataInternal} and options narrowed to the vetted {@link ChartOptsOverrides}.
+ * `ChartOptsInternal._type` holds these, never the caller's own {@link ChartMulti} objects.
+ */
+interface ChartMultiInternal extends Omit<ChartMulti, 'data' | 'options'> {
+  data: OptsChartDataInternal[];
+  options: ChartOptsOverrides;
+}
+interface SlideRelChart extends OptsChartData {
+  type: CHART_NAME | ChartMultiInternal[];
+  opts: ChartOptsInternal;
+  data: OptsChartDataInternal[];
+  rId: number;
+  Target: string;
+  globalId: number;
+  fileName: string;
+  /**
+   * True when `type` is a chartEx (cx:) chart (e.g. waterfall): the part is emitted as
+   * `chartEx{globalId}.xml` in the chart-extension namespace, gets the `chartex+xml` content
+   * type and the MS `.../2014/relationships/chartEx` rel type, and is referenced from the slide
+   * via `<mc:AlternateContent>`. Set at define time from {@link isChartExType}.
+   */
+  isChartEx?: boolean;
+}
+interface SlideRel {
+  type: SlideObjectType;
+  /**
+   * Relationship target, stored **unescaped**. Every emitter escapes it on the way out
+   * (`gen/slide/object.ts`, `gen/slide/notes.ts`, and `read/opc/relationships.ts` for the
+   * append path). Escaping at definition time instead would double-escape on append,
+   * where the serializer escapes again — so `&` in a hyperlink or online-video URL must
+   * arrive here verbatim.
+   */
+  Target: string;
+  fileName?: string;
+  data: any[] | string;
+  opts?: ChartOpts;
+  path?: string;
+  extn?: string;
+  globalId?: number;
+  rId: number;
+}
+interface SlideRelMedia {
+  type: string;
+  opts?: MediaProps;
+  path?: string;
+  extn?: string;
+  data?: string | ArrayBuffer;
+  /**
+   * An `addMedia` poster frame the caller supplied no `cover` for, so it takes the library's
+   * default play-button artwork. `addMediaDefinition` pushes the rel with this flag and no
+   * `data`; `encodeSlideMediaRels` fills the bytes in during the async media pass, behind the
+   * dynamic import that keeps the artwork out of every consumer's entry chunk. Every rel
+   * carrying it has its `data` resolved before any part is emitted.
+   */
+  isDefaultCover?: boolean;
+  /** used to indicate that a media file has already been read/enocded (PERF) */
+  isDuplicate?: boolean;
+  isSvgPng?: boolean;
+  svgSize?: {
+    w: number;
+    h: number;
+  };
+  /**
+   * Embedded OLE object part (`addOleObject`): the `.rels` `Type` URI to emit — `.../package` for
+   * an embedded OPC package (xlsx/docx/pptx, themselves zips) or `.../oleObject` for a generic OLE
+   * server blob (ECMA-376 Part 1 §15.2.10). Present only on OLE payload rels, where it takes
+   * precedence over the image/audio/video branch in `slideObjectRelationsToXml` and `type` carries
+   * the part's content type verbatim for `[Content_Types].xml`. The object's preview picture is a
+   * separate, perfectly ordinary image rel.
+   */
+  oleRelType?: string;
+  /**
+   * Embedded 3D model part (`addModel3d`): the `.rels` `Type` URI to emit — the Microsoft
+   * `…/office/2017/06/relationships/model3d` type, which no `includes('image'|'audio'|'video')`
+   * sniff would ever reach. Present only on the `.glb` payload rel, where it takes precedence
+   * over the image/audio/video branch in `slideObjectRelationsToXml` and `type` carries the
+   * part's content type verbatim for `[Content_Types].xml`. The model's preview picture is a
+   * separate, perfectly ordinary image rel. Same escape hatch as {@link oleRelType}.
+   */
+  model3dRelType?: string;
+  rId: number;
+  /** Unescaped — see {@link SlideRel.Target}. Doubles as the zip entry name for embedded media. */
+  Target: string;
+}
+interface SlideObject {
+  _type: SlideObjectType;
+  options?: ObjectOptionsInternal;
+  text?: TextProps[];
+  arrTabRows?: TableCell[][];
+  chartRid?: number;
+  image?: string;
+  imageRid?: number;
+  hyperlink?: HyperlinkProps;
+  media?: string;
+  mtype?: MediaType;
+  mediaRid?: number;
+  loop?: boolean;
+  loopCount?: number;
+  shape?: SHAPE_NAME;
+  _groupObjects?: SlideObject[];
+  zoom?: ZoomInternal;
+  ole?: OleInternal;
+  model3d?: Model3dInternal;
+}
+/**
+ * Resolved 3D-model payload carried on a {@link SlideObject} until `gen/slide/objects/model3d.ts`
+ * emits it. Camera values are already in `am3d`'s wire units so the emitter does no arithmetic:
+ * positions in 1/36,000,000ths of a metre, `fov` in 60000ths of a degree, and
+ * `meterPerModelUnitN` over a fixed denominator of 1,000,000.
+ */
+interface Model3dInternal {
+  /** rId of the embedded `.glb` part rel (see {@link SlideRelMedia.model3dRelType}). */
+  modelRid: number;
+  /** rId of the preview picture's image rel — shared by `am3d:blip` and the `mc:Fallback` `p:pic`. */
+  previewRid: number;
+  /** `am3d:camera/am3d:pos` (`@x`/`@y`/`@z`). */
+  pos: {
+    x: number;
+    y: number;
+    z: number;
+  };
+  /** `am3d:camera/am3d:lookAt` (`@x`/`@y`/`@z`). */
+  lookAt: {
+    x: number;
+    y: number;
+    z: number;
+  };
+  /** `am3d:camera/am3d:up` (`@dx`/`@dy`/`@dz`). */
+  up: {
+    dx: number;
+    dy: number;
+    dz: number;
+  };
+  /** `am3d:perspective@fov`, in 60000ths of a degree. */
+  fov: number;
+  /** `am3d:meterPerModelUnit@n`; `@d` is always 1,000,000. */
+  meterPerModelUnitN: number;
+}
+/** Resolved OLE payload carried on a {@link SlideObject} until `gen/slide/objects/ole.ts` emits it. */
+interface OleInternal {
+  /** rId of the embedded object part rel (see {@link SlideRelMedia.oleRelType}). */
+  objectRid: number;
+  /** rId of the preview picture's image rel (`p:pic > a:blip@r:embed`). */
+  previewRid: number;
+  /** `p:oleObj@progId` — the OLE server PowerPoint launches on double-click. */
+  progId: string;
+  /** `p:oleObj@name` — the object's kind as PowerPoint labels it (`Worksheet`, `Document`, …). */
+  name: string;
+  /** `p:oleObj@showAsIcon`; omitted when false, matching PowerPoint. */
+  showAsIcon: boolean;
+  /** `p:oleObj@imgW`/`@imgH` (EMU). Undefined means "use the frame's own extent". */
+  imgW?: number;
+  imgH?: number;
+}
+/** One tile inside a zoom object (a Slide/Section Zoom has one; a Summary Zoom has N). */
+interface ZoomTileInternal {
+  /** Slide Zoom: target slide id (= `PresSlideInternal._slideId`, emitted as `sldZmObj@sldId`). */
+  sldId?: number;
+  /** Section/Summary Zoom: target section GUID (`{...}`, emitted as `sectionZmObj@sectionId`). */
+  sectionId?: string;
+  /** rId of the preview/cover image blip (`zmPr>blipFill>a:blip@r:embed`). Shared across tiles when identical. */
+  previewRid: number;
+  /** rId of the `.../slide` rel used by the `mc:Fallback` picture's `hlinkClick` (target/section-start slide). */
+  fallbackSlideRid: number;
+  /** Per-tile `zmPr@id` GUID (`{...}`). */
+  zmPrId: string;
+  /** Summary Zoom only: this tile's grid cell within the graphic-frame coordinate space (EMU). */
+  grid?: {
+    x: number;
+    y: number;
+    cx: number;
+    cy: number;
+  };
+}
+/** Resolved zoom payload carried on a {@link SlideObject} until `gen/slide/objects/zoom.ts` emits it. */
+interface ZoomInternal {
+  variant: 'slide' | 'section' | 'summary';
+  tiles: ZoomTileInternal[];
+  /** `zmPr@returnToParent`; emitted as `"0"`/`"1"` for Slide Zoom, omitted for Section/Summary. */
+  returnToParent: boolean;
+  /** `zmPr@transitionDur` (ms). */
+  transitionDur: number;
+}
+interface SlideBaseProps {
+  _bkgdImgRid?: number;
+  _margin?: Margin;
+  _name?: string;
+  _presLayout: PresLayout;
+  _rels: SlideRel[];
+  _relsChart: SlideRelChart[];
+  _relsMedia: SlideRelMedia[];
+  _comments?: SlideComment[];
+  _txStyles?: MasterTextStyleProps;
+  _slideNum: number;
+  _slideNumberProps?: SlideNumberProps | null;
+  _slideObjects: SlideObject[];
+  /**
+   * Per-kind counters backing default Selection Pane names (`Shape 1`, `Image 1`, `Group 1`, …),
+   * keyed by `SlideObjectType`. Monotonic for the life of the slide: an object consumes its index
+   * when it is added, whether it stays top-level or is moved into a group's `_groupObjects`.
+   * Lazily created by `nextObjectNameIdx` (`gen/define/object-name.ts`).
+   */
+  _objectNameCounts?: Partial<Record<SlideObjectType, number>>;
+  /**
+   * `| undefined` for the same reason {@link Slide.background} carries it: `SlideBuilder`
+   * implements this as an accessor pair, so it is always *present* on a real slide or layout and
+   * answers `undefined` when none is set. The `_`-prefixed members above are plain fields and
+   * keep the strict form.
+   */
+  background?: BackgroundOption | undefined;
+}
+interface SlideLayoutInternal extends SlideBaseProps, SlideLayout {
+  _slide?: {
+    _bkgdImgRid?: number;
+    back: string;
+    color: string;
+    hidden?: boolean;
+  } | null;
+}
+interface PresSlideInternal extends SlideBaseProps, Slide {
+  _rId: number;
+  _slideLayout: SlideLayoutInternal | null;
+  _slideId: number;
+  /** Preset build animations on this slide, in play order (see {@link Slide.addAnimation}). */
+  _animations: AnimationProps[];
+}
+interface SectionInternalProps extends SectionProps {
+  _type?: 'user' | 'default';
+  _slides: PresSlideInternal[];
+  /** Stable section GUID (`{XXXXXXXX-...}`), assigned at section creation so Section/Summary Zoom can address it. */
+  _id: string;
+}
+/**
+ * The deck's slide master as the writer holds it: the relationships, objects and deck-wide settings
+ * `slideMaster1.xml` is written from. It is not a {@link Slide}. Nothing is authored onto it, so it
+ * has none of a slide's methods, and it has no slide number: `_slideNum` is `null`, which is how
+ * media registration tells it from a slide or a layout.
+ */
+interface SlideMasterInternal extends Omit<SlideBaseProps, '_slideNum'> {
+  _slideNum: null;
+}
+interface PresentationPropsInternal extends PresentationProps {
+  masterSlide: SlideMasterInternal;
+  sections: SectionInternalProps[];
+  slideLayouts: SlideLayoutInternal[];
+  slides: PresSlideInternal[];
+  /** Author-side embedded fonts (see {@link TsPptx.embedFont}); empty when none. */
+  embeddedFonts: EmbeddedFont[];
+}
+//#endregion
+//#region src/measure/text-fit.d.ts
+/**
+ * PowerPoint single-spacing line pitch as a multiple of font size.
+ *
+ * Calibrated from `autofit-calibration.json` (Deck 1, `autofit-line-metrics`):
+ * the per-line `cy` delta is a **font-independent** 1.2117× at 12/18/32 pt across
+ * {Aptos, Aptos SemiBold, Calibri, Tahoma, Arial}, and PowerPoint vs LibreOffice
+ * agree to ≤ 0.041 pt. See "Findings behind the constants" in
+ * `docs/contributing/design/text-fit.md`.
+ */
+declare const SINGLE_LINE_PITCH = 1.2117;
+/** PowerPoint's `fontScale` search grid: discrete 2.5% steps (`docs/contributing/design/text-fit.md`). */
+declare const FONT_SCALE_STEP_PCT = 2.5;
+/** Floor for the shrink search (see `docs/contributing/design/text-fit.md` → Wrap simulator and solvers). */
+declare const MIN_FONT_SCALE_PCT = 25;
+/**
+ * Conservative safety factors applied by the shrink solver (not by the pure
+ * `measureHeightPt`). Raw `hmtx` advances summed without shaping still pack a line
+ * a little tighter than PowerPoint, which lays text out at a device DPI and rounds
+ * each glyph advance up — so PowerPoint wraps marginally earlier and its fitted
+ * box is marginally taller. Inflating measured width and height by these factors
+ * makes the computed `fontScale` ≤ PowerPoint's across the calibration oracle
+ * (`test/read/autofit-calibration-oracle.test.js`: 0 violations over the Aptos
+ * cases). They err on the side of shrinking slightly too much, never overflowing.
+ */
+declare const WIDTH_SAFETY_FACTOR = 1.03;
+declare const HEIGHT_SAFETY_FACTOR = 1.04;
+/** One text run with the inputs measurement needs. */
+interface FitRun {
+  text: string;
+  sizePt: number;
+  bold?: boolean;
+  italic?: boolean;
+  fontFace?: string | undefined;
+  /** Character spacing in points (PowerPoint `spc`/1200). */
+  charSpacingPt?: number | undefined;
+}
+/**
+ * One paragraph: its runs plus vertical-rhythm options.
+ *
+ * The three `| undefined` members here are deliberate, and the exception to the rule the
+ * generator's option bags follow (`options-internal.ts`): these are measurement records, built in
+ * one place by `paragraphs.ts` and read in one place by the solver below, with `??` and
+ * truthiness. Nothing spreads or enumerates them, so a key holding `undefined` cannot mean
+ * anything different from an absent one — and the builder does produce every key on every run.
+ * Saying so is more honest than making the builder omit keys nothing distinguishes.
+ */
+interface FitParagraph {
+  runs: FitRun[];
+  /** Line spacing as a percent of single (100 = single). Ignored if `lineSpacingPts` set. */
+  lineSpacingPct?: number;
+  /** Exact line spacing in points (overrides `lineSpacingPct`). */
+  lineSpacingPts?: number | undefined;
+  spaceBeforePts?: number;
+  spaceAfterPts?: number;
+}
+/** Inner box (shape minus insets) the text must fit, in points. */
+interface FitBox {
+  innerWidthPt: number;
+  innerHeightPt: number;
+  /**
+   * `false` when the frame does not wrap (`wrap:false` / `wrap="none"`): text lays
+   * out as one line per paragraph (no width-wrapping), and the shrink solver must
+   * additionally keep the widest line within `innerWidthPt`. A too-wide line
+   * overflows HORIZONTALLY — `normAutofit`'s vertical shrink never catches it, so
+   * without this check a non-wrapping line is never shrunk and spills out of the box
+   * in PowerPoint. Defaults to wrapping (`true`), so table cells and `measureText`
+   * are unaffected.
+   */
+  wrap?: boolean;
+}
+/** Resolve the metrics for a run, or `undefined` if the face is not registered. */
+type MetricsResolver = (run: FitRun) => FontMetrics | undefined;
+interface ShrinkResult {
+  fontScalePct: number;
+  lnSpcReductionPct: number;
+}
+type ShrinkOutcome = {
+  kind: 'fits';
+} | {
+  kind: 'unmeasurable';
+} | {
+  kind: 'shrink';
+  result: ShrinkResult;
+};
+/** Laid-out result of {@link measureLayout}: total height (points) + wrapped line count. */
+interface LayoutResult {
+  heightPt: number;
+  lineCount: number;
+  /**
+   * Width (points) of the widest laid-out line across all paragraphs. Useful for
+   * tightening a box to the actual text extent or measuring a natural (single-line)
+   * width. Carries the same `widthSafety` inflation as the wrap decision, so a box
+   * set to this width will not re-wrap. Conservative (slightly wide).
+   */
+  widestLineWidthPt: number;
+}
+/**
+ * Lay out `paragraphs` at a given scale/reduction and return the total height
+ * (points) and wrapped line count, or `null` if any paragraph is unmeasurable.
+ * Errs tall (conservative): includes space-before/after and the calibrated line
+ * pitch. The single source of truth for both {@link measureHeightPt} (the solvers)
+ * and the public layout-time measure API.
+ */
+declare function measureLayout(paragraphs: FitParagraph[], innerWidthPt: number, resolve: MetricsResolver, fontScalePct: number, lnSpcReductionPct: number, widthSafety?: number): LayoutResult | null;
+/**
+ * Total laid-out height (points) at a given scale/reduction, or `null` if any
+ * paragraph is unmeasurable. Thin wrapper over {@link measureLayout}.
+ */
+declare function measureHeightPt(paragraphs: FitParagraph[], innerWidthPt: number, resolve: MetricsResolver, fontScalePct: number, lnSpcReductionPct: number, widthSafety?: number): number | null;
+/** What the resize solver concluded: it could not measure, or the inner height the text needs. */
+type ResizeOutcome = {
+  kind: 'unmeasurable';
+} | {
+  kind: 'resize';
+  neededInnerHeightPt: number;
+};
+/**
+ * Inner height (points) the text needs at full size — the value to bake into the
+ * shape's `a:ext/@cy` for `fit: 'resize'` (`spAutoFit`). Unlike shrink, resize has
+ * **no safety net**: an under-estimate overflows (there is no text scaling
+ * fallback), so this errs **tall** — width is inflated (earlier wrap ⇒ more lines)
+ * and the laid-out height by the calibrated height factor, so the computed `cy` is
+ * ≥ PowerPoint's and ≥ the LibreOffice-rendered height across the resize oracle.
+ */
+declare function solveResize(paragraphs: FitParagraph[], box: FitBox, resolve: MetricsResolver): ResizeOutcome;
+/**
+ * Largest `fontScale` (on PowerPoint's 2.5% grid) at which the text fits the box.
+ * Width and height both re-measured per scale. Conservative: because the model
+ * over-estimates, the returned scale is ≤ PowerPoint's and the text never overflows.
+ *
+ * `lnSpcReduction` is left at 0 — dropping `fontScale` alone is provably
+ * conservative (PowerPoint trades line-spacing reduction to keep the font *larger*,
+ * so a reduction-free fit is always ≤ PowerPoint's scale). The reduction ramp
+ * PowerPoint applies is recorded in `docs/contributing/design/text-fit.md`.
+ */
+declare function solveShrink(paragraphs: FitParagraph[], box: FitBox, resolve: MetricsResolver): ShrinkOutcome;
+//#endregion
+//#region src/measure/font-metrics.d.ts
+/** Per-(face,bold,italic) advance-width source backed by a parsed font file. */
+interface FontMetrics {
+  /** Font design units per em (advances are in these units). */
+  readonly unitsPerEm: number;
+  /**
+   * Advance width of `text` at `sizePt`, in points. Sums raw glyph advances
+   * (no kerning) and adds `charSpacingPt` after every character, matching how
+   * PowerPoint widens runs with character spacing.
+   */
+  advanceWidthPt: (text: string, sizePt: number, charSpacingPt?: number) => number;
+  /**
+   * True if this face's cmap maps code point `cp` to a real glyph (not the
+   * `.notdef` fallback). Use it to flag source code points the face cannot
+   * render. Authoritative only for file-backed metrics; the unregistered-font
+   * heuristic has no cmap and reports every code point as covered.
+   */
+  hasCodepoint: (cp: number) => boolean;
+}
+/**
+ * Shared, font-independent `FontMetrics` used when a named face has no registered
+ * metrics but the deck has opted into measured fit (some other face is registered).
+ * Approximate but conservative — see `heuristicCharRatio`. A deck with no
+ * registered metrics at all does not engage measured fit, so this never fires there.
+ */
+declare function getHeuristicFontMetrics(): FontMetrics;
+/** Options for {@link parseFontMetrics}. */
+interface ParseFontMetricsOptions {
+  /**
+   * Which font to read out of a file that holds several: a 0-based index, or a name
+   * matched case-insensitively against the family, full, and PostScript names
+   * (`listFontFaces` lists them). Omitted selects the first.
+   *
+   * Collections (`.ttc`/`.otc`) are why this exists: `msgothic.ttc` is three fonts and
+   * `cambria.ttc` is two. The selector means the same thing for a plain TTF/OTF, which
+   * is a one-entry list, so a wrong index or an unmatched name is an error there rather
+   * than being ignored.
+   */
+  readonly font?: number | string;
+}
+/**
+ * Parse a font file into a `FontMetrics`. Lazily imports opentype.js.
+ *
+ * Reads plain TTF/OTF and **font collections** (`.ttc`/`.otc`); for a collection, pass
+ * `font` to say which member, since a collection has no single answer. The underlying
+ * parser does not read the `ttcf` wrapper, so the selected member is unwrapped into a
+ * standalone sfnt first (see `measure/font-collection.ts`).
+ * @param {Uint8Array} data - the font file's bytes
+ * @param {ParseFontMetricsOptions} [opts] - which font, for a file holding several
+ * @returns {Promise<FontMetrics>} advance widths and cmap coverage for that font
+ * @example await parseFontMetrics(bytes) // a plain .ttf
+ * @example await parseFontMetrics(ttcBytes, { font: 'MS PGothic' })
+ */
+declare function parseFontMetrics(data: Uint8Array, opts?: ParseFontMetricsOptions): Promise<FontMetrics>;
+/**
+ * Registry of `FontMetrics` keyed by `(face, bold, italic)`. Variant advances
+ * differ, so bold/italic are stored separately; lookup falls back to the regular
+ * variant (then any registered variant of the face) so a deck that only registers
+ * the regular weight still measures bold runs approximately rather than not at all.
+ */
+declare class FontMetricsRegistry {
+  private readonly map;
+  private key;
+  set(face: string, metrics: FontMetrics, opts?: {
+    bold?: boolean;
+    italic?: boolean;
+  }): void;
+  /** True if any variant of `face` has registered metrics. */
+  hasFace(face: string): boolean;
+  /**
+   * Coverage of code point `cp` for `face`, read from the registered font's cmap:
+   * `true`/`false` when a variant of `face` is registered (see {@link get} for the
+   * exact→regular→any-variant fallback), or `undefined` when the face has **no**
+   * registered metrics — "unknown", deliberately distinct from a `false`
+   * "registered but not covered". A coverage audit must not treat an unregistered
+   * face as fully covered, so callers get `undefined` here rather than the per-face
+   * {@link FontMetrics.hasCodepoint} boolean (which, for the heuristic fallback,
+   * always reports covered). Register the face via {@link parseFontMetrics} +
+   * {@link set} first.
+   */
+  hasCodepoint(face: string | undefined | null, cp: number, opts?: {
+    bold?: boolean;
+    italic?: boolean;
+  }): boolean | undefined;
+  /** Resolve metrics for a run, falling back from exact variant → regular → any variant. */
+  get(face: string | undefined | null, bold?: boolean, italic?: boolean): FontMetrics | undefined;
+  get size(): number;
+}
+/**
+ * A {@link MetricsResolver} backed by a registry: exact metrics for a registered face, otherwise
+ * the shared heuristic fallback (with `onHeuristic` told which face it stood in for). A run with
+ * no `fontFace` at all resolves to `undefined`, which the callers treat as unmeasurable.
+ */
+declare function makeRegistryResolver(registry: FontMetricsRegistry, onHeuristic?: (face: string) => void): MetricsResolver;
+//#endregion
+export { SlideObject as A, solveShrink as C, SectionInternalProps as D, PresentationPropsInternal as E, SlideRelChart as M, SlideRelMedia as N, SlideLayoutInternal as O, solveResize as S, PresSlideInternal as T, ShrinkOutcome as _, makeRegistryResolver as a, measureHeightPt as b, FitBox as c, HEIGHT_SAFETY_FACTOR as d, LayoutResult as f, SINGLE_LINE_PITCH as g, ResizeOutcome as h, getHeuristicFontMetrics as i, SlideRel as j, SlideMasterInternal as k, FitParagraph as l, MetricsResolver as m, FontMetricsRegistry as n, parseFontMetrics as o, MIN_FONT_SCALE_PCT as p, ParseFontMetricsOptions as r, FONT_SCALE_STEP_PCT as s, FontMetrics as t, FitRun as u, ShrinkResult as v, ObjectOptionsInternal as w, measureLayout as x, WIDTH_SAFETY_FACTOR as y };
+//# sourceMappingURL=font-metrics-v5fn7s7e.d.ts.map

package/dist/font-metrics-v5fn7s7e.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"font-metrics-v5fn7s7e.d.ts","names":[],"sources":["../src/types/internal.ts","../src/measure/text-fit.ts","../src/measure/font-metrics.ts"],"mappings":"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"}