postext 1.23.0 → 1.25.0

package/dist/types.d.ts

@@ -88,7 +88,96 @@ export interface ResourcePlacement {
      *  figure's top (its bottom for a bottom float). A page without such a
      *  column keeps the caption under the figure. Column floats only. */
     captionSide?: boolean;
-}
+    /** Scale a floated picture (bitmap, SVG, a video's poster) down, keeping
+     *  its proportions, to the room a slot has, instead of moving it on
+     *  (#626). `'never'`: a float either fits a slot at its size or waits
+     *  for a later one. `'page'`: a float too tall for the band of a fresh
+     *  page — the content area less what already stands there: an opener,
+     *  other floats, footnotes, the float gap — shrinks to that band.
+     *  `'slot'`: as `'page'`, and a float too tall for a slot of the page it
+     *  is cited on (or for a fresh page's band beside another float) shrinks
+     *  to it when it fits there at {@link minScale} or more; the slots are
+     *  tried in their usual order. A picture with a safe area is cropped
+     *  within it first. Tables (which split), floated boxes, comic strips,
+     *  rotated floats and inline embeds are never scaled by it. Default:
+     *  the type's `defaultPlacement`, then `layout.floatShrink.mode`, then
+     *  `'never'`. */
+    shrink?: FloatShrinkMode;
+    /** The smallest scale {@link shrink} sets a picture at, 0 to 1 (default
+     *  0.7, then `layout.floatShrink.minScale`). A slot that needs less is
+     *  passed over; on a fresh page, where the float has nowhere else to go,
+     *  it is set at this scale and runs past the band. */
+    minScale?: number;
+    /** The measure of a picture's caption and note when the picture is
+     *  narrower than its slot (scaled by {@link shrink} or
+     *  `layout.fitFiguresToPage`, or a bitmap smaller than the column):
+     *  `'slot'` (the default) keeps the slot's measure; `'body'` sets them
+     *  as wide as the picture, under it per {@link align}. */
+    captionMeasure?: 'slot' | 'body';
+    /** Run the text beside the resource (#627): it sits at this side of its
+     *  column, and the lines beside it are set to the measure left over,
+     *  {@link wrapGap} clear of its box (caption included), then return to
+     *  the full measure under it. `'left'` / `'right'` are sides of the body
+     *  flow, as {@link align}'s (on a right-to-left document's mirrored
+     *  pages `'left'` is the sheet's right); `'start'` / `'end'` are the
+     *  same sides by their logical names. Applies to an inline embed
+     *  (`position: 'here'`, the text after the `::resource` line runs beside
+     *  it) and to a `span: 'column'` float at the head or foot of one column
+     *  (the column's first or last lines run beside it); a page-span float,
+     *  a float across several columns, a side-column float, a rotated one
+     *  and anything in vertical text keep their whole band. The resource
+     *  takes {@link width} of the column, or `layout.wrap.defaultWidth`
+     *  when it sets none. Where the text left beside it would be narrower
+     *  than `layout.wrap.minTextWidth`, or the resource shorter than
+     *  `layout.wrap.minLinesBeside` lines, it takes its band whole and a
+     *  `textWrap` warning says so. Default `'none'`. */
+    wrap?: WrapSide;
+    /** The space between a wrapped resource's box (caption included) and
+     *  the text beside it, and under it before the text runs full width
+     *  again (rounded up to whole grid lines). Default `layout.wrap.gap`,
+     *  else one body line, the float gap. */
+    wrapGap?: Dimension;
+    /** Let a `'top'` or `'auto'` float head the page (a page-span float) or
+     *  the column (a column float, across {@link columns} too) where the line
+     *  that first cites it lands, as LaTeX's `t` placement does, instead of
+     *  the first free slot after that line (#633). The text above the
+     *  reference moves down under it. It takes that head only when it fits
+     *  there within `layout.maxTopFraction` of the column, when the earlier
+     *  floats of its numbering sequence are already set, when the page is
+     *  not the first of a chapter or the page after a forced break (an
+     *  opener, a part, a `:::pagebreak`), and when nothing spanning the page
+     *  (a heading, a box) stands above the citing line; and only when, so
+     *  set, the citing line still lands on that page (that column). The
+     *  engine settles this over a few extra placement passes; a float that
+     *  does not qualify takes its usual slot. Rotated floats, side-column
+     *  floats and the rest of a table split across pages never do. Default:
+     *  the type's `defaultPlacement`, then `layout.floatsAtCitingPage`, then
+     *  `false`. */
+    citingPage?: boolean;
+}
+/** The side of its column a resource or a box sits on with text running
+ *  beside it (see `ResourcePlacement.wrap`, #627). */
+export type WrapSide = 'none' | 'left' | 'right' | 'start' | 'end';
+/** The document's text wrap settings (`LayoutConfig.wrap`, #627). */
+export interface TextWrapConfig {
+    /** Default `ResourcePlacement.wrapGap`: the space between a wrapped
+     *  picture and the text. Default: one body line (the float gap). */
+    gap?: Dimension;
+    /** The narrowest measure the text beside a wrapped picture may take: a
+     *  length, or a share of the column (`0.3`). Narrower, the picture takes
+     *  its band whole (`textWrap` warning). Default 12 em of body text. */
+    minTextWidth?: Dimension | number;
+    /** The fewest lines of text worth setting beside a picture. A picture
+     *  shorter than that (gap included) takes its band whole (`textWrap`
+     *  warning). Default 2. */
+    minLinesBeside?: number;
+    /** The share of the column a wrapped resource takes when its placement
+     *  sets no `width`, 0 to 1. Default 0.45. */
+    defaultWidth?: number;
+}
+/** How a floated picture is scaled to the room of a slot (see
+ *  `ResourcePlacement.shrink`). */
+export type FloatShrinkMode = 'never' | 'page' | 'slot';
 /** A user-definable category of resource (e.g. "Figure", "Table"). Drives
  *  numbering, caption prefixes, and inline-reference labels. */
 export interface ResourceType {
@@ -351,8 +440,21 @@ export interface Resource {
     bitmap?: {
         fileId: string;
         format: string;
+        /** The file's width in pixels (not its print size). */
         width: number;
+        /** The file's height in pixels. */
         height: number;
+        /** Pixels per inch of the picture at its natural print size (#631):
+         *  its natural width in layout px is `width × page.dpi / resolution`
+         *  (the height likewise), and the column still caps it. Absent:
+         *  `layout.bitmapResolution` decides (by default the pixels are read
+         *  at `page.dpi`). */
+        resolution?: number;
+        /** The resolution stored in the file (PNG `pHYs`, JPEG JFIF / EXIF,
+         *  WebP EXIF; a Word picture's printed extent), as the host read it,
+         *  horizontal ppi. Used under `layout.bitmapResolution: 'file'`, where
+         *  72 and 96 count as unset; shown by the Sandbox. */
+        fileResolution?: number;
     };
     /** Present when `kind === 'svg'`. */
     svg?: {
@@ -371,6 +473,12 @@ export interface Resource {
          *  `diagramStyle.singleInk` is on, since the recolouring pass only
          *  operates on SVG markup. */
         pdfFileId?: string;
+        /** `false` keeps the markup byte-identical when the picture is shown as
+         *  an image: no `@font-face` is added for the families its text names
+         *  (`diagramStyle.inlineFonts`), for an SVG that carries its faces
+         *  already or must stay as it is. Default: the document's
+         *  `diagramStyle.inlineFonts` (on). */
+        inlineFonts?: boolean;
     };
     /** Present when `kind === 'table'`. */
     table?: {
@@ -756,6 +864,10 @@ export interface PageConfig {
     width?: Dimension;
     height?: Dimension;
     margins?: PageMargins;
+    /** Layout px per inch: every length is converted at this rate, and a
+     *  bitmap without a resolution of its own (see `Resource.bitmap.resolution`
+     *  and `layout.bitmapResolution`) is laid out one pixel per layout px.
+     *  Default 300. */
     dpi?: number;
     cutLines?: CutLinesConfig;
     baselineGrid?: BaselineGridConfig;
@@ -857,6 +969,37 @@ export interface LayoutConfig {
      *  pages are sized for their figures; the HTML viewer, whose pages are as
      *  tall as the screen, turns it on. */
     fitFiguresToPage?: boolean;
+    /** How a bitmap without its own `resolution` takes its natural print
+     *  size (#631): `'document'` (default) reads its pixels at `page.dpi`;
+     *  a number is the ppi of every such bitmap; `'file'` uses the
+     *  resolution read from the file (`Resource.bitmap.fileResolution`),
+     *  72 and 96 counting as unset, else `page.dpi`. The column caps the
+     *  natural size either way; a smaller picture is never enlarged. */
+    bitmapResolution?: BitmapResolution;
+    /** The document's default for scaling a floated picture to the room of
+     *  its slot (#626): `mode` as `ResourcePlacement.shrink`, `minScale` as
+     *  `ResourcePlacement.minScale` (default 0.7). A resource's placement,
+     *  then its type's `defaultPlacement`, override it. Default
+     *  `{ mode: 'never' }`. Unlike {@link fitFiguresToPage}, a hard cap at
+     *  the content area, this looks at the band the float would take. */
+    floatShrink?: FloatShrinkConfig;
+    /** Text wrap round a resource or a box narrower than its column (#627):
+     *  the gap, the narrowest text measure, the fewest lines beside and the
+     *  default width (see {@link TextWrapConfig}). A resource opts in with
+     *  `placement.wrap`, a box with its `wrap` attribute. */
+    wrap?: TextWrapConfig;
+    /** The document default of `placement.citingPage` (#633): a `'top'` or
+     *  `'auto'` float may head the page or column where its citing line
+     *  lands, the text above the reference moving down under it. A
+     *  resource's placement, then its type's `defaultPlacement`, override
+     *  it. Default `false`: a float takes the first free slot after the line
+     *  that cites it. */
+    floatsAtCitingPage?: boolean;
+    /** The largest share of a column's height, 0 to 1, a float set at the
+     *  head of the page or column that cites it (`placement.citingPage`) may
+     *  take with the floats already standing there, so the page keeps some
+     *  room for its text (LaTeX's `\topfraction`). Default 0.7. */
+    maxTopFraction?: number;
     /** On the closing page of a chapter (and of the document), move the
      *  page-wide figures and tables set below the last band of text up to sit
      *  one float gap under it, stacked in their order, instead of at the page
@@ -865,6 +1008,19 @@ export interface LayoutConfig {
      *  the page foot on the closing page as on every other page. Pages with a
      *  side column never move them. */
     hugClosingFloats?: boolean;
+    /** Under a page-span opener (a heading level or style with
+     *  `span: 'page'`) set over two or more text columns, the head of the
+     *  opener's own column, right under its band, is a slot for a `'top'` or
+     *  `'auto'` float, of one column or of several from it, level with the
+     *  heads of the other columns of the band (#639): a floated box fenced
+     *  right after the opener, or a resource embedded there, sits under the
+     *  opener in the first column and the column's text starts under it.
+     *  Default `true`. `false` keeps the rule of postext 1.24 and earlier:
+     *  the opener's column offers no head slot, so such a float lands from
+     *  the second column on. A configuration stored by an earlier version is
+     *  read with `false` when it sets a page-span heading (see
+     *  `migrateConfig` in `postext/bundle`). */
+    floatsUnderOpener?: boolean;
     /** Where an inline resource (`placement.position: 'here'`, embedded with
      *  `::resource`) keeps the float gap, a line: `'around'` keeps it above
      *  and below the resource, and the text after it goes back onto the
@@ -886,6 +1042,16 @@ export interface LayoutConfig {
      *  version is read with `false` when its chapters embed a resource (see
      *  `migrateConfig` in `postext/bundle`). */
     inlineResourceGapInBoxes?: boolean;
+    /** `:::columns` groups in the running text and groups that split (#634):
+     *  a `:::columns` fence outside a box sets its blocks in sub-columns of
+     *  the text column (or, with `span="page"`, across the page), and a
+     *  group, in a box or in the text, is cut between its sub-columns when
+     *  the box goes on in the next column or page. Default `true`. `false`
+     *  keeps the rules of postext 1.24 and earlier: a fence outside a box is
+     *  ignored and a box never cuts inside a group. A configuration stored
+     *  by an earlier version is read with `false` when its chapters hold a
+     *  `:::columns` fence (see `migrateConfig` in `postext/bundle`). */
+    flowColumns?: boolean;
     /** Fewest lines of a paragraph or list item that a cut inside it leaves
      *  on each side when a box splits (see `CalloutStyleConfig.splitMinLines`,
      *  which still counts every line on each side of the cut). A whole number,
@@ -909,6 +1075,22 @@ export interface LayoutConfig {
      *  document's writing mode unless it sets its own. */
     writingMode?: WritingMode;
 }
+/** How bitmaps without a resolution of their own are sized (see
+ *  `LayoutConfig.bitmapResolution`): `'document'`, `'file'` or a ppi. */
+export type BitmapResolution = 'document' | 'file' | number;
+/** The document default for scaling floated pictures (see
+ *  `LayoutConfig.floatShrink`). */
+export interface FloatShrinkConfig {
+    mode?: FloatShrinkMode;
+    minScale?: number;
+}
+/** {@link TextWrapConfig} resolved; `gap` absent is one body line. */
+export interface ResolvedTextWrapConfig {
+    gap?: Dimension;
+    minTextWidth: Dimension | number;
+    minLinesBeside: number;
+    defaultWidth: number;
+}
 /** Where an inline resource keeps the float gap (see
  *  `LayoutConfig.inlineResourceGap`). */
 export type InlineResourceGap = 'around' | 'above';
@@ -927,9 +1109,19 @@ export interface ResolvedLayoutConfig {
         lineWidth: Dimension;
     };
     fitFiguresToPage: boolean;
+    bitmapResolution: BitmapResolution;
+    floatShrink: {
+        mode: FloatShrinkMode;
+        minScale: number;
+    };
+    wrap: ResolvedTextWrapConfig;
+    floatsAtCitingPage: boolean;
+    maxTopFraction: number;
     hugClosingFloats: boolean;
+    floatsUnderOpener: boolean;
     inlineResourceGap: InlineResourceGap;
     inlineResourceGapInBoxes: boolean;
+    flowColumns: boolean;
     boxChildSplitMinLines: number;
     writingMode: WritingMode;
 }
@@ -1426,6 +1618,13 @@ export interface VerseConfig {
      *  column (a haiku, a tanka): it moves on whole when it does not fit.
      *  Default `0`, off. */
     keepStanzas?: number;
+    /** A line of verse a little wider than the measure tightens its word
+     *  spaces, down to `bodyText.minWordSpacing` of their natural width, and
+     *  stays on one line; only a line that does not fit even then turns
+     *  over. `false`: every line wider than the measure turns over, as
+     *  postext 1.23 set them (configurations stored by 1.23 are read with it
+     *  when they hold a poem set line by line). Default `true`. */
+    tighten?: boolean;
 }
 export interface ResolvedVerseConfig {
     layout: 'auto' | 'bayt';
@@ -1435,6 +1634,7 @@ export interface ResolvedVerseConfig {
     turnoverMark: string;
     stanzaSpace: number;
     keepStanzas: number;
+    tighten: boolean;
 }
 /** What `lineNumbers` counts (#621): `'verse'`, the lines of `:::verse`
  *  poems (a turnover takes no number); `'all'`, every laid-out line of the
@@ -1875,18 +2075,62 @@ export interface TableStyleConfig {
     borderWidth?: Dimension;
     /** Inner padding inside each cell. Default `0.375em`. */
     cellPadding?: Dimension;
-    /** Which rules to stroke when {@link borders} is on. Default `'grid'`. */
+    /** Which rules to stroke when {@link borders} is on. Default `'grid'`.
+     *  `'booktabs'` strokes its own widths ({@link heavyRuleWidth},
+     *  {@link lightRuleWidth}, {@link spanRuleWidth}) and ignores
+     *  {@link borderWidth}. */
     rules?: TableRules;
     /** Corner radius of the table's outer frame. Default `0` (square). The
      *  cell fills are clipped to the rounded frame, whatever the rules (with
      *  `'none'` the fills alone show the rounded shape); the inner rules stay
      *  straight. A table split across pages rounds the top corners of its
-     *  first part and the bottom corners of its last. */
+     *  first part and the bottom corners of its last. `'booktabs'` rules
+     *  have no frame to round: they stay straight (the fills are still
+     *  clipped). */
     borderRadius?: Dimension;
+    /** `'booktabs'` (#625): width of the rules above the table and under its
+     *  last row (LaTeX `\heavyrulewidth`). An `em` value is relative to
+     *  {@link bodyFontSize}. Default `0.08em`. */
+    heavyRuleWidth?: Dimension;
+    /** `'booktabs'`: width of the rule under the header rows and of the
+     *  group rules (`\lightrulewidth`). An `em` value is relative to
+     *  {@link bodyFontSize}. Default `0.05em`. */
+    lightRuleWidth?: Dimension;
+    /** `'booktabs'`: width of the rules under header cells that span several
+     *  columns (`\cmidrulewidth`). An `em` value is relative to
+     *  {@link bodyFontSize}. Default `0.03em`. */
+    spanRuleWidth?: Dimension;
+    /** `'booktabs'`: the rules under header cells that span more than one
+     *  column, above the last header row: shortened at both ends by
+     *  {@link spanRuleTrim} so neighbouring rules do not touch
+     *  (`'trimmed'`, the default, `\cmidrule(lr)`), across the whole cell
+     *  (`'full'`), or none (`'none'`). */
+    spanRules?: TableSpanRules;
+    /** `'booktabs'`: how much a `'trimmed'` span rule is shortened at each
+     *  end. An `em` value is relative to {@link bodyFontSize}. Default
+     *  `0.5em`. */
+    spanRuleTrim?: Dimension;
+    /** `'booktabs'`: a light rule above every body row that heads a group
+     *  (one cell across every column, or all header cells), except one that
+     *  opens a page. Default `false`. */
+    groupRules?: boolean;
+    /** `'booktabs'`: the rule that closes a part of a split table that goes
+     *  on overleaf: the heavy bottom rule (`'bottom'`), a light rule
+     *  (`'light'`, the default: the heavy rule closes only the real last
+     *  row), or none (`'none'`). */
+    continuedFootRule?: TableContinuedFootRule;
     /** What happens to a table taller than the space a page offers: continue
      *  it on the following pages (`'split'`, the default), keep only the rows
      *  that fit (`'clip'`), or leave it out (`'hide'`). See {@link TableOverflow}. */
     overflow?: TableOverflow;
+    /** Apply {@link overflow} to tables placed `here` too (#634): an inline
+     *  table that does not fit the room left in its column is cut between
+     *  rows and goes on at the head of the next column, before the text
+     *  after it (`'split'`); one taller than a column keeps its leading
+     *  rows (`'clip'`) or is left out (`'hide'`). `false` keeps the rule of
+     *  postext 1.24 and earlier: an inline table moves whole to the next
+     *  column. Default `true`. */
+    splitInline?: boolean;
     /** Suffix appended to the caption of every continuation slice of a split
      *  table (e.g. "Table 6-4. Title *(cont.)*"). Defaults to `"(cont.)"`. */
     continuedSuffix?: string;
@@ -1914,8 +2158,17 @@ export interface ResolvedNamedTableStyleConfig extends ResolvedTableStyleConfig
 /** Letter case of a table's header cells (`TableStyleConfig.headerTextTransform`). */
 export type TableTextTransform = 'none' | 'uppercase';
 /** Rule pattern of a table: the full cell grid, horizontal rules only (top
- *  and bottom edge of every row), the outer frame only, or none. */
-export type TableRules = 'grid' | 'horizontal' | 'outer' | 'none';
+ *  and bottom edge of every row), the outer frame only, none, or the
+ *  booktabs pattern of journal tables (#625): a heavy rule above the table
+ *  and under its last row, a light rule under the header, short rules
+ *  under spanning header cells and no vertical rules. */
+export type TableRules = 'grid' | 'horizontal' | 'outer' | 'none' | 'booktabs';
+/** Rules of a `'booktabs'` table under header cells that span several
+ *  columns (`TableStyleConfig.spanRules`). */
+export type TableSpanRules = 'trimmed' | 'full' | 'none';
+/** What closes a part of a `'booktabs'` table that continues on the next
+ *  page (`TableStyleConfig.continuedFootRule`). */
+export type TableContinuedFootRule = 'bottom' | 'light' | 'none';
 /** Behaviour of a table taller than the page: `'split'` breaks it between
  *  rows and continues on the following pages, repeating the header rows and
  *  suffixing the caption; `'clip'` keeps the leading rows that fit and drops
@@ -1944,7 +2197,15 @@ export interface ResolvedTableStyleConfig {
     cellPadding: Dimension;
     rules: TableRules;
     borderRadius: Dimension;
+    heavyRuleWidth: Dimension;
+    lightRuleWidth: Dimension;
+    spanRuleWidth: Dimension;
+    spanRules: TableSpanRules;
+    spanRuleTrim: Dimension;
+    groupRules: boolean;
+    continuedFootRule: TableContinuedFootRule;
     overflow: TableOverflow;
+    splitInline: boolean;
     continuedSuffix: string;
     continuesMarkerEnabled: boolean;
     continuesMarker: string;
@@ -2046,10 +2307,18 @@ export interface DiagramStyleConfig {
     singleInk?: boolean;
     /** The ink. Defaults to the document's main palette colour. */
     inkColor?: ColorValue;
+    /** Embed the faces an SVG's text names (`font-family`) in the picture as
+     *  `@font-face` data URIs before it is shown as an image (canvas, HTML,
+     *  EPUB, the PDF's raster fallback), so its labels are set in the
+     *  document's fonts: an image cannot see the page's web fonts. Never
+     *  written into the stored file. A resource opts out with
+     *  `svg.inlineFonts: false`. Default `true`. */
+    inlineFonts?: boolean;
 }
 export interface ResolvedDiagramStyleConfig {
     singleInk: boolean;
     inkColor: ColorValue;
+    inlineFonts: boolean;
 }
 /** Where an overlay sits on a video's poster: the centre, a corner or the
  *  middle of a side. The positions are physical: `top-right` is the top
@@ -3258,6 +3527,18 @@ export interface HeadingLevelConfig {
      *  book). The measure narrows by it; a centred heading centres in what is
      *  left. Default `0`. */
     indent?: Dimension;
+    /** Indent of the heading's first line only (#636), measured from
+     *  {@link indent} (so the first line starts `indent + firstLineIndent`
+     *  in): the lines it wraps onto start at `indent`, as a body paragraph's
+     *  turnover lines start at the margin. GB/T 9704 sets every level of
+     *  head two cells in with its turnover back at the margin:
+     *  `{ value: 2, unit: 'em' }`. `em` is the BODY size, as for `indent`,
+     *  so two ems are two cells of the body grid at any heading size. A
+     *  numbered heading's number comes after the indent. A centred heading
+     *  takes it as a centred body paragraph does: its first line centres in
+     *  the room after the indent. A heading overrides it with
+     *  `{firstLineIndent=N}` (`0` clears it). Default `0`. */
+    firstLineIndent?: Dimension;
     /** 字取り (jidori, JLReq §3.7.3, §4.1): a heading shorter than this many
      *  of its own characters is spaced out evenly to fill exactly that width
      *  (`jidori: 3` sets 序章 as 序　章). Applies to a heading that fits one
@@ -3307,6 +3588,8 @@ export interface ResolvedHeadingLevelConfig {
     lineSpan?: number;
     /** Absent unless set (see {@link HeadingLevelConfig.indent}). */
     indent?: Dimension;
+    /** Absent unless set (see {@link HeadingLevelConfig.firstLineIndent}). */
+    firstLineIndent?: Dimension;
     /** Absent unless set (see {@link HeadingLevelConfig.jidori}). */
     jidori?: number;
     /** Absent unless set (see {@link HeadingLevelConfig.dropCap}); a heading
@@ -3380,6 +3663,10 @@ export interface HeadingsConfig {
     levels?: HeadingLevelConfig[];
 }
 export interface ColumnBalancingConfig {
+    /** Default `true`, except in vertical text (`layout.writingMode:
+     *  'vertical-rl'`) and on a character grid (`cjk.grid.enabled`, #632),
+     *  where columns are filled line by line and a column that ends short is
+     *  left short unless the configuration sets `true` itself. */
     enabled?: boolean;
     /** Maximum extra grid lines that may be added above a single heading. */
     maxLinesPerHeading?: number;
@@ -3454,10 +3741,22 @@ export interface ColumnBalancingConfig {
      *  the last line of the column beside it; `'off'` leaves it where it is
      *  there too. Any other value reads as `'first'`. */
     closingBox?: ClosingBoxLever;
+    /** On a character grid (`cjk.grid.enabled`, #632): whether the levers
+     *  that add whole grid lines — above a heading, where a list ends, under
+     *  a display or a box, under a float band — may run. They keep every
+     *  character in its cell (the baseline grid is the grid's line pitch),
+     *  but a standard that counts the lines of a page (GB/T 9704: 22 lines
+     *  of 28 characters) has no empty rows to give: `'off'` keeps them out
+     *  and leaves the other levers. Off the grid it has no effect. Default
+     *  `'allow'`; any other value reads as `'allow'`. */
+    gridLines?: GridLinesLever;
 }
 /** Where the column-balancing lever of a box closing a column runs
  *  (`ColumnBalancingConfig.closingBox`). */
 export type ClosingBoxLever = 'first' | 'last' | 'off';
+/** Whether the whole-line balancing levers run on a character grid
+ *  (`ColumnBalancingConfig.gridLines`). */
+export type GridLinesLever = 'allow' | 'off';
 /** How a paragraph kept with the heading above it splits at a column's foot
  *  (`HeadingsConfig.keepWithNextSplit`). */
 export type KeepWithNextSplit = 'rules' | 'fill';
@@ -3489,6 +3788,9 @@ export interface ResolvedHeadingsConfig {
         trailing: boolean;
         beforeSpan: boolean;
         closingBox: ClosingBoxLever;
+        /** Present only when `'off'` (#632): every other configuration
+         *  resolves as before. */
+        gridLines?: 'off';
     };
     levels: ResolvedHeadingLevelConfig[];
 }
@@ -4414,6 +4716,35 @@ export interface CjkConfig {
      *  picture books) and Korean. Default `'normal'`. A paragraph style may
      *  set its own (`ParagraphStyleConfig.wordBreak`). */
     wordBreak?: CjkWordBreak;
+    /** Book titles kept from one-character breaks (#637): a line breaks
+     *  inside a `《…》` or `〈…〉` title (and inside a `:book[…]` title) only
+     *  where at least this many of its characters stand on either side of
+     *  the break, so a title of up to twice this less one never breaks.
+     *  When no other break fits the line, the line breaks inside the title
+     *  anyway, as the level allows, rather than run past the measure.
+     *  Default `2`; `1` lets a line break anywhere the level allows (as up
+     *  to postext 1.24). */
+    titleMinChars?: number;
+    /** How the circled, parenthesized and full-stop numbers and letters are
+     *  set in a CJK paragraph (①–⑳, ⑴–⒇, ⒈–⒛, ⓐ–ⓩ, ❶–❿, ➀–➓; #637).
+     *  `'cjk'` (the default): as Chinese characters, one cell with no
+     *  Han–Latin space around them, and a line never ends on one (it labels
+     *  the text after it) at the levels that keep a currency sign off a
+     *  line end: every one but `none` and `ja-loose`.
+     *  `'western'`: as Western letters, as up to postext 1.24: the Han–Latin
+     *  space on both sides and a line may end on one. Vertical text sets
+     *  them upright either way. */
+    circledNumbers?: 'cjk' | 'western';
+    /** Whether a design text in Chinese or Japanese (a heading design or an
+     *  opener, a running head, a page design, a part page) is set with the
+     *  CJK rules of the body (#637): the line-start and line-end rules of
+     *  `lineBreak`, the mark widths of `punctuationWidth` and
+     *  `compressAdjacent`, `latinSpacing`, `hangingPunctuation` and the title
+     *  rule. Default `true`; `false` wraps it at spaces and sets every mark
+     *  at the font's own advance, as up to postext 1.24. A text that holds
+     *  no CJK, or more word spaces than CJK letters, is wrapped as Latin
+     *  text either way. */
+    composeDesignText?: boolean;
     /** The space set between a Han character (or kana) and a Latin letter or
      *  a European digit next to it (`用 iPhone 拍照`), in em of the CJK
      *  text's size or any length. Default `{ value: 0.25, unit: 'em' }`; `0`
@@ -4727,6 +5058,14 @@ export interface ResolvedCjkConfig {
     /** Set only when `'keep-all'`: absent, lines break between any two
      *  characters (`normal`). */
     wordBreak?: 'keep-all';
+    /** Characters of a book title kept on either side of a break (1 or
+     *  more). */
+    titleMinChars: number;
+    /** Set only when `'western'`: absent, circled numbers are set as Chinese
+     *  characters. */
+    circledNumbers?: 'western';
+    /** Set (false) only when off: absent, CJK design text is composed. */
+    composeDesignText?: false;
     latinSpacing: Dimension;
     uprightDigits: 0 | 2 | 3 | 4;
     grid: ResolvedCjkGridConfig;
@@ -4993,7 +5332,16 @@ export interface ElementBoxStyle {
  *  mid-word only when what the boundary leaves, that punctuation dropped,
  *  is less than half of what fits (a long word, a URL). A no-break space
  *  or hyphen (U+2011) is no boundary. `'ellipsis-middle'` cuts anywhere but
- *  drops the spaces beside it. */
+ *  drops the spaces beside it.
+ *
+ *  An element that sets none takes its slot's default (#628): `'wrap'` in a
+ *  heading design (`advancedDesign.slot`, an opener or an in-column title)
+ *  and on a part page (`parts.design`, `parts.versoDesign`), where a long
+ *  title should break onto more lines; `'ellipsis-end'` in a running head
+ *  or folio (`header`, `footer`, a heading style's own) and in a contents
+ *  part row (`toc.parts.design`, whose row has a fixed height). A line cut
+ *  by an ellipsis, or clipped with ink past the box, is reported as a
+ *  `designTextTruncated` content warning. */
 export type TextOverflow = 'wrap' | 'ellipsis-start' | 'ellipsis-end' | 'ellipsis-middle' | 'clip';
 /** Outline drawn around the glyphs of a design text (a hollow display
  *  number, a title that stands off a photograph). */
@@ -5074,7 +5422,11 @@ export interface DesignTextElement {
      *  number, a malformed dimension) sets the default leading. */
     lineHeight?: number | Dimension;
     letterSpacing?: Dimension;
-    overflow: TextOverflow;
+    /** What a line wider than the element's room does (see
+     *  {@link TextOverflow}). Unset, the slot decides: `'wrap'` in heading
+     *  and part designs, `'ellipsis-end'` in running heads, folios and
+     *  contents part rows. */
+    overflow?: TextOverflow;
     /** When true, break long words at syllable boundaries while wrapping.
      *  Uses the document's active hyphenation locale. */
     hyphenate?: boolean;
@@ -5197,8 +5549,10 @@ export interface DesignSlot {
     /** Array order = paint order: first = back, last = front. */
     elements: DesignElement[];
 }
-export interface ResolvedDesignTextElement extends Omit<DesignTextElement, 'fontFamily' | 'fontWeight' | 'italic' | 'color' | 'align' | 'verticalAlign' | 'lineHeight' | 'parity'> {
+export interface ResolvedDesignTextElement extends Omit<DesignTextElement, 'fontFamily' | 'fontWeight' | 'italic' | 'color' | 'align' | 'verticalAlign' | 'lineHeight' | 'parity' | 'overflow'> {
     parity: PageParity;
+    /** The element's own `overflow`, else its slot's default. */
+    overflow: TextOverflow;
     fontFamily: string;
     fontWeight: number;
     italic: boolean;
@@ -5407,8 +5761,9 @@ export interface HeadingStyleConfig extends Omit<HeadingLevelConfig, 'level' | '
      *  Only its page geometry is read from it (`layoutType`, `gutterWidth`,
      *  the side column, `columnRule`), plus its `fitFiguresToPage` when a
      *  figure could move from an empty column cut short to a whole one;
-     *  `inlineResourceGap`, `inlineResourceGapInBoxes`,
-     *  `boxChildSplitMinLines` and `hugClosingFloats` stay the document's,
+     *  `inlineResourceGap`, `inlineResourceGapInBoxes`, `flowColumns`,
+     *  `boxChildSplitMinLines`, `hugClosingFloats` and `floatsUnderOpener`
+     *  stay the document's,
      *  and so does the `fitFiguresToPage` that shrinks figures.
      *  Unset, the section uses the document's `layout`. */
     layout?: LayoutConfig;