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

package/dist/index.js

@@ -1,469 +1,623 @@
-import { t as MeasurementToken } from "./contract-DO0emN-T.js";
-import { definePlugin } from "@embedpdf/core";
+import { a as defaultMeasure, c as withUnit, i as MeasurementToken, n as NO_PAGE_SCALE, o as withAreaUnit, r as NO_READOUT, s as withPrecision, t as MEASUREMENT_DEFAULTS } from "./contract-DyqqYfyE.js";
+import { PluginError, composeApi, definePlugin, defineState, memoByKey, toPageRef, toPluginError } from "@embedpdf/core";
 import { AnnotationToken } from "@embedpdf/plugin-annotation/contract/host";
 import { InteractionToken } from "@embedpdf/plugin-interaction/contract";
-import { AnnotationToken as AnnotationToken$1 } from "@embedpdf/plugin-annotation/contract";
-import { EngineError, EngineErrorCode, METRES, PermissionDenied, areaUnitLabel, assertWritableMeasure, measureFromKnownLength, measureFromRatio, measurementPoint, measurementReadout, serializeError, squareMetres, squareOf, viewportForPoint } from "@embedpdf/engine-core/runtime";
-//#region src/scale.ts
-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"
-	}
+import { METRES, assertWritableMeasure, measureFromKnownLength, measureFromRatio, measurementPoint, measurementReadout, pageRefsEqual, serializeError, squareOf, viewportForPoint } from "@embedpdf/engine-core/runtime";
+//#region src/read/scale.ts
+const UNITS = Object.keys(METRES);
+const AREA_UNITS = [
+	...UNITS.map(squareOf),
+	"ha",
+	"acre"
 ];
-const defaultMeasure = (config, userUnit = 1) => typeof config.defaultScale === "object" ? config.defaultScale : measureFromRatio(1, 1, config.defaultScale === "imperial" ? "ft" : "m", userUnit);
-function selectPageScale(viewports, crop, fallback, persistent) {
-	const selected = viewports.find((v) => v.owned) ?? viewportForPoint(viewports, {
-		x: (crop.left + crop.right) / 2,
-		y: (crop.top + crop.bottom) / 2
+function createScaleReads(ctx, { siblings }, { scaleOf }) {
+	const { annotation } = siblings;
+	const settings = ctx.settings();
+	const state = () => ctx.state.get();
+	const readouts = /* @__PURE__ */ new WeakMap();
+	const getReadout = (ref) => {
+		const raw = annotation.get(ref);
+		if (!raw) return NO_READOUT;
+		let readout = readouts.get(raw);
+		if (!readout) {
+			readout = measurementReadout(raw);
+			readouts.set(raw, readout);
+		}
+		return readout;
+	};
+	const measureDistance = (page, from, to) => measurementReadout({
+		subtype: "line",
+		intent: "line-dimension",
+		measure: scaleOf(page).measure,
+		linePoints: {
+			start: from,
+			end: to
+		}
 	});
+	const measureArea = (page, vertices) => measurementReadout({
+		subtype: "polygon",
+		intent: "polygon-dimension",
+		measure: scaleOf(page).measure,
+		vertices: [...vertices]
+	});
+	return { api: {
+		canMeasure: (page) => ctx.allows("annotations:create") && scaleOf(page).ready,
+		getPageScale: scaleOf,
+		isBusy: () => state().pending > 0,
+		listLastReports: () => state().reports,
+		listPresets: () => settings.get().presets,
+		listUnits: () => UNITS,
+		listAreaUnits: () => AREA_UNITS,
+		getReadout,
+		measureDistance,
+		measureArea,
+		getCalibrationRequest: () => state().calibration
+	} };
+}
+//#endregion
+//#region src/services/events.ts
+function createEvents(ctx) {
 	return {
-		measure: selected ? selected.measure ?? null : fallback,
-		source: selected ? selected.owned ? "owned" : "foreign" : "default",
-		ready: true,
-		persistent
+		scaleChanged: ctx.events.source(),
+		calibrationRequested: ctx.events.source(),
+		calibrationCompleted: ctx.events.source(),
+		calibrationDismissed: ctx.events.source()
 	};
 }
-function withUnit(m, unit, area = squareOf(unit)) {
-	const basis = m.x[0]?.unit.trim();
-	if (!(basis in METRES)) throw new RangeError("This scale has an unknown base unit; calibrate it first");
-	const previous = m.distance[m.distance.length - 1];
-	const precision = previous?.fraction === "fraction" ? 100 : previous?.precision ?? 100;
+//#endregion
+//#region src/services/siblings.ts
+/** The sibling plugins: annotation (host lens) and the interaction hub. */
+function resolveSiblings(ctx) {
 	return {
-		...m,
-		distance: [{
-			unit,
-			conversion: METRES[basis] / METRES[unit],
-			precision,
-			fraction: "decimal"
-		}],
-		area: [{
-			unit: areaUnitLabel(area),
-			conversion: METRES[basis] ** 2 / squareMetres(area),
-			precision,
-			fraction: "decimal"
-		}]
+		annotation: ctx.get(AnnotationToken),
+		interaction: ctx.get(InteractionToken)
 	};
 }
-function withPrecision(m, precision) {
-	if (!Number.isInteger(Math.log10(precision)) || precision < 1 || precision > 1e9) throw new RangeError("Invalid decimal precision");
-	const update = (formats) => formats.map((f, i) => i === formats.length - 1 ? {
-		...f,
-		precision,
-		fraction: "decimal"
-	} : f);
+//#endregion
+//#region src/services/store.ts
+/** Changing a page's scale rewrites its measurement annotations. */
+const SCALE_PERMISSION = "doc.annotate.modify";
+function createStore(ctx) {
+	/** A page argument of a verb, as a ref or an index: the page, or `not-found`. */
+	const requirePage = (page) => ctx.pageOf(page);
+	const canCalibrate = () => ctx.allows(SCALE_PERMISSION);
+	/** The pages a verb changes, each resolved: a page that isn't there refuses the whole call. */
+	const targets = (pages) => {
+		if (pages === "all") return (ctx.document()?.pages ?? []).map((layout) => layout.ref);
+		return (Array.isArray(pages) ? pages : [pages]).map((page) => ctx.pageOf(page).ref);
+	};
 	return {
-		...m,
-		distance: update(m.distance),
-		area: update(m.area)
+		requirePage,
+		canCalibrate,
+		targets
 	};
 }
-/** Change the area display unit while preserving imported distance formatting. */
-function withAreaUnit(measure, unit) {
-	const basis = measure.x[0]?.unit.trim();
-	if (!(basis in 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;
+//#endregion
+//#region src/services/index.ts
+function createServices(ctx) {
 	return {
-		...measure,
-		area: [{
-			unit: areaUnitLabel(unit),
-			conversion: METRES[basis] ** 2 / squareMetres(unit),
-			precision,
-			fraction: "decimal"
-		}]
+		events: createEvents(ctx),
+		store: createStore(ctx),
+		siblings: resolveSiblings(ctx)
 	};
 }
 //#endregion
-//#region src/capability.ts
-const LOADING = {
+//#region src/model.ts
+/**
+* The measurement session: scale changes in flight, the pending calibration,
+* the last change's reports, why a page's viewport read failed, and the
+* session-only viewports of engines that cannot persist a scale. The pages'
+* viewports themselves are engine data held by a page mirror. Every
+* transition below is pure; the controller applies them with
+* `ctx.state.update`. `selectPageScale` and `pageScaleOf` are the pure
+* projections from viewports to the public {@link PageScale}.
+*/
+/** No reports yet: the same array every time. */
+const NO_REPORTS = Object.freeze([]);
+const initialMeasurementState = () => ({
+	pending: 0,
+	calibration: null,
+	reports: NO_REPORTS,
+	loadErrors: {},
+	localViewports: {}
+});
+const beginScaleChange = (state) => ({
+	...state,
+	pending: state.pending + 1
+});
+const endScaleChange = (state) => state.pending === 0 ? state : {
+	...state,
+	pending: state.pending - 1
+};
+const setCalibration = (state, calibration) => state.calibration === calibration ? state : {
+	...state,
+	calibration
+};
+const setReports = (state, reports) => state.reports === reports ? state : {
+	...state,
+	reports
+};
+const recordLoadError = (state, pageObjectNumber, error) => ({
+	...state,
+	loadErrors: {
+		...state.loadErrors,
+		[pageObjectNumber]: error
+	}
+});
+const clearLoadError = (state, pageObjectNumber) => {
+	if (!(pageObjectNumber in state.loadErrors)) return state;
+	const { [pageObjectNumber]: _cleared, ...loadErrors } = state.loadErrors;
+	return {
+		...state,
+		loadErrors
+	};
+};
+const setLocalViewports = (state, pageObjectNumber, viewports) => ({
+	...state,
+	localViewports: {
+		...state.localViewports,
+		[pageObjectNumber]: viewports
+	}
+});
+/**
+* The scale a page's viewports resolve to: the owned viewport, else the one
+* containing the page's center, else the fallback.
+*/
+function selectPageScale(viewports, size, fallback, persistent) {
+	const selected = viewports.find((viewport) => viewport.owned) ?? viewportForPoint(viewports, {
+		x: size.width / 2,
+		y: size.height / 2
+	});
+	return {
+		measure: selected ? selected.measure ?? null : fallback,
+		source: selected ? selected.owned ? "owned" : "foreign" : "default",
+		ready: true,
+		persistent
+	};
+}
+/**
+* The public page scale. A page is ready once its viewports were read; a
+* failed re-read keeps the last confirmed viewports in effect and reports
+* its error alongside them.
+*/
+function pageScaleOf(inputs) {
+	const error = inputs.status === "error" && inputs.error ? { error: inputs.error } : {};
+	if (!inputs.viewports || !inputs.size) return {
+		measure: null,
+		source: "default",
+		ready: false,
+		persistent: inputs.persistent,
+		...error
+	};
+	return {
+		...selectPageScale(inputs.viewports, inputs.size, inputs.fallback, inputs.persistent),
+		...error
+	};
+}
+//#endregion
+//#region src/sync/viewports.ts
+/**
+* The pages' viewports: a page mirror re-read whenever a confirmed
+* `pages.scaleSet` names a loaded page, from this session or another
+* (stream gaps and version moves re-read every loaded page). Its `changed`
+* callback tells the annotation plugin a page's viewports, and a new
+* `defaultScale` setting tells it again. `connect` loads every page in the
+* registry, including pages inserted later.
+*/
+/** The scale of a page index past the end: none, and never ready. */
+const NO_PAGE = Object.freeze({
 	measure: null,
 	source: "default",
 	ready: false,
 	persistent: false
-};
-const UNITS = Object.keys(METRES);
-function createMeasurementCapability(ctx, config, effects) {
-	const anno = ctx.get(AnnotationToken$1);
-	const interaction = ctx.get(InteractionToken);
-	const canCalibrate = () => ctx.doc?.security.allows("doc.annotate.modify") ?? false;
-	const pons = (pon, opts) => pon === "all" || opts?.allPages ? (ctx.document()?.pages ?? []).map((p) => p.pageObjectNumber) : [pon];
-	const scaleOf = (pon) => {
-		const scale = ctx.getState().pages[pon]?.scale.measure;
-		if (!scale || scale.subtype !== "RL") throw new RangeError("Calibrate this page before changing its units or precision");
-		return scale;
-	};
-	const presets = config.presets ?? DEFAULT_PRESETS;
-	return {
-		canCalibrate,
-		canMeasure: (pon) => anno.canCreate() && !!ctx.getState().pages[pon]?.scale.ready,
-		pageScale: (pon) => ctx.getState().pages[pon]?.scale ?? LOADING,
-		isBusy: () => ctx.getState().pending > 0,
-		lastReports: () => ctx.getState().reports,
-		prepare: effects.prepare,
-		setPageScale: (pon, measure, opts = {}) => effects.change(pons(pon, opts), () => measure, opts),
-		calibrate: (pon, from, to, real, opts = {}) => {
-			const a = measurementPoint(from);
-			const b = measurementPoint(to);
-			const scale = measureFromKnownLength(Math.hypot(b.x - a.x, b.y - a.y), real);
-			return effects.change(pons(pon, opts), () => scale, opts);
-		},
-		setUnit: (pon, unit, areaUnit, opts = {}) => effects.change(pons(pon, opts), (p) => withUnit(scaleOf(p), unit, areaUnit), {
-			...opts,
-			allPages: pon === "all" || opts.allPages
-		}),
-		setPrecision: (pon, precision, opts = {}) => effects.change(pons(pon, opts), (p) => withPrecision(scaleOf(p), precision), {
-			...opts,
-			allPages: pon === "all" || opts.allPages
-		}),
-		setPreset: (pon, id, opts = {}) => {
-			const preset = presets.find((p) => p.id === id);
-			if (!preset) return Promise.reject(/* @__PURE__ */ new RangeError("Unknown scale preset"));
-			return effects.change(pons(pon, opts), (p) => measureFromRatio(preset.paper, preset.real, preset.unit, ctx.document()?.pages.find((page) => page.pageObjectNumber === p)?.userUnit ?? 1), opts);
-		},
-		presets: () => presets,
-		units: () => UNITS,
-		areaUnits: () => [
-			...UNITS.map(squareOf),
-			"ha",
-			"acre"
-		],
-		setAreaUnit: (pon, unit, opts = {}) => effects.change(pons(pon, opts), (p) => withAreaUnit(scaleOf(p), unit), opts),
-		readout: (ref) => {
-			const dto = anno.get(ref);
-			return dto ? measurementReadout(dto) : { unavailable: "not-dimension" };
-		},
-		startCalibration: () => {
-			if (canCalibrate()) {
-				ctx.dispatch({
-					type: "CALIBRATION",
-					request: null
-				});
-				interaction.activateTool("calibrate");
+});
+function createViewportSync(ctx, { siblings }) {
+	const { annotation } = siblings;
+	const settings = ctx.settings();
+	/** The scale of a page without one: the `defaultScale` setting, in the page's user unit. */
+	const fallbackOf = (layout) => defaultMeasure(settings.get().defaultScale, layout?.userUnit ?? 1);
+	const viewports = ctx.pageMirror({
+		name: "viewports",
+		load: async (doc, page, signal) => {
+			ctx.assertPageRef(page);
+			const service = doc.page(page).measure;
+			if (!service) return ctx.state.get().localViewports[page.objectNumber] ?? [];
+			try {
+				return (await service.listViewports()).viewports;
+			} catch (error) {
+				if (!signal.aborted) ctx.state.update(recordLoadError, page.objectNumber, serializeError(error));
+				throw error;
 			}
 		},
-		calibrationRequest: () => ctx.getState().calibration,
-		dismissCalibration: () => ctx.dispatch({
-			type: "CALIBRATION",
-			request: null
-		}),
-		onCalibrationRequested: (cb) => {
-			effects.calibrationListeners.add(cb);
-			return () => {
-				effects.calibrationListeners.delete(cb);
-			};
-		},
-		onScaleChanged: (cb) => {
-			effects.scaleListeners.add(cb);
-			return () => {
-				effects.scaleListeners.delete(cb);
-			};
+		affected: (event) => event.type === "pages.scaleSet" ? [event.page] : null,
+		changed: ({ page, cause, next }) => {
+			if (cause === "drop" || next === void 0) return;
+			ctx.state.update(clearLoadError, page.objectNumber);
+			const layout = ctx.getPage(page);
+			if (layout) annotation.setPageViewports(page, [...next], fallbackOf(layout));
 		}
+	});
+	/** The engine can persist a scale into the document. */
+	const isPersistent = (page) => ctx.doc.page(page).measure !== void 0;
+	/** The page's public scale, the same object until its viewports, read state or layout change. */
+	const scaleOfPage = memoByKey((pageObjectNumber) => {
+		const page = toPageRef(pageObjectNumber);
+		const layout = ctx.getPage(page);
+		return [
+			viewports.get(page),
+			viewports.getStatus(page),
+			ctx.state.get().loadErrors[pageObjectNumber],
+			layout,
+			layout ? isPersistent(page) : false,
+			settings.get().defaultScale
+		];
+	}, (_pageObjectNumber, pageViewports, status, error, layout, persistent) => pageScaleOf({
+		viewports: pageViewports,
+		status,
+		error,
+		size: layout?.size,
+		fallback: fallbackOf(layout),
+		persistent
+	}));
+	/** A page's scale, by ref or index; a page that isn't there has none, and isn't ready. */
+	const scaleOf = (page) => {
+		if (typeof page !== "number") return scaleOfPage(page.objectNumber);
+		const layout = ctx.getPage(page);
+		return layout ? scaleOfPage(layout.ref.objectNumber) : NO_PAGE;
+	};
+	const ensureLoaded = (page, options) => {
+		const layout = ctx.getPage(page);
+		if (!layout) return Promise.reject(new PluginError("not-found", "measurement", "no such page"));
+		return ctx.cancellable(options?.signal, viewports.ensureLoaded(layout.ref));
+	};
+	const connect = () => {
+		const hydrate = (layouts) => {
+			for (const layout of layouts ?? []) {
+				if (viewports.getStatus(layout.ref) !== "idle") continue;
+				viewports.ensureLoaded(layout.ref).catch(() => {});
+			}
+		};
+		hydrate(ctx.document()?.pages);
+		ctx.watch(() => ctx.document()?.pages, hydrate);
+		ctx.listen(settings.api.onSettingsChanged, ({ changed }) => {
+			if (!changed.includes("defaultScale")) return;
+			for (const layout of ctx.document()?.pages ?? []) {
+				const known = viewports.get(layout.ref);
+				if (known) annotation.setPageViewports(layout.ref, [...known], fallbackOf(layout));
+			}
+		});
+	};
+	return {
+		ensureLoaded,
+		scaleOf,
+		/** Re-read one page; for session-only scales, which no engine event announces. */
+		refresh: (page) => viewports.refresh(page),
+		connect
 	};
 }
 //#endregion
-//#region src/effects.ts
-/** All engine IO and cross-plugin lifecycle work lives here. Calls serialize
-* per page; refresh epochs prevent an old read from replacing a newer scale. */
-function createMeasurementEffects(ctx, config) {
-	const anno = ctx.get(AnnotationToken);
-	const interaction = ctx.get(InteractionToken);
-	let disposed = false;
-	const epochs = /* @__PURE__ */ new Map();
-	const reading = /* @__PURE__ */ new Map();
-	const queues = /* @__PURE__ */ new Map();
-	const calibrationListeners = /* @__PURE__ */ new Set();
-	const scaleListeners = /* @__PURE__ */ new Set();
-	const meta = (pon) => ctx.document()?.pages.find((p) => p.pageObjectNumber === pon);
-	const live = () => {
-		if (disposed || !ctx.doc) throw new EngineError(EngineErrorCode.DocNotOpen);
+//#region src/write/calibration.ts
+/** The calibrate flow: arm the tool, turn a captured distance draft into a
+*  request (page space), and dismiss it. */
+function createCalibration(ctx, { events, store, siblings }) {
+	const { calibrationRequested, calibrationDismissed } = events;
+	const { canCalibrate } = store;
+	const { annotation, interaction } = siblings;
+	const startCalibration = () => {
+		ctx.assertAllowed(SCALE_PERMISSION, "measurement.startCalibration");
+		ctx.state.update(setCalibration, null);
+		interaction.activateTool("calibrate");
 	};
-	const assertAllowed = () => {
-		live();
-		if (!ctx.doc.security.allows("doc.annotate.modify")) throw new PermissionDenied("doc.annotate.modify", "measurement");
+	const dismissCalibration = () => {
+		if (!ctx.state.get().calibration) return;
+		ctx.state.update(setCalibration, null);
+		calibrationDismissed.emit({});
 	};
-	const publish = (pon, viewports) => {
-		if (disposed) return;
-		const page = meta(pon);
-		if (!page) return;
-		const fallback = defaultMeasure(config, page.userUnit);
-		anno.setPageViewports(pon, viewports, fallback);
-		ctx.dispatch({
-			type: "PAGE_SCALE",
-			pon,
-			viewports,
-			scale: selectPageScale(viewports, page.boxes.crop, fallback, !!ctx.doc?.page(pon).measure)
+	/** A distance draft from the calibrate tool becomes the pending request. */
+	const connect = () => {
+		ctx.listen(annotation.onDraftCaptured, (draft) => {
+			if (draft.tool !== "calibrate" || !canCalibrate()) return;
+			const from = measurementPoint(draft.from);
+			const to = measurementPoint(draft.to);
+			const userSpaceLength = Math.hypot(to.x - from.x, to.y - from.y);
+			if (!(userSpaceLength > 0)) return;
+			const request = {
+				page: draft.page,
+				from,
+				to,
+				userSpaceLength
+			};
+			interaction.activateTool("pointer");
+			ctx.state.update(setCalibration, request);
+			calibrationRequested.emit({ request });
 		});
 	};
-	const refresh = (pon) => {
-		live();
-		const page = meta(pon);
-		if (!page) return Promise.reject(new EngineError(EngineErrorCode.NotFound, "Page not found"));
-		const epoch = (epochs.get(pon) ?? 0) + 1;
-		epochs.set(pon, epoch);
-		anno.setPageViewports(pon, void 0, defaultMeasure(config, page.userUnit));
-		const previous = ctx.getState().pages[pon];
-		ctx.dispatch({
-			type: "PAGE_SCALE",
-			pon,
-			viewports: previous?.viewports ?? [],
-			scale: {
-				...previous?.scale ?? {
-					measure: null,
-					source: "default",
-					persistent: !!ctx.doc.page(pon).measure
-				},
-				ready: false
-			}
-		});
-		const service = ctx.doc.page(pon).measure;
-		const request = (async () => {
-			try {
-				const viewports = service ? await service.viewports() : ctx.getState().pages[pon]?.viewports ?? [];
-				if (!disposed && epochs.get(pon) === epoch) publish(pon, viewports);
-			} catch (error) {
-				if (!disposed && epochs.get(pon) === epoch) ctx.dispatch({
-					type: "PAGE_SCALE",
-					pon,
-					viewports: [],
-					scale: {
-						measure: null,
-						source: "default",
-						ready: false,
-						persistent: !!service,
-						error: serializeError(error)
-					}
-				});
-				throw error;
-			} finally {
-				if (epochs.get(pon) === epoch) reading.delete(pon);
+	return {
+		connect,
+		api: {
+			startCalibration,
+			dismissCalibration
+		}
+	};
+}
+//#endregion
+//#region src/write/create.ts
+/** Measurement creation: a measurement annotation with the page's scale, through the annotation plugin. */
+function createMeasuring(ctx, { siblings }, { scaleOf }) {
+	const { annotation } = siblings;
+	/**
+	* The measurement's engine draft: the tool's current defaults (style,
+	* caption and leader), the dimension intent, and the page's scale. The
+	* engine works out the label from the points and the scale.
+	*/
+	const draftOf = (input, page, tool) => {
+		const style = annotation.tools.getDefaults(tool);
+		const shared = {
+			color: style.color,
+			strokeWidth: style.strokeWidth,
+			opacity: style.opacity,
+			measure: scaleOf(page).measure,
+			captionEnabled: style.captionEnabled ?? true
+		};
+		switch (input.kind) {
+			case "distance": {
+				const [from, to] = input.points;
+				if (!from || !to || input.points.length !== 2) return new PluginError("invalid-input", "measurement", "a distance needs exactly two points");
+				return {
+					subtype: "line",
+					intent: "line-dimension",
+					linePoints: {
+						start: from,
+						end: to
+					},
+					lineEndings: style.lineEndings,
+					interiorColor: style.interiorColor ?? style.color,
+					...shared,
+					captionPosition: style.captionPosition ?? "inline",
+					...style.leader ? { leader: style.leader } : {}
+				};
 			}
-		})();
-		reading.set(pon, request);
-		return request;
+			case "perimeter": return {
+				subtype: "polyline",
+				intent: "polyline-dimension",
+				vertices: input.points,
+				lineEndings: style.lineEndings,
+				...shared
+			};
+			case "area": return {
+				subtype: "polygon",
+				intent: "polygon-dimension",
+				vertices: input.points,
+				interiorColor: style.interiorColor,
+				...shared
+			};
+		}
+	};
+	const createMeasurement = async (input, options) => {
+		ctx.assertAllowed("annotations:create", "measurement.createMeasurement");
+		const page = ctx.pageOf(input.page).ref;
+		if (!scaleOf(page).ready) throw new PluginError("not-ready", "measurement", "the page scale is not known yet");
+		const draft = draftOf(input, page, input.tool ?? input.kind);
+		if (draft instanceof Error) throw draft;
+		return annotation.create(page, draft, void 0, { signal: options?.signal });
 	};
-	const prepare = (pon) => reading.get(pon) ?? (ctx.getState().pages[pon]?.scale.ready ? Promise.resolve() : refresh(pon));
-	const enqueue = (pon, action) => {
-		const result = (queues.get(pon) ?? Promise.resolve()).catch(() => {}).then(action);
-		queues.set(pon, result);
-		result.finally(() => {
-			if (queues.get(pon) === result) queues.delete(pon);
-		}).catch(() => {});
-		return result;
+	return { api: { createMeasurement } };
+}
+//#endregion
+//#region src/write/scale.ts
+/**
+* Scale writes. Every change serializes per page, loads the page first, and
+* re-measures the page's measurement annotations unless told not to. A
+* multi-page change reports per-page failures; a single-page change rejects.
+*/
+function createScaleWrites(ctx, { events, store, siblings }, { ensureLoaded, refresh, scaleOf }) {
+	const { scaleChanged, calibrationCompleted } = events;
+	const { requirePage, targets } = store;
+	const { annotation } = siblings;
+	const settings = ctx.settings();
+	/** One write queue per page, so a page's scale changes land in order. */
+	const pageQueues = /* @__PURE__ */ new Map();
+	const queueOf = (page) => {
+		let queue = pageQueues.get(page.objectNumber);
+		if (!queue) {
+			queue = ctx.serialQueue(`scale:${page.objectNumber}`);
+			pageQueues.set(page.objectNumber, queue);
+		}
+		return queue;
 	};
-	const save = async (pon, scale, opts) => {
-		assertAllowed();
-		await prepare(pon);
-		assertAllowed();
-		const service = ctx.doc.page(pon).measure;
+	ctx.onSettle(async () => {
+		await Promise.all([...pageQueues.values()].map((queue) => queue.idle()));
+	});
+	/** Write one page's scale (`null` = back to the default) and re-measure. */
+	const save = async (page, scale, options) => {
+		const { signal } = options;
+		ctx.assertAllowed(SCALE_PERMISSION, "changing a scale");
+		await ensureLoaded(page, { signal });
+		ctx.assertAllowed(SCALE_PERMISSION, "changing a scale");
+		const service = ctx.doc.page(page).measure;
 		if (service) {
-			await service.setScale(scale);
-			live();
-			await refresh(pon);
+			await ctx.cancellable(signal, service.setScale(scale));
+			await ensureLoaded(page);
 		} else {
-			const page = meta(pon);
-			const old = ctx.getState().pages[pon]?.viewports ?? [];
-			publish(pon, [...old.filter((v) => !v.owned), {
-				bbox: page.boxes.crop,
+			const layout = requirePage(page);
+			const kept = (ctx.state.get().localViewports[page.objectNumber] ?? []).filter((viewport) => !viewport.owned);
+			ctx.state.update(setLocalViewports, page.objectNumber, [...kept, ...scale ? [{
+				bbox: {
+					x: 0,
+					y: 0,
+					...layout.size
+				},
 				name: "EmbedPDF",
 				owned: true,
 				measure: scale
-			}]);
+			}] : []]);
+			await refresh(page);
 		}
-		live();
-		const report = opts.recalculate === false ? {
-			pon,
-			scale,
+		const effective = scale ?? defaultMeasure(settings.get().defaultScale, requirePage(page).userUnit);
+		const report = options.recalculate === false ? {
+			page,
+			scale: effective,
 			updated: [],
 			skipped: [],
 			failed: []
-		} : await anno.remeasurePage(pon, scale);
-		live();
-		for (const cb of scaleListeners) try {
-			cb({
-				pon,
-				report
-			});
-		} catch {}
+		} : await ctx.cancellable(signal, annotation.remeasurePage(page, effective));
+		scaleChanged.emit({
+			page,
+			report
+		});
 		return report;
 	};
-	const change = async (pons, measure, opts = {}) => {
-		assertAllowed();
-		ctx.dispatch({
-			type: "PENDING",
-			delta: 1
-		});
+	const change = async (pages, measure, options = {}) => {
+		ctx.assertAllowed(SCALE_PERMISSION, "changing a scale");
+		const target = targets(pages);
+		if (options.signal?.aborted) throw new PluginError("operation-cancelled", "measurement", "operation cancelled", { cause: options.signal.reason });
+		const tolerant = pages === "all" || target.length > 1;
+		ctx.state.update(beginScaleChange);
 		try {
-			const reports = await Promise.all(pons.map((pon) => enqueue(pon, async () => {
+			const reports = await Promise.all(target.map((page) => queueOf(page)(async () => {
 				try {
-					await prepare(pon);
-					const scale = measure(pon);
-					assertWritableMeasure(scale);
-					return await save(pon, scale, opts);
+					await ensureLoaded(page, { signal: options.signal });
+					const scale = measure(page);
+					if (scale) assertWritableMeasure(scale);
+					return await save(page, scale, options);
 				} catch (error) {
-					if (!opts.allPages) throw error;
+					const refused = toPluginError("measurement", error);
+					if (!tolerant || refused.code === "operation-cancelled") throw refused;
 					return {
-						pon,
+						page,
 						updated: [],
 						skipped: [],
 						failed: [],
 						scaleError: serializeError(error)
 					};
 				}
-			})));
-			live();
-			ctx.dispatch({
-				type: "REPORTS",
-				reports
-			});
+			}, options)));
+			ctx.state.update(setReports, reports);
 			return reports;
 		} finally {
-			if (!disposed) ctx.dispatch({
-				type: "PENDING",
-				delta: -1
-			});
+			ctx.state.update(endScaleChange);
 		}
 	};
-	const start = () => {
-		const doc = ctx.doc;
-		if (!doc) return;
-		ctx.cleanup(() => {
-			disposed = true;
-			epochs.clear();
-			queues.clear();
-			calibrationListeners.clear();
-			scaleListeners.clear();
-		});
-		ctx.cleanup(anno.onDraftCaptured((draft) => {
-			if (draft.tool !== "calibrate" || !doc.security.allows("doc.annotate.modify")) return;
-			const a = measurementPoint(draft.from);
-			const b = measurementPoint(draft.to);
-			const userSpaceLength = Math.hypot(b.x - a.x, b.y - a.y);
-			if (!(userSpaceLength > 0)) return;
-			const request = {
-				pon: draft.pon,
-				from: a,
-				to: b,
-				userSpaceLength
-			};
-			interaction.activateTool("pointer");
-			ctx.dispatch({
-				type: "CALIBRATION",
-				request
-			});
-			for (const cb of calibrationListeners) try {
-				cb(request);
-			} catch {}
-		}));
-		const hydrate = () => {
-			for (const page of ctx.document()?.pages ?? []) refresh(page.pageObjectNumber).catch(() => {});
-		};
-		ctx.cleanup(doc.events.subscribe((event) => {
-			if (event.type === "page.viewportsChanged") refresh(event.pageObjectNumber).catch(() => {});
-			else if (event.type === "stream.desynced" || event.type === "document.versioned") hydrate();
-		}));
-		let pages = "";
-		const reconcile = () => {
-			const next = (ctx.document()?.pages ?? []).map((p) => p.pageObjectNumber).join(",");
-			if (next === pages) return;
-			pages = next;
-			for (const page of ctx.document()?.pages ?? []) if (!ctx.getState().pages[page.pageObjectNumber]) prepare(page.pageObjectNumber).catch(() => {});
-		};
-		ctx.cleanup(ctx.subscribe(reconcile));
-		reconcile();
+	/** The page's current rectilinear scale, for unit and precision edits. */
+	const rectilinearOf = (page) => {
+		const scale = scaleOf(page).measure;
+		if (!scale || scale.subtype !== "rectilinear") throw new PluginError("not-ready", "measurement", "calibrate this page before changing its units or precision");
+		return scale;
 	};
-	return {
-		start,
-		prepare,
-		change,
-		calibrationListeners,
-		scaleListeners
+	const calibrate = async (input, options = {}) => {
+		const start = measurementPoint(input.from);
+		const end = measurementPoint(input.to);
+		let scale;
+		try {
+			scale = measureFromKnownLength(Math.hypot(end.x - start.x, end.y - start.y), input.distance);
+		} catch (error) {
+			throw new PluginError("invalid-input", "measurement", String(error.message ?? error));
+		}
+		const { applyTo, ...rest } = options;
+		const page = requirePage(input.page).ref;
+		const reports = await change(applyTo ?? page, () => scale, rest);
+		const request = ctx.state.get().calibration;
+		if (request && pageRefsEqual(request.page, page)) ctx.state.update(setCalibration, null);
+		calibrationCompleted.emit({ page });
+		return reports;
 	};
+	return { api: {
+		setScale: (pages, measure, options) => change(pages, () => measure, options),
+		calibrate,
+		setUnit: (pages, unit, options) => change(pages, (page) => withUnit(rectilinearOf(page), unit), options),
+		setAreaUnit: (pages, unit, options) => change(pages, (page) => withAreaUnit(rectilinearOf(page), unit), options),
+		setPrecision: (pages, precision, options) => change(pages, (page) => withPrecision(rectilinearOf(page), precision), options),
+		setPreset: (pages, presetId, options) => {
+			const preset = settings.get().presets.find((candidate) => candidate.id === presetId);
+			if (!preset) return Promise.reject(new PluginError("not-found", "measurement", `unknown scale preset '${presetId}'`));
+			return change(pages, (page) => measureFromRatio(preset.paper, preset.real, preset.unit, { userUnit: ctx.getPage(page)?.userUnit ?? 1 }), options);
+		},
+		clearScale: (pages, options) => change(pages, () => null, options)
+	} };
 }
 //#endregion
-//#region src/reducer.ts
-const initialMeasurementState = {
-	pages: {},
-	pending: 0,
-	calibration: null,
-	reports: []
-};
-function measurementReducer(s, a) {
-	switch (a.type) {
-		case "PAGE_SCALE": return {
-			...s,
-			pages: {
-				...s.pages,
-				[a.pon]: {
-					viewports: a.viewports,
-					scale: a.scale
-				}
+//#region src/controller.ts
+/**
+* The measurement controller: the composition root. It builds the plugin's
+* services once, wires each area with the services it declares, and
+* assembles the capability from the areas' API slices. No behavior lives
+* here: every verb and read has a home in `read/`, `write/` or `sync/`.
+*/
+function createMeasurementController(ctx) {
+	const services = createServices(ctx);
+	const { events, store } = services;
+	const settings = ctx.settings();
+	const viewports = createViewportSync(ctx, services);
+	const reads = createScaleReads(ctx, services, viewports);
+	const scale = createScaleWrites(ctx, services, viewports);
+	const calibration = createCalibration(ctx, services);
+	const measuring = createMeasuring(ctx, services, viewports);
+	return {
+		api: composeApi("measurement", [
+			settings.api,
+			reads.api,
+			scale.api,
+			calibration.api,
+			measuring.api,
+			{
+				canCalibrate: store.canCalibrate,
+				ensureLoaded: viewports.ensureLoaded,
+				onScaleChanged: events.scaleChanged.on,
+				onCalibrationRequested: events.calibrationRequested.on,
+				onCalibrationCompleted: events.calibrationCompleted.on,
+				onCalibrationDismissed: events.calibrationDismissed.on
 			}
-		};
-		case "PENDING": return {
-			...s,
-			pending: Math.max(0, s.pending + a.delta)
-		};
-		case "CALIBRATION": return {
-			...s,
-			calibration: a.request
-		};
-		case "REPORTS": return {
-			...s,
-			reports: a.reports
-		};
-	}
+		]),
+		connect() {
+			calibration.connect();
+			viewports.connect();
+		}
+	};
 }
 //#endregion
 //#region src/measurement.plugin.ts
-const measurementPlugin = (config = {}) => {
-	const drivers = /* @__PURE__ */ new Map();
-	return definePlugin({
-		id: "measurement",
-		scope: "document",
-		token: MeasurementToken,
-		requires: [AnnotationToken, InteractionToken],
-		initialState: initialMeasurementState,
-		reduce: measurementReducer,
-		capability: (ctx) => {
-			const effects = createMeasurementEffects(ctx, config);
-			drivers.set(ctx.documentId, effects);
-			ctx.cleanup(() => {
-				drivers.delete(ctx.documentId);
-			});
-			return createMeasurementCapability(ctx, config, effects);
-		},
-		effects: (ctx) => {
-			ctx.get(MeasurementToken);
-			drivers.get(ctx.documentId).start();
-		}
-	});
-};
+/**
+* Page scale, calibration and measurement readouts, document-scoped. The
+* annotation plugin owns the measurement annotations; this plugin owns the
+* page's viewports (the scale), keeps the annotation plugin's measure in step,
+* and turns the calibrate tool's drafts into scale requests. `config` is the
+* settings the app registers, over {@link MEASUREMENT_DEFAULTS}.
+*/
+const measurementPlugin = (config) => definePlugin({
+	id: "measurement",
+	scope: "document",
+	token: MeasurementToken,
+	requires: [AnnotationToken, InteractionToken],
+	state: initialMeasurementState,
+	settings: {
+		defaults: MEASUREMENT_DEFAULTS,
+		registered: config,
+		whole: ["defaultScale"]
+	},
+	create: createMeasurementController
+});
+//#endregion
+//#region src/state.ts
+/**
+* The measurements page's State table as code: what `useMeasurementState()`
+* returns, and the same fields in every other framework. A page's scale and a
+* measurement's readout are not here: `usePageScale(page)` and
+* `useMeasurementReadout(ref)` read them, so a component re-renders only for
+* its own page or measurement.
+*/
+const measurementState = defineState(MeasurementToken, {
+	read: (measurement) => ({
+		busy: measurement.isBusy(),
+		calibrationRequest: measurement.getCalibrationRequest(),
+		lastReports: measurement.listLastReports()
+	}),
+	empty: {
+		busy: false,
+		calibrationRequest: null,
+		lastReports: NO_REPORTS
+	}
+});
 //#endregion
-export { MeasurementToken, measurementPlugin };
+export { MEASUREMENT_DEFAULTS, MeasurementToken, NO_PAGE_SCALE, NO_READOUT, measurementPlugin, measurementState };
 
 //# sourceMappingURL=index.js.map