@embedpdf/core-geometry 3.0.0-next.0

package/dist/index.d.cts

@@ -0,0 +1,343 @@
+//#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 (`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
+ * be hand-written (and drift, or be bug-fixed in only one of four adapters).
+ */
+interface Point {
+  x: number;
+  y: number;
+}
+interface Size {
+  width: number;
+  height: number;
+}
+/** Viewer-side rect: top-left origin, y-down (view/page-point convention — NOT the
+ *  engine's bottom-left PDF rect). */
+interface Rect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+/**
+ * The bounding box of a set of rects (null for the empty set). Space-
+ * agnostic: works on any y-down `{x,y,width,height}` rects — search hit
+ * bounds, selection line-merge unions, multi-quad annotation extents.
+ */
+declare function boundsOfRects(rects: readonly Rect[]): Rect | null;
+/**
+ * Intersection of two y-down rects — zero-sized (width/height 0, origin at
+ * the would-be corner) when disjoint, so callers can test `width > 0`
+ * 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;
+/**
+ * Quarter-turn display rotation, degrees clockwise. The viewer-side notion of a
+ * 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.
+ */
+type PageRotation = 0 | 90 | 180 | 270;
+/**
+ * Reserved chrome real estate around a page, one thickness per side (screen px
+ * in the shell; world units in the pure layout). The page content sits inset
+ * by these; the bands hold box-space chrome (labels, buttons, rails) that does
+ * not rotate. The layout reserves the matching space so nothing overlaps.
+ */
+interface PageFrame {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+}
+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)`
+ * — so the wrap arithmetic is never hand-written (and drift) per call site.
+ */
+declare function addRotations(a: PageRotation, b: 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
+ * 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
+ * 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
+ * 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`).
+ *
+ *   content 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
+ * the scene. Placement (camera/layout) stays on `VisiblePage.{x,y}` and positions
+ * 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
+ * `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 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.
+   */
+  readonly rotation: PageRotation;
+  /** 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). */
+  readonly contentWidth: number;
+  readonly contentHeight: number;
+  /** 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
+   *  screen-constant chrome: content units = CSS px ÷ `viewScale`. */
+  readonly viewScale: number;
+  /**
+   * 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.
+   */
+  readonly baseScale: 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 → UN-rotated content view px. For overlays INSIDE the rotated
+   *  content wrapper (markers, annotations) — they ride the wrapper's rotation,
+   *  so they place in content space and only scale here. */
+  pageToContent(p: Point): Point;
+  /** Content point → page-local view px in the DISPLAY box (rotation applied). For
+   *  footprint-space layers (outside the wrapper). */
+  pageToView(p: Point): Point;
+  /** Content rect → its axis-aligned view-px rect (exact for quarter-turns). */
+  pageToViewRect(r: Rect): Rect;
+  /** Inverse — display-box view px (box-local) → content point. Hit-testing. */
+  viewToPage(p: 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. */
+  viewToPageRect(r: Rect): Rect;
+  /** CSS `matrix()` mapping content 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. */
+  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 ×
+ * 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).
+ */
+declare function pageTransform(input: {
+  /** Un-rotated page size in PDF points. */
+  pageSize: Size;
+  rotation: PageRotation;
+  /** View px per PDF point = viewUnitsPerPoint × contentScale × zoom. */
+  scale: number;
+  /**
+   * View px per PDF point at 100% zoom (`viewUnitsPerPoint × userUnit`) — the
+   * page's physical baseline, so `zoom = viewScale / baseScale` reads as
+   * "percent of Acrobat's 100%". Default = `scale`, i.e. zoom ≈ 1: headless /
+   * standalone callers stay neutral unless they declare a baseline.
+   */
+  baseScale?: number;
+  /** Device px per view px (web: devicePixelRatio). */
+  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.
+ */
+type Space = 'pdf' | 'content' | '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`
+ * matrix. The brand is type-only; it carries no runtime field.
+ */
+interface SpaceBrand<S extends Space> {
+  readonly __space?: S;
+}
+/** A point tagged with its coordinate space. */
+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.
+ */
+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.
+ */
+interface Quad {
+  p1: Point;
+  p2: Point;
+  p3: Point;
+  p4: Point;
+}
+/** A quad tagged with its coordinate space. */
+type QuadIn<S extends Space> = Quad & SpaceBrand<S>;
+/**
+ * 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
+ * which spaces a matrix bridges, so composition and application can only be
+ * wired up in the one correct order.
+ */
+type Mat2D<From extends Space = Space, To extends Space = Space> = readonly [number, number, number, number, number, number] & {
+  readonly __from?: From;
+  readonly __to?: To;
+};
+/** 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.
+ */
+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>;
+/** Apply a transform to a point. */
+declare function applyPoint<F extends Space, T extends Space>(m: Mat2D<F, T>, p: 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
+ * 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>;
+/**
+ * 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;
+/** 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). */
+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>;
+/** 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>;
+/** 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;
+/**
+ * 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
+ * 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),
+ * `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;
+/**
+ * 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;
+//#endregion
+export { Mat2D, NO_FRAME, PageFrame, PageGeometry, PageGeometryInput, PageRotation, PageTransform, Point, PointIn, Quad, QuadIn, Rect, RectIn, Size, Space, addRotations, angleOf, applyPoint, applyQuad, applyRect, boundsOfRects, compose, deviceHeightForWidth, displaySize, identity, intersectRects, invert, isQuarterTurn, matrixToCss, pageGeometry, pageTransform, pdfToContentMatrix, rotate, rotateAbout, rotateScaleMatrix, scale, scaleAbout, snapToDevice, translate };
+//# sourceMappingURL=index.d.cts.map