@georeferencing/react 0.1.0 → 0.2.0

package/README.md

@@ -149,35 +149,88 @@ sidecars. Export completion never acknowledges host persistence. See the
 [plugins README](https://github.com/tobilg/georeferencing/blob/main/packages/plugins/README.md)
 for format settings, cancellation and limits.
 
-## Guided matching and preview policy
-
-The Hamburg demo uses `previewMode: "manual"` in its core controller. The visible
-**Preview updates** selector changes that policy through `setPreviewMode`.
-`PreviewControls` is also exported for custom layouts; it displays minimum-point
-readiness and an explicit **Run alignment** action. Worker validation reports
-singular or unusable arrangements when a run is requested. Automatic mode updates
-eligible previews after committed edits without advancing the user's review step.
-
-Supply `referenceView` to `Georeferencer` to opt into the guided layout. It is a
-React node containing the host's map target and optional map controls; the host
-still owns the map and must attach its target before editor effects run (a React
-callback ref is suitable). Without this prop, the existing panel layout remains.
-See the [complete demo host](https://github.com/tobilg/georeferencing/blob/main/packages/demo/main.tsx)
+## Guided four-step layout
+
+Supply `referenceView` to `Georeferencer` to use the guided layout. It is a React
+node containing the host's map target and optional map controls; the host still
+owns the map and must attach its target before editor effects run (a React
+callback ref is suitable). Without this prop, the classic workbench with every
+control remains. See the
+[complete demo host](https://github.com/tobilg/georeferencing/blob/main/packages/demo/main.tsx)
 for a typed integration with target attachment and cleanup.
 
-The guided layout automatically starts image-first/map-second matching after an
-accepted image load, announces the next endpoint, supports Escape to cancel an
-incomplete pair, and keeps both views side by side on desktop. Below 720 px,
-image/map buttons switch the visible pane and follow pending pairs without
-unmounting either viewer. The sticky run toolbar remains accessible while editing
-the point table. After running, review the overlay and residuals, edit/rerun as
-needed, then export or explicitly accept alignment to draw. Drawing controls are
-shown after acceptance; session files remain available during unfinished work.
-
-`AlignmentPanel` accepts `controls={false}` when transformation and preview
-controls are already rendered elsewhere. `PreviewControls.onReview` is called
-only for a successful preview matching the requested document/alignment revision.
-These panels never take map or engine ownership.
+The guided layout leads users through four steps, each with one main action in a
+sticky bar:
+
+1. **Load image**: drop zone with **Choose image** and any `emptyImageActions`
+   (for example a sample-image button).
+2. **Match points**: click a spot in the image, then the same spot on the map.
+   Progress shows how many points the model needs; **Run alignment** fits them.
+3. **Check alignment**: the overlay on the map, a plain-language accuracy summary
+   (average residual in image pixels, or a hint to add a point when the fit is
+   exact) and the point list. **Adjust points** goes back; **Looks good, continue**
+   confirms the alignment.
+4. **Export or draw**: download buttons for the configured formats and, with
+   `digitizing`, drawing tools and **Save features**. **Back to check** returns.
+
+Completed steps in the step bar are clickable. Desktop keeps both views side by
+side; below 720 px, Image/Map buttons switch panes and follow pending points.
+In both views, dragging pans and scrolling zooms; a click without dragging places
+a point.
+
+OpenLayers' `Map` creates its default interactions with `onFocusOnly: true`. If
+the map target has a `tabindex` (for keyboard navigation), mouse panning and wheel
+zoom then only work after the map has focus. Create the host map with
+`interactions: defaults({ onFocusOnly: false })` from `ol/interaction/defaults.js`,
+as the demo does, so both work immediately.
+
+### Choose the controls
+
+The guided layout starts minimal. Add expert controls individually with
+`controls`; omitted flags fall back to `MINIMAL_CONTROLS`:
+
+```tsx
+import { ALL_CONTROLS, Georeferencer } from "@georeferencing/react";
+
+<Georeferencer
+  controller={controller}
+  referenceMap={map}
+  referenceView={mapView}
+  controls={{ transformation: true, outputSettings: true }}
+/>;
+// Every control: controls={ALL_CONTROLS}
+```
+
+| Flag | Default | Adds |
+| --- | --- | --- |
+| `history` | on | Undo and redo |
+| `previewMode` | off | Manual/automatic preview selector (otherwise the controller's `previewMode` applies) |
+| `transformation` | off | Transformation model selector while matching |
+| `pointTable` | off | Full point table with editable coordinates, CRS and residuals (otherwise a compact list) |
+| `manualEntry` | off | Add a point pair by typing coordinates, the keyboard alternative to clicking |
+| `navigation` | off | Previous/next image and map views, linked navigation |
+| `displayAdjustment` | off | Brightness, contrast and histogram stretch |
+| `referenceStatus` | off | Load status of reference providers |
+| `outputSettings` | off | Raster output CRS, resampling, compression, no-data, pixel size and bounds |
+| `sessionFiles` | off | Restore session, import `.points`, save draft and early session downloads |
+| `unsavedIndicator` | off | Unsaved-changes indicator |
+
+Enable `manualEntry` when keyboard-only point entry is required.
+
+### Preview policy and panels
+
+`previewMode: "manual"` on the controller waits for **Run alignment**;
+`"automatic"` updates eligible previews after committed edits without advancing
+the user's step. Worker validation reports singular or unusable arrangements when
+a run is requested.
+
+The composable panels keep every control by default and accept the same opt-outs:
+`GcpPanel` takes `variant` (`"table"` or `"compact"`), `manualEntry` and `tools`;
+`ImagePanel` takes `navigation`, `displayAdjustment` and `emptyActions`;
+`PreviewControls` takes `modeSelector` and calls `onReview` only for a successful
+preview matching the requested revision. `AlignmentPanel` accepts
+`controls={false}` when transformation and preview controls are rendered
+elsewhere. These panels never take map or engine ownership.
 
 ## References, projections and snapping
 

package/dist/Georeferencer.d.ts

@@ -2,6 +2,7 @@ import type { ExportResult, GeoreferencerController } from "@georeferencing/core
 import type { BindingOptions } from "@georeferencing/core/openlayers";
 import type OLMap from "ol/Map.js";
 import type { ReactNode } from "react";
+import type { GeoreferencerControls } from "./controls.js";
 import type { Translate } from "./localization.js";
 import { FeaturePanel } from "./panels/FeaturePanel.js";
 /**
@@ -10,11 +11,23 @@ import { FeaturePanel } from "./panels/FeaturePanel.js";
  */
 export interface GeoreferencerProps {
     /**
-     * Opt into a guided matching/review layout by supplying the host map's rendered
-     * target and controls. The host still creates, targets and disposes the map. This
-     * slot stays mounted across matching/review and responsive image/map tabs.
+     * Opt into the guided four-step layout (load, match, check, export/draw) by supplying
+     * the host map's rendered target and controls. The host still creates, targets and
+     * disposes the map. This slot stays mounted across all steps and responsive
+     * image/map tabs.
      */
     referenceView?: ReactNode;
+    /**
+     * Optional controls of the guided layout. Omitted flags use {@link MINIMAL_CONTROLS};
+     * pass {@link ALL_CONTROLS} for every expert control. The classic layout always shows
+     * all controls.
+     */
+    controls?: Partial<GeoreferencerControls>;
+    /**
+     * Extra actions shown in the empty image drop zone next to "Choose image", for example
+     * a button that loads a sample image.
+     */
+    emptyImageActions?: ReactNode;
     /**
      * Host-owned authoritative controller; the component resumes/suspends it but does not
      * permanently dispose it.
@@ -53,6 +66,6 @@ export interface GeoreferencerProps {
 /**
  * Ready-made React editor for an existing OpenLayers map. Composes image, GCP, alignment, reference, output and optional drawing controls.
  *
- * 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`.
+ * 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 declare function Georeferencer({ controller, referenceMap, bindingOptions, t, className, propertyEditor, onExport, formatError, referenceView, }: GeoreferencerProps): import("react/jsx-runtime").JSX.Element;
+export declare function Georeferencer({ controller, referenceMap, bindingOptions, t, className, propertyEditor, onExport, formatError, referenceView, controls: controlOverrides, emptyImageActions, }: GeoreferencerProps): import("react/jsx-runtime").JSX.Element;

package/dist/Georeferencer.js

@@ -1,8 +1,10 @@
-import { jsxs as _jsxs, jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
-import { coordinateUnits, importPoints, MODELS } from "@georeferencing/core";
+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 { NumberField, TextField } from "./components/fields.js";
+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";
@@ -11,32 +13,39 @@ import { GcpPanel } from "./panels/GcpPanel.js";
 import { ImagePanel } from "./panels/ImagePanel.js";
 import { PreviewControls } from "./panels/PreviewControls.js";
 import { ReferencePanel } from "./panels/ReferencePanel.js";
-import { downloadBlob } from "./utils/downloadBlob.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.
  *
- * 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`.
+ * 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, }) {
+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), sessionInput = useRef(null);
-    const pendingSession = useRef(null);
+    const [guard, setGuard] = useState(null), dialog = useRef(null);
     const guided = referenceView !== undefined;
-    const [editing, setEditing] = useState(true);
-    const [reviewedDocumentRevision, setReviewedDocumentRevision] = useState(null);
+    const controls = { ...MINIMAL_CONTROLS, ...controlOverrides };
+    const [stage, setStage] = useState("match");
     const [mobileView, setMobileView] = useState("image");
-    const imageId = s.document.sourceImage?.id;
+    const d = s.document;
+    const imageId = d.sourceImage?.id;
     const imageReady = Boolean(s.imageUrl);
-    const review = !!s.fit && !editing;
-    const visibleFormats = s.exportFormats.filter((format) => !guided || review || s.mode === "draw" || format.requiresFit === false);
-    const nextPoint = Math.max(0, ...s.document.gcps.map((p) => p.label)) + 1;
+    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;
-        setEditing(true);
-        setReviewedDocumentRevision(null);
+        setStage("match");
         setMobileView("image");
         // A metadata-only restored document still needs its matching local bytes.
         if (imageId && imageReady && controller.getSnapshot().mode === "align")
@@ -46,6 +55,11 @@ export function Georeferencer({ controller, referenceMap, bindingOptions = DEFAU
         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();
@@ -92,6 +106,75 @@ export function Georeferencer({ controller, referenceMap, bindingOptions = DEFAU
             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);
@@ -103,173 +186,32 @@ export function Georeferencer({ controller, referenceMap, bindingOptions = DEFAU
                 binding.current?.cancelDrawing();
                 e.stopPropagation();
             }
-        }, children: [guided ? (_jsxs(_Fragment, { children: [_jsx("ol", { className: "rg-steps", "aria-label": t("Georeferencing steps"), children: [
-                            "Load image",
-                            "Match points",
-                            "Review alignment",
-                            "Export or draw",
-                        ].map((label, i) => (_jsxs("li", { "aria-current": i === (!imageId ? 0 : s.mode === "draw" ? 3 : review ? 2 : 1)
-                                ? "step"
-                                : undefined, children: [i + 1, ". ", t(label)] }, label))) }), _jsxs("div", { className: "rg-matching-bar", children: [_jsxs("div", { className: "rg-instruction", role: "status", "aria-live": "polite", children: [_jsx("strong", { children: !imageReady
-                                            ? t("Choose an image to begin")
-                                            : s.mode === "draw"
-                                                ? t("Draw features on the aligned map")
-                                                : review
-                                                    ? t("Inspect the overlay against the reference map")
-                                                    : s.tool !== "gcp"
-                                                        ? t("Navigation active. Resume matching to add points.")
-                                                        : s.pendingImagePoint
-                                                            ? `${t("Select the matching location on the map")} · ${t("Point")} ${nextPoint}`
-                                                            : `${t("Select a point in the image")} · ${t("Point")} ${nextPoint}` }), _jsx("p", { children: t(reviewedDocumentRevision !== null &&
-                                            reviewedDocumentRevision !== s.document.documentRevision &&
-                                            !s.fit
-                                            ? s.previewMode === "manual"
-                                                ? "Points or settings changed. Run alignment again before reviewing or exporting."
-                                                : "Alignment changed. Wait for the updated preview before reviewing."
-                                            : review
-                                                ? "Check landmarks across the image before exporting or accepting alignment."
-                                                : "Match ground-level corners across the image. Shift-drag to pan; Escape cancels a pending pair.") })] }), !review && s.mode === "align" && (_jsx(PreviewControls, { controller: controller, t: t, onReview: () => {
-                                    setEditing(false);
-                                    setReviewedDocumentRevision(controller.getSnapshot().document.documentRevision);
-                                    setMobileView("map");
-                                } })), review && s.mode === "align" && (_jsx("button", { type: "button", onClick: () => {
-                                    setEditing(true);
-                                    controller.setTool("gcp");
-                                }, children: t("Edit points") }))] }), s.error && (_jsx("p", { className: "rg-error", role: "alert", children: s.errorDetail && formatError
-                            ? formatError(s.errorDetail)
-                            : t(s.error) })), _jsxs("div", { className: "rg-toolbar rg-match-tools", children: [["LineString", "Polygon"].includes(s.tool) && (_jsx("button", { type: "button", onClick: () => binding.current?.finishDrawing(), children: t("Finish drawing") })), _jsx("button", { type: "button", disabled: !imageReady || s.mode === "draw", "aria-pressed": s.tool === "gcp", onClick: () => {
-                                    setEditing(true);
-                                    controller.setTool("gcp");
-                                }, children: t("Match points") }), _jsx("button", { type: "button", disabled: !imageReady || s.mode === "draw", "aria-pressed": s.tool === "navigate", onClick: () => controller.setTool("navigate"), children: t("Pan image") }), _jsx("button", { type: "button", disabled: !s.pendingImagePoint, onClick: () => controller.setPendingPoint(null), children: t("Cancel pending pair") }), _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") }), _jsxs("label", { children: [t("Transformation"), _jsx("select", { disabled: !imageId || s.mode === "draw", value: s.document.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))) })] }), _jsx("span", { className: "rg-dirty", children: t(s.dirty ? "Unsaved changes" : "No unsaved changes") })] }), _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 && !review, children: _jsx(ImagePanel, { controller: controller, t: t }) }), _jsx("div", { className: "rg-reference-pane", "data-active": !!s.pendingImagePoint, children: referenceView })] }), (review || s.mode === "draw") && (_jsxs("div", { className: "rg-review-panels", children: [_jsx(AlignmentPanel, { controller: controller, t: t, controls: false }), s.mode === "draw" && (_jsx(FeaturePanel, { controller: controller, propertyEditor: propertyEditor, t: t }))] })), _jsx(GcpPanel, { controller: controller, t: t }), _jsxs("details", { className: "rg-advanced", children: [_jsx("summary", { children: t("Advanced navigation & reference status") }), _jsxs("div", { className: "rg-toolbar", children: [_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") })] }), _jsx(ReferencePanel, { 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.") })] }), _jsx("span", { className: "rg-dirty", children: t(s.dirty ? "Unsaved changes" : "No unsaved changes") })] }), _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 }), _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(guided && !review && s.mode !== "draw"
-                            ? "Session files"
-                            : "Raster output & session files") }), visibleFormats.some((format) => format.raster) && (_jsxs("div", { className: "rg-output-fields", children: [_jsxs("label", { children: [t("Output CRS"), _jsx(TextField, { label: t("Output CRS"), value: s.document.output.crs, change: (crs) => run(() => {
-                                            if (!crs)
-                                                throw Error("Output CRS is required.");
-                                            controller.setOutput({
-                                                ...s.document.output,
-                                                crs,
-                                            });
-                                        }) })] }), _jsxs("label", { children: [t("Resampling"), _jsx("select", { value: s.document.output.resampler, onChange: (e) => controller.setOutput({
-                                            ...s.document.output,
-                                            resampler: e.target.value,
-                                        }), children: ["nearest", "bilinear", "cubic", "cubicSpline", "lanczos"].map((m) => (_jsx("option", { children: m }, m))) })] }), s.exportFormats.some((format) => format.id === "geotiff") && (_jsxs("label", { children: [t("TIFF compression"), _jsxs("select", { value: s.document.output.compression ?? "none", onChange: (e) => controller.setOutput({
-                                            ...s.document.output,
-                                            compression: e.target.value,
-                                            predictor: e.target.value === "deflate"
-                                                ? s.document.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(s.document.output.sourceNoData)
-                                            ? s.document.output.sourceNoData.join(",")
-                                            : String(s.document.output.sourceNoData ?? ""), change: (value) => run(() => {
-                                            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({
-                                                ...s.document.output,
-                                                sourceNoData: value
-                                                    ? values.length === 1
-                                                        ? values[0]
-                                                        : values
-                                                    : undefined,
-                                            });
-                                        }) })] }), s.exportFormats.some((format) => format.id === "geotiff") && (_jsxs("label", { children: [t("Output no-data (byte; blank = alpha)"), _jsx(TextField, { label: t("Output no-data"), value: String(s.document.output.noData ?? ""), change: (value) => run(() => {
-                                            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({
-                                                ...s.document.output,
-                                                noData: value ? n : undefined,
-                                            });
-                                        }) })] })), s.exportFormats.some((format) => format.id === "geotiff") && (_jsxs(_Fragment, { children: [_jsxs("label", { children: [t("Rows per TIFF strip"), _jsx(NumberField, { label: t("Rows per TIFF strip"), value: s.document.output.rowsPerStrip ?? 256, change: (n) => run(() => {
-                                                    if (!Number.isInteger(n) || n < 1 || n > 4096)
-                                                        throw Error("Rows per strip must be 1–4096.");
-                                                    controller.setOutput({
-                                                        ...s.document.output,
-                                                        rowsPerStrip: n,
-                                                    });
-                                                }) })] }), _jsxs("label", { children: [t("Horizontal TIFF predictor"), _jsx("input", { type: "checkbox", disabled: s.document.output.compression !== "deflate", checked: s.document.output.predictor === 2, onChange: (e) => controller.setOutput({
-                                                    ...s.document.output,
-                                                    predictor: e.target.checked ? 2 : 1,
-                                                }) })] })] })), _jsxs("label", { children: [t("Pixel size (x,y; blank = estimated)"), " \u00B7", " ", coordinateUnits(s.document.output.crs, bindingOptions.definitions), _jsx(TextField, { label: t("Pixel size"), value: s.document.output.resolution?.join(",") ?? "", change: (value) => run(() => {
-                                            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({
-                                                ...s.document.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: s.document.output.bounds?.join(",") ?? "", change: (value) => run(() => {
-                                            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({
-                                                ...s.document.output,
-                                                bounds: value
-                                                    ? values
-                                                    : undefined,
-                                            });
-                                        }) })] })] })), visibleFormats.length > 0 && (_jsxs("div", { className: "rg-toolbar", children: [visibleFormats.map((format) => {
-                                const unavailable = controller.getExportUnavailable(format.id);
-                                return (_jsx("button", { type: "button", "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));
-                            }), _jsx("button", { type: "button", disabled: s.exporting !== "running", onClick: () => controller.cancelExport(), children: t("Cancel export") })] })), s.exporting === "running" && (_jsx("progress", { "aria-label": t("Export progress"), value: s.progress, max: "1" })), _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") }))] })] }), _jsx("div", { className: "rg-status", role: "status", "aria-live": "polite", children: (s.error
-                    ? s.errorDetail && formatError
-                        ? formatError(s.errorDetail)
-                        : t(s.error)
-                    : null) ??
-                    (s.loading === "running"
+        }, 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("Raster export complete.")
-                            : t("Image processing stays on this device.")) }), _jsxs("dialog", { ref: dialog, className: "rg-guard", onCancel: (e) => {
+                            ? 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"

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] })] }));
+}