@georeferencing/react 0.0.0-stage → 0.2.0

package/dist/Georeferencer.js

@@ -0,0 +1,220 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { MODELS } from "@georeferencing/core";
+import { attachReferenceMap } from "@georeferencing/core/openlayers";
+import { useEffect, useId, useRef, useState } from "react";
+import { AccuracySummary } from "./components/accuracy.js";
+import { ExportButtons, ExportProgress, OutputFields, SessionTools, } from "./components/exports.js";
+import { MINIMAL_CONTROLS } from "./controls.js";
+import { useGeoreferencer } from "./hooks/useGeoreferencer.js";
+import { identity } from "./localization.js";
+import { AlignmentPanel } from "./panels/AlignmentPanel.js";
+import { FeaturePanel } from "./panels/FeaturePanel.js";
+import { GcpPanel } from "./panels/GcpPanel.js";
+import { ImagePanel } from "./panels/ImagePanel.js";
+import { PreviewControls } from "./panels/PreviewControls.js";
+import { ReferencePanel } from "./panels/ReferencePanel.js";
+const DEFAULT_BINDING = {};
+const NO_CONTROLS = {};
+/**
+ * Ready-made React editor for an existing OpenLayers map. Composes image, GCP, alignment, reference, output and optional drawing controls.
+ *
+ * Supplying `referenceView` selects the guided four-step layout, whose optional controls are chosen with `controls`; otherwise the classic workbench shows every control. Its effects attach/detach owned map resources and resume/suspend the controller for React Strict Mode. It installs a Save/Discard/Cancel guard and cancels pending dialogs on cleanup. The host retains final ownership of map, controller and engine. Import the optional scoped stylesheet from `@georeferencing/react/styles.css`.
+ */
+export function Georeferencer({ controller, referenceMap, bindingOptions = DEFAULT_BINDING, t = identity, className = "", propertyEditor, onExport, formatError, referenceView, controls: controlOverrides = NO_CONTROLS, emptyImageActions, }) {
+    const guardTitle = useId();
+    const s = useGeoreferencer(controller), binding = useRef(null);
+    const [guard, setGuard] = useState(null), dialog = useRef(null);
+    const guided = referenceView !== undefined;
+    const controls = { ...MINIMAL_CONTROLS, ...controlOverrides };
+    const [stage, setStage] = useState("match");
+    const [mobileView, setMobileView] = useState("image");
+    const d = s.document;
+    const imageId = d.sourceImage?.id;
+    const imageReady = Boolean(s.imageUrl);
+    const confirmed = d.confirmedAlignmentRevision === d.alignmentRevision;
+    // 0 load image · 1 match points · 2 check alignment · 3 export or draw
+    const step = !imageReady
+        ? 0
+        : s.mode === "draw" || (stage === "finish" && confirmed && s.fit)
+            ? 3
+            : stage !== "match" && s.fit
+                ? 2
+                : 1;
+    const nextPoint = Math.max(0, ...d.gcps.map((p) => p.label)) + 1;
+    const hasWork = d.gcps.length > 0 || d.features.features.length > 0;
+    useEffect(() => {
+        if (!guided)
+            return;
+        setStage("match");
+        setMobileView("image");
+        // A metadata-only restored document still needs its matching local bytes.
+        if (imageId && imageReady && controller.getSnapshot().mode === "align")
+            controller.setTool("gcp");
+    }, [controller, guided, imageId, imageReady]);
+    useEffect(() => {
+        if (guided)
+            setMobileView(s.pendingImagePoint ? "map" : "image");
+    }, [guided, s.pendingImagePoint]);
+    // Matching always uses the point tool; dragging pans, so no separate pan mode is needed.
+    useEffect(() => {
+        if (guided && step === 1 && s.tool !== "gcp" && s.mode === "align")
+            controller.setTool("gcp");
+    }, [controller, guided, step, s.tool, s.mode]);
+    useEffect(() => {
+        if (guided && mobileView === "map")
+            referenceMap.updateSize();
+    }, [guided, mobileView, referenceMap]);
+    useEffect(() => {
+        controller.start();
+        binding.current = attachReferenceMap(referenceMap, controller, bindingOptions);
+        return () => {
+            binding.current?.detach();
+            binding.current = null;
+            controller.suspend();
+        };
+    }, [referenceMap, controller, bindingOptions]);
+    useEffect(() => {
+        if (controller.options.guard)
+            return;
+        let pending = null;
+        controller.setGuard((context) => new Promise((resolve) => {
+            pending?.("cancel");
+            pending = resolve;
+            setGuard({ context, resolve });
+        }));
+        return () => {
+            pending?.("cancel");
+            controller.setGuard(undefined);
+        };
+    }, [controller]);
+    useEffect(() => {
+        if (guard) {
+            dialog.current?.showModal();
+            dialog.current?.querySelector("button")?.focus();
+        }
+    }, [guard]);
+    const decide = (choice) => {
+        guard?.resolve(choice);
+        dialog.current?.close();
+        setGuard(null);
+    };
+    const run = (fn) => {
+        try {
+            fn();
+        }
+        catch (e) {
+            controller.reportError(e);
+        }
+    };
+    const error = s.error
+        ? s.errorDetail && formatError
+            ? formatError(s.errorDetail)
+            : t(s.error)
+        : null;
+    const unsaved = (_jsx("span", { className: "rg-dirty", children: t(s.dirty && hasWork ? "Unsaved changes" : "No unsaved changes") }));
+    const goToMatching = () => run(() => {
+        if (controller.getSnapshot().mode === "draw")
+            controller.returnToAlignment();
+        setStage("match");
+        setMobileView("image");
+        controller.setTool("gcp");
+    });
+    const goToReview = () => run(() => {
+        if (controller.getSnapshot().mode === "draw")
+            controller.returnToAlignment();
+        setStage("review");
+        setMobileView("map");
+        controller.setTool("navigate");
+    });
+    const finish = () => run(() => {
+        controller.confirm();
+        setStage("finish");
+        setMobileView("map");
+    });
+    const steps = [
+        "Load image",
+        "Match points",
+        "Check alignment",
+        controller.options.digitizing ? "Export or draw" : "Export",
+    ];
+    const instruction = step === 0
+        ? [
+            "Choose an image to begin",
+            "Drop an image or choose a file. It stays on this device.",
+        ]
+        : step === 1
+            ? [
+                s.pendingImagePoint
+                    ? `${t("Now click the same spot on the map")} · ${t("Point")} ${nextPoint}`
+                    : `${t("Click a recognizable spot in the image")} · ${t("Point")} ${nextPoint}`,
+                stage !== "match"
+                    ? s.previewMode === "manual"
+                        ? "Points or settings changed. Run alignment again to check the result."
+                        : "Alignment changed. Wait for the updated preview."
+                    : "Use ground-level corners of buildings, quays or bridges, spread across the whole image. Drag to pan and scroll to zoom in both views; Esc cancels a point.",
+            ]
+            : step === 2
+                ? [
+                    "Does the image line up with the map?",
+                    "Compare roads, shorelines and building corners across the whole image. If something is off, adjust or add points.",
+                ]
+                : controller.options.digitizing
+                    ? [
+                        "Download the result or draw on the map",
+                        "Your alignment is confirmed. Download files, or draw points, lines and areas on top of the aligned image.",
+                    ]
+                    : [
+                        "Download the result",
+                        "Your alignment is confirmed. Download the georeferenced image.",
+                    ];
+    const primaryFormats = s.exportFormats.filter((format) => format.raster);
+    const otherFormats = s.exportFormats.filter((format) => !format.raster);
+    const toolRow = (step === 1 || step === 3) &&
+        (controls.history ||
+            controls.navigation ||
+            controls.transformation ||
+            controls.unsavedIndicator ||
+            ["LineString", "Polygon"].includes(s.tool)) ? (_jsxs("div", { className: "rg-toolbar rg-match-tools", children: [step === 3 && ["LineString", "Polygon"].includes(s.tool) && (_jsx("button", { type: "button", onClick: () => binding.current?.finishDrawing(), children: t("Finish drawing") })), controls.history && (_jsxs(_Fragment, { children: [_jsx("button", { type: "button", disabled: !s.canUndo, onClick: () => controller.undo(), children: t("Undo") }), _jsx("button", { type: "button", disabled: !s.canRedo, onClick: () => controller.redo(), children: t("Redo") })] })), controls.navigation && (_jsxs(_Fragment, { children: [_jsx("button", { type: "button", onClick: () => binding.current?.navigateHistory(-1), children: t("Previous map view") }), _jsx("button", { type: "button", onClick: () => binding.current?.navigateHistory(1), children: t("Next map view") })] })), (controls.transformation || controls.unsavedIndicator) && (_jsxs("div", { className: "rg-tools-end", children: [controls.transformation && step === 1 && (_jsxs("label", { className: "rg-inline-field", children: [t("Transformation"), _jsx("select", { value: d.model, onChange: (e) => controller.setModel(e.target.value), children: Object.entries(MODELS).map(([key, value]) => (_jsxs("option", { value: key, children: [t(value.label), " \u00B7 ", value.minimum, "+"] }, key))) })] })), controls.unsavedIndicator && unsaved] }))] })) : null;
+    return (_jsxs("section", { className: `rg-editor ${guided ? "rg-guided" : ""} ${className}`, "aria-label": t("Georeferencing editor"), onKeyDownCapture: (e) => {
+            if (guided && e.key === "Escape" && s.pendingImagePoint) {
+                controller.setPendingPoint(null);
+                e.preventDefault();
+                e.stopPropagation();
+            }
+        }, onKeyDown: (e) => {
+            if (e.key === "Escape") {
+                binding.current?.cancelDrawing();
+                e.stopPropagation();
+            }
+        }, children: [guided ? (_jsxs(_Fragment, { children: [_jsx("ol", { className: "rg-steps", "aria-label": t("Georeferencing steps"), children: steps.map((label, i) => {
+                            const state = i < step ? "done" : i === step ? "current" : "todo";
+                            const back = i < step && i === 1
+                                ? goToMatching
+                                : i < step && i === 2
+                                    ? goToReview
+                                    : undefined;
+                            const content = (_jsxs(_Fragment, { children: [_jsx("span", { className: "rg-step-index", "aria-hidden": "true", children: state === "done" ? "✓" : i + 1 }), _jsx("span", { className: "rg-step-label", children: t(label) })] }));
+                            return (_jsx("li", { "data-state": state, "aria-current": state === "current" ? "step" : undefined, children: back ? (_jsx("button", { type: "button", className: "rg-step-button", onClick: back, children: content })) : (content) }, label));
+                        }) }), _jsxs("div", { className: "rg-matching-bar", children: [_jsxs("div", { className: "rg-instruction", role: "status", "aria-live": "polite", children: [_jsx("strong", { children: t(instruction[0]) }), _jsxs("p", { children: [t(instruction[1]), s.pendingImagePoint && (_jsxs(_Fragment, { children: [" ", _jsx("button", { type: "button", className: "rg-link", onClick: () => controller.setPendingPoint(null), children: t("Cancel this point") })] }))] })] }), _jsxs("div", { className: "rg-step-actions", children: [step === 1 && (_jsx(PreviewControls, { controller: controller, t: t, modeSelector: controls.previewMode, onReview: () => {
+                                            setStage("review");
+                                            setMobileView("map");
+                                        } })), step === 2 && (_jsxs(_Fragment, { children: [_jsx("button", { type: "button", onClick: goToMatching, children: t("Adjust points") }), _jsx("button", { type: "button", onClick: () => binding.current?.fitOverlay(), children: t("Zoom map to image") }), _jsx("button", { type: "button", className: "rg-primary", disabled: !s.fit || s.fitRevision !== d.alignmentRevision, onClick: finish, children: t("Looks good, continue") })] })), step === 3 && (_jsx("button", { type: "button", onClick: goToReview, children: t("Back to check") }))] })] }), error && (_jsx("p", { className: "rg-error", role: "alert", children: error })), toolRow, _jsxs("fieldset", { className: "rg-view-tabs", "aria-label": t("Workspace view"), children: [_jsx("button", { type: "button", "aria-pressed": mobileView === "image", onClick: () => setMobileView("image"), children: t("Image") }), _jsxs("button", { type: "button", "aria-pressed": mobileView === "map", onClick: () => setMobileView("map"), children: [t("Map"), s.pendingImagePoint ? ` · ${t("Pick here next")}` : ""] })] }), _jsxs("div", { className: "rg-paired-views", "data-mobile-view": mobileView, children: [_jsx("div", { className: "rg-source-pane", "data-active": s.tool === "gcp" && !s.pendingImagePoint && step === 1, children: _jsx(ImagePanel, { controller: controller, t: t, navigation: controls.navigation, displayAdjustment: controls.displayAdjustment, emptyActions: emptyImageActions }) }), _jsx("div", { className: "rg-reference-pane", "data-active": !!s.pendingImagePoint, children: referenceView })] }), step === 2 && s.fit && (_jsxs("div", { className: "rg-review-panels", children: [_jsxs("section", { className: "rg-card", children: [_jsx("h2", { children: t("Accuracy") }), _jsx(AccuracySummary, { fit: s.fit, model: d.model, gcps: d.gcps, workingCrs: d.workingCrs, t: t }), _jsxs("label", { className: "rg-inline", children: [_jsx("input", { type: "checkbox", checked: s.visible, onChange: (e) => controller.setDisplay({ visible: e.target.checked }) }), t("Show aligned image on the map")] }), _jsxs("label", { children: [t("Image opacity"), _jsx("input", { "aria-label": t("Overlay opacity"), type: "range", min: "0", max: "1", step: "0.05", value: s.opacity, onChange: (e) => controller.setDisplay({
+                                                    opacity: Number(e.target.value),
+                                                }) })] })] }), _jsx(GcpPanel, { controller: controller, t: t, variant: controls.pointTable ? "table" : "compact", manualEntry: false, tools: false })] })), step === 1 && (d.gcps.length > 0 || controls.manualEntry) && (_jsx(GcpPanel, { controller: controller, t: t, variant: controls.pointTable ? "table" : "compact", manualEntry: controls.manualEntry, tools: false })), step === 3 && (_jsxs("div", { className: "rg-review-panels", children: [s.exportFormats.length > 0 && (_jsxs("section", { className: "rg-card", children: [_jsx("h2", { children: t("Download") }), _jsx(ExportButtons, { controller: controller, t: t, formats: primaryFormats, onExport: onExport, primary: () => true, status: false }), otherFormats.length > 0 && (_jsxs(_Fragment, { children: [_jsx("h3", { children: t("More downloads") }), _jsx(ExportButtons, { controller: controller, t: t, formats: otherFormats, onExport: onExport, status: false })] })), _jsx(ExportProgress, { controller: controller, t: t }), controls.outputSettings && primaryFormats.length > 0 && (_jsxs("details", { children: [_jsx("summary", { children: t("Output settings") }), _jsx(OutputFields, { controller: controller, t: t, definitions: bindingOptions.definitions })] }))] })), controller.options.digitizing && (_jsx("div", { className: "rg-card", children: _jsx(FeaturePanel, { controller: controller, propertyEditor: propertyEditor, t: t }) }))] })), controls.referenceStatus && (_jsxs("details", { className: "rg-advanced", children: [_jsx("summary", { children: t("Reference sources") }), _jsx(ReferencePanel, { controller: controller, t: t })] })), controls.sessionFiles && (_jsxs("details", { className: "rg-export", children: [_jsx("summary", { children: t("Session files") }), step < 3 && (_jsx(ExportButtons, { controller: controller, t: t, formats: s.exportFormats.filter((format) => format.requiresFit === false), onExport: onExport, status: false })), step < 3 && _jsx(ExportProgress, { controller: controller, t: t }), _jsx(SessionTools, { controller: controller, t: t })] }))] })) : (_jsxs(_Fragment, { children: [_jsxs("header", { className: "rg-editor-heading", children: [_jsxs("div", { children: [_jsx("span", { className: "rg-eyebrow", children: t("GEOREFERENCE") }), _jsx("h1", { children: t("Place the image. Trace the detail.") })] }), unsaved] }), _jsxs("div", { className: "rg-toolbar rg-history", children: [_jsx("button", { type: "button", disabled: !s.canUndo, onClick: () => controller.undo(), children: t("Undo") }), _jsx("button", { type: "button", disabled: !s.canRedo, onClick: () => controller.redo(), children: t("Redo") }), _jsx("button", { type: "button", disabled: !s.preview, onClick: () => binding.current?.fitOverlay(), children: t("Fit map to image") }), _jsx("button", { type: "button", onClick: () => binding.current?.navigateHistory(-1), children: t("Previous map view") }), _jsx("button", { type: "button", onClick: () => binding.current?.navigateHistory(1), children: t("Next map view") }), ["LineString", "Polygon"].includes(s.tool) && (_jsx("button", { type: "button", onClick: () => binding.current?.finishDrawing(), children: t("Finish drawing") }))] }), _jsxs("div", { className: "rg-workbench", children: [_jsx(ImagePanel, { controller: controller, t: t, emptyActions: emptyImageActions }), _jsxs("div", { className: "rg-settings", children: [_jsx(AlignmentPanel, { controller: controller, t: t }), _jsx(FeaturePanel, { controller: controller, propertyEditor: propertyEditor, t: t })] })] }), _jsx(ReferencePanel, { controller: controller, t: t }), _jsx(GcpPanel, { controller: controller, t: t }), _jsxs("details", { className: "rg-export", children: [_jsx("summary", { children: t("Raster output & session files") }), s.exportFormats.some((format) => format.raster) && (_jsx(OutputFields, { controller: controller, t: t, definitions: bindingOptions.definitions })), _jsx(ExportButtons, { controller: controller, t: t, formats: s.exportFormats, onExport: onExport }), _jsx(SessionTools, { controller: controller, t: t })] })] })), _jsx("div", { className: "rg-status", role: "status", "aria-live": "polite", children: guided
+                    ? s.loading === "running"
+                        ? t("Inspecting local image…")
+                        : s.exporting === "succeeded"
+                            ? t("Export complete.")
+                            : null
+                    : (error ??
+                        (s.loading === "running"
+                            ? t("Inspecting local image…")
+                            : s.exporting === "succeeded"
+                                ? t("Raster export complete.")
+                                : t("Image processing stays on this device."))) }), _jsxs("dialog", { ref: dialog, className: "rg-guard", onCancel: (e) => {
+                    e.preventDefault();
+                    decide("cancel");
+                }, "aria-labelledby": guardTitle, children: [_jsx("h2", { id: guardTitle, children: t("Protect unsaved work") }), _jsx("p", { children: t("Save or discard the current document before replacing it.") }), !guard?.context.canSave && (_jsx("p", { children: t("Saving is unavailable for this draft. Cancel to export a session, or discard.") })), _jsxs("div", { className: "rg-toolbar", children: [_jsx("button", { type: "button", onClick: () => decide("cancel"), children: t("Cancel") }), _jsx("button", { type: "button", onClick: () => decide("discard"), children: t("Discard") }), _jsx("button", { type: "button", disabled: !guard?.context.canSave, onClick: () => decide("save"), children: t(guard?.context.saveKind === "draft"
+                                    ? "Save draft and continue"
+                                    : "Save and continue") })] })] })] }));
+}

package/dist/components/accuracy.d.ts

@@ -0,0 +1,15 @@
+import type { Fit, Gcp, Model } from "@georeferencing/core";
+import type { Translate } from "../localization.js";
+/**
+ * Whether residuals are necessarily zero: thin plate splines interpolate every point,
+ * and every other model matches exactly its minimum number of points.
+ */
+export declare function exactFit(model: Model, gcps: readonly Gcp[]): boolean;
+/** Plain-language fit quality from the root mean square of image-pixel residuals. */
+export declare function AccuracySummary({ fit, model, gcps, workingCrs, t, }: {
+    fit: Fit;
+    model: Model;
+    gcps: readonly Gcp[];
+    workingCrs: string;
+    t: Translate;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/components/accuracy.js

@@ -0,0 +1,39 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { coordinateUnits, MODELS } from "@georeferencing/core";
+/**
+ * Whether residuals are necessarily zero: thin plate splines interpolate every point,
+ * and every other model matches exactly its minimum number of points.
+ */
+export function exactFit(model, gcps) {
+    return (model === "thinPlateSpline" ||
+        gcps.filter((p) => p.enabled).length <= MODELS[model].minimum);
+}
+/** Plain-language fit quality from the root mean square of image-pixel residuals. */
+export function AccuracySummary({ fit, model, gcps, workingCrs, t, }) {
+    if (exactFit(model, gcps))
+        return (_jsxs("div", { className: "rg-accuracy", "data-quality": "unknown", children: [_jsx("strong", { children: t("Accuracy not measured yet") }), _jsx("p", { children: t(model === "thinPlateSpline"
+                        ? "Thin plate spline passes through every point, so it cannot report an error. Judge the overlay visually."
+                        : "The alignment passes exactly through the minimum number of points. Add another point to measure accuracy.") })] }));
+    const pixels = fit.residuals
+        .map((r) => r.pixels)
+        .filter((v) => typeof v === "number");
+    const rms = pixels.length
+        ? Math.sqrt(pixels.reduce((sum, v) => sum + v * v, 0) / pixels.length)
+        : undefined;
+    const quality = rms === undefined
+        ? "unknown"
+        : rms <= 2
+            ? "good"
+            : rms <= 5
+                ? "fair"
+                : "poor";
+    return (_jsxs("div", { className: "rg-accuracy", "data-quality": quality, children: [_jsx("strong", { children: rms === undefined
+                    ? t("Alignment ready")
+                    : `${t(quality === "good"
+                        ? "Good fit"
+                        : quality === "fair"
+                            ? "Fair fit"
+                            : "Poor fit")} · ${t("average error")} ${rms.toFixed(1)} px` }), _jsx("p", { children: t(quality === "poor"
+                    ? "Points disagree. Check the points with the largest residuals, or add more points."
+                    : "Average distance between your map points and where the alignment places them, in image pixels.") }), _jsxs("small", { children: ["RMSE ", fit.rmse.toFixed(2), " ", coordinateUnits(workingCrs), " \u00B7 ", workingCrs] })] }));
+}

package/dist/components/exports.d.ts

@@ -0,0 +1,32 @@
+import type { Definitions, ExportFormat, ExportResult, GeoreferencerController } from "@georeferencing/core";
+import type { Translate } from "../localization.js";
+/** Raster output settings shared by every raster export format. */
+export declare function OutputFields({ controller, t, definitions, }: {
+    controller: GeoreferencerController;
+    t: Translate;
+    definitions?: Definitions;
+}): import("react/jsx-runtime").JSX.Element;
+/** One button per configured format; results go to `onExport` or browser downloads. */
+export declare function ExportButtons({ controller, t, formats, onExport, primary, status, }: {
+    controller: GeoreferencerController;
+    t: Translate;
+    formats: readonly ExportFormat[];
+    onExport?: (result: ExportResult) => void | Promise<void>;
+    /** Formats rendered as primary buttons. */
+    primary?: (format: ExportFormat) => boolean;
+    /**
+     * Include the cancel button and progress bar. Disable when several button groups
+     * share one {@link ExportProgress}.
+     */
+    status?: boolean;
+}): import("react/jsx-runtime").JSX.Element | null;
+/** Progress bar and cancel button while an export runs; renders nothing when idle. */
+export declare function ExportProgress({ controller, t, }: {
+    controller: GeoreferencerController;
+    t: Translate;
+}): import("react/jsx-runtime").JSX.Element | null;
+/** Restore a session with its image, import QGIS `.points` and save a host draft. */
+export declare function SessionTools({ controller, t, }: {
+    controller: GeoreferencerController;
+    t: Translate;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/components/exports.js

@@ -0,0 +1,152 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { coordinateUnits, importPoints } from "@georeferencing/core";
+import { useRef } from "react";
+import { useGeoreferencer } from "../hooks/useGeoreferencer.js";
+import { downloadBlob } from "../utils/downloadBlob.js";
+import { NumberField, TextField } from "./fields.js";
+const run = (controller, fn) => {
+    try {
+        fn();
+    }
+    catch (e) {
+        controller.reportError(e);
+    }
+};
+/** Raster output settings shared by every raster export format. */
+export function OutputFields({ controller, t, definitions, }) {
+    const s = useGeoreferencer(controller);
+    const output = s.document.output;
+    const geotiff = s.exportFormats.some((format) => format.id === "geotiff");
+    return (_jsxs("div", { className: "rg-output-fields", children: [_jsxs("label", { children: [t("Output CRS"), _jsx(TextField, { label: t("Output CRS"), value: output.crs, change: (crs) => run(controller, () => {
+                            if (!crs)
+                                throw Error("Output CRS is required.");
+                            controller.setOutput({ ...output, crs });
+                        }) })] }), _jsxs("label", { children: [t("Resampling"), _jsx("select", { value: output.resampler, onChange: (e) => controller.setOutput({
+                            ...output,
+                            resampler: e.target.value,
+                        }), children: ["nearest", "bilinear", "cubic", "cubicSpline", "lanczos"].map((m) => (_jsx("option", { children: m }, m))) })] }), geotiff && (_jsxs("label", { children: [t("TIFF compression"), _jsxs("select", { value: output.compression ?? "none", onChange: (e) => controller.setOutput({
+                            ...output,
+                            compression: e.target.value,
+                            predictor: e.target.value === "deflate" ? output.predictor : 1,
+                        }), children: [_jsx("option", { value: "none", children: t("Uncompressed") }), _jsx("option", { value: "deflate", children: t("Deflate (lossless)") }), _jsx("option", { value: "packbits", children: t("PackBits (lossless)") })] })] })), _jsxs("label", { children: [t("Input no-data (byte or R,G,B; blank = alpha)"), _jsx(TextField, { label: t("Input no-data"), value: Array.isArray(output.sourceNoData)
+                            ? output.sourceNoData.join(",")
+                            : String(output.sourceNoData ?? ""), change: (value) => run(controller, () => {
+                            const values = value.split(",").map(Number);
+                            if (value &&
+                                (![1, 3].includes(values.length) ||
+                                    values.some((v) => !Number.isInteger(v) || v < 0 || v > 255)))
+                                throw Error("Input no-data requires one or three bytes (0–255).");
+                            controller.setOutput({
+                                ...output,
+                                sourceNoData: value
+                                    ? values.length === 1
+                                        ? values[0]
+                                        : values
+                                    : undefined,
+                            });
+                        }) })] }), geotiff && (_jsxs("label", { children: [t("Output no-data (byte; blank = alpha)"), _jsx(TextField, { label: t("Output no-data"), value: String(output.noData ?? ""), change: (value) => run(controller, () => {
+                            const n = Number(value);
+                            if (value && (!Number.isInteger(n) || n < 0 || n > 255))
+                                throw Error("Output no-data requires a byte (0–255).");
+                            controller.setOutput({
+                                ...output,
+                                noData: value ? n : undefined,
+                            });
+                        }) })] })), geotiff && (_jsxs(_Fragment, { children: [_jsxs("label", { children: [t("Rows per TIFF strip"), _jsx(NumberField, { label: t("Rows per TIFF strip"), value: output.rowsPerStrip ?? 256, change: (n) => run(controller, () => {
+                                    if (!Number.isInteger(n) || n < 1 || n > 4096)
+                                        throw Error("Rows per strip must be 1–4096.");
+                                    controller.setOutput({ ...output, rowsPerStrip: n });
+                                }) })] }), _jsxs("label", { children: [t("Horizontal TIFF predictor"), _jsx("input", { type: "checkbox", disabled: output.compression !== "deflate", checked: output.predictor === 2, onChange: (e) => controller.setOutput({
+                                    ...output,
+                                    predictor: e.target.checked ? 2 : 1,
+                                }) })] })] })), _jsxs("label", { children: [t("Pixel size (x,y; blank = estimated)"), " \u00B7", " ", coordinateUnits(output.crs, definitions), _jsx(TextField, { label: t("Pixel size"), value: output.resolution?.join(",") ?? "", change: (value) => run(controller, () => {
+                            const values = value.split(",").map(Number);
+                            if (value &&
+                                (values.length > 2 ||
+                                    values.some((v) => !Number.isFinite(v) || v <= 0)))
+                                throw Error("Pixel size requires one or two positive numbers.");
+                            controller.setOutput({
+                                ...output,
+                                resolution: value
+                                    ? [values[0], values[1] ?? values[0]]
+                                    : undefined,
+                            });
+                        }) })] }), _jsxs("label", { children: [t("Output bounds (minX,minY,maxX,maxY; blank = footprint)"), _jsx(TextField, { label: t("Output bounds"), value: output.bounds?.join(",") ?? "", change: (value) => run(controller, () => {
+                            const values = value.split(",").map(Number);
+                            if (value &&
+                                (values.length !== 4 ||
+                                    values.some((v) => !Number.isFinite(v)) ||
+                                    values[0] >= values[2] ||
+                                    values[1] >= values[3]))
+                                throw Error("Bounds require four finite numbers with min < max.");
+                            controller.setOutput({
+                                ...output,
+                                bounds: value
+                                    ? values
+                                    : undefined,
+                            });
+                        }) })] })] }));
+}
+/** One button per configured format; results go to `onExport` or browser downloads. */
+export function ExportButtons({ controller, t, formats, onExport, primary = () => false, status = true, }) {
+    const s = useGeoreferencer(controller);
+    if (!formats.length)
+        return null;
+    return (_jsxs(_Fragment, { children: [_jsxs("div", { className: "rg-toolbar", children: [formats.map((format) => {
+                        const unavailable = controller.getExportUnavailable(format.id);
+                        return (_jsx("button", { type: "button", className: primary(format) ? "rg-primary" : undefined, "data-export-format": format.id, title: unavailable ? t(unavailable) : undefined, disabled: Boolean(unavailable) || s.exporting === "running", onClick: () => void controller
+                                .export(format.id)
+                                .then(async (result) => {
+                                if (!result)
+                                    return;
+                                if (onExport)
+                                    await onExport(result);
+                                else
+                                    for (const file of result.files)
+                                        downloadBlob(file.blob, file.name);
+                            })
+                                .catch((error) => controller.reportError(error)), children: t(format.label) }, format.id));
+                    }), status && (_jsx("button", { type: "button", disabled: s.exporting !== "running", onClick: () => controller.cancelExport(), children: t("Cancel export") }))] }), status && s.exporting === "running" && (_jsx("progress", { "aria-label": t("Export progress"), value: s.progress, max: "1" }))] }));
+}
+/** Progress bar and cancel button while an export runs; renders nothing when idle. */
+export function ExportProgress({ controller, t, }) {
+    const s = useGeoreferencer(controller);
+    if (s.exporting !== "running")
+        return null;
+    return (_jsxs("div", { className: "rg-export-progress", children: [_jsx("progress", { "aria-label": t("Export progress"), value: s.progress, max: "1" }), _jsx("button", { type: "button", onClick: () => controller.cancelExport(), children: t("Cancel export") })] }));
+}
+/** Restore a session with its image, import QGIS `.points` and save a host draft. */
+export function SessionTools({ controller, t, }) {
+    const s = useGeoreferencer(controller);
+    const sessionInput = useRef(null);
+    const pendingSession = useRef(null);
+    return (_jsxs("div", { className: "rg-toolbar", children: [_jsxs("label", { className: "rg-file", children: [t("Restore session"), _jsx("input", { type: "file", "aria-label": t("Restore session"), accept: ".json", onChange: async (e) => {
+                            const file = e.target.files?.[0];
+                            if (file) {
+                                pendingSession.current = await file.text();
+                                sessionInput.current?.click();
+                            }
+                            e.target.value = "";
+                        } })] }), _jsx("input", { ref: sessionInput, "aria-label": t("Matching session image"), type: "file", hidden: true, accept: "image/*,.tif,.tiff", onChange: (e) => {
+                    const file = e.target.files?.[0];
+                    if (file && pendingSession.current)
+                        void controller
+                            .restoreSession(pendingSession.current, file)
+                            .catch((e) => controller.reportError(e));
+                    e.target.value = "";
+                } }), _jsxs("label", { className: "rg-file", children: [t("Import .points"), _jsx("input", { type: "file", "aria-label": t("Import .points"), accept: ".points,.csv", disabled: !s.document.sourceImage || s.mode === "draw", onChange: async (e) => {
+                            const f = e.target.files?.[0];
+                            if (f) {
+                                try {
+                                    const imported = importPoints(await f.text(), s.document.workingCrs);
+                                    controller.replaceGcps(imported.gcps);
+                                }
+                                catch (e) {
+                                    controller.reportError(e);
+                                }
+                            }
+                            e.target.value = "";
+                        } })] }), controller.options.onSaveDraft && (_jsx("button", { type: "button", disabled: !s.document.sourceImage || s.saving === "running", onClick: () => void controller
+                    .save("draft")
+                    .catch((e) => controller.reportError(e)), children: t("Save draft") }))] }));
+}

package/dist/components/fields.d.ts

@@ -0,0 +1,17 @@
+export declare function TextField({ value, label, change, }: {
+    value: string;
+    label: string;
+    change: (value: string) => void;
+}): import("react/jsx-runtime").JSX.Element;
+/**
+ * Retain an editable numeric draft and commit only finite values the user changed, on
+ * blur/Enter. `decimals` rounds the displayed value; an untouched rounded display never
+ * overwrites the stored full-precision value.
+ */
+export declare function NumberField({ value, label, change, disabled, decimals, }: {
+    value: number;
+    label: string;
+    change: (value: number) => void;
+    disabled?: boolean;
+    decimals?: number;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/components/fields.js

@@ -0,0 +1,35 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useState } from "react";
+export function TextField({ value, label, change, }) {
+    const [draft, setDraft] = useState(value);
+    useEffect(() => setDraft(value), [value]);
+    return (_jsx("input", { "aria-label": label, value: draft, onChange: (e) => setDraft(e.target.value), onBlur: () => {
+            if (draft.trim() !== value)
+                change(draft.trim());
+        }, onKeyDown: (e) => {
+            if (e.key === "Enter")
+                e.currentTarget.blur();
+        } }));
+}
+/**
+ * Retain an editable numeric draft and commit only finite values the user changed, on
+ * blur/Enter. `decimals` rounds the displayed value; an untouched rounded display never
+ * overwrites the stored full-precision value.
+ */
+export function NumberField({ value, label, change, disabled = false, decimals, }) {
+    const shown = decimals === undefined
+        ? String(value)
+        : String(Number(value.toFixed(decimals)));
+    const [draft, setDraft] = useState(shown);
+    useEffect(() => setDraft(shown), [shown]);
+    return (_jsx("input", { "aria-label": label, type: "number", step: "any", disabled: disabled, value: draft, onChange: (e) => setDraft(e.target.value), onBlur: () => {
+            const n = Number(draft);
+            if (draft.trim() && draft.trim() !== shown && Number.isFinite(n))
+                change(n);
+            else
+                setDraft(shown);
+        }, onKeyDown: (e) => {
+            if (e.key === "Enter")
+                e.currentTarget.blur();
+        } }));
+}

package/dist/controls.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Optional controls of the guided `Georeferencer` layout (used when `referenceView` is
+ * supplied). Each flag adds expert controls on top of the minimal step-by-step flow;
+ * omitted flags fall back to {@link MINIMAL_CONTROLS}. The classic layout always shows
+ * every control.
+ */
+export interface GeoreferencerControls {
+    /** Undo and redo buttons for point and drawing edits. */
+    history: boolean;
+    /**
+     * Manual/automatic preview selector. When hidden, the controller's configured
+     * `previewMode` applies and users run alignment with the main button.
+     */
+    previewMode: boolean;
+    /** Transformation model selector while matching points. Hidden keeps the controller's model. */
+    transformation: boolean;
+    /**
+     * Full control point table with editable coordinates, target CRS and residual columns.
+     * When hidden, a compact list shows each point's use state and residual.
+     */
+    pointTable: boolean;
+    /** Add a point pair by typing coordinates; the keyboard alternative to clicking. */
+    manualEntry: boolean;
+    /** Previous/next image and map views and linked image/map navigation. */
+    navigation: boolean;
+    /** Brightness, contrast and histogram stretch for the source image display. */
+    displayAdjustment: boolean;
+    /** Load status of configured reference providers. */
+    referenceStatus: boolean;
+    /** Raster output settings: CRS, resampling, compression, no-data, pixel size and bounds. */
+    outputSettings: boolean;
+    /** Restore a session, import QGIS `.points` and save drafts; also offers session downloads before the last step. */
+    sessionFiles: boolean;
+    /** Indicator for work that has not been saved by the host. */
+    unsavedIndicator: boolean;
+}
+/** Default guided setup: the four-step flow with undo/redo and nothing else. */
+export declare const MINIMAL_CONTROLS: Readonly<GeoreferencerControls>;
+/** Every optional guided control enabled. */
+export declare const ALL_CONTROLS: Readonly<GeoreferencerControls>;

package/dist/controls.js

@@ -0,0 +1,28 @@
+/** Default guided setup: the four-step flow with undo/redo and nothing else. */
+export const MINIMAL_CONTROLS = Object.freeze({
+    history: true,
+    previewMode: false,
+    transformation: false,
+    pointTable: false,
+    manualEntry: false,
+    navigation: false,
+    displayAdjustment: false,
+    referenceStatus: false,
+    outputSettings: false,
+    sessionFiles: false,
+    unsavedIndicator: false,
+});
+/** Every optional guided control enabled. */
+export const ALL_CONTROLS = Object.freeze({
+    history: true,
+    previewMode: true,
+    transformation: true,
+    pointTable: true,
+    manualEntry: true,
+    navigation: true,
+    displayAdjustment: true,
+    referenceStatus: true,
+    outputSettings: true,
+    sessionFiles: true,
+    unsavedIndicator: true,
+});

package/dist/hooks/useGeoreferencer.d.ts

@@ -0,0 +1,6 @@
+import type { GeoreferencerController } from "@georeferencing/core";
+/**
+ * Subscribe to a controller with React useSyncExternalStore and read its stable
+ * EditorSnapshot. The hook does not attach maps or own controller lifecycle.
+ */
+export declare function useGeoreferencer(controller: GeoreferencerController): import("@georeferencing/core").EditorSnapshot;

package/dist/hooks/useGeoreferencer.js

@@ -0,0 +1,8 @@
+import { useSyncExternalStore } from "react";
+/**
+ * Subscribe to a controller with React useSyncExternalStore and read its stable
+ * EditorSnapshot. The hook does not attach maps or own controller lifecycle.
+ */
+export function useGeoreferencer(controller) {
+    return useSyncExternalStore(controller.subscribe, controller.getSnapshot, controller.getSnapshot);
+}