@embedpdf/core-geometry 3.0.0-next.13 → 3.0.0-next.15

package/dist/index.d.ts

@@ -1,13 +1,24 @@
+//#region src/page-space.d.ts
+/**
+ * Page space: the unrotated page's own frame, origin at the top-left of the
+ * visible page, y down, in points (the
+ * page's UserUnit is applied by the view, not here). The engine gives and
+ * takes every position in this space.
+ */
+type PagePoint = PointIn<'page'>;
+type PageRect = RectIn<'page'>;
+type PageQuad = QuadIn<'page'>;
+//#endregion
 //#region src/index.d.ts
 /**
  * @embedpdf/core-geometry — the viewer's pure 2D coordinate primitives.
  *
  * The bottom of the pyramid: stage-core (layout), plugin-stage (`pageToWorld`),
- * and every framework adapter (`toContentPoint` hit-testing) all sit on these.
+ * and every framework adapter (`toPagePoint` hit-testing) all sit on these.
  * Zero dependencies, DOM-free, serializable — Rust-portable.
  *
  * The page-rotation transforms are the reason this package exists: the same
- * quarter-turn maps content↔box in BOTH directions, and that one rule must not
+ * quarter-turn maps content↔box in both directions, and that one rule must not
  * be hand-written (and drift, or be bug-fixed in only one of four adapters).
  */
 interface Point {
@@ -19,13 +30,9 @@ interface Size {
   height: number;
 }
 /**
- * A rectangle in the VIEWER's coordinates: top-left origin, y-down, PDF-point
- * scale. What every viewer API speaks — `stage.reveal`, selection and search
- * rects, render boxes.
- *
- * The rule: shown on screen → `Rect`; stored in the file → the engine's y-up
- * `PdfRect` (`{left, bottom, right, top}`). The shapes are incompatible on
- * purpose — passing one where the other goes doesn't compile.
+ * A rectangle in page space: top-left origin, y-down, in points. What every
+ * viewer and engine API speaks — annotation rects, `stage.reveal`, selection
+ * and search rects, render boxes.
  */
 interface Rect {
   x: number;
@@ -45,10 +52,21 @@ declare function boundsOfRects(rects: readonly Rect[]): Rect | null;
  * without a null branch. Space-agnostic like {@link boundsOfRects}: view-px
  * viewport ∩ footprint, page-point visibility ∩ tile footprints, ….
  */
-declare function intersectRects(a: Rect, b: Rect): Rect;
+declare function intersectRects(left: Rect, right: Rect): Rect;
+/** The axis-aligned rect spanned by two corners, in any order — a drag box. */
+declare function rectFromCorners(from: Point, to: Point): Rect;
+/** Whether a rect contains a point, edges inclusive. Space-agnostic. */
+declare function rectContains(rect: Rect, point: Point): boolean;
+/** Positive-area overlap of two rects — touching edges do not count. */
+declare function rectsOverlap(left: Rect, right: Rect): boolean;
+/**
+ * The largest rect of `content`'s proportions inside `box`, centred in it:
+ * CSS `object-fit: contain`. `box` itself when `content` has no area.
+ */
+declare function containedRect(content: Size, box: Rect): Rect;
 /**
  * Quarter-turn display rotation, degrees clockwise. The viewer-side notion of a
- * page's on-screen rotation — the TOTAL = (document /Rotate + any view
+ * page's on-screen rotation — the total = (document /Rotate + any view
  * rotation), resolved by the shell. Structurally identical to the engine's
  * `PageRotation`, so the two interoperate without this package depending on the
  * engine.
@@ -70,118 +88,117 @@ declare const NO_FRAME: PageFrame;
 /** True for the quarter-turns that swap a page's width and height. */
 declare function isQuarterTurn(rotation: PageRotation): boolean;
 /**
- * Compose two quarter-turn rotations (mod 360). THE way the shell resolves a
- * page's TOTAL display rotation — `addRotations(page /Rotate, view rotation)`
+ * Compose two quarter-turn rotations (mod 360). The way the shell resolves a
+ * page's total display rotation — `addRotations(page /Rotate, view rotation)`
  * — so the wrap arithmetic is never hand-written (and drift) per call site.
  */
-declare function addRotations(a: PageRotation, b: PageRotation): PageRotation;
+declare function addRotations(left: PageRotation, right: PageRotation): PageRotation;
 /**
  * Snap a view-px value to the device pixel grid: round to a whole device pixel,
- * back to view px. Used for a page's screen POSITION so a CSS-rotated page lands
+ * back to view px. Used for a page's screen position so a CSS-rotated page lands
  * on the grid (no sub-pixel anti-aliased fringe). The shell never hand-rounds.
  */
 declare function snapToDevice(value: number, dpr: number): number;
 /** A page's on-screen footprint: width and height swapped for quarter-turns. */
 declare function displaySize(content: Size, rotation: PageRotation): Size;
 /**
- * The engine's `kind:'width'` height rule, replicated EXACTLY so the viewer can
+ * The engine's `kind:'width'` height rule, replicated exactly so the viewer can
  * predict the rendered bitmap's height up front — the page box is sized to it,
  * so the box matches the bitmap with no reflow and no 1px seam.
  *
  * Mirrors `PageRenderReader.resolveDeviceSize` (engine-services): we render the
- * page UN-rotated (CSS applies the rotation), so there is no width/height swap
- * here — `pageSize` is the page's own points. MUST stay in lockstep with that
+ * page un-rotated (CSS applies the rotation), so there is no width/height swap
+ * here — `pageSize` is the page's own points. Must stay in lockstep with that
  * function; the round-trip test in the render plugin asserts they agree.
  */
 declare function deviceHeightForWidth(pageSize: Size, deviceWidth: number): number;
 /**
- * The single per-page bridge between the viewer's three coordinate spaces. NB:
- * these are all VIEWER spaces — top-left origin, y-down. They are NOT the
- * engine's PDF user space (`Pdf*`, bottom-left origin, y-up); the engine→content
- * hop (the y-flip + crop offset) is a separate matrix (`pageGeometry`).
+ * The single per-page bridge between the viewer's three coordinate spaces, all
+ * top-left origin, y-down. Page space is the engine's own, so engine values
+ * need no hop of their own.
  *
- *   content space  page-local points, top-left, y-down — un-rotated page frame
+ *   page space     page-local points, top-left, y-down — un-rotated page frame
  *   view space     platform logical px (web: CSS px) — layout, DOM, pointer events
  *   device space   physical pixels — the rendered bitmap
  *
- * PAGE-LOCAL by design: it knows this page's own box, NOT where the page sits in
+ * Page-local by design: it knows this page's own box, not where the page sits in
  * the scene. Placement (camera/layout) stays on `VisiblePage.{x,y}` and positions
- * the page container; the transform converts everything INSIDE that container. So
+ * the page container; the transform converts everything inside that container. So
  * it is camera/pan-invariant — it only changes on zoom / rotation / contentScale
  * / dpr, which makes it cheap to memoize.
  *
- * Every plugin and framework adapter consumes THIS — never `x * scale`, never
+ * Every plugin and framework adapter consumes this — never `x * scale`, never
  * `pageToWorld()∘toScreen()`, never `* dpr`. New plugins (annotations, search,
  * forms) do no coordinate math; new platforms (iOS/Android) inject a different
  * `scale` and reuse all of it.
  */
 interface PageTransform {
   /**
-   * The page's TOTAL display rotation (document /Rotate + any view rotation) —
+   * The page's total display rotation (document /Rotate + any view rotation) —
    * the same value the transform's matrices were built from, exposed so
    * consumers that need the quarter-turn itself (an upright-placement rule, a
-   * pointer sample) read it HERE instead of re-deriving it from the matrix.
+   * pointer sample) read it here instead of re-deriving it from the matrix.
    */
   readonly rotation: PageRotation;
-  /** Display footprint in VIEW px (device-snapped) — the page container's size.
+  /** Display footprint in view px (device-snapped) — the page container's size.
    *  Width↔height already swapped for quarter-turns. */
   readonly viewWidth: number;
   readonly viewHeight: number;
-  /** The UN-rotated content box in VIEW px — the size of the wrapper the bitmap
-   *  and content-space overlays live in (before the wrapper's CSS rotation). */
+  /** The un-rotated content box in view px — the size of the wrapper the bitmap
+   *  and page-space overlays live in (before the wrapper's CSS rotation). */
   readonly contentWidth: number;
   readonly contentHeight: number;
-  /** Render the (un-rotated) bitmap at EXACTLY this — `viewport: {kind:'width', width: deviceWidth}`.
+  /** Render the (un-rotated) bitmap at exactly this — `viewport: {kind:'width', width: deviceWidth}`.
    *  Integer device px; `deviceHeight` is the engine's exact derived height. */
   readonly deviceWidth: number;
   readonly deviceHeight: number;
   /** Device px per PDF point (uniform). */
   readonly renderScale: number;
-  /** VIEW px per PDF point (uniform, device-snapped) — the one factor for
+  /** View px per PDF point (uniform, device-snapped) — the one factor for
    *  screen-constant chrome: content units = CSS px ÷ `viewScale`. */
   readonly viewScale: number;
   /**
-   * View px per PDF point at 100% ZOOM — the page's physical baseline:
+   * View px per PDF point at 100% zoom — the page's physical baseline:
    * `viewUnitsPerPoint × userUnit` (web: 96/72 × `/UserUnit`, so 100% maps to
-   * inches on screen, Acrobat-style). What "100%" MEANS for this page.
+   * inches on screen, Acrobat-style). What "100%" means for this page.
    */
   readonly baseScale: number;
   /**
-   * The page's zoom RELATIVE to its 100% baseline (`viewScale / baseScale`,
-   * dimensionless; exactly 1 at 100% for any `userUnit`). THE number
+   * The page's zoom relative to its 100% baseline (`viewScale / baseScale`,
+   * dimensionless; exactly 1 at 100% for any `userUnit`). The number
    * zoom-relative policies consume — e.g. the `/F` NoZoom exemption clamps
    * its body to `zoom ≤ 1`. Distinct from `viewScale` (a units conversion).
    */
   readonly zoom: number;
   /**
    * Content point → this page's pixels (the un-rotated content wrapper's local
-   * px). THE overlay author's converter: elements inside the wrapper ride its
-   * rotation, so they place in content points and only scale here. Convert at
+   * px). The overlay author's converter: elements inside the wrapper ride its
+   * rotation, so they place in page points and only scale here. Convert at
    * the last moment — pixels are never stored.
    */
-  toPixels(p: Point): Point;
-  /** Inverse of {@link toPixels}: wrapper-local px → content point (a pointer
+  toPixels(point: Point): Point;
+  /** Inverse of {@link toPixels}: wrapper-local px → page point (a pointer
    *  event inside the wrapper back to the viewer's coordinates). */
-  fromPixels(p: Point): Point;
-  /** Content point → page-local view px in the DISPLAY box (rotation applied). For
+  fromPixels(point: Point): Point;
+  /** Content point → page-local view px in the display box (rotation applied). For
    *  footprint-space layers (outside the wrapper). */
-  contentToView(p: Point): Point;
+  pageToView(point: Point): Point;
   /** Content rect → its axis-aligned view-px rect (exact for quarter-turns). */
-  contentToViewRect(r: Rect): Rect;
-  /** Inverse — display-box view px (box-local) → content point. Hit-testing. */
-  viewToContent(p: Point): Point;
-  /** Inverse of {@link contentToViewRect}: display-box view-px rect → its content
+  pageToViewRect(rect: Rect): Rect;
+  /** Inverse — display-box view px (box-local) → page point. Hit-testing. */
+  viewToPage(point: Point): Point;
+  /** Inverse of {@link pageToViewRect}: display-box view-px rect → its content
    *  AABB (exact for quarter-turns). The visibility primitive — projecting a
-   *  viewport rect into page points is THIS, never per-adapter corner math. */
-  viewToContentRect(r: Rect): Rect;
-  /** CSS `matrix()` mapping content space → this page's display box. Drop it on
+   *  viewport rect into page points is this, never per-adapter corner math. */
+  viewToPageRect(rect: Rect): Rect;
+  /** CSS `matrix()` mapping page space → this page's display box. Drop it on
    *  a footprint-space layer (`transform`, `transform-origin: 0 0`) and place
-   *  children in content points — rotation + scale handled for free. */
+   *  children in page points — rotation + scale handled for free. */
   readonly cssMatrix: string;
 }
 /**
  * Build a page's transform from its intrinsic size + the platform/view scale.
- * `scale` is VIEW px per PDF point (the shell composes it: `viewUnitsPerPoint ×
+ * `scale` is view px per PDF point (the shell composes it: `viewUnitsPerPoint ×
  * contentScale × zoom`); `dpr` is device px per view px. Device dimensions snap
  * to the grid (crisp, no rotation fringe) and follow the engine's width rule
  * (box == bitmap, no reflow).
@@ -203,15 +220,22 @@ declare function pageTransform(input: {
   dpr: number;
 }): PageTransform;
 /**
- * The coordinate spaces a viewer touches. `pdf` is the engine's PDF user space
- * (y-up, origin at the crop box bottom-left); the rest are viewer-local, y-down.
+ * Whether two transforms place things on the page the same: the same scale, zoom and turn, and
+ * the same content box. A Stage builds a new transform on every frame, also for a plain scroll,
+ * which moves the page but changes nothing inside it; a layer that compares with this redraws
+ * only when what it draws in the page's pixels moved.
  */
-type Space = 'pdf' | 'content' | 'view' | 'screen';
+declare function samePagePlacement(left: Pick<PageTransform, 'viewScale' | 'zoom' | 'rotation' | 'contentWidth' | 'contentHeight'>, right: Pick<PageTransform, 'viewScale' | 'zoom' | 'rotation' | 'contentWidth' | 'contentHeight'>): boolean;
 /**
- * Phantom space brand. It is OPTIONAL so plain `{ x, y }` / `{ x, y, w, h }`
- * literals stay assignable day-to-day (terse), but a value EXPLICITLY tagged
+ * The coordinate spaces a viewer touches, all y-down. `content` is the
+ * engine's page space: points from the top-left of the visible page.
+ */
+type Space = 'page' | 'view' | 'screen';
+/**
+ * Phantom space brand. It is optional so plain `{ x, y }` / `{ x, y, w, h }`
+ * literals stay assignable day-to-day (terse), but a value explicitly tagged
  * with the wrong space is rejected — and `Mat2D<From, To>` enforces the hop at
- * the matrix, so you cannot `applyRect` a `pdf` rect with a `content→view`
+ * the matrix, so you cannot `applyRect` a `view` rect with a `content→view`
  * matrix. The brand is type-only; it carries no runtime field.
  */
 interface SpaceBrand<S extends Space> {
@@ -222,23 +246,29 @@ type PointIn<S extends Space> = Point & SpaceBrand<S>;
 /**
  * An axis-aligned rect tagged with its space, as min-corner + positive extent:
  * `(x, y)` is the corner with the smallest coordinates and `(x+width, y+height)`
- * the largest. In `pdf` space (y-up) that corner is bottom-left (`x=left`,
- * `y=bottom`); in the y-down viewer spaces it is top-left.
+ * the largest: in every space here, the top-left.
  */
 type RectIn<S extends Space> = Rect & SpaceBrand<S>;
 /**
- * Four POSITIONAL points (no corner semantics) — the viewer twin of the engine's
- * `PdfQuad`. Use this (via {@link applyQuad}) for rotatable/skewed content where
- * an axis-aligned rect would lie.
+ * A quad: four corners named in the text's own upright frame, the viewer twin
+ * of the engine's `PageQuad`. `upper` is the ascent side and `lower` the
+ * baseline side; `left` to `right` runs along the frame's x axis. The names
+ * are neither screen directions nor reading order: text turned 180° has its
+ * `upperLeft` at the bottom right, and right-to-left text still runs from
+ * `left` to `right`. In y-down page space an upright quad has `upper*` at the
+ * smaller y. Use it (via {@link applyQuad}) for text and any content that can
+ * turn or skew, where an axis-aligned rect would lie.
  */
 interface Quad {
-  p1: Point;
-  p2: Point;
-  p3: Point;
-  p4: Point;
+  upperLeft: Point;
+  upperRight: Point;
+  lowerLeft: Point;
+  lowerRight: Point;
 }
 /** A quad tagged with its coordinate space. */
 type QuadIn<S extends Space> = Quad & SpaceBrand<S>;
+/** Four points as a polygon ring, for `<polygon>`, fills and hit tests. */
+type QuadRing = [Point, Point, Point, Point];
 /**
  * A 2D affine transform from space `From` to space `To`, stored as the six
  * numbers `[a, b, c, d, e, f]`. The phantom `From`/`To` make the compiler track
@@ -252,154 +282,75 @@ type Mat2D<From extends Space = Space, To extends Space = Space> = readonly [num
 /** The identity transform within a single space. */
 declare function identity<S extends Space>(): Mat2D<S, S>;
 /**
- * Compose two matrices: `compose(m, n)` applies `n` first, then `m` (matrix
- * product `m · n`). The shared middle space `B` must line up, so the type system
- * rejects composing mismatched hops.
+ * Compose two matrices: `compose(matrix, inner)` applies `inner` first, then
+ * `matrix` (matrix product `matrix · inner`). The shared middle space `B` must
+ * line up, so the type system rejects composing mismatched hops.
  */
-declare function compose<A extends Space, B extends Space, C extends Space>(m: Mat2D<B, C>, n: Mat2D<A, B>): Mat2D<A, C>;
-/** Invert a transform — `invert(pdfToView)` is `viewToPdf`, i.e. hit-testing for free. */
-declare function invert<F extends Space, T extends Space>(m: Mat2D<F, T>): Mat2D<T, F>;
+declare function compose<A extends Space, B extends Space, C extends Space>(matrix: Mat2D<B, C>, inner: Mat2D<A, B>): Mat2D<A, C>;
+/** Invert a transform — `invert(pageToView)` is `viewToPage`, i.e. hit-testing for free. */
+declare function invert<F extends Space, T extends Space>(matrix: Mat2D<F, T>): Mat2D<T, F>;
 /** Apply a transform to a point. */
-declare function applyPoint<F extends Space, T extends Space>(m: Mat2D<F, T>, p: PointIn<F>): PointIn<T>;
+declare function applyPoint<F extends Space, T extends Space>(matrix: Mat2D<F, T>, point: PointIn<F>): PointIn<T>;
 /**
  * Apply a transform to a rect, returning the axis-aligned bounding box of the
- * four transformed corners. EXACT for translate/scale/quarter-turn (every page
+ * four transformed corners. Exact for translate/scale/quarter-turn (every page
  * transform `pageGeometry` produces); lossy under skew — use {@link applyQuad}
  * for content that can be rotated off-axis.
  */
-declare function applyRect<F extends Space, T extends Space>(m: Mat2D<F, T>, r: RectIn<F>): RectIn<T>;
-/** Apply a transform to a quad, preserving orientation (maps the four points). */
-declare function applyQuad<F extends Space, T extends Space>(m: Mat2D<F, T>, q: QuadIn<F>): QuadIn<T>;
+declare function applyRect<F extends Space, T extends Space>(matrix: Mat2D<F, T>, rect: RectIn<F>): RectIn<T>;
+/** Apply a transform to a quad: each corner moves and keeps its name. */
+declare function applyQuad<F extends Space, T extends Space>(matrix: Mat2D<F, T>, quad: QuadIn<F>): QuadIn<T>;
 /**
- * A `Mat2D` IS a CSS `matrix()` — the six numbers are identical. Drop the result
+ * A `Mat2D` is a CSS `matrix()` — the six numbers are identical. Drop the result
  * on a footprint-space layer (`transform`, `transform-origin: 0 0`) and place
  * children in the source space; the rotation + scale are handled for free.
  */
-declare function matrixToCss(m: Mat2D): string;
+declare function matrixToCss(matrix: Mat2D): string;
 /** Translate within a space. */
 declare function translate<S extends Space>(tx: number, ty: number): Mat2D<S, S>;
 /** Scale about the space origin. */
 declare function scale<S extends Space>(sx: number, sy: number): Mat2D<S, S>;
-/** Rotate about the space origin (radians; clockwise in y-down content space). */
+/** Rotate about the space origin (radians; clockwise in y-down page space). */
 declare function rotate<S extends Space>(rad: number): Mat2D<S, S>;
 /** Rotate about an arbitrary pivot: `T(c) · R(rad) · T(-c)`. */
-declare function rotateAbout<S extends Space>(c: PointIn<S>, rad: number): Mat2D<S, S>;
+declare function rotateAbout<S extends Space>(point: PointIn<S>, rad: number): Mat2D<S, S>;
 /** Scale about an arbitrary anchor: `T(a) · S(sx, sy) · T(-a)`. */
-declare function scaleAbout<S extends Space>(a: PointIn<S>, sx: number, sy: number): Mat2D<S, S>;
+declare function scaleAbout<S extends Space>(point: PointIn<S>, sx: number, sy: number): Mat2D<S, S>;
 /** The rotation angle (radians) encoded in a matrix — `atan2(b, a)`. Positive is
- *  clockwise in y-down content space (the inverse of {@link rotate}). */
-declare function angleOf(m: Mat2D): number;
+ *  clockwise in y-down page space (the inverse of {@link rotate}). */
+declare function angleOf(matrix: Mat2D): number;
 /**
- * The page's scale + integer quarter-turn as a `Mat2D`: a content point maps to
- * its place in the rotated DISPLAY box. `scale` is output units per content
- * point; `boxW`/`boxH` are the UN-rotated content's extents in those same output
+ * The page's scale + integer quarter-turn as a `Mat2D`: a page point maps to
+ * its place in the rotated display box. `scale` is output units per content
+ * point; `boxW`/`boxH` are the un-rotated content's extents in those same output
  * units, and the offsets keep the footprint in the box's positive quadrant
  * (origin at the box top-left).
  *
- * THE single encoding of the quarter-turn — `pageTransform` (view px),
+ * The single encoding of the quarter-turn — `pageTransform` (view px),
  * `pageGeometry` (the `content→view` hop), and `pageToWorld` (world units) all
  * build on this one function, so the rotation can never drift between them.
  */
 declare function rotateScaleMatrix(scale: number, boxW: number, boxH: number, rotation: PageRotation): Mat2D;
+/** An upright quad over a rect (y-down: upper = smaller y). */
+declare function quadFromRect(rect: Rect): Quad;
+/** The four corners: upper-left, upper-right, lower-left, lower-right. */
+declare function quadCorners(quad: Quad): [Point, Point, Point, Point];
+/** The corners as a polygon ring: upper-left, upper-right, lower-right, lower-left. */
+declare function quadRing(quad: Quad): QuadRing;
 /**
- * The per-page geometry input. Structurally a subset of the engine's
- * `PageLayout` (so a layout can be passed straight in), but defined here to keep
- * this package dependency-free — the same reason {@link PageRotation} is a
- * structural twin of the engine's rotation.
- */
-interface PageGeometryInput {
-  /** Effective crop box in PDF user space (y-up edges); origin preserved, so
-   *  `left`/`bottom` may be non-zero or negative. */
-  crop: {
-    left: number;
-    bottom: number;
-    right: number;
-    top: number;
-  };
-  /** Persistent page rotation (the document's `/Rotate`). */
-  rotation: PageRotation;
-  /** PDF `userUnit` (§14.11.6): scales PDF points into the layout. 1 for most docs. */
-  userUnit: number;
-}
-/** The matrices bridging one page's spaces — every other matrix composes from these. */
-interface PageGeometry {
-  /** PDF user space (y-up, crop-relative) → content space (y-down, crop top-left, unscaled points). */
-  readonly pdfToContent: Mat2D<'pdf', 'content'>;
-  /** Content → view: scale (zoom × userUnit) + the page's quarter-turn rotation. */
-  readonly contentToView: Mat2D<'content', 'view'>;
-  /** PDF → view, precomposed. */
-  readonly pdfToView: Mat2D<'pdf', 'view'>;
-  /** View → PDF, the inverse — hit-testing for free. */
-  readonly viewToPdf: Mat2D<'view', 'pdf'>;
-}
-/**
- * PDF user space (y-up, origin = crop bottom-left) → content space (y-down,
- * origin = crop top-left, unscaled points). THE single encoding of the engine→
- * content y-flip + crop offset: `pageGeometry` composes its `pdfToContent` from
- * this, and pure annotation geometry (content-space editing) reuses it too, so
- * the rule can never be hand-written twice and drift.
- */
-declare function pdfToContentMatrix(crop: {
-  left: number;
-  top: number;
-}): Mat2D<'pdf', 'content'>;
-/**
- * Build a page's space matrices from its crop box, rotation, and `userUnit` plus
- * the viewer `zoom`. This is the ONE function that knows the y-flip, crop origin,
- * `userUnit`, and rotation; everything else composes from its output. The engine
- * never emits these — they bake in viewer state (zoom, later scroll/dpr) — so the
- * boundary stays clean: engine owns `Pdf*` truth, the viewer composes the rest.
- */
-declare function pageGeometry(input: PageGeometryInput, zoom: number): PageGeometry;
-interface TextQuad {
-  upperStart: Point;
-  upperEnd: Point;
-  lowerStart: Point;
-  lowerEnd: Point;
-}
-/** A TextQuad tagged with its coordinate space. */
-type TextQuadIn<S extends Space> = TextQuad & SpaceBrand<S>;
-/** Axis-aligned TextQuad over a rect (y-down: upper = smaller y). */
-declare function textQuadFromRect(r: Rect): TextQuad;
-/** The four corners in slot order: upper-start, upper-end, lower-start, lower-end. */
-declare function textQuadPoints(t: TextQuad): [Point, Point, Point, Point];
-/** The corners as a polygon RING (US → UE → LE → LS) — for `<polygon>`/fills. */
-declare function textQuadRing(t: TextQuad): [Point, Point, Point, Point];
-/**
- * One SIDE edge of the cell — the start (`US → LS`) or end (`UE → LE`) edge,
- * ASCENT CORNER FIRST. This is the segment a caret or a selection handle
+ * One side edge of the cell, the left (`UL → LL`) or right (`UR → LR`) one,
+ * ascent corner first. This is the segment a caret or a selection handle
  * occupies: its length is the glyph's ink height in the text's own frame (not
  * the AABB height, which grows with tilt), and its direction carries the
- * text's rotation. Which side is the selection's LEADING edge is a reading
+ * text's rotation. Which side is the selection's leading edge is a reading
  * -order question — decide it with `advance`, not with geometry.
  */
-declare function textQuadEdge(t: TextQuad, side: 'start' | 'end'): [Point, Point];
-/** Corner-wise equality — an AABB comparison would call a quad that ROTATED
+declare function quadEdge(quad: Quad, side: 'left' | 'right'): [Point, Point];
+/** Corner-wise equality — an AABB comparison would call a quad that rotated
  *  in place "unchanged"; corners cannot. (Change-detection for quad consumers.) */
-declare function textQuadEquals(a: TextQuad, b: TextQuad): boolean;
-/** Axis-aligned bounds of a TextQuad. */
-declare function textQuadBounds(t: TextQuad): Rect;
-/** Map a TextQuad through an affine transform (corner semantics ride along). */
-declare function applyTextQuad<F extends Space, T extends Space>(m: Mat2D<F, T>, t: TextQuadIn<F>): TextQuadIn<T>;
-/** Serialize to the positional zigzag convention (`p1..p4` = US, UE, LS, LE). */
-declare function positionalQuad(t: TextQuad): Quad;
-/**
- * Interpret an arbitrary positional quad (an imported `/QuadPoints` entry,
- * already in content space) as a TextQuad — a NORMALIZER, not a cast:
- *
- *   1. the de-facto zigzag order (US, UE, LS, LE) passes through untouched —
- *      this covers every well-formed writer, rotated quads included;
- *   2. the common ring order (US, UE, LE, LS) is recognized and repaired;
- *   3. anything else gets a deterministic geometric labeling: corners sorted
- *      into a ring around their centroid, "upper" = the edge whose midpoint
- *      sits highest on screen (smallest y). The 180° "which side is up"
- *      ambiguity is unresolvable from geometry alone — convention decides.
- *
- * Drawing code downstream (`markupScene`) reads corner SEMANTICS, so a
- * mislabeled import can shift an underline to the wrong edge but can never
- * crash or self-intersect.
- */
-declare function normalizeQuad(q: Quad): TextQuad;
+declare function quadEquals(left: Quad, right: Quad): boolean;
+/** Axis-aligned bounds of a quad. */
+declare function quadBounds(quad: Quad): Rect;
 //#endregion
-export { Mat2D, NO_FRAME, PageFrame, PageGeometry, PageGeometryInput, PageRotation, PageTransform, Point, PointIn, Quad, QuadIn, Rect, RectIn, Size, Space, TextQuad, TextQuadIn, addRotations, angleOf, applyPoint, applyQuad, applyRect, applyTextQuad, boundsOfRects, compose, deviceHeightForWidth, displaySize, identity, intersectRects, invert, isQuarterTurn, matrixToCss, normalizeQuad, pageGeometry, pageTransform, pdfToContentMatrix, positionalQuad, rotate, rotateAbout, rotateScaleMatrix, scale, scaleAbout, snapToDevice, textQuadBounds, textQuadEdge, textQuadEquals, textQuadFromRect, textQuadPoints, textQuadRing, translate };
+export { Mat2D, NO_FRAME, PageFrame, PagePoint, PageQuad, PageRect, PageRotation, PageTransform, Point, PointIn, Quad, QuadIn, QuadRing, Rect, RectIn, Size, Space, addRotations, angleOf, applyPoint, applyQuad, applyRect, boundsOfRects, compose, containedRect, deviceHeightForWidth, displaySize, identity, intersectRects, invert, isQuarterTurn, matrixToCss, pageTransform, quadBounds, quadCorners, quadEdge, quadEquals, quadFromRect, quadRing, rectContains, rectFromCorners, rectsOverlap, rotate, rotateAbout, rotateScaleMatrix, samePagePlacement, scale, scaleAbout, snapToDevice, translate };
 //# sourceMappingURL=index.d.ts.map