@embedpdf/plugin-measurement 3.0.0-next.14 → 3.0.0-next.16

package/README.md

@@ -1,59 +1,73 @@
 # @embedpdf/plugin-measurement
 
-Document-scoped page calibration, distance authoring, and measurement readouts.
+Document-scoped page calibration, measurement authoring, and measurement readouts.
 Install alongside `annotationPlugin()` and `interactionPlugin()`:
 
 ```ts
-import {
-  measurementPlugin,
-  MeasurementToken,
-} from '@embedpdf/plugin-measurement';
+import { measurementPlugin, MeasurementToken } from '@embedpdf/plugin-measurement';
 
 const plugins = [
-  /* interaction, annotation, ... */ measurementPlugin({
-    defaultScale: 'metric',
-  }),
+  /* interaction, annotation, ... */
+  measurementPlugin({ defaultScale: 'metric' }),
 ];
+
 const measurements = viewer.get(MeasurementToken);
-await measurements.calibrate(pageObjectNumber, fromPdfPoint, toPdfPoint, {
-  value: 5,
-  unit: 'm',
-});
+await measurements.calibrate({ page, from, to, distance: { value: 5, unit: 'm' } });
 ```
 
-`calibrate` points are original PDF user space: y-up, including the page's CropBox
-origin. The line's length is rounded through the engine's float32 coordinate
-rules. `UserUnit` participates in ratio presets; a calibration from a known
-length already expresses the full conversion.
-
-The annotation plugin supplies the `distance` and `calibrate` tools. Distance
-captures the last viewport containing its **first point**. A foreign or invalid
-winning viewport prevents creation; a default is used only outside all viewports.
-Until viewport reads finish, distance creation is unavailable.
-
-`setPageScale`, `setPreset`, `setUnit`, `setPrecision`, and `calibrate` accept
-`{ recalculate?: boolean, allPages?: boolean }`. Recalculation defaults to true.
-Every annotation stores its own scale snapshot. Setting `recalculate: false`
-changes subsequent measurements while preserving existing values.
-
-Recalculation reports list updated, skipped, and failed annotations. A page-wide
-annotation read failure appears as `error`. A single-page viewport write failure
-rejects before annotation writes; all-pages operations return per-page
-`scaleError` results and finish the remaining pages. Page scales persist in the
-PDF when the engine provides `page.measure`; older engines retain them for the
-session (`pageScale().persistent === false`).
-
-`canCalibrate()` mirrors `doc.annotate.modify`; `canMeasure(pon)` combines
+`calibrate` points are page space, like the `CalibrationRequest` the calibrate
+tool produces; the plugin converts them to PDF user space, and the line's length
+is rounded through the engine's float32 coordinate rules. `UserUnit` participates
+in ratio presets; a calibration from a known length already expresses the full
+conversion.
+
+The annotation plugin supplies the `distance`, `perimeter`, `area`, and
+`calibrate` tools. A measurement captures the last viewport containing its
+**first point**. A foreign or invalid winning viewport prevents creation; the
+default scale is used only outside all viewports. Until the page's viewport reads
+finish, measurement creation is unavailable.
+`createMeasurement({ kind, page, points })` creates the same annotations from
+code, resolves `{ annotation }`, and rejects with `not-ready` before the page's
+scale is known. A page is a ref or an index everywhere.
+`startCalibration()` arms the calibrate tool, and throws `permission-denied`
+without `doc.annotate.modify`; its two points arrive as
+`onCalibrationRequested` (and `getCalibrationRequest()`) awaiting the real
+length, and `dismissCalibration()` drops the request.
+
+`setScale`, `setPreset`, `setUnit`, `setAreaUnit`, `setPrecision`, and
+`clearScale` take a page target — one page, an array of pages, or `'all'` — and
+`{ recalculate?: boolean }`. `calibrate` writes its input page unless `applyTo`
+names a wider target. Recalculation defaults to true. Every annotation stores its
+own scale snapshot. Setting `recalculate: false` changes subsequent measurements
+while preserving existing values.
+
+Each scale change resolves to one report per page listing updated, skipped, and
+failed annotations; `listLastReports()` keeps the last set and `onScaleChanged`
+fires per page. A page-wide annotation read failure appears as `error`. A
+single-page viewport write failure rejects before annotation writes; multi-page
+operations (several pages or `'all'`) return per-page `scaleError` results and
+finish the remaining pages. Page scales persist in the PDF when the engine
+provides `page.measure`; without it they last for the session
+(`getPageScale(page).persistent === false`).
+
+`canCalibrate()` mirrors `doc.annotate.modify`; `canMeasure(page)` combines
 annotation creation authority and viewport readiness. Per-record permissions and
-PDF flags gate recalculation and caption dragging. Distance contents are derived
-and cannot be edited as comment text.
+PDF flags gate recalculation and caption dragging. Measurement contents are
+derived and cannot be edited as comment text. `getReadout(ref)` formats a
+measurement annotation; `measureDistance` and `measureArea` convert page-space
+points in the page's scale without creating anything.
+
+The settings, `defaultScale` and `presets`, change while the app runs:
+`updateSettings()`, `resetSettings()` and `onSettingsChanged`, shared by every
+document.
 
-React consumers import `measurementPlugin`, `useMeasurement`, `usePageScale`, and
-`useMeasurementReadout` from `@embedpdf/react/measurement`. The full viewer includes
-a Measure toolbar, scale sidebar, and known-length calibration dialog.
+React consumers import `measurementPlugin`, `useMeasurement` (the capability),
+`useMeasurementState` (`busy`, `calibrationRequest`, `lastReports`),
+`useMeasurementSettings`, `usePageScale`, `useMeasurementReadout` and
+`useMeasurementEvent` from `@embedpdf/react/measurement`. The full viewer includes a Measure toolbar
+(distance, perimeter, area, calibrate), a scale sidebar, and a known-length
+calibration dialog.
 
 Distance captions use standard PDF line-axis offsets. Their live layout uses an
 estimated Helvetica advance; committed annotations render the native PDF
-appearance. Perimeter and area authoring tools are not included in this package's
-initial viewer increment; readouts and page recalculation support their existing
-engine annotations.
+appearance.

package/dist/contract-BGn30CU9.d.cts

@@ -0,0 +1,185 @@
+import { EventHook, OperationOptions, SettingsApi } from "@embedpdf/core";
+import { Point } from "@embedpdf/core-geometry";
+import { Annotation, AnnotationRef, AnnotationRef as AnnotationRef$1, AreaUnit, AreaUnit as AreaUnit$1, LengthUnit, LengthUnit as LengthUnit$1, MeasurementReadout, MeasurementReadout as MeasurementReadout$1, MeasurementUnavailable, MeasurementUnavailable as MeasurementUnavailable$1, PageRef, PdfMeasure, PdfMeasure as PdfMeasure$1, PdfMeasurement, SerializedEngineError } from "@embedpdf/engine-core/runtime";
+import { RecalibrationReport, RecalibrationReport as RecalibrationReport$1 } from "@embedpdf/plugin-annotation/contract/host";
+//#region src/token.d.ts
+declare const MeasurementToken: import("@embedpdf/core").CapabilityToken<MeasurementCapability>;
+//#endregion
+//#region src/contract.d.ts
+/** One page, several pages, or every page of the document: each a ref or an index. */
+type PageTarget = PageRef | number | readonly (PageRef | number)[] | 'all';
+interface ScalePreset {
+  id: string;
+  label: string;
+  paper: number;
+  real: number;
+  unit: LengthUnit;
+}
+/**
+ * The measurement plugin's settings. `measurementPlugin(config)` registers
+ * them over {@link MEASUREMENT_DEFAULTS}, and `updateSettings()` changes them
+ * for every document while the app runs.
+ */
+interface MeasurementSettings {
+  /**
+   * The scale of a page that has none: 1:1 in meters (`'metric'`) or in
+   * feet (`'imperial'`), or a scale of your own.
+   */
+  readonly defaultScale: 'metric' | 'imperial' | PdfMeasure;
+  /** The scales `listPresets()` offers. */
+  readonly presets: readonly ScalePreset[];
+}
+/** What the measurement settings are when the app registers none. */
+declare const MEASUREMENT_DEFAULTS: MeasurementSettings;
+/** What `measurementPlugin(config)` takes: either setting, each a whole value. */
+type MeasurementConfig = Partial<MeasurementSettings>;
+interface ScaleChangeOptions extends OperationOptions {
+  /** Re-measure the page's measurement annotations with the new scale. Default true. */
+  recalculate?: boolean;
+}
+interface PageScale {
+  measure: PdfMeasurement | null;
+  source: 'owned' | 'foreign' | 'default';
+  /** The page's viewports are known. */
+  ready: boolean;
+  /** The engine can persist a scale into the document. */
+  persistent: boolean;
+  /** Why the last read of the page's viewports failed; the last known viewports stay in effect. */
+  error?: SerializedEngineError;
+}
+/**
+ * A page's scale where there is none to read: before a document opens, or for
+ * a page that isn't there. Not ready, with no measure; the same object every
+ * time, so a framework read compares it by identity.
+ */
+declare const NO_PAGE_SCALE: PageScale;
+/**
+ * The readout where there is no measurement to read: before a document
+ * opens, or for an annotation that isn't there. `getReadout` answers it too.
+ */
+declare const NO_READOUT: MeasurementUnavailable;
+/** Two points captured by the calibrate tool, awaiting the real length. Page space. */
+interface CalibrationRequest {
+  page: PageRef;
+  from: Point;
+  to: Point;
+  /** The captured length in PDF user space (the scale is derived from it). */
+  userSpaceLength: number;
+}
+interface CalibrateInput {
+  /** The page, as a ref or an index. */
+  page: PageRef | number;
+  /** The two ends of the known length, in page space. */
+  from: Point;
+  to: Point;
+  /** The real-world length between the two points. */
+  distance: {
+    value: number;
+    unit: LengthUnit;
+  };
+}
+/** A failed viewport write is reported per page for a multi-page change.
+ *  Single-page failures reject before any annotation write. */
+type ScaleChangeReport = (RecalibrationReport & {
+  scaleError?: never;
+}) | {
+  page: PageRef;
+  scale?: never;
+  error?: never;
+  updated: [];
+  skipped: [];
+  failed: [];
+  scaleError: SerializedEngineError;
+};
+type MeasurementKind = 'distance' | 'perimeter' | 'area';
+interface CreateMeasurementInput {
+  kind: MeasurementKind;
+  /** The page, as a ref or an index. */
+  page: PageRef | number;
+  /** Page-space points: two for a distance, the vertices otherwise. */
+  points: readonly Point[];
+  /** The authoring tool whose defaults apply (defaults to the kind's own tool). */
+  tool?: string;
+}
+interface MeasurementScaleChangedEvent {
+  readonly page: PageRef;
+  readonly report: ScaleChangeReport;
+}
+interface CalibrationRequestedEvent {
+  readonly request: CalibrationRequest;
+}
+interface CalibrationCompletedEvent {
+  readonly page: PageRef;
+}
+type CalibrationDismissedEvent = Record<string, never>;
+/**
+ * Page scales, calibration and measurement readouts for one document. A page
+ * argument is a ref or an index: a read given a page that isn't there
+ * answers empty, a verb refuses it with `not-found`. Every async verb takes
+ * a `signal`. The settings belong to the plugin, not to a document: a change
+ * reaches every open document.
+ */
+interface MeasurementCapability extends SettingsApi<MeasurementSettings> {
+  /** May write a page scale and calibrate (`doc.annotate.modify`). */
+  canCalibrate(): boolean;
+  /** May measure on the page: `annotations:create`, and the page's scale has loaded. */
+  canMeasure(page: PageRef | number): boolean;
+  /** The resolved scale, its source and readiness. Reference-stable while unchanged. */
+  getPageScale(page: PageRef | number): PageScale;
+  /** Load the page's viewports. Resolves at once when already known. Rejects `not-found`. */
+  ensureLoaded(page: PageRef | number, options?: OperationOptions): Promise<void>;
+  /** A scale change is in flight. */
+  isBusy(): boolean;
+  /** The reports of the last scale change, one per page. */
+  listLastReports(): readonly ScaleChangeReport[];
+  listPresets(): readonly ScalePreset[];
+  listUnits(): readonly LengthUnit[];
+  listAreaUnits(): readonly AreaUnit[];
+  /**
+   * The formatted measurement of a measurement annotation, or why there is
+   * none ({@link NO_READOUT} for an annotation that isn't there). The same
+   * object until the annotation changes.
+   */
+  getReadout(ref: AnnotationRef): MeasurementReadout | MeasurementUnavailable;
+  /** A distance between two page-space points in the page's scale: a pure conversion, no annotation. */
+  measureDistance(page: PageRef | number, from: Point, to: Point): MeasurementReadout | MeasurementUnavailable;
+  /** The area of a page-space polygon in the page's scale: a pure conversion, no annotation. */
+  measureArea(page: PageRef | number, vertices: readonly Point[]): MeasurementReadout | MeasurementUnavailable;
+  /** Two points captured, awaiting a length. */
+  getCalibrationRequest(): CalibrationRequest | null;
+  setScale(pages: PageTarget, measure: PdfMeasure, options?: ScaleChangeOptions): Promise<readonly ScaleChangeReport[]>;
+  /** Derive a scale from a known length between two page points. `applyTo` widens the write (default: the input page). Fires `onCalibrationCompleted`. */
+  calibrate(input: CalibrateInput, options?: ScaleChangeOptions & {
+    applyTo?: PageTarget;
+  }): Promise<readonly ScaleChangeReport[]>;
+  setUnit(pages: PageTarget, unit: LengthUnit, options?: ScaleChangeOptions): Promise<readonly ScaleChangeReport[]>;
+  setAreaUnit(pages: PageTarget, unit: AreaUnit, options?: ScaleChangeOptions): Promise<readonly ScaleChangeReport[]>;
+  setPrecision(pages: PageTarget, precision: number, options?: ScaleChangeOptions): Promise<readonly ScaleChangeReport[]>;
+  /** A scale from the `presets` setting. Rejects `not-found` for an unknown preset. */
+  setPreset(pages: PageTarget, presetId: string, options?: ScaleChangeOptions): Promise<readonly ScaleChangeReport[]>;
+  /** Back to the default scale (the owned viewport is removed). */
+  clearScale(pages: PageTarget, options?: ScaleChangeOptions): Promise<readonly ScaleChangeReport[]>;
+  /**
+   * Create a measurement annotation with the page's scale and the tool's
+   * style. Resolves `{ annotation }`. Rejects `permission-denied` without
+   * `annotations:create`, `not-ready` before the scale is known,
+   * `not-found` for a page that isn't in the document.
+   */
+  createMeasurement(input: CreateMeasurementInput, options?: OperationOptions): Promise<{
+    annotation: Annotation;
+  }>;
+  /**
+   * Arm the calibrate tool (two points, then `onCalibrationRequested`).
+   * Throws `permission-denied` without `doc.annotate.modify` (see `canCalibrate`).
+   */
+  startCalibration(): void;
+  /** Drop the pending request. Fires `onCalibrationDismissed` when there was one. */
+  dismissCalibration(): void;
+  readonly onScaleChanged: EventHook<MeasurementScaleChangedEvent>;
+  readonly onCalibrationRequested: EventHook<CalibrationRequestedEvent>;
+  readonly onCalibrationCompleted: EventHook<CalibrationCompletedEvent>;
+  readonly onCalibrationDismissed: EventHook<CalibrationDismissedEvent>;
+}
+//#endregion
+export { RecalibrationReport$1 as C, MeasurementToken as D, ScalePreset as E, PdfMeasure$1 as S, ScaleChangeReport as T, MeasurementUnavailable$1 as _, CalibrationDismissedEvent as a, PageScale as b, CreateMeasurementInput as c, MeasurementCapability as d, MeasurementConfig as f, MeasurementSettings as g, MeasurementScaleChangedEvent as h, CalibrationCompletedEvent as i, LengthUnit$1 as l, MeasurementReadout$1 as m, AreaUnit$1 as n, CalibrationRequest as o, MeasurementKind as p, CalibrateInput as r, CalibrationRequestedEvent as s, AnnotationRef$1 as t, MEASUREMENT_DEFAULTS as u, NO_PAGE_SCALE as v, ScaleChangeOptions as w, PageTarget as x, NO_READOUT as y };
+//# sourceMappingURL=contract-BGn30CU9.d.cts.map

package/dist/contract-BHj3w9WF.cjs

@@ -0,0 +1,178 @@
+let _embedpdf_core = require("@embedpdf/core");
+let _embedpdf_engine_core_runtime = require("@embedpdf/engine-core/runtime");
+//#region src/scale.ts
+/** Scale arithmetic: the default presets and scale, and unit and precision edits of a scale. */
+/** The scales offered when the app registers none: metric 1:1 to 1:200, and two imperial ones. */
+const DEFAULT_PRESETS = [
+	...[
+		1,
+		10,
+		20,
+		50,
+		100,
+		200
+	].map((real) => ({
+		id: `metric-${real}`,
+		label: `1:${real}`,
+		paper: 1,
+		real,
+		unit: "m"
+	})),
+	{
+		id: "imperial-quarter",
+		label: "1/4 in = 1 ft",
+		paper: 1,
+		real: 48,
+		unit: "ft"
+	},
+	{
+		id: "imperial-eighth",
+		label: "1/8 in = 1 ft",
+		paper: 1,
+		real: 96,
+		unit: "ft"
+	}
+];
+/** The scale of a page that has none, from the `defaultScale` setting. */
+const defaultMeasure = (defaultScale, userUnit = 1) => typeof defaultScale === "object" ? defaultScale : (0, _embedpdf_engine_core_runtime.measureFromRatio)(1, 1, defaultScale === "imperial" ? "ft" : "m", { userUnit });
+function withUnit(measure, unit, area = (0, _embedpdf_engine_core_runtime.squareOf)(unit)) {
+	const basis = measure.x[0]?.unit.trim();
+	if (!(basis in _embedpdf_engine_core_runtime.METRES)) throw new RangeError("This scale has an unknown base unit; calibrate it first");
+	const previous = measure.distance[measure.distance.length - 1];
+	const precision = previous?.fraction === "fraction" ? 100 : previous?.precision ?? 100;
+	return {
+		...measure,
+		distance: [{
+			unit,
+			conversion: _embedpdf_engine_core_runtime.METRES[basis] / _embedpdf_engine_core_runtime.METRES[unit],
+			precision,
+			fraction: "decimal"
+		}],
+		area: [{
+			unit: (0, _embedpdf_engine_core_runtime.areaUnitLabel)(area),
+			conversion: _embedpdf_engine_core_runtime.METRES[basis] ** 2 / (0, _embedpdf_engine_core_runtime.squareMetres)(area),
+			precision,
+			fraction: "decimal"
+		}]
+	};
+}
+function withPrecision(measure, precision) {
+	if (!Number.isInteger(Math.log10(precision)) || precision < 1 || precision > 1e9) throw new RangeError("Invalid decimal precision");
+	const update = (formats) => formats.map((format, index) => index === formats.length - 1 ? {
+		...format,
+		precision,
+		fraction: "decimal"
+	} : format);
+	return {
+		...measure,
+		distance: update(measure.distance),
+		area: update(measure.area)
+	};
+}
+/** Change the area display unit while preserving imported distance formatting. */
+function withAreaUnit(measure, unit) {
+	const basis = measure.x[0]?.unit.trim();
+	if (!(basis in _embedpdf_engine_core_runtime.METRES)) throw new RangeError("This scale has an unknown base unit; calibrate it first");
+	const previous = measure.area[measure.area.length - 1];
+	const precision = previous?.fraction === "fraction" ? 100 : previous?.precision ?? 100;
+	return {
+		...measure,
+		area: [{
+			unit: (0, _embedpdf_engine_core_runtime.areaUnitLabel)(unit),
+			conversion: _embedpdf_engine_core_runtime.METRES[basis] ** 2 / (0, _embedpdf_engine_core_runtime.squareMetres)(unit),
+			precision,
+			fraction: "decimal"
+		}]
+	};
+}
+//#endregion
+//#region src/token.ts
+/** The package token, created once here and re-exported by `contract.ts`. */
+const MeasurementToken = (0, _embedpdf_core.createCapabilityToken)("measurement", {
+	hint: `add measurementPlugin() from '@embedpdf/plugin-measurement' to your plugins list`,
+	promises: {
+		ensureLoaded: true,
+		setScale: true,
+		calibrate: true,
+		setUnit: true,
+		setAreaUnit: true,
+		setPrecision: true,
+		setPreset: true,
+		clearScale: true,
+		createMeasurement: true
+	}
+});
+//#endregion
+//#region src/contract.ts
+/** What the measurement settings are when the app registers none. */
+const MEASUREMENT_DEFAULTS = {
+	defaultScale: "metric",
+	presets: DEFAULT_PRESETS
+};
+/**
+* A page's scale where there is none to read: before a document opens, or for
+* a page that isn't there. Not ready, with no measure; the same object every
+* time, so a framework read compares it by identity.
+*/
+const NO_PAGE_SCALE = Object.freeze({
+	measure: null,
+	source: "default",
+	ready: false,
+	persistent: false
+});
+/**
+* The readout where there is no measurement to read: before a document
+* opens, or for an annotation that isn't there. `getReadout` answers it too.
+*/
+const NO_READOUT = Object.freeze({ unavailable: "not-dimension" });
+//#endregion
+Object.defineProperty(exports, "MEASUREMENT_DEFAULTS", {
+	enumerable: true,
+	get: function() {
+		return MEASUREMENT_DEFAULTS;
+	}
+});
+Object.defineProperty(exports, "MeasurementToken", {
+	enumerable: true,
+	get: function() {
+		return MeasurementToken;
+	}
+});
+Object.defineProperty(exports, "NO_PAGE_SCALE", {
+	enumerable: true,
+	get: function() {
+		return NO_PAGE_SCALE;
+	}
+});
+Object.defineProperty(exports, "NO_READOUT", {
+	enumerable: true,
+	get: function() {
+		return NO_READOUT;
+	}
+});
+Object.defineProperty(exports, "defaultMeasure", {
+	enumerable: true,
+	get: function() {
+		return defaultMeasure;
+	}
+});
+Object.defineProperty(exports, "withAreaUnit", {
+	enumerable: true,
+	get: function() {
+		return withAreaUnit;
+	}
+});
+Object.defineProperty(exports, "withPrecision", {
+	enumerable: true,
+	get: function() {
+		return withPrecision;
+	}
+});
+Object.defineProperty(exports, "withUnit", {
+	enumerable: true,
+	get: function() {
+		return withUnit;
+	}
+});
+
+//# sourceMappingURL=contract-BHj3w9WF.cjs.map

package/dist/contract-BHj3w9WF.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-BHj3w9WF.cjs","names":["METRES"],"sources":["../src/scale.ts","../src/token.ts","../src/contract.ts"],"sourcesContent":["/** Scale arithmetic: the default presets and scale, and unit and precision edits of a scale. */\nimport {\n  areaUnitLabel,\n  measureFromRatio,\n  METRES,\n  squareMetres,\n  squareOf,\n} from '@embedpdf/engine-core/runtime';\nimport type { AreaUnit, LengthUnit, PdfMeasure } from '@embedpdf/engine-core/runtime';\n\nimport type { MeasurementSettings, ScalePreset } from './contract';\n\n/** The scales offered when the app registers none: metric 1:1 to 1:200, and two imperial ones. */\nexport const DEFAULT_PRESETS: readonly ScalePreset[] = [\n  ...[1, 10, 20, 50, 100, 200].map((real) => ({\n    id: `metric-${real}`,\n    label: `1:${real}`,\n    paper: 1,\n    real,\n    unit: 'm' as const,\n  })),\n  { id: 'imperial-quarter', label: '1/4 in = 1 ft', paper: 1, real: 48, unit: 'ft' },\n  { id: 'imperial-eighth', label: '1/8 in = 1 ft', paper: 1, real: 96, unit: 'ft' },\n];\n\n/** The scale of a page that has none, from the `defaultScale` setting. */\nexport const defaultMeasure = (\n  defaultScale: MeasurementSettings['defaultScale'],\n  userUnit = 1,\n): PdfMeasure =>\n  typeof defaultScale === 'object'\n    ? defaultScale\n    : measureFromRatio(1, 1, defaultScale === 'imperial' ? 'ft' : 'm', { userUnit });\n\nexport function withUnit(\n  measure: PdfMeasure,\n  unit: LengthUnit,\n  area: AreaUnit = squareOf(unit),\n): PdfMeasure {\n  const basis = measure.x[0]?.unit.trim() as LengthUnit;\n  if (!(basis in METRES)) {\n    throw new RangeError('This scale has an unknown base unit; calibrate it first');\n  }\n  const previous = measure.distance[measure.distance.length - 1];\n  const precision = previous?.fraction === 'fraction' ? 100 : (previous?.precision ?? 100);\n  return {\n    ...measure,\n    distance: [{ unit, conversion: METRES[basis] / METRES[unit], precision, fraction: 'decimal' }],\n    area: [\n      {\n        unit: areaUnitLabel(area),\n        conversion: METRES[basis] ** 2 / squareMetres(area),\n        precision,\n        fraction: 'decimal',\n      },\n    ],\n  };\n}\n\nexport function withPrecision(measure: PdfMeasure, precision: number): PdfMeasure {\n  if (!Number.isInteger(Math.log10(precision)) || precision < 1 || precision > 1e9) {\n    throw new RangeError('Invalid decimal precision');\n  }\n  const update = (formats: PdfMeasure['distance']) =>\n    formats.map((format, index) =>\n      index === formats.length - 1\n        ? { ...format, precision, fraction: 'decimal' as const }\n        : format,\n    );\n  return { ...measure, distance: update(measure.distance), area: update(measure.area) };\n}\n\n/** Change the area display unit while preserving imported distance formatting. */\nexport function withAreaUnit(measure: PdfMeasure, unit: AreaUnit): PdfMeasure {\n  const basis = measure.x[0]?.unit.trim() as LengthUnit;\n  if (!(basis in METRES)) {\n    throw new RangeError('This scale has an unknown base unit; calibrate it first');\n  }\n  const previous = measure.area[measure.area.length - 1];\n  const precision = previous?.fraction === 'fraction' ? 100 : (previous?.precision ?? 100);\n  return {\n    ...measure,\n    area: [\n      {\n        unit: areaUnitLabel(unit),\n        conversion: METRES[basis] ** 2 / squareMetres(unit),\n        precision,\n        fraction: 'decimal',\n      },\n    ],\n  };\n}\n","/** The package token, created once here and re-exported by `contract.ts`. */\nimport { createCapabilityToken } from '@embedpdf/core';\n\nimport type { MeasurementCapability } from './contract';\n\nexport const MeasurementToken = createCapabilityToken<MeasurementCapability>('measurement', {\n  hint: `add measurementPlugin() from '@embedpdf/plugin-measurement' to your plugins list`,\n  // Without a document, an adapter's stand-in rejects these with `not-ready`, as the\n  // capability would; the type asks for every member that returns a promise.\n  promises: {\n    ensureLoaded: true,\n    setScale: true,\n    calibrate: true,\n    setUnit: true,\n    setAreaUnit: true,\n    setPrecision: true,\n    setPreset: true,\n    clearScale: true,\n    createMeasurement: true,\n  },\n});\n","/**\n * @embedpdf/plugin-measurement/contract: the public measurement vocabulary:\n * page scale, calibration, scale-aware readouts, and measurement creation.\n * Creating a measurement annotation is `annotation.create` with a\n * measurement tool; this plugin adds the page-scale sugar around it.\n */\nimport type { EventHook, OperationOptions, SettingsApi } from '@embedpdf/core';\nimport type { Point } from '@embedpdf/core-geometry';\nimport type {\n  Annotation,\n  AnnotationRef,\n  AreaUnit,\n  LengthUnit,\n  MeasurementReadout,\n  MeasurementUnavailable,\n  PageRef,\n  PdfMeasure,\n  PdfMeasurement,\n  SerializedEngineError,\n} from '@embedpdf/engine-core/runtime';\nimport type { RecalibrationReport } from '@embedpdf/plugin-annotation/contract/host';\n\nimport { DEFAULT_PRESETS } from './scale';\n\nexport { MeasurementToken } from './token';\nexport type { RecalibrationReport } from '@embedpdf/plugin-annotation/contract/host';\nexport type {\n  AnnotationRef,\n  AreaUnit,\n  LengthUnit,\n  MeasurementReadout,\n  MeasurementUnavailable,\n  PdfMeasure,\n} from '@embedpdf/engine-core/runtime';\n\n/** One page, several pages, or every page of the document: each a ref or an index. */\nexport type PageTarget = PageRef | number | readonly (PageRef | number)[] | 'all';\n\nexport interface ScalePreset {\n  id: string;\n  label: string;\n  paper: number;\n  real: number;\n  unit: LengthUnit;\n}\n\n/**\n * The measurement plugin's settings. `measurementPlugin(config)` registers\n * them over {@link MEASUREMENT_DEFAULTS}, and `updateSettings()` changes them\n * for every document while the app runs.\n */\nexport interface MeasurementSettings {\n  /**\n   * The scale of a page that has none: 1:1 in meters (`'metric'`) or in\n   * feet (`'imperial'`), or a scale of your own.\n   */\n  readonly defaultScale: 'metric' | 'imperial' | PdfMeasure;\n  /** The scales `listPresets()` offers. */\n  readonly presets: readonly ScalePreset[];\n}\n\n/** What the measurement settings are when the app registers none. */\nexport const MEASUREMENT_DEFAULTS: MeasurementSettings = {\n  defaultScale: 'metric',\n  presets: DEFAULT_PRESETS,\n};\n\n/** What `measurementPlugin(config)` takes: either setting, each a whole value. */\nexport type MeasurementConfig = Partial<MeasurementSettings>;\n\nexport interface ScaleChangeOptions extends OperationOptions {\n  /** Re-measure the page's measurement annotations with the new scale. Default true. */\n  recalculate?: boolean;\n}\n\nexport interface PageScale {\n  measure: PdfMeasurement | null;\n  source: 'owned' | 'foreign' | 'default';\n  /** The page's viewports are known. */\n  ready: boolean;\n  /** The engine can persist a scale into the document. */\n  persistent: boolean;\n  /** Why the last read of the page's viewports failed; the last known viewports stay in effect. */\n  error?: SerializedEngineError;\n}\n\n/**\n * A page's scale where there is none to read: before a document opens, or for\n * a page that isn't there. Not ready, with no measure; the same object every\n * time, so a framework read compares it by identity.\n */\nexport const NO_PAGE_SCALE: PageScale = Object.freeze({\n  measure: null,\n  source: 'default',\n  ready: false,\n  persistent: false,\n});\n\n/**\n * The readout where there is no measurement to read: before a document\n * opens, or for an annotation that isn't there. `getReadout` answers it too.\n */\nexport const NO_READOUT: MeasurementUnavailable = Object.freeze({ unavailable: 'not-dimension' });\n\n/** Two points captured by the calibrate tool, awaiting the real length. Page space. */\nexport interface CalibrationRequest {\n  page: PageRef;\n  from: Point;\n  to: Point;\n  /** The captured length in PDF user space (the scale is derived from it). */\n  userSpaceLength: number;\n}\n\nexport interface CalibrateInput {\n  /** The page, as a ref or an index. */\n  page: PageRef | number;\n  /** The two ends of the known length, in page space. */\n  from: Point;\n  to: Point;\n  /** The real-world length between the two points. */\n  distance: { value: number; unit: LengthUnit };\n}\n\n/** A failed viewport write is reported per page for a multi-page change.\n *  Single-page failures reject before any annotation write. */\nexport type ScaleChangeReport =\n  | (RecalibrationReport & { scaleError?: never })\n  | {\n      page: PageRef;\n      scale?: never;\n      error?: never;\n      updated: [];\n      skipped: [];\n      failed: [];\n      scaleError: SerializedEngineError;\n    };\n\nexport type MeasurementKind = 'distance' | 'perimeter' | 'area';\n\nexport interface CreateMeasurementInput {\n  kind: MeasurementKind;\n  /** The page, as a ref or an index. */\n  page: PageRef | number;\n  /** Page-space points: two for a distance, the vertices otherwise. */\n  points: readonly Point[];\n  /** The authoring tool whose defaults apply (defaults to the kind's own tool). */\n  tool?: string;\n}\n\n// ── events ──\nexport interface MeasurementScaleChangedEvent {\n  readonly page: PageRef;\n  readonly report: ScaleChangeReport;\n}\nexport interface CalibrationRequestedEvent {\n  readonly request: CalibrationRequest;\n}\nexport interface CalibrationCompletedEvent {\n  readonly page: PageRef;\n}\nexport type CalibrationDismissedEvent = Record<string, never>;\n\n/**\n * Page scales, calibration and measurement readouts for one document. A page\n * argument is a ref or an index: a read given a page that isn't there\n * answers empty, a verb refuses it with `not-found`. Every async verb takes\n * a `signal`. The settings belong to the plugin, not to a document: a change\n * reaches every open document.\n */\nexport interface MeasurementCapability extends SettingsApi<MeasurementSettings> {\n  // ── twins ──\n  /** May write a page scale and calibrate (`doc.annotate.modify`). */\n  canCalibrate(): boolean;\n  /** May measure on the page: `annotations:create`, and the page's scale has loaded. */\n  canMeasure(page: PageRef | number): boolean;\n\n  // ── reading ──\n  /** The resolved scale, its source and readiness. Reference-stable while unchanged. */\n  getPageScale(page: PageRef | number): PageScale;\n  /** Load the page's viewports. Resolves at once when already known. Rejects `not-found`. */\n  ensureLoaded(page: PageRef | number, options?: OperationOptions): Promise<void>;\n  /** A scale change is in flight. */\n  isBusy(): boolean;\n  /** The reports of the last scale change, one per page. */\n  listLastReports(): readonly ScaleChangeReport[];\n  listPresets(): readonly ScalePreset[];\n  listUnits(): readonly LengthUnit[];\n  listAreaUnits(): readonly AreaUnit[];\n  /**\n   * The formatted measurement of a measurement annotation, or why there is\n   * none ({@link NO_READOUT} for an annotation that isn't there). The same\n   * object until the annotation changes.\n   */\n  getReadout(ref: AnnotationRef): MeasurementReadout | MeasurementUnavailable;\n  /** A distance between two page-space points in the page's scale: a pure conversion, no annotation. */\n  measureDistance(\n    page: PageRef | number,\n    from: Point,\n    to: Point,\n  ): MeasurementReadout | MeasurementUnavailable;\n  /** The area of a page-space polygon in the page's scale: a pure conversion, no annotation. */\n  measureArea(\n    page: PageRef | number,\n    vertices: readonly Point[],\n  ): MeasurementReadout | MeasurementUnavailable;\n  /** Two points captured, awaiting a length. */\n  getCalibrationRequest(): CalibrationRequest | null;\n\n  // ── the scale ──\n  // Every scale change rejects `permission-denied` without\n  // `doc.annotate.modify` (see `canCalibrate`), and `not-found` for a page\n  // that isn't in the document.\n  setScale(\n    pages: PageTarget,\n    measure: PdfMeasure,\n    options?: ScaleChangeOptions,\n  ): Promise<readonly ScaleChangeReport[]>;\n  /** Derive a scale from a known length between two page points. `applyTo` widens the write (default: the input page). Fires `onCalibrationCompleted`. */\n  calibrate(\n    input: CalibrateInput,\n    options?: ScaleChangeOptions & { applyTo?: PageTarget },\n  ): Promise<readonly ScaleChangeReport[]>;\n  setUnit(\n    pages: PageTarget,\n    unit: LengthUnit,\n    options?: ScaleChangeOptions,\n  ): Promise<readonly ScaleChangeReport[]>;\n  setAreaUnit(\n    pages: PageTarget,\n    unit: AreaUnit,\n    options?: ScaleChangeOptions,\n  ): Promise<readonly ScaleChangeReport[]>;\n  setPrecision(\n    pages: PageTarget,\n    precision: number,\n    options?: ScaleChangeOptions,\n  ): Promise<readonly ScaleChangeReport[]>;\n  /** A scale from the `presets` setting. Rejects `not-found` for an unknown preset. */\n  setPreset(\n    pages: PageTarget,\n    presetId: string,\n    options?: ScaleChangeOptions,\n  ): Promise<readonly ScaleChangeReport[]>;\n  /** Back to the default scale (the owned viewport is removed). */\n  clearScale(\n    pages: PageTarget,\n    options?: ScaleChangeOptions,\n  ): Promise<readonly ScaleChangeReport[]>;\n\n  // ── measuring ──\n  /**\n   * Create a measurement annotation with the page's scale and the tool's\n   * style. Resolves `{ annotation }`. Rejects `permission-denied` without\n   * `annotations:create`, `not-ready` before the scale is known,\n   * `not-found` for a page that isn't in the document.\n   */\n  createMeasurement(\n    input: CreateMeasurementInput,\n    options?: OperationOptions,\n  ): Promise<{ annotation: Annotation }>;\n\n  // ── calibration flow ──\n  /**\n   * Arm the calibrate tool (two points, then `onCalibrationRequested`).\n   * Throws `permission-denied` without `doc.annotate.modify` (see `canCalibrate`).\n   */\n  startCalibration(): void;\n  /** Drop the pending request. Fires `onCalibrationDismissed` when there was one. */\n  dismissCalibration(): void;\n\n  // ── events ──\n  readonly onScaleChanged: EventHook<MeasurementScaleChangedEvent>;\n  readonly onCalibrationRequested: EventHook<CalibrationRequestedEvent>;\n  readonly onCalibrationCompleted: EventHook<CalibrationCompletedEvent>;\n  readonly onCalibrationDismissed: EventHook<CalibrationDismissedEvent>;\n}\n"],"mappings":";;;;;AAaA,MAAa,kBAA0C;CACrD,GAAG;EAAC;EAAG;EAAI;EAAI;EAAI;EAAK;CAAG,CAAC,CAAC,KAAK,UAAU;EAC1C,IAAI,UAAU;EACd,OAAO,KAAK;EACZ,OAAO;EACP;EACA,MAAM;CACR,EAAE;CACF;EAAE,IAAI;EAAoB,OAAO;EAAiB,OAAO;EAAG,MAAM;EAAI,MAAM;CAAK;CACjF;EAAE,IAAI;EAAmB,OAAO;EAAiB,OAAO;EAAG,MAAM;EAAI,MAAM;CAAK;AAClF;;AAGA,MAAa,kBACX,cACA,WAAW,MAEX,OAAO,iBAAiB,WACpB,gBAAA,GAAA,8BAAA,iBAAA,CACiB,GAAG,GAAG,iBAAiB,aAAa,OAAO,KAAK,EAAE,SAAS,CAAC;AAEnF,SAAgB,SACd,SACA,MACA,QAAA,GAAA,8BAAA,SAAA,CAA0B,IAAI,GAClB;CACZ,MAAM,QAAQ,QAAQ,EAAE,EAAE,EAAE,KAAK,KAAK;CACtC,IAAI,EAAE,SAASA,8BAAAA,SACb,MAAM,IAAI,WAAW,yDAAyD;CAEhF,MAAM,WAAW,QAAQ,SAAS,QAAQ,SAAS,SAAS;CAC5D,MAAM,YAAY,UAAU,aAAa,aAAa,MAAO,UAAU,aAAa;CACpF,OAAO;EACL,GAAG;EACH,UAAU,CAAC;GAAE;GAAM,YAAYA,8BAAAA,OAAO,SAASA,8BAAAA,OAAO;GAAO;GAAW,UAAU;EAAU,CAAC;EAC7F,MAAM,CACJ;GACE,OAAA,GAAA,8BAAA,cAAA,CAAoB,IAAI;GACxB,YAAYA,8BAAAA,OAAO,UAAU,KAAA,GAAA,8BAAA,aAAA,CAAiB,IAAI;GAClD;GACA,UAAU;EACZ,CACF;CACF;AACF;AAEA,SAAgB,cAAc,SAAqB,WAA+B;CAChF,IAAI,CAAC,OAAO,UAAU,KAAK,MAAM,SAAS,CAAC,KAAK,YAAY,KAAK,YAAY,KAC3E,MAAM,IAAI,WAAW,2BAA2B;CAElD,MAAM,UAAU,YACd,QAAQ,KAAK,QAAQ,UACnB,UAAU,QAAQ,SAAS,IACvB;EAAE,GAAG;EAAQ;EAAW,UAAU;CAAmB,IACrD,MACN;CACF,OAAO;EAAE,GAAG;EAAS,UAAU,OAAO,QAAQ,QAAQ;EAAG,MAAM,OAAO,QAAQ,IAAI;CAAE;AACtF;;AAGA,SAAgB,aAAa,SAAqB,MAA4B;CAC5E,MAAM,QAAQ,QAAQ,EAAE,EAAE,EAAE,KAAK,KAAK;CACtC,IAAI,EAAE,SAASA,8BAAAA,SACb,MAAM,IAAI,WAAW,yDAAyD;CAEhF,MAAM,WAAW,QAAQ,KAAK,QAAQ,KAAK,SAAS;CACpD,MAAM,YAAY,UAAU,aAAa,aAAa,MAAO,UAAU,aAAa;CACpF,OAAO;EACL,GAAG;EACH,MAAM,CACJ;GACE,OAAA,GAAA,8BAAA,cAAA,CAAoB,IAAI;GACxB,YAAYA,8BAAAA,OAAO,UAAU,KAAA,GAAA,8BAAA,aAAA,CAAiB,IAAI;GAClD;GACA,UAAU;EACZ,CACF;CACF;AACF;;;;ACtFA,MAAa,oBAAA,GAAA,eAAA,sBAAA,CAAgE,eAAe;CAC1F,MAAM;CAGN,UAAU;EACR,cAAc;EACd,UAAU;EACV,WAAW;EACX,SAAS;EACT,aAAa;EACb,cAAc;EACd,WAAW;EACX,YAAY;EACZ,mBAAmB;CACrB;AACF,CAAC;;;;AC0CD,MAAa,uBAA4C;CACvD,cAAc;CACd,SAAS;AACX;;;;;;AA0BA,MAAa,gBAA2B,OAAO,OAAO;CACpD,SAAS;CACT,QAAQ;CACR,OAAO;CACP,YAAY;AACd,CAAC;;;;;AAMD,MAAa,aAAqC,OAAO,OAAO,EAAE,aAAa,gBAAgB,CAAC"}