poly-prune 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,129 @@
+# PolyPrune Outer Approximation
+
+Deterministic outer-approximation helper for GeoJSON polygons.
+
+## Install
+
+```bash
+npm install poly-prune
+```
+
+## What It Guarantees
+
+- Strict containment: output polygon never cuts inside the original polygon.
+- Exact vertex count: output has exactly `targetVertexCount` vertices.
+- Minimum deviation objective: algorithm minimizes outward deviation for the requested target.
+- `maxDeviation` is only an upper limit (optional), never the optimization target.
+- Deterministic output: same input always returns the same result.
+
+## API
+
+```ts
+outerApproximatePolygon(
+  originalPolygon: GeoJSONPolygon,
+  targetVertexCount: number,
+  maxDeviation?: number
+): {
+  polygon: GeoJSONPolygon;
+  achievedDeviation: number;
+  maxDeviation: number;
+  maxDeviationProvided: boolean;
+}
+```
+
+### Inputs
+
+- `originalPolygon`: GeoJSON `Polygon` geometry (single outer ring, no holes).
+- `targetVertexCount`: integer `>= 3`.
+- `maxDeviation` (optional): non-negative numeric cap.
+
+### Output Fields
+
+- `polygon`: resulting outer polygon.
+- `achievedDeviation`: measured outward deviation of result.
+- `maxDeviation`: provided cap, or inferred value (`achievedDeviation`) when omitted.
+- `maxDeviationProvided`: `true` if caller passed `maxDeviation`.
+
+## Behavior Rules
+
+1. Minimize deviation first.
+2. If `maxDeviation` is provided, return only if `achievedDeviation <= maxDeviation`.
+3. If impossible under cap, throws `OuterApproximationError` with code `TARGET_NOT_REACHABLE`.
+
+## Examples
+
+### CommonJS
+
+```js
+const { outerApproximatePolygon } = require('poly-prune');
+
+const result = outerApproximatePolygon(polygon, 4, 0.005);
+console.log(result.achievedDeviation);
+console.log(JSON.stringify(result.polygon));
+```
+
+### TypeScript
+
+```ts
+import { outerApproximatePolygon } from 'poly-prune';
+
+const result = outerApproximatePolygon(polygon, 4);
+```
+
+## Error Handling (Public API)
+
+The library throws `OuterApproximationError` with stable `code` values and structured `details`.
+
+```js
+const {
+  outerApproximatePolygon,
+  OuterApproximationError,
+  OUTER_APPROXIMATION_ERROR_CODES,
+} = require('poly-prune');
+
+try {
+  const result = outerApproximatePolygon(polygon, 4, 0.005);
+  console.log(result.polygon);
+} catch (error) {
+  if (error instanceof OuterApproximationError) {
+    if (error.code === OUTER_APPROXIMATION_ERROR_CODES.TARGET_NOT_REACHABLE) {
+      console.error('Not feasible under maxDeviation', error.details);
+    } else {
+      console.error('Invalid input', error.code, error.details);
+    }
+  } else {
+    throw error;
+  }
+}
+```
+
+### Common Error Codes
+
+- `TARGET_NOT_REACHABLE`
+- `INVALID_POLYGON_OBJECT`
+- `INVALID_POLYGON_TYPE`
+- `MISSING_COORDINATES`
+- `HOLES_NOT_SUPPORTED`
+- `INVALID_TARGET_VERTEX_COUNT`
+- `INVALID_MAX_DEVIATION`
+- `INVALID_RING_LENGTH`
+- `INVALID_COORDINATE_TUPLE`
+- `INVALID_COORDINATE_VALUE`
+- `RING_NOT_CLOSED`
+- `INSUFFICIENT_UNIQUE_VERTICES`
+- `SELF_INTERSECTING_POLYGON`
+- `DEGENERATE_EDGE_INSERTION`
+
+## Local Development
+
+- Run tests: `npm test`
+- Preview package artifact: `npm run pack:check`
+
+## Publish Checklist
+
+1. Update `name` if needed (must be unique on npm).
+2. Update `version` (semver).
+3. `npm test`
+4. `npm run pack:check`
+5. `npm login`
+6. `npm publish --access public`

package/index.d.ts

@@ -0,0 +1 @@
+export * from "./outerApproximatePolygon";

package/index.js

@@ -0,0 +1,3 @@
+"use strict";
+
+module.exports = require("./outerApproximatePolygon");

package/outerApproximatePolygon.d.ts

@@ -0,0 +1,45 @@
+export type OuterApproximationErrorCode =
+  | "INVALID_POLYGON_OBJECT"
+  | "INVALID_POLYGON_TYPE"
+  | "MISSING_COORDINATES"
+  | "HOLES_NOT_SUPPORTED"
+  | "INVALID_TARGET_VERTEX_COUNT"
+  | "INVALID_MAX_DEVIATION"
+  | "INVALID_RING_LENGTH"
+  | "INVALID_COORDINATE_TUPLE"
+  | "INVALID_COORDINATE_VALUE"
+  | "RING_NOT_CLOSED"
+  | "INSUFFICIENT_UNIQUE_VERTICES"
+  | "SELF_INTERSECTING_POLYGON"
+  | "DEGENERATE_EDGE_INSERTION"
+  | "TARGET_NOT_REACHABLE";
+
+export interface GeoJSONPolygon {
+  type: "Polygon";
+  coordinates: number[][][];
+}
+
+export interface OuterApproximationResult {
+  polygon: GeoJSONPolygon;
+  achievedDeviation: number;
+  maxDeviation: number;
+  maxDeviationProvided: boolean;
+}
+
+export interface OuterApproximationErrorDetails {
+  [key: string]: unknown;
+}
+
+export class OuterApproximationError extends Error {
+  readonly code: OuterApproximationErrorCode;
+  readonly details: OuterApproximationErrorDetails;
+  constructor(code: OuterApproximationErrorCode, message: string, details?: OuterApproximationErrorDetails);
+}
+
+export const OUTER_APPROXIMATION_ERROR_CODES: Readonly<Record<OuterApproximationErrorCode, OuterApproximationErrorCode>>;
+
+export function outerApproximatePolygon(
+  originalPolygon: GeoJSONPolygon,
+  targetVertexCount: number,
+  maxDeviation?: number
+): OuterApproximationResult;

package/outerApproximatePolygon.js

@@ -0,0 +1,1092 @@
+"use strict";
+
+const EPS = 1e-9;
+const OUTER_APPROXIMATION_ERROR_CODES = Object.freeze({
+  INVALID_POLYGON_OBJECT: "INVALID_POLYGON_OBJECT",
+  INVALID_POLYGON_TYPE: "INVALID_POLYGON_TYPE",
+  MISSING_COORDINATES: "MISSING_COORDINATES",
+  HOLES_NOT_SUPPORTED: "HOLES_NOT_SUPPORTED",
+  INVALID_TARGET_VERTEX_COUNT: "INVALID_TARGET_VERTEX_COUNT",
+  INVALID_MAX_DEVIATION: "INVALID_MAX_DEVIATION",
+  INVALID_RING_LENGTH: "INVALID_RING_LENGTH",
+  INVALID_COORDINATE_TUPLE: "INVALID_COORDINATE_TUPLE",
+  INVALID_COORDINATE_VALUE: "INVALID_COORDINATE_VALUE",
+  RING_NOT_CLOSED: "RING_NOT_CLOSED",
+  INSUFFICIENT_UNIQUE_VERTICES: "INSUFFICIENT_UNIQUE_VERTICES",
+  SELF_INTERSECTING_POLYGON: "SELF_INTERSECTING_POLYGON",
+  DEGENERATE_EDGE_INSERTION: "DEGENERATE_EDGE_INSERTION",
+  TARGET_NOT_REACHABLE: "TARGET_NOT_REACHABLE",
+});
+
+class OuterApproximationError extends Error {
+  constructor(code, message, details = {}) {
+    super(message);
+    this.name = "OuterApproximationError";
+    this.code = code;
+    this.details = details;
+    Object.setPrototypeOf(this, OuterApproximationError.prototype);
+  }
+}
+
+function createOuterApproximationError(code, message, details = {}) {
+  return new OuterApproximationError(code, message, details);
+}
+
+/**
+ * Deterministic outer-approximation helper.
+ *
+ * Inputs:
+ * - originalPolygon: GeoJSON Polygon geometry (single outer ring required)
+ * - targetVertexCount (Y): exact vertex count in the returned outer ring (without closure point)
+ * - maxDeviation (Z): maximum allowed outward boundary deviation
+ *
+ * Output:
+ * - GeoJSON Polygon geometry on success
+ * - throws OuterApproximationError on invalid input or geometric impossibility
+ */
+function outerApproximatePolygon(originalPolygon, targetVertexCount, maxDeviation) {
+  validateInputs(originalPolygon, targetVertexCount, maxDeviation);
+  const originalRing = normalizeOuterRing(originalPolygon);
+  const originalCount = originalRing.length;
+  const hasDeviationLimit = typeof maxDeviation === "number";
+  const deviationLimit = hasDeviationLimit ? maxDeviation : Number.POSITIVE_INFINITY;
+
+  if (targetVertexCount === originalCount) {
+    const polygon = toGeoJSONPolygon(originalRing);
+    return buildResult(polygon, originalRing, maxDeviation, hasDeviationLimit);
+  }
+
+  if (targetVertexCount > originalCount) {
+    const grown = addVerticesWithoutChangingBoundary(originalRing, targetVertexCount);
+    const polygon = toGeoJSONPolygon(grown);
+    return buildResult(polygon, originalRing, maxDeviation, hasDeviationLimit);
+  }
+
+  // Phase 1: globally optimal direct reduction search.
+  const direct = findOptimalDirectReduction(originalRing, targetVertexCount, deviationLimit);
+  if (direct) {
+    const tightened = maybeTightenRing(direct.ring, originalRing);
+    const polygon = toGeoJSONPolygon(tightened);
+    return buildResult(polygon, originalRing, maxDeviation, hasDeviationLimit);
+  }
+
+  // Phase 2: deterministic convex-support removals when direct removals are exhausted.
+  let current = cloneRing(originalRing);
+  let convex = convexHull(current);
+  if (convex.length < 3) {
+    throw cannotReachTargetError(targetVertexCount, maxDeviation, hasDeviationLimit);
+  }
+
+  if (signedArea(convex) < 0) {
+    convex.reverse();
+  }
+
+  const hullDeviation = directedBoundaryDeviation(convex, originalRing);
+  if (hullDeviation > deviationLimit + EPS) {
+    throw cannotReachTargetError(targetVertexCount, maxDeviation, hasDeviationLimit);
+  }
+
+  if (!polygonContainsPolygon(convex, originalRing)) {
+    throw cannotReachTargetError(targetVertexCount, maxDeviation, hasDeviationLimit);
+  }
+
+  current = convex;
+
+  if (current.length < targetVertexCount) {
+    const grown = addVerticesWithoutChangingBoundary(current, targetVertexCount);
+    const grownDeviation = directedBoundaryDeviation(grown, originalRing);
+    if (grownDeviation > deviationLimit + EPS) {
+      throw cannotReachTargetError(targetVertexCount, maxDeviation, hasDeviationLimit);
+    }
+    if (!polygonContainsPolygon(grown, originalRing)) {
+      throw cannotReachTargetError(targetVertexCount, maxDeviation, hasDeviationLimit);
+    }
+    const polygon = toGeoJSONPolygon(grown);
+    return buildResult(polygon, originalRing, maxDeviation, hasDeviationLimit);
+  }
+
+  const convexBest = findOptimalConvexReduction(current, originalRing, targetVertexCount, deviationLimit);
+  if (!convexBest) {
+    throw cannotReachTargetError(targetVertexCount, maxDeviation, hasDeviationLimit);
+  }
+  current = convexBest.ring;
+
+  if (!polygonContainsPolygon(current, originalRing)) {
+    throw cannotReachTargetError(targetVertexCount, maxDeviation, hasDeviationLimit);
+  }
+
+  const finalDeviation = directedBoundaryDeviation(current, originalRing);
+  if (finalDeviation > deviationLimit + EPS) {
+    throw cannotReachTargetError(targetVertexCount, maxDeviation, hasDeviationLimit);
+  }
+
+  if (current.length !== targetVertexCount) {
+    throw cannotReachTargetError(targetVertexCount, maxDeviation, hasDeviationLimit);
+  }
+
+  const tightened = maybeTightenRing(current, originalRing);
+  const polygon = toGeoJSONPolygon(tightened);
+  return buildResult(polygon, originalRing, maxDeviation, hasDeviationLimit);
+}
+
+function validateInputs(originalPolygon, targetVertexCount, maxDeviation) {
+  if (!originalPolygon || typeof originalPolygon !== "object") {
+    throw createOuterApproximationError("INVALID_POLYGON_OBJECT", "originalPolygon must be a GeoJSON Polygon geometry object.", { receivedType: typeof originalPolygon });
+  }
+  if (originalPolygon.type !== "Polygon") {
+    throw createOuterApproximationError("INVALID_POLYGON_TYPE", "originalPolygon.type must be 'Polygon'.", { receivedType: originalPolygon.type });
+  }
+  if (!Array.isArray(originalPolygon.coordinates) || originalPolygon.coordinates.length === 0) {
+    throw createOuterApproximationError("MISSING_COORDINATES", "originalPolygon.coordinates must contain at least one ring.");
+  }
+  if (originalPolygon.coordinates.length > 1) {
+    throw createOuterApproximationError("HOLES_NOT_SUPPORTED", "Polygons with holes are not supported by this helper.", { ringCount: originalPolygon.coordinates.length });
+  }
+  if (!Number.isInteger(targetVertexCount) || targetVertexCount < 3) {
+    throw createOuterApproximationError("INVALID_TARGET_VERTEX_COUNT", "targetVertexCount must be an integer >= 3.", { targetVertexCount });
+  }
+  if (
+    maxDeviation !== undefined &&
+    (typeof maxDeviation !== "number" || !Number.isFinite(maxDeviation) || maxDeviation < 0)
+  ) {
+    throw createOuterApproximationError("INVALID_MAX_DEVIATION", "maxDeviation must be a finite number >= 0 when provided.", { maxDeviation });
+  }
+}
+
+function cannotReachTargetError(targetVertexCount, maxDeviation, hasDeviationLimit) {
+  if (hasDeviationLimit) {
+    return createOuterApproximationError(
+      "TARGET_NOT_REACHABLE",
+      `Cannot reach ${targetVertexCount} coordinates without exceeding max deviation ${maxDeviation}.`,
+      { targetVertexCount, maxDeviation, maxDeviationProvided: true }
+    );
+  }
+  return createOuterApproximationError(
+    "TARGET_NOT_REACHABLE",
+    `Cannot reach ${targetVertexCount} coordinates while preserving strict containment.`,
+    { targetVertexCount, maxDeviationProvided: false }
+  );
+}
+
+function buildResult(polygon, originalRing, maxDeviation, hasDeviationLimit) {
+  const outputRing = polygon.coordinates[0].slice(0, polygon.coordinates[0].length - 1);
+  const achievedDeviation = directedBoundaryDeviation(outputRing, originalRing);
+  return {
+    polygon,
+    achievedDeviation,
+    maxDeviation: hasDeviationLimit ? maxDeviation : achievedDeviation,
+    maxDeviationProvided: hasDeviationLimit,
+  };
+}
+
+function findOptimalDirectReduction(originalRing, targetVertexCount, deviationLimit) {
+  const n = originalRing.length;
+  if (targetVertexCount > n || targetVertexCount < 3) {
+    return null;
+  }
+
+  const startIndices = [];
+  for (let i = 0; i < n; i += 1) {
+    startIndices.push(i);
+  }
+
+  const startTight = maybeTightenRing(cloneRing(originalRing), originalRing);
+  const startDeviation = directedBoundaryDeviation(startTight, originalRing);
+  const stack = [{ indices: startIndices, ring: startTight, deviation: startDeviation }];
+  const seen = new Set([indicesKey(startIndices)]);
+
+  let best = null;
+
+  while (stack.length > 0) {
+    const state = stack.pop();
+
+    if (state.indices.length === targetVertexCount) {
+      if (
+        !best ||
+        state.deviation < best.deviation - EPS ||
+        (almostEqual(state.deviation, best.deviation) && compareIndexArrays(state.indices, best.indices) < 0)
+      ) {
+        best = {
+          indices: state.indices.slice(),
+          ring: cloneRing(state.ring),
+          deviation: state.deviation,
+        };
+      }
+      continue;
+    }
+
+    for (let removePos = 0; removePos < state.indices.length; removePos += 1) {
+      const nextIndices = state.indices.slice(0, removePos).concat(state.indices.slice(removePos + 1));
+      if (nextIndices.length < targetVertexCount) {
+        continue;
+      }
+
+      const key = indicesKey(nextIndices);
+      if (seen.has(key)) {
+        continue;
+      }
+
+      const candidateBaseRing = ringFromIndices(originalRing, nextIndices);
+      if (candidateBaseRing.length < 3) {
+        continue;
+      }
+      if (!isSimplePolygon(candidateBaseRing)) {
+        continue;
+      }
+      if (!polygonContainsPolygon(candidateBaseRing, originalRing)) {
+        continue;
+      }
+
+      const candidateRing = maybeTightenRing(candidateBaseRing, originalRing);
+      if (!isSimplePolygon(candidateRing)) {
+        continue;
+      }
+      if (!polygonContainsPolygon(candidateRing, originalRing)) {
+        continue;
+      }
+
+      const deviation = directedBoundaryDeviation(candidateRing, originalRing);
+      if (deviation > deviationLimit + EPS) {
+        continue;
+      }
+
+      seen.add(key);
+      stack.push({ indices: nextIndices, ring: candidateRing, deviation });
+    }
+  }
+
+  return best;
+}
+
+function ringFromIndices(originalRing, indices) {
+  const out = [];
+  for (let i = 0; i < indices.length; i += 1) {
+    const p = originalRing[indices[i]];
+    out.push([p[0], p[1]]);
+  }
+  return out;
+}
+
+function indicesKey(indices) {
+  return indices.join(",");
+}
+
+function compareIndexArrays(a, b) {
+  const n = Math.min(a.length, b.length);
+  for (let i = 0; i < n; i += 1) {
+    if (a[i] < b[i]) {
+      return -1;
+    }
+    if (a[i] > b[i]) {
+      return 1;
+    }
+  }
+  if (a.length < b.length) {
+    return -1;
+  }
+  if (a.length > b.length) {
+    return 1;
+  }
+  return 0;
+}
+function normalizeOuterRing(polygon) {
+  const ring = polygon.coordinates[0];
+  if (!Array.isArray(ring) || ring.length < 4) {
+    throw createOuterApproximationError("INVALID_RING_LENGTH", "Polygon outer ring must contain at least 4 positions (including closure).", { ringLength: ring.length });
+  }
+
+  const cleaned = [];
+  for (let i = 0; i < ring.length; i += 1) {
+    const p = ring[i];
+    if (!Array.isArray(p) || p.length < 2) {
+      throw createOuterApproximationError("INVALID_COORDINATE_TUPLE", "Every coordinate must be a [x, y] tuple.", { index: i });
+    }
+    const x = Number(p[0]);
+    const y = Number(p[1]);
+    if (!Number.isFinite(x) || !Number.isFinite(y)) {
+      throw createOuterApproximationError("INVALID_COORDINATE_VALUE", "Every coordinate must be finite.", { index: i });
+    }
+    cleaned.push([x, y]);
+  }
+
+  if (!samePoint(cleaned[0], cleaned[cleaned.length - 1])) {
+    throw createOuterApproximationError("RING_NOT_CLOSED", "GeoJSON linear ring must be explicitly closed (first point == last point).");
+  }
+
+  // Drop closure point and consecutive duplicate points.
+  const open = cleaned.slice(0, cleaned.length - 1);
+  const deduped = [];
+  for (let i = 0; i < open.length; i += 1) {
+    if (deduped.length === 0 || !samePoint(deduped[deduped.length - 1], open[i])) {
+      deduped.push(open[i]);
+    }
+  }
+  if (deduped.length >= 2 && samePoint(deduped[0], deduped[deduped.length - 1])) {
+    deduped.pop();
+  }
+
+  if (deduped.length < 3) {
+    throw createOuterApproximationError("INSUFFICIENT_UNIQUE_VERTICES", "Polygon must contain at least 3 unique vertices.");
+  }
+
+  if (!isSimplePolygon(deduped)) {
+    throw createOuterApproximationError("SELF_INTERSECTING_POLYGON", "Input polygon must be simple (no self-intersections).");
+  }
+
+  if (signedArea(deduped) < 0) {
+    deduped.reverse();
+  }
+
+  return deduped;
+}
+
+function toGeoJSONPolygon(openRing) {
+  const closed = cloneRing(openRing);
+  closed.push([openRing[0][0], openRing[0][1]]);
+  return {
+    type: "Polygon",
+    coordinates: [closed],
+  };
+}
+
+function findBestDirectRemoval(currentRing, originalRing) {
+  let best = null;
+
+  for (let i = 0; i < currentRing.length; i += 1) {
+    const candidate = removeVertex(currentRing, i);
+    if (candidate.length < 3) {
+      continue;
+    }
+    if (!isSimplePolygon(candidate)) {
+      continue;
+    }
+    if (!polygonContainsPolygon(candidate, originalRing)) {
+      continue;
+    }
+    const deviation = directedBoundaryDeviation(candidate, originalRing);
+    if (!best || deviation < best.deviation - EPS || (almostEqual(deviation, best.deviation) && i < best.index)) {
+      best = { ring: candidate, deviation, index: i };
+    }
+  }
+
+  return best;
+}
+
+function findOptimalConvexReduction(startRing, originalRing, targetVertexCount, deviationLimit) {
+  if (startRing.length < targetVertexCount || targetVertexCount < 3) {
+    return null;
+  }
+
+  const startTight = maybeTightenRing(cloneRing(startRing), originalRing);
+  const startDeviation = directedBoundaryDeviation(startTight, originalRing);
+  const stack = [{ ring: startTight, deviation: startDeviation }];
+  const seen = new Map([[canonicalRingKey(startTight), startDeviation]]);
+
+  let best = null;
+
+  while (stack.length > 0) {
+    const state = stack.pop();
+    const stateKey = canonicalRingKey(state.ring);
+    const bestSeenForState = seen.get(stateKey);
+    if (bestSeenForState !== undefined && state.deviation > bestSeenForState + EPS) {
+      continue;
+    }
+
+    if (state.ring.length === targetVertexCount) {
+      if (
+        !best ||
+        state.deviation < best.deviation - EPS ||
+        (almostEqual(state.deviation, best.deviation) && stateKey < best.signature)
+      ) {
+        best = {
+          ring: cloneRing(state.ring),
+          deviation: state.deviation,
+          signature: stateKey,
+        };
+      }
+      continue;
+    }
+
+    for (let i = 0; i < state.ring.length; i += 1) {
+      const candidateRaw = makeConvexRemovalCandidate(state.ring, i);
+      if (!candidateRaw) {
+        continue;
+      }
+      if (!isSimplePolygon(candidateRaw)) {
+        continue;
+      }
+      if (!isConvexCCW(candidateRaw)) {
+        continue;
+      }
+      if (!polygonContainsPolygon(candidateRaw, originalRing)) {
+        continue;
+      }
+
+      const candidate = maybeTightenRing(candidateRaw, originalRing);
+      if (!isSimplePolygon(candidate)) {
+        continue;
+      }
+      if (!isConvexCCW(candidate)) {
+        continue;
+      }
+      if (!polygonContainsPolygon(candidate, originalRing)) {
+        continue;
+      }
+
+      const deviation = directedBoundaryDeviation(candidate, originalRing);
+      if (deviation > deviationLimit + EPS) {
+        continue;
+      }
+
+      const sig = canonicalRingKey(candidate);
+      const seenDeviation = seen.get(sig);
+      if (seenDeviation !== undefined && seenDeviation <= deviation + EPS) {
+        continue;
+      }
+
+      seen.set(sig, deviation);
+      stack.push({ ring: candidate, deviation });
+    }
+  }
+
+  return best;
+}
+
+function canonicalRingKey(ring) {
+  const n = ring.length;
+  if (n === 0) {
+    return "";
+  }
+
+  let start = 0;
+  for (let i = 1; i < n; i += 1) {
+    const pi = ring[i];
+    const ps = ring[start];
+    if (pi[0] < ps[0] - EPS || (almostEqual(pi[0], ps[0]) && pi[1] < ps[1] - EPS)) {
+      start = i;
+    }
+  }
+
+  const parts = [];
+  for (let k = 0; k < n; k += 1) {
+    const p = ring[(start + k) % n];
+    parts.push(`${p[0].toFixed(12)},${p[1].toFixed(12)}`);
+  }
+  return parts.join("|");
+}
+
+function maybeTightenRing(ring, originalRing) {
+  if (!isConvexCCW(ring)) {
+    return ring;
+  }
+
+  let current = cloneRing(ring);
+  let currentDeviation = directedBoundaryDeviation(current, originalRing);
+  let prevKey = canonicalRingKey(current);
+
+  for (let iter = 0; iter < 8; iter += 1) {
+    const tightened = tightenConvexRingParallelSupportOnce(current, originalRing);
+    if (!tightened) {
+      break;
+    }
+    if (!isSimplePolygon(tightened) || !isConvexCCW(tightened)) {
+      break;
+    }
+    if (!polygonContainsPolygon(tightened, originalRing)) {
+      break;
+    }
+
+    const nextDeviation = directedBoundaryDeviation(tightened, originalRing);
+    if (nextDeviation > currentDeviation + 1e-12) {
+      break;
+    }
+
+    const nextKey = canonicalRingKey(tightened);
+    current = tightened;
+    currentDeviation = nextDeviation;
+    if (nextKey === prevKey) {
+      break;
+    }
+    prevKey = nextKey;
+  }
+
+  return current;
+}
+
+function tightenConvexRingParallelSupportOnce(ring, originalRing) {
+  const m = ring.length;
+  if (m < 3) {
+    return null;
+  }
+
+  const lines = [];
+  for (let i = 0; i < m; i += 1) {
+    const a = ring[i];
+    const b = ring[(i + 1) % m];
+    const edge = sub(b, a);
+    if (lengthSquared(edge) <= EPS) {
+      return null;
+    }
+
+    const normal = normalize(perpLeft(edge));
+    let support = Infinity;
+    for (let k = 0; k < originalRing.length; k += 1) {
+      support = Math.min(support, dot(normal, originalRing[k]));
+    }
+    lines.push({ normal, support });
+  }
+
+  const out = [];
+  for (let i = 0; i < m; i += 1) {
+    const prev = lines[mod(i - 1, m)];
+    const curr = lines[i];
+    const v = intersectNormalLines(prev.normal, prev.support, curr.normal, curr.support);
+    if (!v) {
+      return null;
+    }
+    out.push(v);
+  }
+
+  const normalized = removeConsecutiveDuplicates(out);
+  if (normalized.length !== m) {
+    return null;
+  }
+  if (signedArea(normalized) < 0) {
+    normalized.reverse();
+  }
+  return normalized;
+}
+
+function intersectNormalLines(n1, c1, n2, c2) {
+  const det = n1[0] * n2[1] - n1[1] * n2[0];
+  if (Math.abs(det) <= EPS) {
+    return null;
+  }
+  const x = (c1 * n2[1] - n1[1] * c2) / det;
+  const y = (n1[0] * c2 - c1 * n2[0]) / det;
+  return [x, y];
+}
+
+function findBestConvexRemoval(currentRing, originalRing) {
+  let best = null;
+
+  for (let i = 0; i < currentRing.length; i += 1) {
+    const candidate = makeConvexRemovalCandidate(currentRing, i);
+    if (!candidate) {
+      continue;
+    }
+    if (!isSimplePolygon(candidate)) {
+      continue;
+    }
+    if (!isConvexCCW(candidate)) {
+      continue;
+    }
+    if (!polygonContainsPolygon(candidate, originalRing)) {
+      continue;
+    }
+
+    const deviation = directedBoundaryDeviation(candidate, originalRing);
+    if (!best || deviation < best.deviation - EPS || (almostEqual(deviation, best.deviation) && i < best.index)) {
+      best = { ring: candidate, deviation, index: i };
+    }
+  }
+
+  return best;
+}
+
+function makeConvexRemovalCandidate(ring, i) {
+  const m = ring.length;
+  if (m < 4) {
+    return null;
+  }
+
+  const im2 = mod(i - 2, m);
+  const im1 = mod(i - 1, m);
+  const ip1 = mod(i + 1, m);
+  const ip2 = mod(i + 2, m);
+
+  const a = ring[im1];
+  const b = ring[i];
+  const c = ring[ip1];
+  const chord = sub(c, a);
+  if (lengthSquared(chord) <= EPS) {
+    return null;
+  }
+
+  let normal = normalize(perpLeft(chord));
+  let c0 = dot(normal, a);
+  if (dot(normal, b) <= c0 + EPS) {
+    normal = [-normal[0], -normal[1]];
+    c0 = dot(normal, a);
+  }
+
+  // Tightest support line for this normal that still contains current polygon.
+  let support = -Infinity;
+  for (let k = 0; k < m; k += 1) {
+    support = Math.max(support, dot(normal, ring[k]));
+  }
+
+  const prevLine = lineThrough(ring[im2], ring[im1]);
+  const nextLine = lineThrough(ring[ip1], ring[ip2]);
+  const u = intersectGeneralAndNormalLine(prevLine, normal, support);
+  const w = intersectGeneralAndNormalLine(nextLine, normal, support);
+  if (!u || !w || distanceSquared(u, w) <= EPS) {
+    return null;
+  }
+
+  const candidate = [];
+  for (let j = 0; j < m; j += 1) {
+    if (j === i) {
+      continue;
+    }
+    if (j === im1) {
+      candidate.push(u);
+      continue;
+    }
+    if (j === ip1) {
+      candidate.push(w);
+      continue;
+    }
+    candidate.push([ring[j][0], ring[j][1]]);
+  }
+
+  const normalized = removeConsecutiveDuplicates(candidate);
+  if (normalized.length !== m - 1) {
+    return null;
+  }
+  if (signedArea(normalized) < 0) {
+    normalized.reverse();
+  }
+  return normalized;
+}
+
+function addVerticesWithoutChangingBoundary(ring, targetVertexCount) {
+  const out = cloneRing(ring);
+  while (out.length < targetVertexCount) {
+    let bestEdge = -1;
+    let bestLen2 = -1;
+    for (let i = 0; i < out.length; i += 1) {
+      const j = (i + 1) % out.length;
+      const len2 = distanceSquared(out[i], out[j]);
+      if (len2 > bestLen2 + EPS || (almostEqual(len2, bestLen2) && i < bestEdge)) {
+        bestLen2 = len2;
+        bestEdge = i;
+      }
+    }
+    if (bestEdge === -1 || bestLen2 <= EPS) {
+      throw createOuterApproximationError("DEGENERATE_EDGE_INSERTION", "Cannot insert more vertices: all edges are degenerate.");
+    }
+    const j = (bestEdge + 1) % out.length;
+    const mid = midpoint(out[bestEdge], out[j]);
+    out.splice(j, 0, mid);
+  }
+  return out;
+}
+
+function removeVertex(ring, idx) {
+  const out = [];
+  for (let i = 0; i < ring.length; i += 1) {
+    if (i !== idx) {
+      out.push([ring[i][0], ring[i][1]]);
+    }
+  }
+  return removeConsecutiveDuplicates(out);
+}
+
+function directedBoundaryDeviation(candidateRing, originalRing) {
+  const samplePoints = [];
+
+  for (let i = 0; i < candidateRing.length; i += 1) {
+    samplePoints.push(candidateRing[i]);
+  }
+
+  for (let i = 0; i < candidateRing.length; i += 1) {
+    const a = candidateRing[i];
+    const b = candidateRing[(i + 1) % candidateRing.length];
+    samplePoints.push(midpoint(a, b));
+
+    for (let k = 0; k < originalRing.length; k += 1) {
+      const v = originalRing[k];
+      const t = projectionParameterOnSegment(v, a, b);
+      if (t > EPS && t < 1 - EPS) {
+        samplePoints.push(interpolate(a, b, t));
+      }
+    }
+  }
+
+  let maxDistance = 0;
+  for (let i = 0; i < samplePoints.length; i += 1) {
+    const d = distancePointToPolyline(samplePoints[i], originalRing);
+    if (d > maxDistance) {
+      maxDistance = d;
+    }
+  }
+
+  return maxDistance;
+}
+
+function polygonContainsPolygon(containerRing, containeeRing) {
+  for (let i = 0; i < containeeRing.length; i += 1) {
+    if (!pointInPolygonOrOnBoundary(containeeRing[i], containerRing)) {
+      return false;
+    }
+  }
+
+  for (let i = 0; i < containeeRing.length; i += 1) {
+    const a1 = containeeRing[i];
+    const a2 = containeeRing[(i + 1) % containeeRing.length];
+    for (let j = 0; j < containerRing.length; j += 1) {
+      const b1 = containerRing[j];
+      const b2 = containerRing[(j + 1) % containerRing.length];
+      if (properSegmentIntersection(a1, a2, b1, b2)) {
+        return false;
+      }
+    }
+  }
+
+  return true;
+}
+
+function pointInPolygonOrOnBoundary(point, ring) {
+  for (let i = 0; i < ring.length; i += 1) {
+    const a = ring[i];
+    const b = ring[(i + 1) % ring.length];
+    if (pointOnSegment(point, a, b)) {
+      return true;
+    }
+  }
+
+  // Ray casting (x direction).
+  let inside = false;
+  const x = point[0];
+  const y = point[1];
+  for (let i = 0, j = ring.length - 1; i < ring.length; j = i, i += 1) {
+    const xi = ring[i][0];
+    const yi = ring[i][1];
+    const xj = ring[j][0];
+    const yj = ring[j][1];
+
+    const intersects = (yi > y) !== (yj > y) && x < ((xj - xi) * (y - yi)) / (yj - yi) + xi;
+    if (intersects) {
+      inside = !inside;
+    }
+  }
+  return inside;
+}
+
+function isSimplePolygon(ring) {
+  const n = ring.length;
+  if (n < 3) {
+    return false;
+  }
+  for (let i = 0; i < n; i += 1) {
+    const a1 = ring[i];
+    const a2 = ring[(i + 1) % n];
+    for (let j = i + 1; j < n; j += 1) {
+      const b1 = ring[j];
+      const b2 = ring[(j + 1) % n];
+
+      if (i === j) {
+        continue;
+      }
+      if ((i + 1) % n === j || i === (j + 1) % n) {
+        continue; // adjacent edges share one endpoint
+      }
+      if (segmentsIntersectInclusive(a1, a2, b1, b2)) {
+        return false;
+      }
+    }
+  }
+  return true;
+}
+
+function isConvexCCW(ring) {
+  if (ring.length < 3) {
+    return false;
+  }
+  if (signedArea(ring) <= EPS) {
+    return false;
+  }
+  let sawPositive = false;
+  for (let i = 0; i < ring.length; i += 1) {
+    const a = ring[i];
+    const b = ring[(i + 1) % ring.length];
+    const c = ring[(i + 2) % ring.length];
+    const z = cross(sub(b, a), sub(c, b));
+    if (z < -EPS) {
+      return false;
+    }
+    if (z > EPS) {
+      sawPositive = true;
+    }
+  }
+  return sawPositive;
+}
+
+function convexHull(points) {
+  const unique = uniquePoints(points);
+  if (unique.length <= 1) {
+    return unique;
+  }
+  unique.sort((p, q) => (p[0] === q[0] ? p[1] - q[1] : p[0] - q[0]));
+
+  const lower = [];
+  for (let i = 0; i < unique.length; i += 1) {
+    while (lower.length >= 2) {
+      const p1 = lower[lower.length - 2];
+      const p2 = lower[lower.length - 1];
+      const p3 = unique[i];
+      if (cross(sub(p2, p1), sub(p3, p2)) <= EPS) {
+        lower.pop();
+      } else {
+        break;
+      }
+    }
+    lower.push(unique[i]);
+  }
+
+  const upper = [];
+  for (let i = unique.length - 1; i >= 0; i -= 1) {
+    while (upper.length >= 2) {
+      const p1 = upper[upper.length - 2];
+      const p2 = upper[upper.length - 1];
+      const p3 = unique[i];
+      if (cross(sub(p2, p1), sub(p3, p2)) <= EPS) {
+        upper.pop();
+      } else {
+        break;
+      }
+    }
+    upper.push(unique[i]);
+  }
+
+  lower.pop();
+  upper.pop();
+  return lower.concat(upper);
+}
+
+function distancePointToPolyline(point, ring) {
+  let best = Infinity;
+  for (let i = 0; i < ring.length; i += 1) {
+    const a = ring[i];
+    const b = ring[(i + 1) % ring.length];
+    const d = distancePointToSegment(point, a, b);
+    if (d < best) {
+      best = d;
+    }
+  }
+  return best;
+}
+
+function distancePointToSegment(p, a, b) {
+  const t = projectionParameterOnSegment(p, a, b);
+  const q = interpolate(a, b, t);
+  return Math.sqrt(distanceSquared(p, q));
+}
+
+function projectionParameterOnSegment(p, a, b) {
+  const ab = sub(b, a);
+  const denom = dot(ab, ab);
+  if (denom <= EPS) {
+    return 0;
+  }
+  const t = dot(sub(p, a), ab) / denom;
+  if (t <= 0) {
+    return 0;
+  }
+  if (t >= 1) {
+    return 1;
+  }
+  return t;
+}
+
+function properSegmentIntersection(a, b, c, d) {
+  const o1 = orient(a, b, c);
+  const o2 = orient(a, b, d);
+  const o3 = orient(c, d, a);
+  const o4 = orient(c, d, b);
+
+  return o1 * o2 < -EPS && o3 * o4 < -EPS;
+}
+
+function segmentsIntersectInclusive(a, b, c, d) {
+  const o1 = orient(a, b, c);
+  const o2 = orient(a, b, d);
+  const o3 = orient(c, d, a);
+  const o4 = orient(c, d, b);
+
+  if (o1 * o2 < -EPS && o3 * o4 < -EPS) {
+    return true;
+  }
+  if (Math.abs(o1) <= EPS && pointOnSegment(c, a, b)) {
+    return true;
+  }
+  if (Math.abs(o2) <= EPS && pointOnSegment(d, a, b)) {
+    return true;
+  }
+  if (Math.abs(o3) <= EPS && pointOnSegment(a, c, d)) {
+    return true;
+  }
+  if (Math.abs(o4) <= EPS && pointOnSegment(b, c, d)) {
+    return true;
+  }
+  return false;
+}
+
+function pointOnSegment(p, a, b) {
+  if (Math.abs(orient(a, b, p)) > EPS) {
+    return false;
+  }
+  const minX = Math.min(a[0], b[0]) - EPS;
+  const maxX = Math.max(a[0], b[0]) + EPS;
+  const minY = Math.min(a[1], b[1]) - EPS;
+  const maxY = Math.max(a[1], b[1]) + EPS;
+  return p[0] >= minX && p[0] <= maxX && p[1] >= minY && p[1] <= maxY;
+}
+
+function lineThrough(p, q) {
+  // Ax + By = C
+  const A = q[1] - p[1];
+  const B = p[0] - q[0];
+  const C = A * p[0] + B * p[1];
+  return { A, B, C };
+}
+
+function intersectGeneralAndNormalLine(line, normal, constant) {
+  const A1 = line.A;
+  const B1 = line.B;
+  const C1 = line.C;
+  const A2 = normal[0];
+  const B2 = normal[1];
+  const C2 = constant;
+
+  const det = A1 * B2 - B1 * A2;
+  if (Math.abs(det) <= EPS) {
+    return null;
+  }
+  const x = (C1 * B2 - B1 * C2) / det;
+  const y = (A1 * C2 - C1 * A2) / det;
+  return [x, y];
+}
+
+function signedArea(ring) {
+  let area2 = 0;
+  for (let i = 0; i < ring.length; i += 1) {
+    const p = ring[i];
+    const q = ring[(i + 1) % ring.length];
+    area2 += p[0] * q[1] - q[0] * p[1];
+  }
+  return area2 / 2;
+}
+
+function uniquePoints(points) {
+  const out = [];
+  for (let i = 0; i < points.length; i += 1) {
+    let seen = false;
+    for (let j = 0; j < out.length; j += 1) {
+      if (samePoint(points[i], out[j])) {
+        seen = true;
+        break;
+      }
+    }
+    if (!seen) {
+      out.push([points[i][0], points[i][1]]);
+    }
+  }
+  return out;
+}
+
+function removeConsecutiveDuplicates(ring) {
+  const out = [];
+  for (let i = 0; i < ring.length; i += 1) {
+    if (out.length === 0 || !samePoint(out[out.length - 1], ring[i])) {
+      out.push([ring[i][0], ring[i][1]]);
+    }
+  }
+  if (out.length > 1 && samePoint(out[0], out[out.length - 1])) {
+    out.pop();
+  }
+  return out;
+}
+
+function cloneRing(ring) {
+  return ring.map((p) => [p[0], p[1]]);
+}
+
+function samePoint(a, b) {
+  return Math.abs(a[0] - b[0]) <= EPS && Math.abs(a[1] - b[1]) <= EPS;
+}
+
+function midpoint(a, b) {
+  return [(a[0] + b[0]) / 2, (a[1] + b[1]) / 2];
+}
+
+function interpolate(a, b, t) {
+  return [a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t];
+}
+
+function orient(a, b, c) {
+  return cross(sub(b, a), sub(c, a));
+}
+
+function sub(a, b) {
+  return [a[0] - b[0], a[1] - b[1]];
+}
+
+function dot(a, b) {
+  return a[0] * b[0] + a[1] * b[1];
+}
+
+function cross(a, b) {
+  return a[0] * b[1] - a[1] * b[0];
+}
+
+function perpLeft(v) {
+  return [-v[1], v[0]];
+}
+
+function normalize(v) {
+  const len = Math.sqrt(dot(v, v));
+  if (len <= EPS) {
+    return [0, 0];
+  }
+  return [v[0] / len, v[1] / len];
+}
+
+function distanceSquared(a, b) {
+  const dx = a[0] - b[0];
+  const dy = a[1] - b[1];
+  return dx * dx + dy * dy;
+}
+
+function lengthSquared(v) {
+  return dot(v, v);
+}
+
+function almostEqual(a, b) {
+  return Math.abs(a - b) <= EPS;
+}
+
+function mod(x, m) {
+  return ((x % m) + m) % m;
+}
+
+module.exports = {
+  outerApproximatePolygon,
+  OuterApproximationError,
+  OUTER_APPROXIMATION_ERROR_CODES,
+};
+
+
+
+
+
+
+
+
+
+
+
+
+
+

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "poly-prune",
+  "version": "1.0.0",
+  "description": "Deterministic GeoJSON outer-approximation with exact vertex target and strict deviation cap.",
+  "license": "MIT",
+  "packageManager": "npm@6.13.4",
+  "type": "commonjs",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "require": "./index.js",
+      "default": "./index.js"
+    }
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "outerApproximatePolygon.js",
+    "outerApproximatePolygon.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "geojson",
+    "polygon",
+    "geometry",
+    "simplification",
+    "hull",
+    "map"
+  ],
+  "scripts": {
+    "test": "node tests/outerApproximatePolygon.test.js",
+    "pack:check": "npm pack --dry-run",
+    "prepublishOnly": "npm test"
+  },
+  "engines": {
+    "node": ">=12"
+  }
+}