### Install Geviert

Source: https://geviert.melissawiederrecht.com/

Install the library via npm.

```bash
npm install geviert
```

--------------------------------

### programme(spec: object)

Source: https://geviert.melissawiederrecht.com/docs

Initializes a programme with a given specification, returning an object with methods to retrieve solutions, count, layout, reroll, and sample.

```APIDOC
## programme(spec: object)

### Description
Initializes a programme with a given specification. Returns an interface to interact with the generated solutions.

### Methods
- **solutions(opts?: { limit?: number })**: Returns an array of solutions.
- **count()**: Returns the number of solutions.
- **layout(seed: string)**: Returns the layout object for a given seed.
- **reroll(seed: string, opts?: { lock?: string[] })**: Rerolls the layout based on a seed and optional locks.
- **sample(seed: string, n: number)**: Returns a sample of n solutions based on a seed.
```

--------------------------------

### programmes.book(opts)

Source: https://geviert.melissawiederrecht.com/docs

Creates a preset for an A4 book layout with a legal grid and type system.

```APIDOC
## programmes.book(opts)

### Description
Creates a complete, opinionated commission for an A4 book layout. Every key is overridable after the spread.

### Parameters
- **opts** (object) - Optional
  - **font** (string) - Optional
  - **accent** (string) - Optional
  - **page** (object) - Optional
    - **w** (number)
    - **h** (number)
  - **module** (number) - Optional

### Returns
- **ProgrammePreset** (object) - The configured layout preset.
```

--------------------------------

### style(size, leading, opts)

Source: https://geviert.melissawiederrecht.com/docs

Creates a new text style object with specified size, leading, and optional font properties.

```APIDOC
## style(size, leading, opts)

### Description
Creates a text style object. Leading is the space added to the size (e.g., 9/3 results in 12pt line height).

### Parameters
- **size** (number) - Required - The font size.
- **leading** (number) - Required - The space added to the size.
- **opts** (object) - Optional - Configuration object containing font, weight, italic, and color.
```

--------------------------------

### Manage Font Metrics and Registration

Source: https://geviert.melissawiederrecht.com/docs

Handles font registration, metric retrieval, and CSS generation for web-based rendering.

```typescript
export interface FontMetrics {
  family: string; capHeight: number; xHeight: number; descent: number;
  fallbackWidth: number; widths: Record<string, number>;
  dataUri?: string; format?: string;
}
export function registerFont(name: string, metrics: FontMetrics): void;
export function fontMetrics(name: string): FontMetrics;
/** @font-face CSS for every registered font that carries a dataUri. */
export function fontFaceCSS(): string;
```

--------------------------------

### Compose a Document

Source: https://geviert.melissawiederrecht.com/

Register fonts, define a type system, and compose a document using grid constraints and a seed.

```javascript
// Any real font, one call (optional peer: opentype.js)
await registerFontFile('inter', './Inter-Regular.ttf');

// The register: refuses illegal line heights, and names the legal ones
const T = typeSystem({ module: 12, roles: { body, chapter, caption } }).roles;

const pages = composeDocument({
  grid: ({ side }) => grid({ page: 'A4', margins, columns: 4,
                             line: T.body.lineHeight, rows: 8, side }),
  styles: T,
  story: [{ text: 'ONE', role: 'chapter', rule: true }, ...paragraphs],
  figures: [
    { anchor: '(Plate 3)', sizes: [{ cols: 2, rows: 3 }], href, caption },
    { anchor: '(Chart 1)', sizes: [{ cols: 2, rows: 3 }],
      chart: { data } },       // bars are WHOLE TEXT LINES, by law
  ],
  paragraphDevice: 'indent',   // or 'line'; MB p.34 names both
  bodyAlign: 'justify',        // grid-aware Knuth–Plass
  seed: 'a-seed',              // same seed, same book, forever
}).pages;

renderDOM(pages[0], el);          // live text on the baseline grid
renderPage(pages[0]);             // or SVG, or print-ready PDF
```

--------------------------------

### renderDOM(page, container, opts)

Source: https://geviert.melissawiederrecht.com/docs

Renders a page into a live DOM element with selectable text on a baseline grid.

```APIDOC
## renderDOM(page, container, opts)

### Description
Renders a page into a live DOM element. Baselines are measured from the browser.

### Parameters
- **page** (object) - Required
  - **grid** (GridGeometry) - Optional
  - **page** (object) - Optional
    - **w** (number)
    - **h** (number)
  - **items** (PageItem[]) - Required
- **container** (HTMLElement) - Required
- **opts** (object) - Optional
  - **scale** (number) - Optional
  - **background** (string) - Optional
  - **showGrid** (boolean) - Optional
  - **showBaselines** (boolean) - Optional

### Returns
- **HTMLElement** - The rendered DOM element.
```

--------------------------------

### Document Programme Presets

Source: https://geviert.melissawiederrecht.com/docs

Defines opinionated document structures including grids, type systems, and layout settings. Use these presets to initialize a document configuration before spreading into composeDocument.

```typescript
/**
 * Complete, opinionated commissions ready to spread into composeDocument:
 * a legal grid, a registered type system, and the setting options a book of
 * that kind wants. One line to a good page; every key overridable after the
 * spread. book: MB's own A4 page (p.87). essay: one generous measure with a
 * deep margin. booklet: A5, two narrow columns, small face.
 */
export const programmes: {
  book(opts?: { font?: string; accent?: string; page?: { w: number; h: number }; module?: number }): ProgrammePreset;
  essay(opts?: { font?: string; page?: { w: number; h: number }; module?: number }): ProgrammePreset;
  booklet(opts?: { font?: string; accent?: string; page?: { w: number; h: number }; module?: number }): ProgrammePreset;
};
export interface ProgrammePreset {
  grid: (ctx: { side: 'left' | 'right' }) => GridGeometry;
  styles: Record<string, Style> & { body: Style };
  textSpan: number;
  bodyAlign: 'left' | 'justify';
  paragraphDevice: 'line' | 'indent';
}
```

--------------------------------

### Configure Measurement and Breaking Backends

Source: https://geviert.melissawiederrecht.com/docs

Allows overriding the default measurement and greedy breaking logic for custom environments.

```typescript
/** Replace the measurement backend (the browser adapter uses this). */
export function setMeasurer(fn: ((text: string, st: Style) => number) | null): void;
/**
 * Optional fast path for GREEDY breaking (never Knuth–Plass). Must agree with
 * the built-in breaker line for line; return null to decline.
 */
export function setGreedyBreaker(fn: ((text: string, width: number, st: Style) => string[] | null) | null): void;
```

--------------------------------

### Grid Layout Interfaces and Functions

Source: https://geviert.melissawiederrecht.com/docs

Core interfaces for defining page dimensions and margins, along with functions to generate grid geometries and calculate type areas.

```typescript
export interface Rect { x: number; y: number; w: number; h: number }
export interface Margins { inner: number; head: number; outer: number; tail: number }

export function marginsFromRatio(ratio: 'classical' | 'golden' | Margins, scale: number): Margins;
/**
 * Scale a margin canon so the type area is exactly `fraction` of the page
 * area (p.51 diagrams 1–2: the 1:2 relation).
 */
export function marginsForAreaFraction(page: { w: number; h: number }, ratio: 'classical' | 'golden' | Margins, fraction?: number): Margins;
export function typeArea(page: { w: number; h: number }, margins: Margins, side?: 'left' | 'right'): Rect;

export interface GridGeometry {
  page: { w: number; h: number };
  margins: Margins;
  typeArea: Rect;
  columns: Rect[];
  rows: Rect[];
  fields: Rect[];
  line: number;
  columnGutter: number;
  rowGutter: number;
  linesPerField: number;
  side: 'left' | 'right';
  /** rect spanning fields [col..col+cols) × [row..row+rows) */
  field(col: number, row: number, cols?: number, rows?: number): Rect;
  baselines(): number[];
}

/**
 * The modular grid (pp.57–70): field heights are whole lines, gutters are
 * whole empty lines. There is no way to express an off-grid position.
 */
export function grid(spec: {
  page: { w: number; h: number } | 'A4' | 'A5' | 'A3';
  margins: Margins;
  columns: number; columnGutter: number;
  line: number; rows: number; rowGutterLines?: number;
  side?: 'left' | 'right';
}): GridGeometry;

/** The book's own dimensioned A4 reference grids (pp.73, 77, 88). */
export const presets: {
  mb8(side?: 'left' | 'right'): GridGeometry;
  mb20(side?: 'left' | 'right'): GridGeometry;
  mb32(side?: 'left' | 'right'): GridGeometry;
};
```

--------------------------------

### captionBelow

Source: https://geviert.melissawiederrecht.com/docs

Creates a caption positioned below a specified image rectangle.

```APIDOC
## captionBelow

### Description
Generates a caption item placed below an image rectangle with defined text and styling.

### Signature
`export function captionBelow(imageRect: Rect, text: string, st: Style, opts?: { lines?: number; gapLines?: number }): PageItem;`
```

--------------------------------

### Measure Text and Calculate Sizes

Source: https://geviert.melissawiederrecht.com/docs

Functions for calculating string width and determining optimal font sizes based on measure constraints.

```typescript
/** Width of a string in a style, from the registered metrics or the seam. */
export function measure(text: string, st: Style): number;
export function wordsPerLine(width: number, st: Style): number;

/**
 * The largest face (min..max) whose measure holds `words` per line : the
 * column decides the face (p.57); 8–12pt is the book floor (p.18).
 */
export function sizeForMeasure(width: number, opts?: {
  words?: number; font?: string; min?: number; max?: number;
  leadingRatio?: number; weight?: Style['weight'];
}): { size: number; leading: number; lineHeight: number; wordsPerLine: number; meets: boolean };
```

--------------------------------

### grid

Source: https://geviert.melissawiederrecht.com/docs

Generates a modular grid geometry based on page specifications and layout constraints.

```APIDOC
## grid(spec)

### Description
Creates a modular grid geometry where field heights and gutters are aligned to whole lines.

### Parameters
- **spec** (Object) - Required - Configuration object containing page dimensions, margins, column/row counts, and gutter settings.
```

--------------------------------

### Layout Helper Functions

Source: https://geviert.melissawiederrecht.com/docs

Functions for generating document layout elements like contents leaves, folios, and captions.

```typescript
/**
 * A contents leaf from report.contents: titles on the left of a column, page
 * numbers flush at its right edge, heads indented one em. Fills columns as the
 * list demands. Returns items for a hand-built leaf.
 */
export function contentsLeaf(g: GridGeometry, entries: { title: string; role: string; page: number }[], opts: {
  styles: Record<string, Style> & { body: Style };
  title?: string; roles?: string[]; ink?: string; accent?: string;
  /** list rhythm, in body lines per entry */
  leading?: number;
  /** grid columns per list column (default: half the grid) */
  span?: number | null;
}): PageItem[];

export function folio(g: GridGeometry, pageNumber: number, opts?: {
  placement?: 'second-column' | 'left' | 'outer' | 'center';
  lines?: number; style: Style; side?: 'left' | 'right';
}): PageItem;
export function captionBelow(imageRect: Rect, text: string, st: Style, opts?: { lines?: number; gapLines?: number }): PageItem;
```

--------------------------------

### Hyphenation Configuration

Source: https://geviert.melissawiederrecht.com/docs

Utilities for setting and creating hyphenation functions.

```typescript
export function setHyphenator(fn: ((word: string) => string[]) | null): void;
export function hyphenatorFrom(hyphenateSync: (word: string) => string): (word: string) => string[];
```

--------------------------------

### typeSystem(spec)

Source: https://geviert.melissawiederrecht.com/docs

Enforces a cross-size register where every role's line height must divide the module or be a whole multiple of it.

```APIDOC
## typeSystem(spec)

### Description
Validates that all roles in the type system adhere to the module-based line height constraints. Throws an error if a role breaks the register.

### Parameters
- **spec** (object) - Required - Contains the module number and a record of roles (Style objects).
```

--------------------------------

### Hyphenation Utilities

Source: https://geviert.melissawiederrecht.com/docs

Functions to configure and create hyphenation logic for text layout.

```APIDOC
## setHyphenator
`export function setHyphenator(fn: ((word: string) => string[]) | null): void;`

## hyphenatorFrom
`export function hyphenatorFrom(hyphenateSync: (word: string) => string): (word: string) => string[];`
```

--------------------------------

### marginsFromRatio

Source: https://geviert.melissawiederrecht.com/docs

Calculates margin dimensions based on a predefined ratio or custom margin object.

```APIDOC
## marginsFromRatio(ratio, scale)

### Description
Calculates margin dimensions based on a predefined ratio ('classical' or 'golden') or a custom Margins object, scaled by a provided factor.

### Parameters
- **ratio** ('classical' | 'golden' | Margins) - Required - The ratio type or custom margin object.
- **scale** (number) - Required - The scaling factor for the margins.
```

--------------------------------

### gerstnerNumber(divisions: number[], gutter: number)

Source: https://geviert.melissawiederrecht.com/docs

Calculates the units and widths based on divisions and gutter settings.

```APIDOC
## gerstnerNumber(divisions: number[], gutter: number)

### Description
Calculates layout units and widths based on the provided division array and gutter size.

### Returns
- **units** (number)
- **widths** (Record<number, number[]>)
```

--------------------------------

### Document Rendering Functions

Source: https://geviert.melissawiederrecht.com/docs

Provides utilities for rendering document specifications to SVG or DOM, including browser-based font measurement and baseline cache management.

```typescript
/** One page → a self-contained SVG string. */
export function renderPage(spec: {
  grid?: GridGeometry; page?: { w: number; h: number };
  items?: PageItem[];
  showGrid?: boolean; showBaselines?: boolean;
  background?: string; scale?: number;
}): string;

/**
 * One page → live DOM: selectable text on the baseline grid, baselines
 * MEASURED from the browser (never computed from font metrics).
 */
export function renderDOM(page: { grid?: GridGeometry; page?: { w: number; h: number }; items: PageItem[] },
  container: HTMLElement,
  opts?: { scale?: number; background?: string; showGrid?: boolean; showBaselines?: boolean }): HTMLElement;
export function clearBaselineCache(): void;

/** Measure through the canvas of the very fonts about to be drawn. */
export function useBrowserFonts(opts?: { families?: Record<string, string>; scale?: number }): Promise<void>;
export function pageFromElement(el: HTMLElement): { w: number; h: number };
```

--------------------------------

### Define Typography Styles and Systems

Source: https://geviert.melissawiederrecht.com/docs

Defines the Style interface and functions for creating styles and enforcing type system constraints.

```typescript
export interface Style {
  size: number;
  leading: number;
  /** size + leading : the vertical unit everything registers on */
  lineHeight: number;
  font: string;
  weight: 'normal' | 'bold' | 'semibold' | number;
  italic?: boolean;
  /** optional per-role ink (used when the style is a typeSystem role) */
  color?: string;
  /** optional per-role setting; 'center' is the centred axis (p.79) */
  align?: 'left' | 'center' | 'justify';
}

/** A text style. Leading is the space ADDED to the size (9/3 → 12pt line). */
export function style(size: number, leading: number, opts?: {
  font?: string; weight?: Style['weight']; italic?: boolean; color?: string;
}): Style;

/**
 * Enforces the cross-size register (pp.59, 66): every role's line height must
 * divide the module or be a whole multiple of it. Throws with the nearest
 * legal settings named when a role breaks it.
 */
export function typeSystem<R extends Record<string, Style>>(spec: { module: number; roles: R }): {
  module: number; roles: R;
};
```

--------------------------------

### marginsForAreaFraction

Source: https://geviert.melissawiederrecht.com/docs

Calculates margins such that the type area occupies a specific fraction of the total page area.

```APIDOC
## marginsForAreaFraction(page, ratio, fraction)

### Description
Calculates a margin canon so the type area is exactly the specified fraction of the page area.

### Parameters
- **page** ({ w: number; h: number }) - Required - The dimensions of the page.
- **ratio** ('classical' | 'golden' | Margins) - Required - The ratio type or custom margin object.
- **fraction** (number) - Optional - The target fraction of the page area to be occupied by the type area.
```

--------------------------------

### morphologicalBox(axes: Record<string, unknown[]>)

Source: https://geviert.melissawiederrecht.com/docs

Creates a morphological box from the provided axes, allowing for indexing and sampling.

```APIDOC
## morphologicalBox(axes: Record<string, unknown[]>)

### Description
Creates a morphological box structure from defined axes.

### Methods
- **count**: Returns the total count of combinations.
- **at(index: number)**: Returns the record at a specific index.
- **sample(seed: string)**: Returns a sampled record based on a seed.
```

--------------------------------

### Break Paragraphs into Lines

Source: https://geviert.melissawiederrecht.com/docs

Provides utilities for breaking text into lines using either Knuth–Plass or greedy algorithms, including support for variable measures and indentation.

```typescript
export interface BreakOptions {
  /** Knuth–Plass when true (default); greedy when false */
  optimal?: boolean;
  mode?: 'left' | 'justify';
}
/** Break a paragraph at a fixed measure. */
export function breakLines(text: string, width: number, st: Style, opts?: BreakOptions): string[];
/** The same breaker where the measure may change per line (drop caps, intrusions). */
export function breakVariable(text: string, widthFor: (line: number) => number, st: Style, opts?: BreakOptions): string[];
export function breakIndented(text: string, width: number, st: Style, indentLines: number, indentWidth: number, opts?: BreakOptions): string[];
```

--------------------------------

### Define Paragraph and FlowBox Interfaces

Source: https://geviert.melissawiederrecht.com/docs

Interfaces for configuring paragraph layout properties and representing the resulting flow boxes.

```typescript
export interface Paragraph {
  text: string;
  /** a heading keeps `keep` lines of what follows with it */
  keepWithNext?: boolean;
  /** whole empty lines before (number), or false; default 1 ('line' device) */
  spaceBefore?: number | boolean;
  /** extra whole empty lines after : the rest zone (p.69) */
  spaceAfter?: number;
  /** set in styles[role]: its own face, whole slots, never split (pp.46-47, 87) */
  role?: string;
  /** hairline under the titled line (placement example 8, p.47) */
  rule?: boolean;
  /** a dropped initial, from dropCap() */
  initial?: ReturnType<typeof dropCap>;
  /** open a new page before this paragraph (a chapter, a concert) */
  pageBreak?: boolean;
  /**
   * Footnotes. Numbered across the book; a superscript marker is appended to
   * this paragraph's text before measurement, and the notes are set at the
   * foot of the last text column of the page where the paragraph ENDS, above
   * a short hairline, in styles.note (else the caption role). Array-form
   * stories only.
   */
  notes?: string[];
  /** shorthand for notes: [note] */
  note?: string;
}

export interface FlowBox {
  rect: Rect; lines: string[]; indents: number[]; flush: boolean[];
  roles: (string | undefined)[]; slots: number[]; ruleAfter: boolean[];
}
```

--------------------------------

### measure(text, st)

Source: https://geviert.melissawiederrecht.com/docs

Calculates the width of a string based on the provided style.

```APIDOC
## measure(text, st)

### Description
Returns the width of a string in a given style, using registered metrics.

### Parameters
- **text** (string) - Required - The text to measure.
- **st** (Style) - Required - The style object to apply.
```

--------------------------------

### Gerstner Programme Layer API Definitions

Source: https://geviert.melissawiederrecht.com/docs

Provides the core function signatures for programme generation, grid management, and morphological box operations.

```typescript
// Typed loosely on purpose: the solver's DSL is documented in the README and
// research/foundations.md; these types keep call sites honest without
// freezing a young API.

export function programme(spec: object): {
  solutions(opts?: { limit?: number }): object[];
  count(): number;
  layout(seed: string): object;
  reroll(seed: string, opts?: { lock?: string[] }): object;
  sample(seed: string, n: number): object[];
};
export function mobileGrid(units: number, opts?: object): object;
export function mobileProgramme(spec: object): object;
export function gerstnerNumber(divisions: number[], gutter: number): { units: number; widths: Record<number, number[]> };
export function compoundProgramme(spec: object): object;
export function morphologicalBox(axes: Record<string, unknown[]>): {
  count: number; at(index: number): Record<string, unknown>; sample(seed: string): Record<string, unknown>;
};

export function mfield(...args: unknown[]): object;
export function malign(...args: unknown[]): { left(): object; right(): object; top(): object };
export function mbelow(...args: unknown[]): object;
export function mwhitespace(...args: unknown[]): object;
export function story(...args: unknown[]): object;
export function initialIndents(...args: unknown[]): number[];
```

--------------------------------

### breakLines(text, width, st, opts)

Source: https://geviert.melissawiederrecht.com/docs

Breaks a paragraph into lines at a fixed measure.

```APIDOC
## breakLines(text, width, st, opts)

### Description
Breaks a paragraph at a fixed measure using Knuth–Plass or greedy algorithms.

### Parameters
- **text** (string) - Required - The text to break.
- **width** (number) - Required - The width constraint.
- **st** (Style) - Required - The style to apply.
- **opts** (BreakOptions) - Optional - Configuration for optimal (Knuth-Plass) or greedy mode.
```

--------------------------------

### registerFont(name, metrics)

Source: https://geviert.melissawiederrecht.com/docs

Registers font metrics for use in the library.

```APIDOC
## registerFont(name, metrics)

### Description
Registers font metrics including cap height, x-height, and character widths.

### Parameters
- **name** (string) - Required - The font name.
- **metrics** (FontMetrics) - Required - The font metrics object.
```

--------------------------------

### typeArea

Source: https://geviert.melissawiederrecht.com/docs

Calculates the rectangle representing the type area on a page given specific margins.

```APIDOC
## typeArea(page, margins, side)

### Description
Computes the Rect dimensions for the type area based on page size and margin constraints.

### Parameters
- **page** ({ w: number; h: number }) - Required - The dimensions of the page.
- **margins** (Margins) - Required - The margin configuration.
- **side** ('left' | 'right') - Optional - The page side for asymmetric margin calculations.
```

--------------------------------

### Flow Text and Paragraphs Functions

Source: https://geviert.melissawiederrecht.com/docs

Functions for processing text and paragraph arrays into layout boxes.

```typescript
export function flowText(text: string, rects: Rect[], st: Style): {
  boxes: { rect: Rect; lines: string[] }[]; overflow: string | null; overflowWords: number; spareLines: number;
};
export function flowParagraphs(paragraphs: (Paragraph | string)[], rects: Rect[], st: Style, opts?: {
  keep?: number; widowControl?: boolean; minLines?: number;
  mode?: 'left' | 'justify'; optimal?: boolean;
  styles?: Record<string, Style> | null;
  /** paragraph device (p.34): 'line' (default) or 'indent' */
  device?: 'line' | 'indent';
  indentWidth?: number | null;
}): {
  boxes: FlowBox[];
  initials: { box: number; line: number; slot: number; letter: string; initial: ReturnType<typeof dropCap> }[];
  overflow: string | null; overflowWords: number;
  overflowParagraphs: Paragraph[]; spareLines: number;
};
```

--------------------------------

### Deterministic Randomness

Source: https://geviert.melissawiederrecht.com/docs

A seeded PRNG class and underlying algorithms for deterministic random number generation.

```typescript
/** xmur3 + sfc32: the seeded PRNG everything deterministic runs on. */
export class Rand {
  constructor(seed: string);
  dec(): number;
  int(maxExclusive: number): number;
  choice<T>(arr: T[]): T;
}
export function xmur3(seed: string): () => number;
export function sfc32(a: number, b: number, c: number, d: number): () => number;
```

--------------------------------

### renderPage(spec)

Source: https://geviert.melissawiederrecht.com/docs

Renders a single page into a self-contained SVG string.

```APIDOC
## renderPage(spec)

### Description
Converts a page specification into a self-contained SVG string.

### Parameters
- **spec** (object) - Required
  - **grid** (GridGeometry) - Optional
  - **page** (object) - Optional
    - **w** (number)
    - **h** (number)
  - **items** (PageItem[]) - Optional
  - **showGrid** (boolean) - Optional
  - **showBaselines** (boolean) - Optional
  - **background** (string) - Optional
  - **scale** (number) - Optional

### Returns
- **string** - The rendered SVG content.
```

--------------------------------

### Generate Drop Caps

Source: https://geviert.melissawiederrecht.com/docs

Calculates the layout parameters for a dropped initial character based on body style and line count.

```typescript
/** A dropped initial (p.36): size derived from N body lines of cap height. */
export function dropCap(letter: string, opts: {
  bodyStyle: Style; lines?: number; font?: string; weight?: Style['weight'];
  italic?: boolean; color?: string; snap?: boolean;
}): { letter: string; lines: number; width: number; style: Style; color?: string; offsetY?: number };
```

--------------------------------

### Rand Class

Source: https://geviert.melissawiederrecht.com/docs

A seeded pseudo-random number generator for deterministic document generation.

```APIDOC
## Rand

### Description
Class providing deterministic random number generation based on a seed.

### Methods
- `constructor(seed: string)`
- `dec(): number`
- `int(maxExclusive: number): number`
- `choice<T>(arr: T[]): T`
```

--------------------------------

### Define Document Layer Interfaces

Source: https://geviert.melissawiederrecht.com/docs

Interfaces for figures, page items, and the document composition engine. The composeDocument function is deterministic based on the provided seed.

```typescript
export interface Figure {
  id?: string;
  /** substring of the story this figure belongs beside ("(Plate 3)") */
  anchor?: string;
  /** size vocabulary in grid columns × field rows : few graded sizes (p.11) */
  sizes?: { cols: number; rows: number }[];
  cols?: number; rows?: number;
  href?: string;
  /**
   * preferred w/h. The beam scores placements against it, and a placed picture
   * is NEVER cropped: when the chosen fields miss the aspect, the picture keeps
   * its proportions inside them (full width hung from the top, or full height
   * on the reading edge) and the caption follows the picture's edge.
   */
  aspect?: number;
  aspectWeight?: number;
  caption?: string;
  captionColor?: string;
  /** one ink (feColorMatrix ramp in SVG) */
  duotone?: boolean | { shadow: string; highlight: string };
  /** 'cover' opts back in to cropping, for photographs that can afford it */
  fit?: 'meet' | 'cover';
  /** run off the paper on these sides */
  bleed?: boolean | ('left' | 'right' | 'top' | 'bottom')[];
  /** take the whole leaf, caption in the margin */
  fullPage?: boolean;
  captionBg?: string;
  /** ── the cut-out apparatus (p.98) ── */
  /** colour area beneath the cut-out, sized to its fields */
  tint?: string;
  /** line border with the field's dimensions */
  border?: boolean; borderWidth?: number; borderColor?: string;
  /** rules at the field's top and bottom limits */
  bracket?: boolean; bracketWidth?: number; bracketColor?: string;
  /** colour printed over the photograph : dominant */
  overprint?: string;
  /** a pull quote occupying fields, sized to fill them */
  quote?: string; quoteStyle?: Style; quoteColor?: string;
  /** a statistic occupying fields; bars are whole text lines (pp.14, 58-59) */
  chart?: {
    data: { label?: string; value: number }[];
    max?: number; barColor?: string; color?: string;
    format?: (v: number) => string;
  };
  seed?: string;
}

export interface PageItem {
  kind: 'text' | 'image' | 'block' | 'rule' | 'frame' | 'chart';
  rect: Rect;
  [key: string]: unknown;
}
export interface ComposedPage {
  number: number; grid: GridGeometry; items: PageItem[];
  side: 'left' | 'right'; plate?: boolean;
}

/**
 * The point of the library: story + figures + grid + seed → pages.
 * Deterministic: the same seed returns the same book, forever.
 */
export function composeDocument(spec: {
  grid: GridGeometry | ((ctx: { pageNo: number; side: 'left' | 'right' }) => GridGeometry);
  styles: Record<string, Style> & { body: Style };
  /**
   * The manuscript. Text may contain "{page:figureId}" tokens: each resolves
   * to the page its figure lands on (compose, substitute, recompose until
   * stable); unknown ids are set as 00 and listed in report.unresolvedRefs.
   */
  story: string | (Paragraph | string)[];
  title?: string | null; titleRows?: number;
  figures?: Figure[];
  seed?: string;
  folio?: { start?: number; placement?: 'second-column' | 'left' | 'outer' | 'center' } | false;
  maxPages?: number;
  ink?: string | null;
  /** grid columns per text column (the book's own page spans 2, p.87) */
  textSpan?: number;
  textSnap?: boolean | null;
  /** the taste dial, in cost units : see each key's page in the source */
  harmony?: { newSize?: number; sameBand?: number; sharedEdge?: number; stacked?: number; adrift?: number };
  /** pull toward the anchor's column: a preference, not a law */
  anchorPull?: number;
  dispositions?: { bands?: number[]; bandPull?: number; heroChance?: number; heroPull?: number };
  bodyAlign?: 'left' | 'justify' | 'center';
  minSegmentLines?: number;
  marginCaptions?: boolean;
  /** paragraph device (p.34): 'line' | 'indent' */
  paragraphDevice?: 'line' | 'indent';
  indentWidth?: number | null;
  /** elastic limits for justified spaces, in multiples of the natural space */
  justify?: { shrink?: number; stretch?: number };
  captionAir?: number;
  titleRule?: { offset?: number; width?: number };
  quoteFit?: { ceiling?: number; leading?: number };
  /** softmax temperature of the page search; 0 = deterministic top-k */
  explore?: number;
  /**
   * A running head on every page except chapter openings and the first:
   * true (the current chapter's title), a fixed string, or a function of
   * ({ pageNo, side, chapter }). Set at the outer edge of the head margin,
   * in styles.runningHead, else the caption role.
   */
  runningHead?: boolean | string | ((ctx: { pageNo: number; side: 'left' | 'right'; chapter: string | null }) => string);
}): {
  pages: ComposedPage[];
  report: {
    fits: boolean; leftoverWords: number;
    figures: { id: string; placed: boolean; page?: number; anchorPage?: number; drift?: number }[];
    /** every chapter and head, with the page it landed on : feed to contentsLeaf() */
    contents: { title: string; role: string; page: number }[];
    /** "{page:id}" tokens whose figure never placed (set as 00 in the text) */
    unresolvedRefs?: string[];
  };
};
```

--------------------------------

### composeDocument

Source: https://geviert.melissawiederrecht.com/docs

The primary function of the library. It takes a document specification including story text, figures, and grid settings, and returns the composed pages along with a report on the placement of figures and references.

```APIDOC
## composeDocument

### Description
Composes a document from a manuscript, figures, and grid configuration. The process is deterministic based on the provided seed.

### Parameters
- **spec** (object) - Required - The document specification object.
  - **grid** (GridGeometry | function) - Required - The grid layout or a function returning the grid based on page context.
  - **styles** (object) - Required - Style definitions including a mandatory 'body' style.
  - **story** (string | array) - Required - The manuscript text, potentially containing "{page:figureId}" tokens.
  - **figures** (array) - Optional - A list of Figure objects to be placed in the document.
  - **seed** (string) - Optional - A seed for deterministic output.

### Response
- **pages** (array) - The resulting list of ComposedPage objects.
- **report** (object) - A summary report containing:
  - **fits** (boolean) - Whether the content fit within the constraints.
  - **leftoverWords** (number) - Count of words that could not be placed.
  - **figures** (array) - Status of each figure placement.
  - **contents** (array) - List of chapters and heads with their page numbers.
  - **unresolvedRefs** (array) - List of figure IDs that could not be resolved.
```

--------------------------------

### folio

Source: https://geviert.melissawiederrecht.com/docs

Places a page number (folio) on a document page based on specified placement and styling.

```APIDOC
## folio

### Description
Generates a page item representing a folio number with specific placement and styling rules.

### Signature
`export function folio(g: GridGeometry, pageNumber: number, opts?: { placement?: 'second-column' | 'left' | 'outer' | 'center'; lines?: number; style: Style; side?: 'left' | 'right'; }): PageItem;`
```

--------------------------------

### contentsLeaf

Source: https://geviert.melissawiederrecht.com/docs

Generates a table of contents leaf for a document, handling column filling and formatting.

```APIDOC
## contentsLeaf

### Description
Creates a contents leaf from report entries, aligning titles and page numbers within a grid layout.

### Signature
`export function contentsLeaf(g: GridGeometry, entries: { title: string; role: string; page: number }[], opts: { styles: Record<string, Style> & { body: Style }; title?: string; roles?: string[]; ink?: string; accent?: string; leading?: number; span?: number | null; }): PageItem[];`
```

--------------------------------

### flowText

Source: https://geviert.melissawiederrecht.com/docs

Flows a string of text into a series of rectangular areas.

```APIDOC
## flowText(text, rects, st)

### Description
Flows a string of text into an array of provided rectangles based on the provided style.

### Parameters
- **text** (string) - The text content to flow.
- **rects** (Rect[]) - An array of rectangles to flow the text into.
- **st** (Style) - The style configuration for the text.

### Response
- **boxes** (Array) - The resulting boxes containing rects and lines.
- **overflow** (string | null) - Remaining text if it does not fit.
- **overflowWords** (number) - Count of words that did not fit.
- **spareLines** (number) - Number of unused lines.
```

--------------------------------

### flowParagraphs

Source: https://geviert.melissawiederrecht.com/docs

Flows an array of paragraphs into a series of rectangular areas with advanced layout options.

```APIDOC
## flowParagraphs(paragraphs, rects, st, opts)

### Description
Flows structured paragraphs into rectangles, supporting features like widow control, indentation, and custom styles.

### Parameters
- **paragraphs** ((Paragraph | string)[]) - The list of paragraphs or strings to flow.
- **rects** (Rect[]) - The target rectangles.
- **st** (Style) - The base style configuration.
- **opts** (Object) - Optional configuration including keep, widowControl, minLines, mode, optimal, styles, device, and indentWidth.

### Response
- **boxes** (FlowBox[]) - The resulting flow boxes.
- **initials** (Array) - Information about dropped initials.
- **overflow** (string | null) - Remaining text if it does not fit.
- **overflowWords** (number) - Count of words that did not fit.
- **overflowParagraphs** (Paragraph[]) - Paragraphs that did not fit.
- **spareLines** (number) - Number of unused lines.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.