# Composable path transforms

Create a reusable mapping, then apply it to independent geometry:

```ts
import {
  PathGeometry,
  composeTransforms,
  envelopeTransform,
  affineTransform,
  arcBendTransform,
  transformPath,
} from "@pibbl/core";

const original = new PathGeometry();
original.rect(0, 0, 200, 50);
const textBounds = { x: 0, y: 0, width: 200, height: 50 };
const top = new PathGeometry();
top.moveTo(0, 0);
top.lineTo(200, 20);
const bottom = new PathGeometry();
bottom.moveTo(0, 50);
bottom.lineTo(200, 70);
const mapping = composeTransforms(
  envelopeTransform({ source: textBounds, top, bottom }),
  affineTransform({ a: 1.2, d: 1.2, e: 100, f: 60 }),
);
const result = transformPath(original, mapping, { tolerance: 0.25 });
```

Composition runs left to right in ordinary coordinates. `source` belongs to a
mapping; each later source rectangle describes the preceding mapping's output.
`transformPath` approximates the final composed outline, including closing
edges, in destination units. It preserves source geometry and contour order.
All-affine compositions preserve curve segments. Nonlinear output uses lines.
`tolerance` is required and positive; `maxSegments` defaults to one million.
Work, output, precision, and domain failures throw without returning partial output.

Envelope inputs can instead use `guides: [{ at: 0, path: top }, { at: 0.4,
path: middle }, { at: 1, path: bottom }]`. Positions strictly increase from zero
to one. Interpolation is linear between guides and may crease at interior guides.
Guides are independent snapshots of one nonempty open contour. They match by
normalized arc length. `{ path, reverse: true, stations: [{ at: 0, distance: 0 },
{ at: 1, distance: 1 }] }` supplies direction and correspondence landmarks.
Stations increase strictly on both axes; distance is measured after reversal.
Crossed guides and intentional folds are allowed. Envelope source bounds are
required; geometry outside them is rejected rather than clamped.

`quadTransform({ source, destination, mode })` accepts the existing four named
corners. Mode is `bilinear` (default) or `perspective`. Perspective requires a
strictly convex destination. Quad mappings allow finite extrapolation.

`mapPoint({ x, y }, { tolerance: 0.0001 })` evaluates a mapping for editor guides
and annotations. The tolerance option is optional and defaults to 0.0001.
Values are opaque; arbitrary objects or callbacks are not PathTransforms.

Sequential `transformPath` calls remain supported when intermediate geometry
is useful. Each call has an independent tolerance; later maps can amplify earlier
approximation error. Prefer composition for a single final accuracy target.

## Meshes

`meshTransform({ source, columns, rows, horizontal, vertical })` creates a grid
of Coons patches. Columns and rows are strictly increasing normalized coordinates
from 0 to 1. Horizontal contains one row of edges per row boundary, each with
`columns.length - 1` left-to-right guides. Vertical contains one column of edges
per column boundary, each with `rows.length - 1` top-to-bottom guides.

Edges share exact endpoint coordinates. Mismatches throw; no points are moved
implicitly. Shared edges are supplied once. Each cell interpolates its four
boundaries. Adjacent cells meet continuously, but matching slopes are not promised.
Folds are permitted. The constructor accepts at most 4,096 cells. Source geometry
must remain inside the source rectangle.

## Bends

Continuing with the imports and original geometry above:

```ts
const bend = arcBendTransform({
  source: { x: 0, y: 0, width: 200, height: 50 },
  arc: { cx: 300, cy: 300, radius: 180, startAngle: -Math.PI, sweep: Math.PI },
  baseline: "bottom",
  fit: "stretch",
});
const bentResult = transformPath(
  original,
  composeTransforms(bend, affineTransform({ e: 20 })),
  {
    tolerance: 0.25,
  },
);
```

`pathBendTransform({ source, guide, ...placement })` takes an explicit
`PathGeometry` guide. Both constructors accept `BendTransformOptions`; arc and
path variants add `arc` and `guide`, respectively. See [path bending](/reference/functions/path-bending/)
for alignment, baseline, fitting, offsets, and overflow rules. Bends retain their
existing smooth-guide requirements; envelopes and meshes also support corners.

## Migration

`warpPath`, `bendPathAlongArc`, and `bendPathAlongPath` are replaced by
`transformPath(path, quadTransform(mapping), quality)`,
`transformPath(path, arcBendTransform(mapping), quality)`, and
`transformPath(path, pathBendTransform({ ...mapping, guide }), quality)`.
There are no root compatibility exports. Separate `tolerance` and `maxSegments`
from mapping options. The root exports `PathPoint`, `PathRect`, `PathQuadCorners`,
and `PathQuadMode` instead of the former warp-specific point/rectangle types.

The in-place `PathGeometry.transform(matrix)` builder remains available. Use
`affineTransform` with `transformPath` when independent results or composition
are needed. Flattening, subdivision, and simplification remain separate geometry
operations rather than spatial mappings.

## API details from source

<span id="api-meshTransform"></span>

### meshTransform

Creates a mapping through a mesh bounded by horizontal and vertical path guides.

```ts
meshTransform: (options: MeshTransformOptions) => PathTransform
```

Related API: [meshTransform](/reference/functions/path-transforms/), [MeshTransformOptions](/reference/functions/path-transforms/), [PathTransform](/reference/functions/path-transforms/).

#### Parameters

- **`options`** — Source rectangle and the four boundary guides used to deform it. See
[MeshTransformOptions](/reference/functions/path-transforms/) .

#### Returns

A point mapping suitable for transformPath. See [PathTransform](/reference/functions/path-transforms/).

#### See also

[MeshTransformOptions](/reference/functions/path-transforms/)

[PathTransform](/reference/functions/path-transforms/)

[View source — packages/core/src/lib/geometry/transform-mesh.ts:61](/source/packages/core/src/lib/geometry/transform-mesh-ts/#L61)

<span id="api-arcBendTransform"></span>

### arcBendTransform

Creates a reusable mapping that bends source geometry around a circular arc.

```ts
arcBendTransform: (options: ArcBendTransformOptions) => PathTransform
```

Related API: [arcBendTransform](/reference/functions/path-transforms/), [ArcBendTransformOptions](/reference/functions/path-transforms/), [PathTransform](/reference/functions/path-transforms/).

#### Parameters

- **`options`** — Source bounds and circular bend geometry. See [ArcBendTransformOptions](/reference/functions/path-transforms/).

#### Returns

A point mapping that bends the source along a circular arc. See [PathTransform](/reference/functions/path-transforms/).

#### See also

[ArcBendTransformOptions](/reference/functions/path-transforms/)

[PathTransform](/reference/functions/path-transforms/)

[View source — packages/core/src/lib/geometry/transform-bend.ts:119](/source/packages/core/src/lib/geometry/transform-bend-ts/#L119)

<span id="api-pathBendTransform"></span>

### pathBendTransform

Creates a reusable mapping that bends source geometry along a guide path.

```ts
pathBendTransform: (options: PathBendTransformOptions) => PathTransform
```

Related API: [pathBendTransform](/reference/functions/path-transforms/), [PathBendTransformOptions](/reference/functions/path-transforms/), [PathTransform](/reference/functions/path-transforms/).

#### Parameters

- **`options`** — Source bounds, target guide, and alignment along that guide. See
[PathBendTransformOptions](/reference/functions/path-transforms/) .

#### Returns

A point mapping that bends the source along the target path. See [PathTransform](/reference/functions/path-transforms/).

#### See also

[PathBendTransformOptions](/reference/functions/path-transforms/)

[PathTransform](/reference/functions/path-transforms/)

[View source — packages/core/src/lib/geometry/transform-bend.ts:212](/source/packages/core/src/lib/geometry/transform-bend-ts/#L212)

<span id="api-MeshTransformOptions"></span>

### MeshTransformOptions

Source rectangle, normalized cell boundaries, and horizontal/vertical path guides for a mesh
transform.

```ts
interface MeshTransformOptions
```

Related API: [MeshTransformOptions](/reference/functions/path-transforms/).

#### See also

[PathRect](/reference/functions/path-transforms/)

[PathGuide](/reference/functions/path-transforms/)

[meshTransform](/reference/functions/path-transforms/)

[View source — packages/core/src/lib/geometry/transform-mesh.ts:33](/source/packages/core/src/lib/geometry/transform-mesh-ts/#L33)

#### Properties and methods

<span id="api-MeshTransformOptions-source"></span>
<details>
<summary>source</summary>


```ts
readonly source: PathRect
```

Related API: [PathRect](/reference/functions/path-transforms/).

Source rectangle whose normalized cells are mapped through the guide mesh. See PathRect.

[View source — packages/core/src/lib/geometry/transform-mesh.ts:35](/source/packages/core/src/lib/geometry/transform-mesh-ts/#L35)

</details>

<span id="api-MeshTransformOptions-columns"></span>
<details>
<summary>columns</summary>


```ts
readonly columns: readonly number[]
```

Strictly increasing normalized column boundaries, beginning at 0 and ending at 1. See
MeshTransformOptions.

[View source — packages/core/src/lib/geometry/transform-mesh.ts:40](/source/packages/core/src/lib/geometry/transform-mesh-ts/#L40)

</details>

<span id="api-MeshTransformOptions-rows"></span>
<details>
<summary>rows</summary>


```ts
readonly rows: readonly number[]
```

Strictly increasing normalized row boundaries, beginning at 0 and ending at 1. See
MeshTransformOptions.

[View source — packages/core/src/lib/geometry/transform-mesh.ts:45](/source/packages/core/src/lib/geometry/transform-mesh-ts/#L45)

</details>

<span id="api-MeshTransformOptions-horizontal"></span>
<details>
<summary>horizontal</summary>


```ts
readonly horizontal: readonly (readonly PathGuide[])[]
```

Related API: [PathGuide](/reference/functions/path-transforms/).

Boundary rows; each contains columns.length - 1 left-to-right edges.

[View source — packages/core/src/lib/geometry/transform-mesh.ts:47](/source/packages/core/src/lib/geometry/transform-mesh-ts/#L47)

</details>

<span id="api-MeshTransformOptions-vertical"></span>
<details>
<summary>vertical</summary>


```ts
readonly vertical: readonly (readonly PathGuide[])[]
```

Related API: [PathGuide](/reference/functions/path-transforms/).

Boundary columns; each contains rows.length - 1 top-to-bottom edges.

[View source — packages/core/src/lib/geometry/transform-mesh.ts:49](/source/packages/core/src/lib/geometry/transform-mesh-ts/#L49)

</details>

<span id="api-ArcBendTransformOptions"></span>

### ArcBendTransformOptions

Circular bending parameters for a reusable arc transform; accuracy is supplied when applying it.

```ts
type ArcBendTransformOptions = Omit<
  BendPathAlongArcOptions,
  'tolerance' | 'maxSegments'
>
```

Related API: [ArcBendTransformOptions](/reference/functions/path-transforms/).

#### See also

[arcBendTransform](/reference/functions/path-transforms/)

[View source — packages/core/src/lib/geometry/transform-bend.ts:43](/source/packages/core/src/lib/geometry/transform-bend-ts/#L43)

#### Properties and methods

<span id="api-ArcBendTransformOptions-source"></span>
<details>
<summary>source</summary>


```ts
readonly source: PathBendFrame
```

Source coordinate frame used to normalize the geometry before bending. See
PathBendFrame.

[View source — packages/core/src/lib/geometry/path-bending.ts:64](/source/packages/core/src/lib/geometry/path-bending-ts/#L64)

</details>

<span id="api-ArcBendTransformOptions-align"></span>
<details>
<summary>align (optional)</summary>


```ts
readonly align?: PathBendAlign | undefined
```

Related API: [PathBendAlign](/reference/functions/path-bending/).

Placement of the source length along the guide. See PathBendAlign.

[View source — packages/core/src/lib/geometry/path-bending.ts:66](/source/packages/core/src/lib/geometry/path-bending-ts/#L66)

</details>

<span id="api-ArcBendTransformOptions-baseline"></span>
<details>
<summary>baseline (optional)</summary>


```ts
readonly baseline?: PathBendBaseline | undefined
```

Related API: [PathBendBaseline](/reference/functions/path-bending/).

Source baseline mapped onto the guide. See PathBendBaseline.

[View source — packages/core/src/lib/geometry/path-bending.ts:68](/source/packages/core/src/lib/geometry/path-bending-ts/#L68)

</details>

<span id="api-ArcBendTransformOptions-fit"></span>
<details>
<summary>fit (optional)</summary>


```ts
readonly fit?: PathBendFit | undefined
```

Related API: [PathBendFit](/reference/functions/path-bending/).

Policy for fitting content within its available box. See PathBendFit.

[View source — packages/core/src/lib/geometry/path-bending.ts:70](/source/packages/core/src/lib/geometry/path-bending-ts/#L70)

</details>

<span id="api-ArcBendTransformOptions-offset"></span>
<details>
<summary>offset (optional)</summary>


```ts
readonly offset?: number | undefined
```

Offset along the guide. See PathBendOptions.

[View source — packages/core/src/lib/geometry/path-bending.ts:72](/source/packages/core/src/lib/geometry/path-bending-ts/#L72)

</details>

<span id="api-ArcBendTransformOptions-normalOffset"></span>
<details>
<summary>normalOffset (optional)</summary>


```ts
readonly normalOffset?: number | undefined
```

Offset perpendicular to the guide. See PathBendOptions.

[View source — packages/core/src/lib/geometry/path-bending.ts:74](/source/packages/core/src/lib/geometry/path-bending-ts/#L74)

</details>

<span id="api-ArcBendTransformOptions-overflow"></span>
<details>
<summary>overflow (optional)</summary>


```ts
readonly overflow?: PathBendOverflow | undefined
```

Related API: [PathBendOverflow](/reference/functions/path-bending/).

Policy for geometry extending beyond the guide's available length. See
PathBendOverflow.

[View source — packages/core/src/lib/geometry/path-bending.ts:79](/source/packages/core/src/lib/geometry/path-bending-ts/#L79)

</details>

<span id="api-ArcBendTransformOptions-arc"></span>
<details>
<summary>arc</summary>


```ts
readonly arc: PathBendArc
```

Related API: [PathBendArc](/reference/functions/path-bending/).



[View source — packages/core/src/lib/geometry/path-bending.ts:85](/source/packages/core/src/lib/geometry/path-bending-ts/#L85)

</details>

<span id="api-PathBendTransformOptions"></span>

### PathBendTransformOptions

Guide path and bending parameters for a reusable path transform.

```ts
type PathBendTransformOptions = Omit<
  PathBendOptions,
  'tolerance' | 'maxSegments'
> & {
  /** Path used as the bending guide. See {@link PathGeometry}. */
  readonly guide: PathGeometry;
}
```

Related API: [PathBendTransformOptions](/reference/functions/path-transforms/), [Path](/reference/components/path/), [PathGeometry](/reference/functions/path-geometry/).

#### See also

[PathGeometry](/reference/functions/path-geometry/)

[pathBendTransform](/reference/functions/path-transforms/)

[View source — packages/core/src/lib/geometry/transform-bend.ts:53](/source/packages/core/src/lib/geometry/transform-bend-ts/#L53)

#### Properties and methods

<span id="api-PathBendTransformOptions-source"></span>
<details>
<summary>source</summary>


```ts
readonly source: PathBendFrame
```

Source coordinate frame used to normalize the geometry before bending. See
PathBendFrame.

[View source — packages/core/src/lib/geometry/path-bending.ts:64](/source/packages/core/src/lib/geometry/path-bending-ts/#L64)

</details>

<span id="api-PathBendTransformOptions-align"></span>
<details>
<summary>align (optional)</summary>


```ts
readonly align?: PathBendAlign | undefined
```

Related API: [PathBendAlign](/reference/functions/path-bending/).

Placement of the source length along the guide. See PathBendAlign.

[View source — packages/core/src/lib/geometry/path-bending.ts:66](/source/packages/core/src/lib/geometry/path-bending-ts/#L66)

</details>

<span id="api-PathBendTransformOptions-baseline"></span>
<details>
<summary>baseline (optional)</summary>


```ts
readonly baseline?: PathBendBaseline | undefined
```

Related API: [PathBendBaseline](/reference/functions/path-bending/).

Source baseline mapped onto the guide. See PathBendBaseline.

[View source — packages/core/src/lib/geometry/path-bending.ts:68](/source/packages/core/src/lib/geometry/path-bending-ts/#L68)

</details>

<span id="api-PathBendTransformOptions-fit"></span>
<details>
<summary>fit (optional)</summary>


```ts
readonly fit?: PathBendFit | undefined
```

Related API: [PathBendFit](/reference/functions/path-bending/).

Policy for fitting content within its available box. See PathBendFit.

[View source — packages/core/src/lib/geometry/path-bending.ts:70](/source/packages/core/src/lib/geometry/path-bending-ts/#L70)

</details>

<span id="api-PathBendTransformOptions-offset"></span>
<details>
<summary>offset (optional)</summary>


```ts
readonly offset?: number | undefined
```

Offset along the guide. See PathBendOptions.

[View source — packages/core/src/lib/geometry/path-bending.ts:72](/source/packages/core/src/lib/geometry/path-bending-ts/#L72)

</details>

<span id="api-PathBendTransformOptions-normalOffset"></span>
<details>
<summary>normalOffset (optional)</summary>


```ts
readonly normalOffset?: number | undefined
```

Offset perpendicular to the guide. See PathBendOptions.

[View source — packages/core/src/lib/geometry/path-bending.ts:74](/source/packages/core/src/lib/geometry/path-bending-ts/#L74)

</details>

<span id="api-PathBendTransformOptions-overflow"></span>
<details>
<summary>overflow (optional)</summary>


```ts
readonly overflow?: PathBendOverflow | undefined
```

Related API: [PathBendOverflow](/reference/functions/path-bending/).

Policy for geometry extending beyond the guide's available length. See
PathBendOverflow.

[View source — packages/core/src/lib/geometry/path-bending.ts:79](/source/packages/core/src/lib/geometry/path-bending-ts/#L79)

</details>

<span id="api-PathBendTransformOptions-guide"></span>
<details>
<summary>guide</summary>


```ts
readonly guide: PathGeometry
```

Related API: [PathGeometry](/reference/functions/path-geometry/).

Path used as the bending guide. See PathGeometry.

[View source — packages/core/src/lib/geometry/transform-bend.ts:58](/source/packages/core/src/lib/geometry/transform-bend-ts/#L58)

</details>

<span id="api-transformPath"></span>

### transformPath

Return independent geometry. Nonlinear mappings approximate the final composed curve once.

```ts
transformPath: (path: PathGeometry, transform: PathTransform, options: TransformPathOptions) => PathGeometry
```

Related API: [transformPath](/reference/functions/path-transforms/), [PathGeometry](/reference/functions/path-geometry/), [PathTransform](/reference/functions/path-transforms/), [TransformPathOptions](/reference/functions/path-transforms/).

#### Parameters

- **`path`** — Source geometry; it is not modified. See [PathGeometry](/reference/functions/path-geometry/).

- **`transform`** — Point mapping to apply to the source. See [PathTransform](/reference/functions/path-transforms/).

- **`options`** — Approximation tolerance and work limits for transformed curves. See
[TransformPathOptions](/reference/functions/path-transforms/) .

#### Returns

Independent geometry containing the transformed path. See [PathGeometry](/reference/functions/path-geometry/).

#### See also

[PathGeometry](/reference/functions/path-geometry/)

[PathTransform](/reference/functions/path-transforms/)

[TransformPathOptions](/reference/functions/path-transforms/)

[View source — packages/core/src/lib/geometry/path-transforms.ts:524](/source/packages/core/src/lib/geometry/path-transforms-ts/#L524)

<span id="api-composeTransforms"></span>

### composeTransforms

Apply mappings in the order written. Empty composition is identity.

```ts
composeTransforms: (...transforms: readonly PathTransform[]) => PathTransform
```

Related API: [composeTransforms](/reference/functions/path-transforms/), [PathTransform](/reference/functions/path-transforms/).

#### Parameters

- **`transforms`** — Point mappings in the order they should be applied. See
[PathTransform](/reference/functions/path-transforms/) .

#### Returns

One mapping that applies each supplied transform in order. See [PathTransform](/reference/functions/path-transforms/).

#### See also

[PathTransform](/reference/functions/path-transforms/)

[View source — packages/core/src/lib/geometry/path-transforms.ts:276](/source/packages/core/src/lib/geometry/path-transforms-ts/#L276)

<span id="api-affineTransform"></span>

### affineTransform

Creates a reusable 2D affine mapping; an omitted matrix produces identity.

```ts
affineTransform: (matrix?: DOMMatrix2DInit) => PathTransform
```

Related API: [affineTransform](/reference/functions/path-transforms/), [PathTransform](/reference/functions/path-transforms/).

#### Parameters

- **`matrix`** — Affine matrix coefficients; omitted coefficients use the identity matrix.

#### Returns

A point mapping applying the matrix. See [PathTransform](/reference/functions/path-transforms/).

#### See also

[PathTransform](/reference/functions/path-transforms/)

[View source — packages/core/src/lib/geometry/path-transforms.ts:289](/source/packages/core/src/lib/geometry/path-transforms-ts/#L289)

<span id="api-quadTransform"></span>

### quadTransform

Maps a source rectangle into four destination corners using bilinear or perspective
interpolation.

```ts
quadTransform: (options: QuadTransformOptions) => PathTransform
```

Related API: [quadTransform](/reference/functions/path-transforms/), [QuadTransformOptions](/reference/functions/path-transforms/), [PathTransform](/reference/functions/path-transforms/).

#### Parameters

- **`options`** — Source rectangle and destination corner positions. See
[QuadTransformOptions](/reference/functions/path-transforms/) .

#### Returns

A point mapping from the source rectangle to the destination quadrilateral. See
[PathTransform](/reference/functions/path-transforms/) .

#### See also

[QuadTransformOptions](/reference/functions/path-transforms/)

[PathTransform](/reference/functions/path-transforms/)

[View source — packages/core/src/lib/geometry/path-transforms.ts:314](/source/packages/core/src/lib/geometry/path-transforms-ts/#L314)

<span id="api-envelopeTransform"></span>

### envelopeTransform

Maps a source rectangle between ordered guide paths using linear interpolation.

```ts
envelopeTransform: (options: EnvelopeTransformOptions) => PathTransform
```

Related API: [envelopeTransform](/reference/functions/path-transforms/), [EnvelopeTransformOptions](/reference/functions/path-transforms/), [PathTransform](/reference/functions/path-transforms/).

#### Parameters

- **`options`** — Source bounds and envelope guides defining the deformation. See
[EnvelopeTransformOptions](/reference/functions/path-transforms/) .

#### Returns

A point mapping that deforms the source into the envelope. See [PathTransform](/reference/functions/path-transforms/).

#### See also

[EnvelopeTransformOptions](/reference/functions/path-transforms/)

[PathTransform](/reference/functions/path-transforms/)

[View source — packages/core/src/lib/geometry/path-transforms.ts:394](/source/packages/core/src/lib/geometry/path-transforms-ts/#L394)

<span id="api-PathTransform"></span>

### PathTransform

A constructor-created, reusable coordinate mapping for path transformation.

```ts
interface PathTransform
```

Related API: [PathTransform](/reference/functions/path-transforms/).

#### See also

[PathPoint](/reference/functions/path-transforms/)

[transformPath](/reference/functions/path-transforms/)

[composeTransforms](/reference/functions/path-transforms/)

[affineTransform](/reference/functions/path-transforms/)

[View source — packages/core/src/lib/geometry/path-transforms.ts:70](/source/packages/core/src/lib/geometry/path-transforms-ts/#L70)

#### Properties and methods

<span id="api-PathTransform-mapPoint"></span>
<details>
<summary>mapPoint</summary>


```ts
mapPoint: (point: PathPoint, options?: { readonly tolerance?: number; }) => PathPoint
```

Related API: [PathPoint](/reference/functions/path-transforms/).

Evaluate in ordinary source/destination coordinates. Guide approximation is bounded by
tolerance.

##### Parameters

- **`point`** — Source point in the transform's input coordinate system. See [PathPoint](/reference/functions/path-transforms/).

- **`options`** — Optional approximation tolerance for evaluating the mapping.

##### Returns

The mapped point in the transform's output coordinate system. See [PathPoint](/reference/functions/path-transforms/).

[View source — packages/core/src/lib/geometry/path-transforms.ts:79](/source/packages/core/src/lib/geometry/path-transforms-ts/#L79)

</details>

<span id="api-PathPoint"></span>

### PathPoint

A point in source or destination path coordinates.

```ts
interface PathPoint
```

Related API: [PathPoint](/reference/functions/path-transforms/).

#### See also

[PathTransform](/reference/functions/path-transforms/)

[PathRect](/reference/functions/path-transforms/)

[View source — packages/core/src/lib/geometry/path-transforms.ts:36](/source/packages/core/src/lib/geometry/path-transforms-ts/#L36)

#### Properties and methods

<span id="api-PathPoint-x"></span>
<details>
<summary>x</summary>


```ts
readonly x: number
```

Horizontal coordinate or displacement in the containing coordinate system. See
PathPoint.

[View source — packages/core/src/lib/geometry/path-transforms.ts:41](/source/packages/core/src/lib/geometry/path-transforms-ts/#L41)

</details>

<span id="api-PathPoint-y"></span>
<details>
<summary>y</summary>


```ts
readonly y: number
```

Vertical coordinate or displacement in the containing coordinate system. See PathPoint
.

[View source — packages/core/src/lib/geometry/path-transforms.ts:46](/source/packages/core/src/lib/geometry/path-transforms-ts/#L46)

</details>

<span id="api-PathRect"></span>

### PathRect

A source rectangle with an origin and finite positive dimensions.

```ts
interface PathRect extends PathPoint
```

Related API: [PathRect](/reference/functions/path-transforms/), [PathPoint](/reference/functions/path-transforms/).

#### See also

[PathPoint](/reference/functions/path-transforms/)

[QuadTransformOptions](/reference/functions/path-transforms/)

[EnvelopeTransformOptions](/reference/functions/path-transforms/)

[View source — packages/core/src/lib/geometry/path-transforms.ts:55](/source/packages/core/src/lib/geometry/path-transforms-ts/#L55)

#### Properties and methods

<span id="api-PathRect-width"></span>
<details>
<summary>width</summary>


```ts
readonly width: number
```

Horizontal extent in the units of the containing geometry or surface. See PathRect.

[View source — packages/core/src/lib/geometry/path-transforms.ts:57](/source/packages/core/src/lib/geometry/path-transforms-ts/#L57)

</details>

<span id="api-PathRect-height"></span>
<details>
<summary>height</summary>


```ts
readonly height: number
```

Vertical extent in the units of the containing geometry or surface. See PathRect.

[View source — packages/core/src/lib/geometry/path-transforms.ts:59](/source/packages/core/src/lib/geometry/path-transforms-ts/#L59)

</details>

<span id="api-PathRect-x"></span>
<details>
<summary>x</summary>


```ts
readonly x: number
```

Horizontal coordinate or displacement in the containing coordinate system. See
PathPoint.

[View source — packages/core/src/lib/geometry/path-transforms.ts:41](/source/packages/core/src/lib/geometry/path-transforms-ts/#L41)

</details>

<span id="api-PathRect-y"></span>
<details>
<summary>y</summary>


```ts
readonly y: number
```

Vertical coordinate or displacement in the containing coordinate system. See PathPoint
.

[View source — packages/core/src/lib/geometry/path-transforms.ts:46](/source/packages/core/src/lib/geometry/path-transforms-ts/#L46)

</details>

<span id="api-TransformPathOptions"></span>

### TransformPathOptions

Accuracy and output-segment limits for applying a path transform.

```ts
interface TransformPathOptions
```

Related API: [TransformPathOptions](/reference/functions/path-transforms/).

#### See also

[transformPath](/reference/functions/path-transforms/)

[View source — packages/core/src/lib/geometry/path-transforms.ts:92](/source/packages/core/src/lib/geometry/path-transforms-ts/#L92)

#### Properties and methods

<span id="api-TransformPathOptions-tolerance"></span>
<details>
<summary>tolerance</summary>


```ts
readonly tolerance: number
```

Positive maximum geometric approximation error. See TransformPathOptions.

[View source — packages/core/src/lib/geometry/path-transforms.ts:94](/source/packages/core/src/lib/geometry/path-transforms-ts/#L94)

</details>

<span id="api-TransformPathOptions-maxSegments"></span>
<details>
<summary>maxSegments (optional)</summary>


```ts
readonly maxSegments?: number | undefined
```

Upper bound on the number of output path segments. See TransformPathOptions.

[View source — packages/core/src/lib/geometry/path-transforms.ts:96](/source/packages/core/src/lib/geometry/path-transforms-ts/#L96)

</details>

<span id="api-QuadTransformOptions"></span>

### QuadTransformOptions

Source rectangle, destination corners, and interpolation mode for a quadrilateral transform.

```ts
interface QuadTransformOptions
```

Related API: [QuadTransformOptions](/reference/functions/path-transforms/).

#### See also

[PathRect](/reference/functions/path-transforms/)

[PathQuadCorners](/reference/functions/path-transforms/)

[PathQuadMode](/reference/functions/path-transforms/)

[quadTransform](/reference/functions/path-transforms/)

[View source — packages/core/src/lib/geometry/path-transforms.ts:118](/source/packages/core/src/lib/geometry/path-transforms-ts/#L118)

#### Properties and methods

<span id="api-QuadTransformOptions-source"></span>
<details>
<summary>source</summary>


```ts
readonly source: PathRect
```

Related API: [PathRect](/reference/functions/path-transforms/).

Source rectangle mapped to the destination quadrilateral. See PathRect.

[View source — packages/core/src/lib/geometry/path-transforms.ts:120](/source/packages/core/src/lib/geometry/path-transforms-ts/#L120)

</details>

<span id="api-QuadTransformOptions-destination"></span>
<details>
<summary>destination</summary>


```ts
readonly destination: PathWarpCorners
```

Destination corners into which the source rectangle maps. See PathQuadCorners.

[View source — packages/core/src/lib/geometry/path-transforms.ts:122](/source/packages/core/src/lib/geometry/path-transforms-ts/#L122)

</details>

<span id="api-QuadTransformOptions-mode"></span>
<details>
<summary>mode (optional)</summary>


```ts
readonly mode?: PathWarpMode | undefined
```

Selects the supported mapping, placement, or result policy. See PathQuadMode.

[View source — packages/core/src/lib/geometry/path-transforms.ts:124](/source/packages/core/src/lib/geometry/path-transforms-ts/#L124)

</details>

<span id="api-PathQuadCorners"></span>

### PathQuadCorners

The four destination corners used by a quadrilateral path transform.

```ts
type PathQuadCorners = PathWarpCorners
```

Related API: [PathQuadCorners](/reference/functions/path-transforms/).

#### See also

[QuadTransformOptions](/reference/functions/path-transforms/)

[View source — packages/core/src/lib/geometry/path-transforms.ts:103](/source/packages/core/src/lib/geometry/path-transforms-ts/#L103)

#### Properties and methods

<span id="api-PathQuadCorners-topLeft"></span>
<details>
<summary>topLeft</summary>


```ts
readonly topLeft: PathWarpPoint
```



[View source — packages/core/src/lib/geometry/path-warp.ts:8](/source/packages/core/src/lib/geometry/path-warp-ts/#L8)

</details>

<span id="api-PathQuadCorners-topRight"></span>
<details>
<summary>topRight</summary>


```ts
readonly topRight: PathWarpPoint
```



[View source — packages/core/src/lib/geometry/path-warp.ts:9](/source/packages/core/src/lib/geometry/path-warp-ts/#L9)

</details>

<span id="api-PathQuadCorners-bottomLeft"></span>
<details>
<summary>bottomLeft</summary>


```ts
readonly bottomLeft: PathWarpPoint
```



[View source — packages/core/src/lib/geometry/path-warp.ts:10](/source/packages/core/src/lib/geometry/path-warp-ts/#L10)

</details>

<span id="api-PathQuadCorners-bottomRight"></span>
<details>
<summary>bottomRight</summary>


```ts
readonly bottomRight: PathWarpPoint
```



[View source — packages/core/src/lib/geometry/path-warp.ts:11](/source/packages/core/src/lib/geometry/path-warp-ts/#L11)

</details>

<span id="api-PathQuadMode"></span>

### PathQuadMode

Selects bilinear or perspective interpolation for a quadrilateral transform.

```ts
type PathQuadMode = PathWarpMode
```

Related API: [PathQuadMode](/reference/functions/path-transforms/).

#### See also

[QuadTransformOptions](/reference/functions/path-transforms/)

[View source — packages/core/src/lib/geometry/path-transforms.ts:109](/source/packages/core/src/lib/geometry/path-transforms-ts/#L109)

<span id="api-BendTransformOptions"></span>

### BendTransformOptions

Alignment, fitting, baseline, and overflow controls shared by reusable bend transforms.

```ts
type BendTransformOptions = Omit<
  PathBendOptions,
  'tolerance' | 'maxSegments'
>
```

Related API: [BendTransformOptions](/reference/functions/path-transforms/).

#### See also

[PathBendTransformOptions](/reference/functions/path-transforms/)

[View source — packages/core/src/lib/geometry/transform-bend.ts:34](/source/packages/core/src/lib/geometry/transform-bend-ts/#L34)

#### Properties and methods

<span id="api-BendTransformOptions-source"></span>
<details>
<summary>source</summary>


```ts
readonly source: PathBendFrame
```

Source coordinate frame used to normalize the geometry before bending. See
PathBendFrame.

[View source — packages/core/src/lib/geometry/path-bending.ts:64](/source/packages/core/src/lib/geometry/path-bending-ts/#L64)

</details>

<span id="api-BendTransformOptions-align"></span>
<details>
<summary>align (optional)</summary>


```ts
readonly align?: PathBendAlign | undefined
```

Related API: [PathBendAlign](/reference/functions/path-bending/).

Placement of the source length along the guide. See PathBendAlign.

[View source — packages/core/src/lib/geometry/path-bending.ts:66](/source/packages/core/src/lib/geometry/path-bending-ts/#L66)

</details>

<span id="api-BendTransformOptions-baseline"></span>
<details>
<summary>baseline (optional)</summary>


```ts
readonly baseline?: PathBendBaseline | undefined
```

Related API: [PathBendBaseline](/reference/functions/path-bending/).

Source baseline mapped onto the guide. See PathBendBaseline.

[View source — packages/core/src/lib/geometry/path-bending.ts:68](/source/packages/core/src/lib/geometry/path-bending-ts/#L68)

</details>

<span id="api-BendTransformOptions-fit"></span>
<details>
<summary>fit (optional)</summary>


```ts
readonly fit?: PathBendFit | undefined
```

Related API: [PathBendFit](/reference/functions/path-bending/).

Policy for fitting content within its available box. See PathBendFit.

[View source — packages/core/src/lib/geometry/path-bending.ts:70](/source/packages/core/src/lib/geometry/path-bending-ts/#L70)

</details>

<span id="api-BendTransformOptions-offset"></span>
<details>
<summary>offset (optional)</summary>


```ts
readonly offset?: number | undefined
```

Offset along the guide. See PathBendOptions.

[View source — packages/core/src/lib/geometry/path-bending.ts:72](/source/packages/core/src/lib/geometry/path-bending-ts/#L72)

</details>

<span id="api-BendTransformOptions-normalOffset"></span>
<details>
<summary>normalOffset (optional)</summary>


```ts
readonly normalOffset?: number | undefined
```

Offset perpendicular to the guide. See PathBendOptions.

[View source — packages/core/src/lib/geometry/path-bending.ts:74](/source/packages/core/src/lib/geometry/path-bending-ts/#L74)

</details>

<span id="api-BendTransformOptions-overflow"></span>
<details>
<summary>overflow (optional)</summary>


```ts
readonly overflow?: PathBendOverflow | undefined
```

Related API: [PathBendOverflow](/reference/functions/path-bending/).

Policy for geometry extending beyond the guide's available length. See
PathBendOverflow.

[View source — packages/core/src/lib/geometry/path-bending.ts:79](/source/packages/core/src/lib/geometry/path-bending-ts/#L79)

</details>

<span id="api-EnvelopeTransformOptions"></span>

### EnvelopeTransformOptions

Source rectangle and either a top/bottom pair or ordered envelope guides.

<details>
<summary>Full type declaration</summary>

```ts
type EnvelopeTransformOptions = {
  /** Source rectangle mapped between the envelope guides. See {@link PathRect}. */
  readonly source: PathRect;
  /** Interpolation between successive guide paths; only linear interpolation is supported. See {@link EnvelopeTransformOptions}. */
  readonly interpolation?: 'linear';
} & (
  | {
      /** Top edge value or top envelope guide. See {@link PathGuide}. */
      readonly top: PathGuide;
      /** Bottom edge value or bottom envelope guide. See {@link PathGuide}. */
      readonly bottom: PathGuide;
      /**
       * Not accepted in this variant; use the alternative fields instead. See
       * {@link EnvelopeTransformOptions}.
       */
      readonly guides?: never;
    }
  | {
      /**
       * Ordered guide paths defining the envelope from its first to last station. See
       * {@link EnvelopeGuide}.
       */
      readonly guides: readonly EnvelopeGuide[];
      /**
       * Not accepted in this variant; use the alternative fields instead. See
       * {@link EnvelopeTransformOptions}.
       */
      readonly top?: never;
      /**
       * Not accepted in this variant; use the alternative fields instead. See
       * {@link EnvelopeTransformOptions}.
       */
      readonly bottom?: never;
    }
)
```

</details>

Related API: [EnvelopeTransformOptions](/reference/functions/path-transforms/), [PathRect](/reference/functions/path-transforms/), [PathGuide](/reference/functions/path-transforms/), [EnvelopeGuide](/reference/functions/path-transforms/).

#### See also

[PathRect](/reference/functions/path-transforms/)

[PathGuide](/reference/functions/path-transforms/)

[EnvelopeGuide](/reference/functions/path-transforms/)

[envelopeTransform](/reference/functions/path-transforms/)

[View source — packages/core/src/lib/geometry/path-transforms.ts:146](/source/packages/core/src/lib/geometry/path-transforms-ts/#L146)

#### Properties and methods

<span id="api-EnvelopeTransformOptions-source"></span>
<details>
<summary>source</summary>


```ts
readonly source: PathRect
```

Related API: [PathRect](/reference/functions/path-transforms/).

Source rectangle mapped between the envelope guides. See PathRect.

[View source — packages/core/src/lib/geometry/path-transforms.ts:148](/source/packages/core/src/lib/geometry/path-transforms-ts/#L148)

</details>

<span id="api-EnvelopeTransformOptions-interpolation"></span>
<details>
<summary>interpolation (optional)</summary>


```ts
readonly interpolation?: "linear" | undefined
```

Interpolation between successive guide paths; only linear interpolation is supported. See EnvelopeTransformOptions.

[View source — packages/core/src/lib/geometry/path-transforms.ts:150](/source/packages/core/src/lib/geometry/path-transforms-ts/#L150)

</details>

<span id="api-EnvelopeTransformOptions-top"></span>
<details>
<summary>top (optional)</summary>


```ts
readonly top?: PathGuide | undefined
```

Related API: [PathGuide](/reference/functions/path-transforms/).

Top edge value or top envelope guide. See PathGuide.
Not accepted in this variant; use the alternative fields instead. See
EnvelopeTransformOptions.

[View source — packages/core/src/lib/geometry/path-transforms.ts:154](/source/packages/core/src/lib/geometry/path-transforms-ts/#L154)

</details>

<span id="api-EnvelopeTransformOptions-bottom"></span>
<details>
<summary>bottom (optional)</summary>


```ts
readonly bottom?: PathGuide | undefined
```

Related API: [PathGuide](/reference/functions/path-transforms/).

Bottom edge value or bottom envelope guide. See PathGuide.
Not accepted in this variant; use the alternative fields instead. See
EnvelopeTransformOptions.

[View source — packages/core/src/lib/geometry/path-transforms.ts:156](/source/packages/core/src/lib/geometry/path-transforms-ts/#L156)

</details>

<span id="api-EnvelopeTransformOptions-guides"></span>
<details>
<summary>guides (optional)</summary>


```ts
readonly guides?: readonly EnvelopeGuide[] | undefined
```

Related API: [EnvelopeGuide](/reference/functions/path-transforms/).

Not accepted in this variant; use the alternative fields instead. See
EnvelopeTransformOptions.
Ordered guide paths defining the envelope from its first to last station. See
EnvelopeGuide.

[View source — packages/core/src/lib/geometry/path-transforms.ts:161](/source/packages/core/src/lib/geometry/path-transforms-ts/#L161)

</details>

<span id="api-EnvelopeGuide"></span>

### EnvelopeGuide

A guide path positioned at a normalized station across an envelope.

```ts
interface EnvelopeGuide
```

Related API: [EnvelopeGuide](/reference/functions/path-transforms/).

#### See also

[PathGuide](/reference/functions/path-transforms/)

[EnvelopeTransformOptions](/reference/functions/path-transforms/)

[View source — packages/core/src/lib/geometry/path-transforms.ts:132](/source/packages/core/src/lib/geometry/path-transforms-ts/#L132)

#### Properties and methods

<span id="api-EnvelopeGuide-at"></span>
<details>
<summary>at</summary>


```ts
readonly at: number
```

Normalized station position. See EnvelopeGuide.

[View source — packages/core/src/lib/geometry/path-transforms.ts:134](/source/packages/core/src/lib/geometry/path-transforms-ts/#L134)

</details>

<span id="api-EnvelopeGuide-path"></span>
<details>
<summary>path</summary>


```ts
readonly path: PathGuide
```

Related API: [PathGuide](/reference/functions/path-transforms/).

Path geometry used by this operation. See PathGuide.

[View source — packages/core/src/lib/geometry/path-transforms.ts:136](/source/packages/core/src/lib/geometry/path-transforms-ts/#L136)

</details>

<span id="api-PathGuide"></span>

### PathGuide

A geometry path or a path with explicit guide-sampling configuration.

```ts
type PathGuide = PathGeometry | PathGuideOptions
```

Related API: [PathGuide](/reference/functions/path-transforms/), [PathGeometry](/reference/functions/path-geometry/), [PathGuideOptions](/reference/functions/path-transforms/).

#### See also

[PathGeometry](/reference/functions/path-geometry/)

[PathGuideOptions](/reference/functions/path-transforms/)

[MeshTransformOptions](/reference/functions/path-transforms/)

[EnvelopeTransformOptions](/reference/functions/path-transforms/)

[EnvelopeGuide](/reference/functions/path-transforms/)

[View source — packages/core/src/lib/geometry/transform-guide.ts:59](/source/packages/core/src/lib/geometry/transform-guide-ts/#L59)

<span id="api-PathGuideOptions"></span>

### PathGuideOptions

Geometry and stations that define how a transformation samples a guide.

```ts
interface PathGuideOptions
```

Related API: [PathGuideOptions](/reference/functions/path-transforms/).

#### See also

[PathGeometry](/reference/functions/path-geometry/)

[PathGuideStation](/reference/functions/path-transforms/)

[PathGuide](/reference/functions/path-transforms/)

[View source — packages/core/src/lib/geometry/transform-guide.ts:39](/source/packages/core/src/lib/geometry/transform-guide-ts/#L39)

#### Properties and methods

<span id="api-PathGuideOptions-path"></span>
<details>
<summary>path</summary>


```ts
readonly path: PathGeometry
```

Related API: [PathGeometry](/reference/functions/path-geometry/).

Path geometry used by this operation. See PathGeometry.

[View source — packages/core/src/lib/geometry/transform-guide.ts:41](/source/packages/core/src/lib/geometry/transform-guide-ts/#L41)

</details>

<span id="api-PathGuideOptions-reverse"></span>
<details>
<summary>reverse (optional)</summary>


```ts
readonly reverse?: boolean | undefined
```

Whether to reverse the direction of the mapping or guide. See PathGuideOptions.

[View source — packages/core/src/lib/geometry/transform-guide.ts:43](/source/packages/core/src/lib/geometry/transform-guide-ts/#L43)

</details>

<span id="api-PathGuideOptions-stations"></span>
<details>
<summary>stations (optional)</summary>


```ts
readonly stations?: readonly PathGuideStation[] | undefined
```

Related API: [PathGuideStation](/reference/functions/path-transforms/).

Explicit correspondence between normalized stations and guide distance. See
PathGuideStation.

[View source — packages/core/src/lib/geometry/transform-guide.ts:48](/source/packages/core/src/lib/geometry/transform-guide-ts/#L48)

</details>

<span id="api-PathGuideStation"></span>

### PathGuideStation

A station mapping normalized guide position to normalized arc-length distance along its path.

```ts
interface PathGuideStation
```

Related API: [PathGuideStation](/reference/functions/path-transforms/).

#### See also

[PathGuideOptions](/reference/functions/path-transforms/)

[View source — packages/core/src/lib/geometry/transform-guide.ts:26](/source/packages/core/src/lib/geometry/transform-guide-ts/#L26)

#### Properties and methods

<span id="api-PathGuideStation-at"></span>
<details>
<summary>at</summary>


```ts
readonly at: number
```

Normalized station position. See PathGuideStation.

[View source — packages/core/src/lib/geometry/transform-guide.ts:28](/source/packages/core/src/lib/geometry/transform-guide-ts/#L28)

</details>

<span id="api-PathGuideStation-distance"></span>
<details>
<summary>distance</summary>


```ts
readonly distance: number
```

Normalized arc-length distance from 0 to 1. See PathGuideStation.

[View source — packages/core/src/lib/geometry/transform-guide.ts:30](/source/packages/core/src/lib/geometry/transform-guide-ts/#L30)

</details>

## Implementation guidance for agents

Read the [Drawing, layout, and effects companion](/agents/topics/layout/) for ownership, adaptation, failure modes, and verification. [Agent start](/agents/) provides the version-selection workflow.

## Complete minimal examples

- [Quad and envelope warps](/minimal-examples/paths/quad-envelope/): Warp a tile through a quadrilateral and between measured guide paths. [Plain source](/minimal/paths/quad-envelope.ts)
- [Arc and path bending](/minimal-examples/paths/bends/): Bend geometry around an arc and along a guide with explicit placement options. [Plain source](/minimal/paths/bends.ts)
- [Mesh warp](/minimal-examples/paths/mesh/): Define a one-cell guide mesh and warp a circle through it. [Plain source](/minimal/paths/mesh.ts)
- [Affine transforms](/minimal-examples/paths/affine/): Compose translation and scaling, then transform geometry and a sample point. [Plain source](/minimal/paths/affine.ts)
## Interactive examples

- [Four-corner path warp](/examples/path-warp/) · [Full page](/experience/path-warp/)
- [Along Arc](/examples/path-bending/) · [Full page](/experience/path-bending/)
- [Along Path](/examples/along-path/) · [Full page](/experience/along-path/)
- [Text envelope playground](/examples/text-envelope/) · [Full page](/experience/text-envelope/)
## Documentation version

Documentation built with @pibbl/core 0.0.2, revision 272a94a. ALPHA — NOT FOR PRODUCTION USE.