@ngis/plugin-ui 0.4.0

package/dist/src/components/plugin-ui/param-form-model.d.ts

@@ -0,0 +1,187 @@
+/**
+ * `<ParamForm>`'s pure half (Stage 14 Y3 — **F14.9**, F14.8, F14.2).
+ *
+ * Nothing here imports React, a store or an API client. That is the same rule
+ * Y2's `picker-model.ts` keeps, and it matters more here: F14.9 freezes a
+ * **four-phase lifecycle** whose hardest requirement — *a repopulate never
+ * overwrites a field whose `altered` is `true`* — is a rule about state
+ * transitions, and a rule spread across `useEffect` bodies cannot be asserted
+ * without a DOM. So every phase is a total function from the UI schema plus the
+ * current state to the next state, and `ParamForm.tsx` only renders the result.
+ *
+ * The four phase names are `w2-contracts.ts`'s `NgisParamFormPhase`, verbatim,
+ * for the reason the kickoff froze them: they are ArcGIS's (design-v2 App. E),
+ * not invented here, and a fifth phase would be a contract change.
+ *
+ * ## What each phase is responsible for
+ *
+ * | phase | function | rule it carries |
+ * |---|---|---|
+ * | `initialize` | {@link initializeParamForm} | seed from `default_value`; `altered: false`, `hasBeenValidated: false` |
+ * | `mutate` | {@link mutateParamForm} | `depends_on` visibility, then repopulation — **never clobbering `altered`** |
+ * | `validate-client` | {@link validateParamFormClient} | `required`, `value_type`, `choices`, `minimum`/`maximum` — errors block submit |
+ * | `validate-server` | `param-form-data.ts` | `host.models.validate`, debounced 400 ms |
+ *
+ * `mutate` runs **before** validation, always. Validating first would report a
+ * `required` error on a field the very next repopulate is about to hide.
+ *
+ * ## Hidden is not disabled, and a hidden field does not submit
+ *
+ * F14.10 forbids a `disabled` prop anywhere in plugin-ui, and F14.9's
+ * `depends_on` is *visibility*. A field the schema says is not applicable is
+ * therefore absent from client validation and absent from the submission — not
+ * present-and-empty. `NgisFieldState.visible` is the flag; nothing here ever
+ * produces a `disabled`.
+ */
+import type { NgisToolUiParam, NgisToolUiSchema } from "../../types/analysis";
+import { type NgisFieldState, type NgisParamValue, type NgisParamValues, type NgisRunSubmission } from "./w2-contracts";
+/**
+ * A schema-shaped defect the form found in its own inputs — an unresolvable
+ * `depends_on`, a dependency cycle, an override naming a param that does not
+ * exist. **Surfaced, never masked** (the `ExtensionSettingsForm` rule): the
+ * form still renders, and the reason is rendered beside it.
+ */
+export interface NgisParamFormDefect {
+    readonly kind: "unknown-dependency" | "dependency-cycle" | "unknown-hide" | "unknown-widget-override";
+    /** The param the defect is attached to, or the offending override key. */
+    readonly subject: string;
+    /** The other end of the relation, when there is one. */
+    readonly detail: string | null;
+}
+export interface NgisParamFormState {
+    /** Keyed by `NgisToolUiParam.name`. Every param of the schema is present. */
+    readonly fields: Readonly<Record<string, NgisFieldState>>;
+    /** The last phase that ran. Diagnostic; the form never branches on it. */
+    readonly phase: "initialize" | "mutate" | "validate-client";
+    /**
+     * Values kept because their field is `altered` even though the current option
+     * list no longer offers them (F14.9). Keyed by param name. Rendered as a
+     * notice; never a reason to clear the value.
+     */
+    readonly stale: Readonly<Record<string, string>>;
+    readonly defects: readonly NgisParamFormDefect[];
+}
+/** An author's per-param overrides. Unknown keys **survive and are surfaced**. */
+export interface NgisParamFormOverrides {
+    /** Param names the author renders elsewhere (already bound by a flow port). */
+    readonly hide?: readonly string[];
+    /** Param name → widget key. Selects `textarea`/`extent`/`field-select`. */
+    readonly widgets?: Readonly<Record<string, NgisToolUiParam["widget"]>>;
+}
+export interface NgisParamFormInit extends NgisParamFormOverrides {
+    /**
+     * Wire-shaped seed values (F14.8's preset `params`, or a saved recipe's
+     * bindings). Applied over `default_value`, and coerced through
+     * `fromWireValue` so a form value and the value the server will see cannot
+     * disagree.
+     */
+    readonly seed?: Readonly<Record<string, string>>;
+    /** Option lists a widget resolves at runtime — `field-select`'s field names. */
+    readonly optionLists?: Readonly<Record<string, readonly string[]>>;
+}
+/**
+ * The spelling a `depends_on.equals[]` entry is compared against, and the one
+ * `toWireParams` will send. **A boolean parent is compared as its wire
+ * spelling** (`"true"`), which is why the authored probe pins
+ * `REFINE_PASSES.depends_on[0].equals === ["true"]` rather than a JSON `true`.
+ */
+export declare function wireSpelling(value: NgisParamValue): string;
+/**
+ * **initialize** (F14.9). Every field seeded from `default_value` — or from a
+ * preset/recipe seed — with `altered: false` and `hasBeenValidated: false`.
+ *
+ * `altered` stays `false` even for a seeded field, because F14.9's text is
+ * explicit and `altered` means *the user edited this*. The consequence is real
+ * and deliberate: a preset value in a field whose option list repopulates can
+ * be dropped by `mutate`, exactly as a `default_value` can. A launch that must
+ * not lose a preset value hides that param instead (`hide`), which is what
+ * F14.22's `hide={["ELEV"]}` is for.
+ *
+ * `mutate` is run immediately, so the state this returns already has correct
+ * visibility — a form is never rendered with a field the schema says is not
+ * applicable.
+ */
+export declare function initializeParamForm(schema: NgisToolUiSchema, init?: NgisParamFormInit): NgisParamFormState;
+/**
+ * **mutate** (F14.9). Runs after every interaction and **before** validation.
+ *
+ * Two steps, in this order:
+ *
+ * 1. **Visibility** from `depends_on` — see {@link resolveVisibility}.
+ * 2. **Repopulation.** A value the current option list no longer offers is
+ *    dropped **only when the field is not `altered`**; an altered value is kept
+ *    and reported in `stale` so the form can say so. That is F14.9's one hard
+ *    rule, and it is the same decision Y2's `reconcileFieldValue` makes for
+ *    `FieldSelect` — stated once, here, for every widget with a list.
+ *
+ * A multi-valued field (`multiple`) is repopulated **per member**: the members
+ * the new list still offers survive, and the ones it does not are dropped from
+ * an unaltered field or kept-and-reported on an altered one. Dropping the whole
+ * selection because one member went away would be a clobber by another name.
+ */
+export declare function mutateParamForm(schema: NgisToolUiSchema, state: NgisParamFormState, optionLists?: Readonly<Record<string, readonly string[]>>): NgisParamFormState;
+/** Record the user's edit. Sets `altered`, which `mutate` must then respect. */
+export declare function setParamValue(schema: NgisToolUiSchema, state: NgisParamFormState, name: string, value: NgisParamValue, optionLists?: Readonly<Record<string, readonly string[]>>): NgisParamFormState;
+/**
+ * The client-side rules, and **only** the rules F14.9 names: `required`,
+ * `value_type`, `choices` membership, `minimum`/`maximum`. Every one of them is
+ * read off the UI schema; none is inferred, and none duplicates a server rule
+ * the server is authoritative for (that is `validate-server`).
+ *
+ * A message is a **key under `GIS.pluginUi.form`** plus its placeholders,
+ * resolved by the component — not a sentence. Keeping the copy out of here is
+ * what lets this run in a node test with no `next-intl` provider.
+ */
+export interface NgisParamFormError {
+    readonly param: string;
+    readonly rule: "required" | "value-type" | "choices" | "minimum" | "maximum";
+    readonly bound: number | null;
+}
+/** Hidden fields are skipped: either `depends_on` or the caller's `hide` override. */
+export declare function validateParamFormClient(schema: NgisToolUiSchema, state: NgisParamFormState, hidden?: readonly string[]): readonly NgisParamFormError[];
+/** Fold client errors back onto the fields, marking them `hasBeenValidated`. */
+export declare function applyClientErrors(state: NgisParamFormState, errors: readonly NgisParamFormError[], render: (error: NgisParamFormError) => string): NgisParamFormState;
+export declare function valuesOf(state: NgisParamFormState): NgisParamValues;
+/**
+ * The Y3 → Y4 data contract (`NgisRunSubmission`), split by **role** exactly as
+ * `validate-execution` takes it: `params` is option-role only, `bindings` is
+ * input-role resource ports, `outputNames` is the `output-name` widgets.
+ * Merging them here would force Y4 to re-split with a second copy of the role
+ * rules — the class of duplication this stage exists to remove.
+ *
+ * A hidden or empty field contributes nothing. `multiple` inputs are split on
+ * `,`, which is the spelling F14.2 fixes for a comma-joined file-id list.
+ */
+export declare function toSubmission(schema: NgisToolUiSchema, state: NgisParamFormState, hidden?: readonly string[]): NgisRunSubmission;
+/**
+ * The params the visible fields would submit, in the wire shape
+ * `validate-execution` and the task API both take. Y3's pre-flight and Y4's
+ * submit go through `toWireParams` — this only chooses *which* keys.
+ */
+export declare function visibleParamNames(schema: NgisToolUiSchema, state: NgisParamFormState): readonly string[];
+/**
+ * F14.8's launch resolution. **A `$context:` reference resolving to `null`,
+ * `undefined` or `""` refuses the launch, naming the key** — it is never
+ * submitted as an empty string, because an empty string is a value the server
+ * would accept and act on.
+ *
+ * `$$` escapes a literal `$` (`parsePresetValue`, frozen at the kickoff so the
+ * rail launcher and a recipe reader parse alike).
+ *
+ * Keys are visited in **sorted order** so that a stanza with two unresolvable
+ * references always names the same one. A refusal message that changed between
+ * runs would be untriageable.
+ */
+export type NgisPresetResolution = {
+    readonly kind: "resolved";
+    readonly params: Readonly<Record<string, string>>;
+} | {
+    readonly kind: "refused";
+    /** The context key that resolved to nothing. */
+    readonly key: string;
+    /** The preset param that referenced it. */
+    readonly param: string;
+};
+/** What a context read can return — F13.2's `NgisContextValue` shape, widened. */
+export type NgisPresetContextValue = string | number | boolean | null | readonly (string | number)[] | undefined;
+export declare function resolvePresetParams(params: Readonly<Record<string, string>>, read: (key: string) => NgisPresetContextValue): NgisPresetResolution;

package/dist/src/components/plugin-ui/param-widgets.d.ts

@@ -0,0 +1,88 @@
+/**
+ * The widget registry (Stage 14 Y3 — **F14.2 / F14.9 / YD35**).
+ *
+ * **Total over `NgisWidgetKey`, with no fallback widget.** The type is
+ * `NgisWidgetRegistry<NgisParamWidget>` from `w2-contracts.ts`, i.e.
+ * `{ readonly [K in NgisWidgetKey]: T }` — so a key F14.2 grows and this file
+ * does not cover is a **compile** error, not a runtime `undefined` that renders
+ * nothing. That is the whole reason the registry is not a `Partial` plus a
+ * default text input: a silently-degraded control is indistinguishable from a
+ * control that works, and F14.2 says an unknown widget is a render-time error
+ * surfaced in place.
+ *
+ * YB1 emits only seven of the twelve keys in v1 (`field-select`, `extent`,
+ * `textarea`, `multi-select` and `resource-multi` are never emitted — `V-45`
+ * and `src/types/analysis.ts`'s own note). The other five are reachable through
+ * an author's `widgets` override and a recipe's promoted inputs, and they are
+ * exercised by `src/sdk/__fixtures__/ui-schema/authored/w2-dependency-probe.json`.
+ *
+ * ## Four of the twelve are Y2's pickers, not new controls
+ *
+ * `resource-select`, `resource-multi`, `field-select` and `extent` delegate to
+ * `ResourceSelect` / `FieldSelect` / `ExtentPicker`. Rebuilding those controls
+ * would give the form a second, subtly different notion of type widening, of
+ * field repopulation and of the two extent sources. They are rendered with
+ * **no `label`**, because the form's own field chrome carries the label — the
+ * picker's `PickerField` then contributes only its notice slot, which is where
+ * F14.1's widening and F14.9's kept-but-absent field surface.
+ *
+ * ## No `disabled`, anywhere
+ *
+ * F14.10: enablement is derived from port satisfaction and nothing else, and no
+ * plugin-ui component accepts a `disabled` prop. A widget with nothing to offer
+ * renders the reason instead of a dead control.
+ */
+import type { ReactNode } from "react";
+import type { NgisHostAPI } from "../../sdk/host-api";
+import type { NgisBounds } from "../../sdk/map-api";
+import type { NgisToolUiParam, NgisToolUiSchema } from "../../types/analysis";
+import type { NgisFieldState, NgisParamValue, NgisParamValues, NgisWidgetRegistry } from "./w2-contracts";
+/** Already-translated host copy a widget may render. Keys are `GIS.pluginUi.form`. */
+export interface NgisParamWidgetLabels {
+    /** A `select` / `multi-select` whose schema carries no `choices`. */
+    noChoices: string;
+    /** Suffix hint on an `output-name` field. Receives `output_extension`. */
+    outputExtension: (extension: string) => string;
+    /** Clear control on a single-value list. */
+    clear: string;
+    /** Placeholder on a closed list. */
+    placeholder: string;
+}
+export interface NgisParamWidgetProps {
+    /** The 0.4 facade — always the one `createGisPluginHostFactory` minted. */
+    host: NgisHostAPI;
+    /** The whole schema: `field-select` needs to resolve its parent param. */
+    schema: NgisToolUiSchema;
+    param: NgisToolUiParam;
+    field: NgisFieldState;
+    /**
+     * Every field's current value. Only `field-select` reads it — it follows a
+     * *sibling* param's value (QGIS's `parentLayerParameterName`) — but it is on
+     * all twelve props rather than smuggled in through a module-level slot,
+     * because a widget is rendered by React later than the form's render pass and
+     * anything ambient would be stale by then.
+     */
+    values: NgisParamValues;
+    /** `<label for>` target. Seeded from the form's `id` plus the param name. */
+    controlId: string;
+    /** Class for portalled `<Select>` content — Radix lands on `document.body`. */
+    contentClassName?: string;
+    /** Exact layer selected from a duplicate-named resource choice, if any. */
+    onSameNamedLayerSelect?: (layerId: string) => void;
+    /** Records the edit. Sets `altered`, which F14.9's *mutate* must respect. */
+    onChange: (value: NgisParamValue) => void;
+    labels: NgisParamWidgetLabels;
+}
+/**
+ * A widget is a React component, so it may hold hooks — `ResourceSelect` and
+ * `FieldSelect` do. The registry stores components and `ParamForm` renders them
+ * as `<Widget …/>`; nothing calls one as a plain function.
+ */
+export type NgisParamWidget = (props: NgisParamWidgetProps) => ReactNode;
+/** `[west, south, east, north]` round-tripped through the comma-joined wire form. */
+export declare function parseBounds(value: NgisParamValue): NgisBounds | null;
+/**
+ * **Total over `NgisWidgetKey`. There is no fallback entry, and adding one would
+ * be a contract change** (F14.2, YD35).
+ */
+export declare const NGIS_PARAM_WIDGETS: NgisWidgetRegistry<NgisParamWidget>;

package/dist/src/components/plugin-ui/picker-data.d.ts

@@ -0,0 +1,141 @@
+/**
+ * The host reads behind the four W1 pickers (Stage 14 Y2).
+ *
+ * Every function here takes the 0.4 facade and returns plain data. Keeping them
+ * out of the components is what lets the wave's real exit criterion — "the
+ * pickers work **through `createGisPluginHostFactory`**" — be asserted offline:
+ * a node test builds the real, scope-enforced facade and calls these, so a
+ * scope refusal or a facet stub surfaces here exactly as it would in the
+ * browser. A facade assembled anywhere else is an ungated 0.4 surface every
+ * unit test calls green, and this stage has already hit that once.
+ *
+ * **`ModelSelect` reads `host.models.list`, not `host.models.search`.** F14.3
+ * adds the `search` leg and F14.24 ships it as a stub that *throws* until Y4
+ * implements it in W2 — deliberately, so a missing implementation cannot read
+ * as an empty result. `list` is the F13.2 surface that exists today, and its
+ * `query` filters client-side on name/description. The server-side
+ * `inputTypes`/`outputTypes` facets `search` will bring are therefore not
+ * expressible here; that is a W2 upgrade, not a W1 gap to paper over.
+ */
+import type { NgisHostAPI } from "../../sdk/host-api";
+import type { NgisDataType, NgisModelSearchRequest, NgisResourceField, NgisResourceType } from "../../sdk/facets/types";
+import type { NgisBounds } from "../../sdk/map-api";
+import { type NgisFieldReconcileResult, type NgisPickerOption, type NgisTypeWidening } from "./picker-model";
+export interface NgisResourceLoad {
+    options: readonly NgisPickerOption[];
+    /** F14.1 — rendered beneath the control, never swallowed. */
+    widenings: readonly NgisTypeWidening[];
+    /** Cached metadata could not be refreshed; retry is meaningful. */
+    unavailableCount: number;
+    /** The scene references a Dataset that no longer exists. */
+    missingCount: number;
+}
+export declare function loadResourceOptions(host: NgisHostAPI, types?: readonly NgisDataType[], options?: {
+    refresh?: boolean;
+}): Promise<NgisResourceLoad>;
+export interface NgisModelFilter {
+    provider?: string;
+    category?: string;
+    modelboxId?: string;
+    query?: string;
+}
+export declare function loadModelOptions(host: NgisHostAPI, filter?: NgisModelFilter): Promise<readonly NgisPickerOption[]>;
+/**
+ * `host.models.search` — the F14.3 leg, wired in W2 and reached from
+ * `ModelSelect` from W4 (**YD54**, the upgrade YD46 deferred out of W3).
+ *
+ * **It is a second leg, not a replacement, and the reason is a capability `search`
+ * does not have.** `GET /api/analysis/tools/search` declares no `category` and no
+ * `modelbox_id` filter — only `modelbox_path` — so `NgisModelSearchRequest`
+ * (`facets/types.ts:241-250`) has no member for either, while
+ * `NgisModelsFacet.list`'s filter has both and `ModelSelect` takes both as props.
+ * Routing everything through `search` would therefore have silently dropped two
+ * filters, which is worse than a picker that cannot filter by data type. The
+ * component keeps `list` for the catalog-narrowing path and reaches this one for
+ * the facet path, and the two arms are **mutually exclusive by type** so no author
+ * can write the combination that would have to drop something.
+ *
+ * One more asymmetry, recorded because it is invisible: `search` is **capped**.
+ * `limit` defaults to 10 server-side and the server maximum is 50
+ * (`facets/types.ts:243-244`), so a search hit list is a ranked top-N and never the
+ * catalog. `list` is unpaged. A caller that wants "every tool" wants `list`.
+ */
+export declare function loadModelSearchOptions(host: NgisHostAPI, request: NgisModelSearchRequest): Promise<readonly NgisPickerOption[]>;
+/**
+ * Why this is a union rather than an option list plus a boolean: each arm is a
+ * state the author has to be able to tell apart, and collapsing "no parent
+ * chosen" into "no fields" is the exact silent-empty-state failure the stage's
+ * stub rule exists to prevent.
+ */
+export type NgisFieldLoad = 
+/** No parent value bound yet. */
+{
+    kind: "no-parent";
+}
+/** The parent's file id matches no resource in this scene. */
+ | {
+    kind: "unresolved";
+    fileId: string;
+}
+/** Resolved, but fields are vector-only (`NgisResourceDetail.fields`). */
+ | {
+    kind: "not-vector";
+    type: NgisResourceType;
+} | {
+    kind: "ready";
+    options: readonly NgisPickerOption[];
+};
+/**
+ * `FieldSelect` follows a **resource port**, whose value is a *file* id
+ * (F14.5), while `host.resources.get` takes a *scene-resource* id. The join is
+ * `NgisResourceSummary.fileId`, so this resolves the parent through
+ * `resources.list()` first. Reported as `unresolved` rather than guessed: a
+ * file id that is not in the scene is a real state (the resource was removed),
+ * and treating it as "no fields" would hide it.
+ */
+export declare function loadFieldOptions(host: NgisHostAPI, parentFileId: string | null): Promise<NgisFieldLoad>;
+/** The live state `FieldSelect` carries across a repopulate (F14.9). */
+export interface NgisFieldSelection {
+    value: string | null;
+    /** `true` once the user has picked. Never reset by a repopulate. */
+    altered: boolean;
+}
+/** The fields a load actually produced; `[]` for every not-ready arm. */
+export declare function fieldsOf(load: NgisFieldLoad): readonly NgisResourceField[];
+/**
+ * **The whole of `FieldSelect`'s parent-change decision, in one function.**
+ *
+ * F14.9 asks for two things that pull against each other — repopulate on parent
+ * change, and never clobber a value the user altered — so the decision lives
+ * here rather than inside a `useEffect`: a rule spread across an effect body
+ * cannot be asserted without a DOM, and a rule that cannot be asserted is a rule
+ * that regresses. `FieldSelect` calls exactly this and renders the result, so
+ * the test and the component agree by construction rather than by resemblance.
+ *
+ * `load === null` means the new parent's fields are still in flight and
+ * **nothing is decided yet**: the value is passed through untouched. Reconciling
+ * against an empty list mid-load would clear an unaltered selection and then
+ * restore nothing, which reads as a flicker and is indistinguishable from a
+ * parent that genuinely has no fields.
+ */
+export declare function reconcileFieldLoad(load: NgisFieldLoad | null, selection: NgisFieldSelection): NgisFieldReconcileResult;
+export type NgisExtentMode = "draw" | "viewport";
+/**
+ * Both modes ride the **ungated** 0.3 surface (F14.18), so neither needs a
+ * scope and neither can be refused by consent.
+ *
+ * `draw` is `host.api.draw.snapshot()`. It returned `[]` in every shipping host
+ * until this session widened `GisMapHandle` with `getDrawSnapshot()` — the
+ * producer (`DrawController`) and the SDK-side delegation (`map-api.ts`) both
+ * already existed; only the composed handle never surfaced it.
+ *
+ * `viewport` is `host.api.getMap()?.getBounds()`. **Not `camera.getView()`** —
+ * that returns `{ center, zoom, pitch, bearing }` and no extent can be derived
+ * from it without the viewport size the facade does not expose.
+ *
+ * `null` means "no extent available right now" and the caller must say which of
+ * the two reasons applies; it is never rendered as an empty bbox.
+ */
+export declare function readExtent(host: NgisHostAPI, mode: NgisExtentMode): NgisBounds | null;
+/** Whether a raw map is bound at all — the two `null`s of {@link readExtent}. */
+export declare function hasBoundMap(host: NgisHostAPI): boolean;

package/dist/src/components/plugin-ui/picker-model.d.ts

@@ -0,0 +1,150 @@
+/**
+ * The pure projections behind the four W1 pickers (Stage 14 Y2 — F14.1, F14.18).
+ *
+ * Nothing here imports React, a store or an API client: every function is a
+ * total mapping from data the host already has to data a picker renders. That
+ * is what keeps the components **host-renderable from declarative data** — the
+ * property Stage 15's worker tier depends on — and it is what makes the four
+ * behaviours that actually matter (type widening, field repopulation, the two
+ * extent sources) testable offline without a DOM.
+ *
+ * `src/components/` rather than `src/sdk/`: these read the SDK's frozen types
+ * but they are host UI, and `src/sdk/` is the module set `@ngis/plugin-sdk` is
+ * extracted from. `@ngis/plugin-ui` re-exports the components from here instead
+ * (F14.14 — "the components' runtime lives in the host bundle").
+ */
+import { type NgisDataType, type NgisModelSearchResult, type NgisModelSummary, type NgisResourceField, type NgisResourceSummary, type NgisResourceType } from "../../sdk/facets/types";
+import type { NgisBounds } from "../../sdk/map-api";
+/** One row of any of the four pickers. Data only — no node, no callback. */
+export interface NgisPickerOption {
+    /**
+     * Stable UI identity. Resource-layer rows use a layer id here while keeping
+     * `value` as the file id a tool parameter requires.
+     */
+    id?: string;
+    /** Concrete scene-layer identity, absent for the legacy resource fallback. */
+    sceneLayerId?: string;
+    /** The port value this row binds. */
+    value: string;
+    /** Display text. Never a message key: resource/tool/field names are data. */
+    label: string;
+    /** Secondary line (type, status, provider). `null` when there is nothing to add. */
+    hint: string | null;
+    /** Listed but not ready — greyed, still selectable, never hidden. */
+    muted: boolean;
+    /** A scene layer is currently hidden but remains a valid data input. */
+    hidden?: boolean;
+    /** Present only when another eligible layer has the same visible name. */
+    sameName?: boolean;
+    /** Group path, or a stable layer id when the layer has no group. */
+    disambiguation?: string;
+}
+/** One requested {@link NgisDataType} and the resource types it actually lists. */
+export interface NgisTypeWidening {
+    requested: NgisDataType;
+    listed: readonly NgisResourceType[];
+}
+export interface NgisResourceTypeFilter {
+    /** What `host.resources.list({ types })` is asked for; `null` means no filter. */
+    resourceTypes: readonly NgisResourceType[] | null;
+    /** Empty when every requested type resolves to itself. */
+    widenings: readonly NgisTypeWidening[];
+}
+export declare function widenDataTypes(types?: readonly NgisDataType[]): NgisResourceTypeFilter;
+/**
+ * **The value is the file id, not the scene-resource id** (F14.2's
+ * `resource-select`, F14.5's `resource` port kind): every dataset API and every
+ * tool binding takes `effectiveFileId`. `NgisResourceSummary` carries both, so
+ * this is a choice rather than a limitation, and it is the contract's choice.
+ */
+export declare function resourceOptions(summaries: readonly NgisResourceSummary[]): NgisPickerOption[];
+/**
+ * Project a file-typed resource input onto the scene layers a person actually
+ * recognises. The submitted value remains the resource's `effectiveFileId`;
+ * `id` is the layer identity used only by the picker UI. This intentionally
+ * keeps every layer when several render the same file.
+ *
+ * A source that predates the optional `summary.layers` projection falls back
+ * to the old resource row. A source that supplies `layers: []` has stated that
+ * the resource has no scene layer, so it is not selectable here.
+ */
+export declare function resourceLayerOptions(summaries: readonly NgisResourceSummary[]): NgisPickerOption[];
+/** A disabled tool stays listed and greyed — never hidden (the XD12 posture). */
+export declare function modelOptions(models: readonly NgisModelSummary[]): NgisPickerOption[];
+/**
+ * `host.models.search`'s hits, as options (Stage 14 Y7 — **YD54**, the `ModelSelect`
+ * upgrade YD46 deferred out of W3).
+ *
+ * **Two things `search` cannot tell us that `list` can, stated where they are
+ * lost.** `NgisModelSearchResult` (`src/sdk/facets/types.ts:253-277`) is an
+ * allowlist projection of `ToolSearchResult` and carries **no `enabled` flag** and
+ * **no `category`** — so on this path:
+ *
+ *   - **`muted` is always `false`.** XD12's posture ("a disabled tool is listed
+ *     and greyed, never hidden") cannot be honoured, because the search projection
+ *     does not report enablement. Recovering it would mean one `models.get` per
+ *     hit, which is the N+1 XD7 already refused for `resources.types`. Recorded as
+ *     `V-287` rather than papered over with a guess.
+ *   - **`hint` falls back to `modelboxPath`**, which `list` does not carry at all,
+ *     so the two legs' hints differ in kind. That is honest: a search hit really is
+ *     located by its modelbox path, and printing a `category` the projection never
+ *     received would be an invention.
+ *
+ * Order is the server's — `search` ranks by `score` and the ranking *is* the
+ * answer, so re-sorting here would discard the only thing the facet added over
+ * `list`.
+ */
+export declare function modelSearchOptions(results: readonly NgisModelSearchResult[]): NgisPickerOption[];
+export declare function fieldOptions(fields: readonly NgisResourceField[]): NgisPickerOption[];
+export interface NgisFieldReconcileInput {
+    /** The repopulated field list for the *new* parent. */
+    fields: readonly NgisResourceField[];
+    value: string | null;
+    /** `true` once the user has picked. F14.9's `altered` flag. */
+    altered: boolean;
+}
+export interface NgisFieldReconcileResult {
+    value: string | null;
+    /**
+     * The altered value that survived a repopulate without being present in the
+     * new list. Non-`null` means "render the mismatch"; it is never a reason to
+     * clear the value.
+     */
+    missing: string | null;
+}
+/**
+ * QGIS's `parentLayerParameterName` behaviour, plus F14.9's one hard rule: **a
+ * repopulate never overwrites a field whose `altered` is `true`.**
+ *
+ * So an altered value that the new parent does not carry is *kept and
+ * surfaced*, not silently cleared — the `ExtensionSettingsForm` rule ("refusals
+ * and approximations are surfaced, not masked"). Clearing it would look to the
+ * author like the host discarding their input; blocking on it is Y3's
+ * validation phase and Y5's enablement, not this component's call.
+ *
+ * A value the user never touched carries no such claim, so a repopulate clears
+ * it when the new parent cannot honour it.
+ */
+export declare function reconcileFieldValue(input: NgisFieldReconcileInput): NgisFieldReconcileResult;
+/**
+ * `NgisBounds` = `[west, south, east, north]` over every position in a raw
+ * Terra Draw snapshot, or `null` when the snapshot holds no usable coordinate.
+ *
+ * The snapshot is typed `unknown[]` all the way from
+ * `host.api.draw.snapshot()`, so this walks the coordinate tree structurally
+ * rather than trusting a GeoJSON type — a draw session can hold any geometry
+ * kind and F14 does not restrict which.
+ */
+export declare function boundsOfDrawSnapshot(features: readonly unknown[]): NgisBounds | null;
+/**
+ * A MapLibre `LngLatBounds` → `NgisBounds`.
+ *
+ * **CORRECTION carried from F14.18:** `camera.getView()` returns
+ * `{ center, zoom, pitch, bearing }`, **not** an extent, so viewport mode
+ * cannot be built from it. It needs the raw map's `getBounds()`, which the
+ * ungated `getMap()` already provides. Duck-typed so the projection stays
+ * testable without a GL context.
+ */
+export declare function boundsFromLngLatBounds(value: unknown): NgisBounds | null;
+/** Six decimals ≈ 0.1 m — enough to read, short enough to fit the control. */
+export declare function formatBounds(bounds: NgisBounds): string;