@ngis/plugin-ui 0.4.0 → 0.4.1

package/dist/src/components/resources/CrsPicker/CrsChip.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The CRS chip and its unit sigil (Stage 25, **F25.2 / F25.13**).
+ *
+ * ## The design thesis, in one rule: round means degrees, square means metres
+ *
+ * Every CRS in the product opens with a **unit sigil** — a small box carrying
+ * the unit glyph (`°` / `m` / `ft` / `?`). A **geographic** CRS gets a
+ * **circle**; a **projected** CRS gets a **square**. That single shape rule is
+ * the whole visual system, and it is chosen for exactly the thing this stage
+ * exists to prevent: G-U says *no distance in degrees*, and a user who has
+ * learned one shape rule sees the hazard across the room before reading a digit.
+ *
+ * Colour reinforces it and never carries it alone. S25-02 verified the rule
+ * under the Iris family, where `--ring` and `--primary` are both violet and the
+ * shape still reads. That is the accessibility floor here, not a nicety: the
+ * distinction this chip draws is the one a colour-blind user most needs.
+ *
+ * `NEEDS_CRS` is drawn as **absence** — a hollow *dashed* circle and muted type
+ * — never as an error. D25-3 makes it a state, not a failure; colouring it
+ * `destructive` would say the opposite, and a user who reads "broken" deletes
+ * the dataset instead of setting its projection.
+ *
+ * ## The grammar is `code · name`
+ *
+ * The code sits in `--font-mono` (tabular, tight), the name in the UI sans,
+ * separated by a middot. The pairing *is* the chip: it reads as
+ * "identifier · human name" rather than one undifferentiated blob. The string
+ * itself comes from {@link formatCrs} and is never assembled here — that is how
+ * the chip and the table cell are kept from drifting, and it is where G-CRS
+ * lives.
+ */
+import { type NgisCrsRef } from "../../../domain/models/crs";
+export interface CrsChipProps {
+    /** `null` renders the NEEDS_CRS state. It is never treated as EPSG:4326. */
+    crs: NgisCrsRef | null;
+    /**
+     * `full` — sigil, code and name (detail panels, the picker footer).
+     * `compact` — sigil and code only (table cells, list rows, `ResourceSelect`).
+     */
+    density?: "full" | "compact";
+    /**
+     * Already-translated. Host-supplied for the same reason `PickerField`'s
+     * notices are: this component holds no translator and cannot invent copy.
+     * Defaults to `formatCrs`'s own English fallback.
+     */
+    needsCrsText?: string;
+    /** Rendered after the text when the CRS is absent — the ⚠ of F25.5's badge. */
+    warn?: boolean;
+    className?: string;
+}
+/**
+ * The sigil alone. Exported inside this folder only — five call sites draw it
+ * (full chip, compact chip, picker trigger, list row, the "needs projection"
+ * filter toggle) and an inlined copy would drift on the first restyle.
+ */
+export declare function CrsUnitSigil({ crs, className, }: {
+    crs: NgisCrsRef | null;
+    className?: string;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function CrsChip({ crs, density, needsCrsText, warn, className, }: CrsChipProps): import("react/jsx-runtime").JSX.Element;

package/dist/src/components/resources/CrsPicker/CrsParamControl.d.ts

@@ -0,0 +1,10 @@
+import type { NgisCrsRequirement } from "../../../domain/models/crs";
+export interface CrsParamControlProps {
+    /** The wire value: a `NgisCrsRef.key`, or `null` for "compute in the input's own CRS". */
+    value: string | null;
+    onChange: (value: string | null) => void;
+    requirement?: NgisCrsRequirement;
+    id?: string;
+    contentClassName?: string;
+}
+export declare function CrsParamControl({ value, onChange, requirement, id, contentClassName, }: CrsParamControlProps): import("react/jsx-runtime").JSX.Element;

package/dist/src/components/resources/CrsPicker/CrsPicker.d.ts

@@ -0,0 +1,41 @@
+import { type NgisCrsRef, type NgisCrsRequirement } from "../../../domain/models/crs";
+import type { NgisBounds } from "../../../sdk/map-api";
+export type CrsPickerMode = "select" | "assign";
+export interface CrsPickerProps {
+    /**
+     * `select` — choose a CRS to compute/export in. `assign` — declare what a
+     * dataset's coordinates already are. **The two never share copy** (G-A).
+     */
+    mode: CrsPickerMode;
+    /** `null` is a real value in `select` mode: "compute in the input's own CRS". */
+    value: NgisCrsRef | null;
+    onChange: (value: NgisCrsRef | null) => void;
+    /** Enables the Suggested tab, and makes it the default. `[w, s, e, n]` in EPSG:4326. */
+    suggestFrom?: NgisBounds;
+    /** Default `true`. The Custom tab reaches the oracle's resolve leg. */
+    allowCustom?: boolean;
+    /** The tool's `x-crs-requirement`. Filters Search, and the picker says so. */
+    requirement?: NgisCrsRequirement;
+    /** Named in `assign` mode's header — the thing being labelled. */
+    datasetName?: string;
+    /** Control id, so a `<label for>` reaches the trigger. */
+    id?: string;
+    className?: string;
+    /**
+     * Class for the portalled dialog content. Radix portals to `document.body`,
+     * **outside** `.gis-theme` — pass `"gis-theme"` when this is mounted inside the
+     * GIS workspace. The `VersionPolicyControl` / `ResourceSelect` precedent, and
+     * it has already cost two sessions.
+     */
+    contentClassName?: string;
+}
+export declare function CrsPicker({ mode, value, onChange, suggestFrom, allowCustom, requirement, datasetName, id, className, contentClassName, }: CrsPickerProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * `CrsSelect` — the `@ngis/plugin-ui` spelling of the same component in `select`
+ * mode (F25.9), so it sits beside `ResourceSelect` / `ModelSelect` /
+ * `FieldSelect` on a plugin's import line. The internal component keeps the name
+ * `CrsPicker` because it is a **dialog**, not a `<select>`, and naming a dialog
+ * after a form control is how a component ends up rebuilt by someone who read
+ * only its name.
+ */
+export declare function CrsSelect(props: Omit<CrsPickerProps, "mode" | "datasetName">): import("react/jsx-runtime").JSX.Element;

package/dist/src/components/resources/CrsPicker/crs-recent.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The picker's **Recent** tab (F25.2): the last CRSs this user chose, at most
+ * eight, in `localStorage`.
+ *
+ * ## Why per user, and why the id is in the key
+ *
+ * A shared browser is the normal case on a survey workstation. Keying the list
+ * by the token subject means signing in as someone else does not hand you their
+ * working projections — which look exactly like your own and are wrong for your
+ * data. With no subject available (signed out, or a token this build cannot
+ * read) the list is scoped to `anon` rather than to a global bucket.
+ *
+ * ## Every read is defensive, and a failed read is empty — never a default
+ *
+ * `localStorage` throws in a private window and under a blocked-site-data
+ * setting, and its contents are user-editable text. So the whole surface is
+ * try/caught and the parse is validated: a corrupt entry yields an empty list,
+ * never a fabricated CRS. G-CRS is not only about the server — a recent list
+ * that invented `EPSG:4326` after a bad parse would be the same defect wearing
+ * a different hat.
+ *
+ * The functions are pure over an injected `Storage`, so they are asserted
+ * without a DOM.
+ */
+import type { NgisCrsRef } from "../../../domain/models/crs";
+/** F25.2 caps the list at eight. Beyond that it stops being *recent*. */
+export declare const CRS_RECENT_LIMIT = 8;
+export declare function crsRecentStorageKey(userId: string | null): string;
+/** Parse a raw storage string. Never throws; a corrupt value reads as empty. */
+export declare function parseCrsRecent(raw: string | null): readonly NgisCrsRef[];
+/**
+ * The list after choosing `crs`: most recent first, de-duplicated **by key**,
+ * capped. Re-choosing a CRS moves it to the front rather than adding a second
+ * row — and the newly-stored ref wins, so a ref that has since been resolved
+ * replaces the bare one that was stored before the oracle answered.
+ */
+export declare function withCrsRecent(current: readonly NgisCrsRef[], crs: NgisCrsRef | null): readonly NgisCrsRef[];
+export declare function readCrsRecent(storage: Storage | null | undefined, userId: string | null): readonly NgisCrsRef[];
+/** Returns the list it wrote, so a caller can update state without re-reading. */
+export declare function pushCrsRecent(storage: Storage | null | undefined, userId: string | null, crs: NgisCrsRef | null): readonly NgisCrsRef[];

package/dist/src/components/resources/CrsPicker/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `CrsPicker` — the Stage 25 CRS picker (F25.2, F25.13).
+ *
+ * The exported names are **frozen**: `CrsPicker`, `CrsPickerProps`,
+ * `CrsPickerMode`, `CrsChip`, `CrsChipProps`, plus `CrsSelect` — the spelling
+ * `@ngis/plugin-ui` publishes, so it sits beside `ResourceSelect` /
+ * `ModelSelect` / `FieldSelect` on a plugin's import line. A session needing
+ * another name records it and raises; it never invents one.
+ */
+export { CrsPicker, CrsSelect } from "./CrsPicker";
+export type { CrsPickerMode, CrsPickerProps } from "./CrsPicker";
+export { CrsChip, CrsUnitSigil } from "./CrsChip";
+export type { CrsChipProps } from "./CrsChip";
+export { CRS_RECENT_LIMIT, crsRecentStorageKey, parseCrsRecent, pushCrsRecent, readCrsRecent, withCrsRecent, } from "./crs-recent";

package/dist/src/components/resources/resource-library-crs.d.ts

@@ -0,0 +1,117 @@
+/**
+ * The projection rules of the resource library, as pure functions (Stage 25,
+ * **F25.5**).
+ *
+ * Everything here is decided *outside* a component on purpose. This repo has no
+ * DOM in tests (`S25-V127`), so a rule that lives inside a `useMemo` cannot be
+ * asserted; a rule that cannot be asserted is a rule that regresses. The three
+ * that matter are all here:
+ *
+ * - **what "needs projection" means** — a state, read from two independent
+ *   fields, never from the pipeline status alone;
+ * - **which formats a dataset can be written as** — and that a dataset with no
+ *   projection may only leave as its original bytes;
+ * - **which body an assign sends** — `{ key }` or `{ wkt2 }`, never a srid.
+ *
+ * G-CRS lives above all of them: nothing here invents a CRS, and no branch has a
+ * `4326` fallback.
+ */
+import type { ResourceListItem, ResourceType } from "../../api/resources";
+import type { NgisAssignCrsBody } from "../../api/crs";
+import type { NgisCrsRef, NgisCrsSource } from "../../domain/models/crs";
+/**
+ * `DatasetInfo.status` for a dataset whose CRS the server does not know
+ * (D25-3). Kept as one constant because it is compared in four places and a
+ * literal typo would read as "this dataset is fine".
+ */
+export declare const NEEDS_CRS_STATUS = "NEEDS_CRS";
+/**
+ * **Two fields, either of which is decisive.**
+ *
+ * `datasetStatus` is the server's word and is authoritative when it is present.
+ * But `ResourceListItem` is assembled from a hydration that can fail
+ * (`getDatasetHydration`), and a row whose dataset read failed carries
+ * `datasetStatus: "N/A"` with `crs: null` — which is *also* "we cannot say what
+ * this is in", and the badge must say so rather than draw a confident blank.
+ *
+ * Note what this does **not** do: it never infers "has a projection" from a
+ * status of `DONE`. A `DONE` row with no `crs` is still a row with no
+ * projection, and treating the status as the answer is how `"-"` got printed
+ * over an unknown CRS for two stages (F25.1).
+ */
+export declare function needsProjection(item: Pick<ResourceListItem, "crs" | "datasetStatus">): boolean;
+/** How many rows of a list are in the state the filter selects. */
+export declare function countNeedsProjection(items: readonly Pick<ResourceListItem, "crs" | "datasetStatus">[]): number;
+/**
+ * Whether the caller may declare this dataset's projection. **Ownership, not
+ * status**: `NEEDS_CRS` is a state a shared or public dataset can be in too, and
+ * the person who may fix it is its owner (F25.5). A dataset in the trash is not
+ * assignable — the assign dispatches a re-import, and re-importing something the
+ * user has deleted is not a state the pipeline should be asked to reach.
+ */
+export declare function canAssignProjection(item: Pick<ResourceListItem, "scope" | "canDelete">): boolean;
+/**
+ * The i18n leaf under `ResourceLibrary.projection.sources.*` for a ref's
+ * provenance. `"unknown"` for a ref the server sent without a `source` — which
+ * is a real case (a `crs` carried on a search hit, a suggestion) and is
+ * deliberately *not* collapsed into `DETECTED`: "we do not know how this was
+ * decided" and "the file said so" are the two facts G-CRS exists to keep apart.
+ */
+export declare function crsSourceKey(ref: NgisCrsRef | null): NgisCrsSource | "unknown";
+/**
+ * The download formats offered per resource type, plus `original` — the bytes
+ * as uploaded, which is the only honest option for a dataset the platform has
+ * not imported.
+ *
+ * `original` is first in every list because it is the default and because it is
+ * the only one that cannot fail: everything else is a conversion the server
+ * performs.
+ */
+export type ResourceDownloadFormat = "original" | "geojson" | "gpkg" | "shp" | "tif";
+export declare function downloadFormatsFor(type: ResourceType): readonly ResourceDownloadFormat[];
+/**
+ * The query the download leg is called with (F25.5).
+ *
+ * Three rules, and each of them is a defect this stage is closing:
+ *
+ * 1. **`original` sends no `format`** — the original bytes are the absence of a
+ *    conversion, not a conversion named "original".
+ * 2. **A CRS equal to the dataset's own sends no `crs`** — asking the server to
+ *    reproject a file into the CRS it is already in would spend a reprojection
+ *    to produce the same coordinates, and (worse) would register a variant under
+ *    a key the original already owns.
+ * 3. **Never `srid`.** `?srid=` survives this stage only as a deprecated alias
+ *    the server accepts from older clients (F25.12); nothing here emits it.
+ */
+export declare function downloadQuery(options: {
+    format: ResourceDownloadFormat;
+    /** The CRS the user chose, or `null` for "the dataset's own". */
+    crs: NgisCrsRef | null;
+    /** The dataset's own CRS, so an unchanged choice sends nothing. */
+    datasetCrs: NgisCrsRef | null;
+}): {
+    format?: string;
+    crs?: string;
+};
+/**
+ * What the browser saves the download as.
+ *
+ * `original` keeps the stored filename verbatim. A converted download takes the
+ * dataset's name with the **format's real** extension — including `.zip` for a
+ * Shapefile, which is a bundle and not a file.
+ */
+export declare function downloadFileName(resource: Pick<ResourceListItem, "filename" | "name">, format?: string): string;
+/** Whether the chosen CRS means bytes move on the way out — the copy switches on this. */
+export declare function downloadReprojects(options: {
+    crs: NgisCrsRef | null;
+    datasetCrs: NgisCrsRef | null;
+}): boolean;
+/**
+ * The `PUT /api/datasets/{id}/crs` body for a ref the picker returned.
+ *
+ * A ref with a `custom:` key that the caller has **already registered** is sent
+ * by key; a ref that carries only a definition is sent as `wkt2` so the server
+ * registers it. `null` is not an assignable value — un-declaring a projection is
+ * a different operation and this returns `null` rather than inventing one.
+ */
+export declare function assignBodyFor(ref: NgisCrsRef | null): NgisAssignCrsBody | null;

package/dist/src/components/ui/dialog.d.ts

@@ -0,0 +1,25 @@
+import * as React from "react";
+import * as DialogPrimitive from "@radix-ui/react-dialog";
+declare function Dialog({ ...props }: React.ComponentProps<typeof DialogPrimitive.Root>): import("react/jsx-runtime").JSX.Element;
+declare function DialogTrigger({ ...props }: React.ComponentProps<typeof DialogPrimitive.Trigger>): import("react/jsx-runtime").JSX.Element;
+declare function DialogPortal({ ...props }: React.ComponentProps<typeof DialogPrimitive.Portal>): import("react/jsx-runtime").JSX.Element;
+declare function DialogClose({ ...props }: React.ComponentProps<typeof DialogPrimitive.Close>): import("react/jsx-runtime").JSX.Element;
+declare function DialogOverlay({ className, ...props }: React.ComponentProps<typeof DialogPrimitive.Overlay>): import("react/jsx-runtime").JSX.Element;
+declare function DialogContent({ className, children, showCloseButton, showOverlay, overlayClassName, sizeClassName, ...props }: React.ComponentProps<typeof DialogPrimitive.Content> & {
+    showCloseButton?: boolean;
+    showOverlay?: boolean;
+    overlayClassName?: string;
+    sizeClassName?: string;
+}): import("react/jsx-runtime").JSX.Element;
+declare function DraggableDialogContent({ children, resizable, minWidth, minHeight, onOpenAutoFocus, onPointerDown, onPointerMove, onPointerUp, onPointerCancel, style, ...props }: React.ComponentProps<typeof DialogContent> & {
+    resizable?: boolean;
+    minWidth?: number;
+    minHeight?: number;
+}): import("react/jsx-runtime").JSX.Element;
+declare function DialogHeader({ className, ...props }: React.ComponentProps<"div">): import("react/jsx-runtime").JSX.Element;
+declare function DialogFooter({ className, showCloseButton, children, ...props }: React.ComponentProps<"div"> & {
+    showCloseButton?: boolean;
+}): import("react/jsx-runtime").JSX.Element;
+declare function DialogTitle({ className, ...props }: React.ComponentProps<typeof DialogPrimitive.Title>): import("react/jsx-runtime").JSX.Element;
+declare function DialogDescription({ className, ...props }: React.ComponentProps<typeof DialogPrimitive.Description>): import("react/jsx-runtime").JSX.Element;
+export { Dialog, DialogClose, DialogContent, DraggableDialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, };

package/dist/src/domain/algorithms/flow-field-style.d.ts

@@ -0,0 +1,68 @@
+import type { FlowFieldStyle } from "../models/flow-field-style";
+export declare const FLOW_FIELD_STYLE_VERSION: 1;
+export declare const FLOW_FIELD_COLOR_RAMP_TEXTURE_SIZE = 256;
+export declare const FLOW_FIELD_MAX_PARTICLES = 262144;
+/**
+ * Practical ranges for the style editor. These are intentionally narrower
+ * than the parser's safety bounds so normal operation has useful low-end
+ * precision, without invalidating richer styles saved by earlier releases.
+ */
+export declare const FLOW_FIELD_STYLE_CONTROL_RANGES: {
+    readonly lineWidth: {
+        readonly min: 0.5;
+        readonly max: 2.5;
+        readonly step: 0.25;
+    };
+    readonly speedFactor: {
+        readonly min: 0.1;
+        readonly max: 1.4;
+        readonly step: 0.05;
+    };
+    readonly frameDurationMs: {
+        readonly min: 250;
+        readonly max: 1750;
+        readonly step: 50;
+    };
+    readonly particleCount: {
+        readonly min: 1000;
+        readonly max: 11000;
+        readonly step: 500;
+    };
+    readonly trailLength: {
+        readonly min: 2;
+        readonly max: 10;
+        readonly step: 1;
+    };
+    readonly maxParticleAge: {
+        readonly min: 30;
+        readonly max: 150;
+        readonly step: 1;
+    };
+    readonly dropRate: {
+        readonly min: 0.001;
+        readonly max: 0.007;
+        readonly step: 0.001;
+    };
+    readonly dropRateBump: {
+        readonly min: 0;
+        readonly max: 0.004;
+        readonly step: 0.001;
+    };
+};
+export declare const DEFAULT_FLOW_FIELD_COLORS: readonly ["#3288bd", "#66c2a5", "#abdda4", "#e6f598", "#fee08b", "#fdae61", "#f46d43", "#d53e4f"];
+export declare const DEFAULT_FLOW_FIELD_STYLE: Readonly<FlowFieldStyle>;
+export declare function createDefaultFlowFieldStyle(): FlowFieldStyle;
+export declare function parseFlowFieldColors(value: unknown): string[] | null;
+/**
+ * Migrates every pre-v1 flow style into the v1 contract and removes unknown
+ * properties so a layer style remains a safe, portable JSON payload.
+ */
+export declare function parseFlowFieldStyle(value: unknown): FlowFieldStyle;
+export declare function parseFlowFieldStyleJson(styleJson: string | null | undefined): FlowFieldStyle;
+export declare function serializeFlowFieldStyle(value: unknown): string;
+export declare function sanitizeFlowFieldStyleJson(styleJson: string | null | undefined): {
+    styleJson: string;
+    changed: boolean;
+};
+export declare function isFlowFieldStyle(value: unknown): boolean;
+export declare function sampleFlowFieldColorRamp(colors: readonly string[], count?: number): Uint8Array<ArrayBuffer>;

package/dist/src/domain/map/types.d.ts

@@ -99,6 +99,8 @@ export interface SceneLayerHighlight {
     allFeatures?: boolean;
     /** Only meaningful with `allFeatures`; rows unchecked after select-all. */
     excludedFeatureIds?: string[];
+    /** Optional MapLibre predicate narrowing an all-matching table selection. */
+    attributeFilter?: HighlightFilterExpression;
 }
 export type SceneLayerStyle = Record<string, unknown>;
 export type SceneLayerRenderMode = "maplibre" | "custom-raster-color" | "custom-flow-field";

package/dist/src/domain/models/crs.d.ts

@@ -0,0 +1,187 @@
+/**
+ * Stage 25 (F25.1) — the frontend's CRS domain model.
+ *
+ * **Authored by the W1 kickoff: TYPES AND CONSTANTS ONLY. Read-only to every W1 session
+ * except S25-13, which owns this file and adds the function bodies below.**
+ *
+ * This is the TypeScript leg of the Stage 25 twin triple. The other two are `CrsDto`
+ * (ngis-file, `io.ngis.file.dto`) and `crs_ref.py` (ngis-geoanalysis). All three mirror
+ * `ngis-protos/crs.proto`'s `CrsRef` and the fixtures in `__fixtures__/crs/`, which are
+ * byte-identical across four copies (F25.14 — compare with `diff --strip-trailing-cr`,
+ * never an on-disk hash: the two repos normalise line endings differently).
+ *
+ * ## G-CRS lives here
+ *
+ * `key` is the identity and the only field a caller must round-trip. An absent CRS is
+ * `null` — never `key: ""`, never `epsg: 0`. Zero is not "unknown", it is absent. The whole
+ * stage exists because `crs.py:78` silently turned an undetectable vector CRS into 4326 and
+ * nothing downstream could tell the difference.
+ *
+ * @see docs/projection_management_stage/README.md — F25.1, F25.13 (frozen names)
+ */
+/** How a CRS came to be attached to a dataset. Never absent on a stored CRS (G-CRS). */
+export type NgisCrsSource = "DETECTED" | "SPEC_DEFAULT" | "USER_ASSIGNED" | "DERIVED";
+/**
+ * The display accessor over `NgisCrsRef.geographic`. The boolean is right on the wire, but
+ * `!ref.geographic` reads as a double negative at every UI call site (F25.13).
+ */
+export type NgisCrsKind = "geographic" | "projected";
+/**
+ * What a tool requires of its inputs' CRS.
+ *
+ * `"uniform"` is **not** a member — D25-5 struck it. `"geographic"` is hand-authored only.
+ */
+export type NgisCrsRequirement = "any" | "projected" | "geographic";
+/**
+ * Where a tool's `crsRequirement` came from. A `CLASSIFIER` requirement may only ever raise
+ * an **advisory** issue (R10 / D25-5 as amended): no classifier rule measured better than
+ * 0.800 precision, and a false `"projected"` refuses a run the user is entitled to make.
+ */
+export type NgisCrsRequirementSource = "HAND_AUTHORED" | "CLASSIFIER";
+/** One coordinate reference system. `key` is `"EPSG:<code>"` or `"custom:<ulid>"`. */
+export interface NgisCrsRef {
+    /** The identity, and the only field a caller must round-trip. */
+    readonly key: string;
+    /** Set iff `key` is an `EPSG:` ref. Never `0` — an absent CRS is a `null` ref. */
+    readonly epsg?: number;
+    /** Always on a resolved custom ref; on an EPSG ref only when asked. */
+    readonly wkt2?: string;
+    /** e.g. `"WGS 84 / UTM zone 50N"`. Present iff the oracle has resolved the ref. */
+    readonly name?: string;
+    readonly geographic?: boolean;
+    /** `"metre"` | `"degree"` | `"foot"` | `"us-foot"` | … */
+    readonly unit?: string;
+    readonly source?: NgisCrsSource;
+}
+/** Blocking refuses the submit with 400; advisory never gates Run (R9). */
+export type NgisValidationIssueSeverity = "blocking" | "advisory";
+/**
+ * Open by design — a later stage may add a code, and an unknown code must render as its
+ * `messageKey` rather than being dropped (the `ExtensionSettingsForm` rule, F14.9).
+ */
+export type NgisCrsIssueCode = "CRS_UNKNOWN" | "CRS_PROJECTED_REQUIRED" | "CRS_GEOGRAPHIC_REQUIRED" | "CRS_REPROJECT_NOTICE" | "CRS_UNSUPPORTED_BY_PROVIDER" | (string & {});
+/** The one-click remedy attached to a blocking issue. Carries the `NgisPickerNotice.action`. */
+export interface NgisValidationIssueFix {
+    /** The parameter the fix sets — e.g. `"ngis:outputCrs"`. */
+    readonly param: string;
+    readonly value: string;
+    /** Client-localised under `Crs.issues.fix.*`. */
+    readonly labelKey: string;
+    readonly params?: Readonly<Record<string, string | number>>;
+}
+/**
+ * A typed, per-parameter validation issue (F25.6). **Additive** to F14.9's string arrays:
+ * `missingParameters` / `parameterErrors` / `outputErrors` / `warnings` keep their meaning.
+ *
+ * `param` routes it to that field's `notices`; `port` routes it to that input port.
+ */
+export interface NgisValidationIssue {
+    readonly code: NgisCrsIssueCode;
+    readonly severity: NgisValidationIssueSeverity;
+    /** Client-localised under `Crs.issues.*`. */
+    readonly messageKey: string;
+    readonly params?: Readonly<Record<string, string | number>>;
+    readonly param?: string;
+    readonly port?: string;
+    readonly fix?: NgisValidationIssueFix;
+    readonly crs?: {
+        readonly input?: NgisCrsRef;
+        readonly suggested?: NgisCrsRef;
+        readonly compute?: NgisCrsRef;
+    };
+}
+/** One input as the compiled plan sees it. */
+export interface NgisCrsPlanInput {
+    readonly port: string;
+    /** The CRS the stored dataset is in. */
+    readonly from: string;
+    /** The CRS it is staged into for this run. Equal to `from` when no staging is needed. */
+    readonly to: string;
+    /** Written back as a cached export variant above `STAGING_CACHE_MIN_BYTES` (20 MiB). */
+    readonly cacheable?: boolean;
+}
+/**
+ * The server-compiled CRS plan (F25.4). Every executor path executes **this** rather than
+ * re-deriving a CRS from dataset metadata or a fallback — that is G-U.
+ *
+ * `null` whenever a blocking issue was raised (R9).
+ */
+export interface NgisCrsPlan {
+    /** The CRS the run computes in. */
+    readonly computeCrs: string;
+    /**
+     * The integer that reaches the PostGIS SQL, the `-t_srs` of ogr2ogr/gdalwarp and the
+     * iObjects `inputSrids`: the EPSG code, or the registry's `spatial_ref_sys` srid
+     * (>= 900001) for a custom CRS. No executor re-derives it (R7).
+     */
+    readonly pgSrid: number;
+    /** The CRS the result is registered in. */
+    readonly resultCrs: string;
+    /** Always `"DERIVED"` when present (R6). */
+    readonly resultCrsSource?: NgisCrsSource;
+    /** One entry per input that had to be reprojected for the run. Staging never mutates storage. */
+    readonly stage: readonly NgisCrsPlanInput[];
+}
+/** The one platform projection parameter, injected into every tool's UI schema (F25.4). */
+export declare const NGIS_OUTPUT_CRS_PARAM = "ngis:outputCrs";
+/** `x-role` of a synthetic platform parameter. `w2-fixture.test.ts:252` excludes these. */
+export declare const NGIS_PLATFORM_ROLE = "platform";
+/**
+ * The identifier half of the chip, alone — `"EPSG:32650"`, `"Custom"`, or the
+ * NEEDS_CRS text. It exists so the chip, the table cell and the picker footer
+ * cannot drift: `formatCrs` is this plus the name, never a second spelling.
+ *
+ * **G-CRS.** A bare integer is never returned. A key that *is* a bare integer —
+ * which is what a server still on the old numeric `srid` would send — is
+ * rendered `EPSG:<n>`, because the one thing the user must never see is a naked
+ * number they cannot tell from a feature count.
+ */
+export declare function formatCrsKey(key: string | null, needsCrsText?: string): string;
+/**
+ * The full chip string — `"EPSG:32650 · WGS 84 / UTM zone 50N"`, `"Custom · <name>"`.
+ *
+ * **This is where G-CRS lives on the client.** It never prints a bare integer,
+ * and `formatCrs(null)` returns the NEEDS_CRS text — never `"-"`, and never
+ * `"EPSG:4326"`, which is the silent default the whole stage exists to remove.
+ * A ref whose oracle lookup has not happened yet has no `name`, and renders as
+ * its identifier alone rather than borrowing one.
+ */
+export declare function formatCrs(ref: NgisCrsRef | null, needsCrsText?: string): string;
+/**
+ * `true` only for a ref the oracle has resolved *and* reported as projected.
+ *
+ * An **unresolved** ref (no `geographic`) is `false` here, exactly as
+ * `crs_ref.py`'s `.projected` is — but it is never `true`, so "we have not asked
+ * yet" can never read as "this is safe to measure distance in". That asymmetry
+ * is G-U, restated in one predicate.
+ */
+export declare function isProjectedCrs(ref: NgisCrsRef | null): boolean;
+/**
+ * The display accessor over `NgisCrsRef.geographic` (F25.13). The boolean is
+ * right on the wire; `!ref.geographic` reads as a double negative at every UI
+ * call site, and a UI that has to negate to say "projected" eventually forgets to.
+ *
+ * Reports `"projected"` on exactly the refs {@link isProjectedCrs} accepts, so
+ * the two cannot drift. An unresolved ref reports `"geographic"` — the
+ * conservative half — and the chip draws it with the unknown sigil instead,
+ * because {@link crsUnitGlyph} has no unit to show.
+ */
+export declare function crsKind(ref: NgisCrsRef): NgisCrsKind;
+/**
+ * The unit sigil's glyph: `°` · `m` · `ft` · `?`.
+ *
+ * Exported because the sigil is drawn in five places (full chip, compact chip,
+ * picker trigger, list row, "needs projection" filter) and an inlined map would
+ * drift between them. `"?"` is the honest answer for both an absent ref and a
+ * unit no client mapping knows — a guessed glyph on an unknown unit is exactly
+ * the silent default this stage removes.
+ */
+export declare function crsUnitGlyph(ref: NgisCrsRef | null): string;
+/**
+ * The wire value — the ref's `key`, or `null`. This is what the `crs` widget
+ * puts in the params payload and what `PUT /api/datasets/{id}/crs` echoes.
+ *
+ * An empty-string key is `null`, not `""`: `key: ""` is not a CRS, and letting
+ * it through is how an absent CRS gets laundered into a present one.
+ */
+export declare function crsKeyOf(ref: NgisCrsRef | null): string | null;