@ngis/plugin-ui 0.4.0

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

@@ -0,0 +1,179 @@
+/**
+ * Pure projections behind `RunButton` / `TaskStatus` / `TaskList` (Stage 14 Y4a).
+ *
+ * No React, no host, no clock — the `picker-model.ts` discipline. Everything a
+ * run or a task *means* is decided here so it can be asserted without a DOM,
+ * and so the two places a parameter map is built (the pre-flight
+ * `validate-execution` body and the `tasks.run` payload) are literally the same
+ * function composed twice. A differing coercion between those two is the bug
+ * that makes a validate pass and the run fail, which is why F14/YD34 froze
+ * {@link toWireParams} in `w2-contracts.ts` and why nothing here re-implements
+ * it.
+ *
+ * ## The one thing to read before changing anything below
+ *
+ * **`validate-execution` takes `params` and `bindings` separately;
+ * `POST /api/analysis/tasks` takes one flat `params` map.** F14.3's request body
+ * has `bindings: [{port_name, file_ids}]` beside `params`, while
+ * `CreateAnalysisTaskParams` (`src/api/analysis.ts:72-78`) and therefore
+ * `NgisTaskRunRequest.params` (`src/sdk/facets/types.ts:325-332`) are
+ * `Record<string, string>` and nothing else. So the run payload is the validate
+ * payload **plus** the bindings folded in as parameters, comma-joined per F14.2's
+ * `resource-multi` rule. {@link runParamsOf} is that fold, and it is defined as a
+ * superset of {@link validateParamsOf} rather than as a second construction.
+ *
+ * ## Lifecycle stages, and why there are two lanes
+ *
+ * F13.2 keeps `NgisTaskStatus` (the *run*) and `NgisTaskStage` (the *lifecycle
+ * including scene integration*) apart, and `status: "SUCCESS"` with
+ * `stage: "waiting_scene_integration"` is a real, common state. Surfacing it is
+ * the whole reason these components exist, so {@link taskLifecycle} reports the
+ * two axes separately and never collapses them.
+ *
+ * The lanes differ because the branches differ, and the difference is read off
+ * the facet rather than assumed: the DIRECT projection reuses
+ * `analysis-task-runtime.ts`, which really does write
+ * `waiting_output_datasets` and `refreshing_scene`
+ * (`analysis-task-runtime.ts:339`, `:361`), while `toWorkflowTaskState`
+ * (`src/sdk/facets/tasks.ts:225-272`) can only ever produce
+ * `queued`/`running`/`waiting_scene_integration`/`success`/`failed`/`cancelled`.
+ * A single nine-step lane would leave a workflow run with two segments that can
+ * never fill.
+ */
+import type { NgisTaskOutput, NgisTaskStage, NgisTaskState } from "../../sdk/facets/types";
+import type { NgisExecutionValidation } from "../../types/analysis";
+import { type NgisPortBinding, type NgisRunSubmission } from "./w2-contracts";
+/**
+ * A binding contributes nothing when it resolves to no file ids.
+ *
+ * F14.4 is explicit that absent, `null`, `""` and `[]` are all **unbound, never
+ * "bound to empty"** — so an empty `fileIds` must not become `PORT: ""`. The
+ * server would read that as a supplied-but-invalid file id and answer with a
+ * parameter error about a value the author never entered.
+ */
+export declare function bindingParams(bindings: readonly NgisPortBinding[]): Record<string, string>;
+/**
+ * The `params` half of the pre-flight body.
+ *
+ * Option values plus **output names**: an `output-name` widget's value is a
+ * parameter on the wire (F14.2 — it names the output, it is not a file id), and
+ * `execution_validation.py:208-218` relies on seeing it, or auto-fills it.
+ * Bindings are *not* here — `validate-execution` takes those in their own field.
+ */
+export declare function validateParamsOf(submission: NgisRunSubmission): Record<string, string>;
+/**
+ * The flat `params` map `host.tasks.run` takes — {@link validateParamsOf} plus
+ * the bindings.
+ *
+ * Bindings are spread **last** deliberately. The three groups are disjoint by
+ * role, so a collision means the submission is malformed; when one happens the
+ * resource binding is the value the user actually chose in a picker, and losing
+ * it to a stale option value would submit a run against the wrong dataset.
+ * Deterministic beats clever.
+ */
+export declare function runParamsOf(submission: NgisRunSubmission): Record<string, string>;
+/**
+ * Whether a submission can be submitted, and what to say when it cannot.
+ *
+ * The block/advise split is **read from `w2-contracts.ts`, never re-derived**
+ * (YD34): F14.9 puts `parameter_errors` / `output_errors` /
+ * `missing_parameters` and binding-level `errors` on the blocking side and
+ * `warnings` on the advisory side, and two components disagreeing about that
+ * line is the same class of bug as two coercions.
+ */
+export interface NgisRunGate {
+    /** `false` ⇒ the action is inert and a reason is rendered (F14.10). */
+    readonly ready: boolean;
+    /** Blocking server messages, in F14.9's order. Empty when `ready`. */
+    readonly blocking: readonly string[];
+    /** Never blocks. Rendered beside a ready action, not instead of it. */
+    readonly advisory: readonly string[];
+}
+/**
+ * `validation === null` is **not ready**, and that is F14.9 rather than caution:
+ * server validation runs *always once before submit*, so a run that has never
+ * been validated has not met the precondition. The caller distinguishes "not
+ * validated yet" from "validated and blocked" by the empty `blocking` list, and
+ * renders its own reason for the former.
+ */
+export declare function runGate(submission: NgisRunSubmission | null, validation: NgisExecutionValidation | null): NgisRunGate;
+/**
+ * DIRECT's lane. Every member is a stage `analysis-task-runtime.ts` can actually
+ * write; `queued` is in the union and reachable through `normalizeTaskStatus`,
+ * and a lane step the runtime skips reads as *behind us*, not as stuck — see
+ * {@link taskLifecycle}.
+ */
+export declare const NGIS_DIRECT_STAGE_LANE: readonly NgisTaskStage[];
+/**
+ * WORKFLOW's lane — four steps, because that is all the polling projection can
+ * produce. There is no `submitting` (the invoke returns an instance that is
+ * already `PENDING`), no `waiting_output_datasets` and no `refreshing_scene`.
+ */
+export declare const NGIS_WORKFLOW_STAGE_LANE: readonly NgisTaskStage[];
+export declare function taskStageLane(kind: NgisTaskState["kind"]): readonly NgisTaskStage[];
+export type NgisTaskSegmentState = "done" | "current" | "open";
+export interface NgisTaskRailSegment {
+    readonly stage: NgisTaskStage;
+    readonly state: NgisTaskSegmentState;
+}
+export interface NgisTaskLifecycle {
+    readonly lane: readonly NgisTaskStage[];
+    readonly segments: readonly NgisTaskRailSegment[];
+    /** `failed` or `cancelled`: the lifecycle stopped off-lane. No segment is
+     *  `current`, because claiming a position would claim progress the server
+     *  never reported. */
+    readonly halted: boolean;
+    /** `status === "SUCCESS"` — the computation finished. */
+    readonly runComplete: boolean;
+    /** `stage === "success"` — the lifecycle finished, scene integration
+     *  included. **`runComplete && !integrated` is the distinction these
+     *  components exist to render.** */
+    readonly integrated: boolean;
+}
+/**
+ * The rail, from one `NgisTaskState`.
+ *
+ * A stage the branch skipped is marked `done` rather than left `open`: the task
+ * is demonstrably past it, and rendering it as pending would invent a step the
+ * run is waiting on. A stage that is not a lane member at all (only `failed` and
+ * `cancelled`) sets `halted` and leaves every segment `open`.
+ */
+export declare function taskLifecycle(state: NgisTaskState): NgisTaskLifecycle;
+/**
+ * Whether this state can still change. Mirrors `isActiveTaskState`'s intent from
+ * the other side: a run that is `SUCCESS` but not yet integrated is **not**
+ * terminal, because the stage is still moving.
+ */
+export declare function isTerminalTaskState(state: NgisTaskState): boolean;
+/**
+ * Cancellable while the *run* is still going. Deliberately keyed on `status`,
+ * not `stage`: once the computation has succeeded there is nothing left to
+ * cancel, and offering the action during scene integration would promise
+ * something `tasks.cancel` cannot deliver on either branch.
+ */
+export declare function canCancelTaskState(state: NgisTaskState): boolean;
+/**
+ * **There is no workflow SSE.** `watch` polls for `kind: "workflow"` and
+ * `NgisTaskState.logs` is permanently `[]` there (`facets/tasks.ts:261`), so a
+ * component that renders "no output yet" over a workflow task is telling the
+ * author to wait for something that will never arrive. Half of all tasks have no
+ * log stream, and this function is how a caller says so instead.
+ */
+export declare function hasLogStream(state: NgisTaskState): boolean;
+/** Newest activity first — the order both task surfaces already present. */
+export declare function sortTaskStates(states: readonly NgisTaskState[]): readonly NgisTaskState[];
+/**
+ * The primary output, or the first — F14.4's `"@run"` resolution rule.
+ *
+ * **Delegates to the canonical rule (`V-127`, YD45).** This was one of three
+ * implementations of one clause; binding resolution is where `"@run"` is decided
+ * now, so `flow-model.ts` owns the rule and this is the projection onto a task
+ * state. Behaviour is unchanged — neither this nor `ngisPrimaryTaskOutput`
+ * filters on `fileId`, which is the case the three disagreed about and which the
+ * canonical rule decides explicitly (see its doc comment).
+ *
+ * The **explicit return annotation is part of the fix**: without it the emitted
+ * `.d.ts` widened away the `| null`, so every consumer of the built package
+ * believed this function always returns an output.
+ */
+export declare function primaryTaskOutput(state: NgisTaskState): NgisTaskOutput | null;

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

@@ -0,0 +1,168 @@
+/**
+ * `<StatChart>`'s whole projection: `NgisChartSpec` → an ECharts option, a table
+ * twin, and the advisories that go beneath it (Stage 14 Y4b, **F14.3**).
+ *
+ * ## Why the projection is a pure module and not part of the component
+ *
+ * The `picker-model.ts` / `picker-data.ts` discipline Y2 established, applied to
+ * a chart: everything decidable from the spec alone lives here and is asserted
+ * without a DOM and **without loading ECharts at all** (the only ECharts
+ * reference below is a type-only import, erased at runtime). What is left in
+ * `StatChart.tsx` is mounting, theming and the table toggle.
+ *
+ * That split is also what keeps `viz.chart` worker-ready: `NgisChartSpec` is
+ * declarative data (F14.3 / F13.1 L6), and the whole chart is a function of it.
+ * A spec that carried a formatter callback or a raw ECharts option would not
+ * survive Stage 15's worker tier, and nothing here needs one.
+ *
+ * ## The colour system is computed, not chosen
+ *
+ * The eight categorical slots below are the `dataviz` skill's validated default
+ * palette, **re-validated against this codebase's real surfaces** rather than
+ * the skill's defaults, because a contrast or CVD result only means something
+ * against the surface the chart actually renders on. Every plugin-ui component
+ * renders inside `.gis-theme` (Tenon, `DESIGN_new.md`), so the surfaces are the
+ * Tenon card steps — light `#efe9de`, dark `#0f1011`:
+ *
+ * ```
+ * light  #efe9de : band PASS · chroma PASS · CVD adjacent worst ΔE 9.1 · normal-vision worst ΔE 19.6 · contrast WARN
+ * dark   #0f1011 : band PASS · chroma PASS · CVD adjacent worst ΔE 8.4 · normal-vision worst ΔE 19.3 · contrast PASS
+ * ```
+ *
+ * The **light-mode contrast WARN is not dismissable** — four slots sit under
+ * 3:1 on parchment — so the relief it obliges is shipped: a legend is always
+ * present for two or more series, and every chart has a table twin one click
+ * away ({@link chartTable}). That is also why `StatChart` has a table toggle at
+ * all; it is an accessibility obligation, not a nicety.
+ *
+ * **Slot order is the CVD-safety mechanism, not decoration.** Do not reorder,
+ * do not extend past eight, and never generate a ninth hue — a generated hue is
+ * indistinguishable from an existing slot under simulated CVD. Past eight the
+ * tail is dropped with an advisory (and, for `pie`, folded into one `Other`
+ * segment, which is the part-to-whole answer).
+ *
+ * **Series colour follows the entity's slot index, never its rank.** Filtering
+ * a series out must not repaint the survivors, so nothing here sorts before
+ * assigning a colour — except `pie`, where the fold *is* the encoding.
+ */
+import type { EChartsCoreOption } from "echarts/core";
+import type { NgisChartSeries, NgisChartSpec } from "../../sdk/host-api";
+export type NgisChartTheme = "light" | "dark";
+/**
+ * The eight categorical slots, in frozen order. Both columns are the same eight
+ * hues stepped for their own surface — not two palettes.
+ */
+export declare const NGIS_CHART_SERIES_COLORS: Readonly<Record<NgisChartTheme, readonly string[]>>;
+/**
+ * Chart chrome. **Text never wears the data colour** — axis labels, legend text
+ * and tooltip labels are ink; identity comes from the coloured mark beside the
+ * text. `surface` is what the 2px separator gaps and the marker rings are
+ * painted in, so it must match the card the chart sits on.
+ */
+export declare const NGIS_CHART_INK: Readonly<Record<NgisChartTheme, {
+    readonly surface: string;
+    readonly primary: string;
+    readonly secondary: string;
+    readonly muted: string;
+    readonly grid: string;
+    readonly axis: string;
+}>>;
+/** The token ceiling. A ninth hue is never generated (see the header). */
+export declare const NGIS_CHART_MAX_SERIES = 8;
+/** Part-to-whole at a glance stops working past this; the tail folds to `Other`. */
+export declare const NGIS_CHART_MAX_PIE_SEGMENTS = 6;
+/** Bar/column mark cap. The band's leftover is air, never a wider bar. */
+export declare const NGIS_CHART_MAX_BAR_WIDTH = 24;
+/** The 2px separator that does the separating — never a stroke around a mark. */
+export declare const NGIS_CHART_SURFACE_GAP = 2;
+export declare function chartSeriesColor(index: number, theme: NgisChartTheme): string;
+/**
+ * What the chart could not do exactly as asked. Returned as **codes with their
+ * numbers**, never as text: this module is locale-free by construction, and the
+ * component translates under `GIS.pluginUi.run.chart.*`. Surfaced, never
+ * masked — the `ExtensionSettingsForm` rule.
+ */
+export type NgisChartAdvisory = 
+/** The spec carries no plottable numbers. */
+{
+    readonly id: "empty";
+}
+/** More than `NGIS_CHART_MAX_SERIES`; `dropped` series were not drawn. */
+ | {
+    readonly id: "seriesCapped";
+    readonly dropped: number;
+}
+/** A pie past `NGIS_CHART_MAX_PIE_SEGMENTS`; `folded` segments became `Other`. */
+ | {
+    readonly id: "pieFolded";
+    readonly folded: number;
+}
+/** `categories` is shorter than the longest series, so the tail has no label. */
+ | {
+    readonly id: "categoriesShort";
+    readonly missing: number;
+}
+/** `scatter` fell back to the point index because `categories` are not numeric. */
+ | {
+    readonly id: "scatterIndexed";
+};
+/** `true` when every category parses as a finite number — `scatter`'s x source. */
+export declare function categoriesAreNumeric(categories: readonly string[] | undefined): boolean;
+export declare function chartAdvisories(spec: NgisChartSpec): readonly NgisChartAdvisory[];
+export interface NgisHistogramBins {
+    /** `bins + 1` edges, ascending. */
+    readonly edges: readonly number[];
+    /** One label per bin, `[lo, hi)`. */
+    readonly labels: readonly string[];
+    /** One count array per input series, over the shared edges. */
+    readonly counts: readonly (readonly number[])[];
+}
+/**
+ * **`histogram` reads `values` as raw observations, not as bar heights.** That
+ * is the whole difference between `histogram` and `bar` — `bar` takes heights
+ * already aligned to `categories`, and if `histogram` did too it would be an
+ * alias with a different name. Stated here because the frozen `NgisChartSpec`
+ * has no field to say which, and F14.3's five kinds have to differ in something.
+ *
+ * Bin width is **Freedman–Diaconis** (`2·IQR·n^(-1/3)`), which is robust to the
+ * long tails real analysis output produces, falling back to **Sturges**
+ * (`⌈log₂ n⌉ + 1`) when the IQR is zero — the degenerate case where FD would ask
+ * for an infinite number of bins.
+ *
+ * Every series is binned over **one shared edge set** computed from the pooled
+ * observations, so two distributions are actually comparable; binning each
+ * series on its own edges would put different x axes in one plot.
+ */
+export declare function binHistogram(series: readonly NgisChartSeries[]): NgisHistogramBins;
+export interface NgisChartTable {
+    readonly head: readonly string[];
+    readonly rows: readonly (readonly string[])[];
+}
+/**
+ * The WCAG-clean twin every chart has to have — and, on the light Tenon surface,
+ * the relief the palette's sub-3:1 slots oblige. Values are reachable here
+ * without hovering anything, so no tooltip ever *gates* a number.
+ *
+ * `head[0]` is intentionally empty rather than "Category": the caller supplies
+ * `xLabel` and this module holds no copy.
+ */
+export declare function chartTable(spec: NgisChartSpec): NgisChartTable;
+export interface NgisChartOptionLabels {
+    /** The folded pie tail's segment name. */
+    readonly other: string;
+}
+/**
+ * `NgisChartSpec` → the option `setOption` takes.
+ *
+ * Marks follow one fixed spec across all five kinds, so charts from different
+ * plugins read as one system: **≤24px bars with a 4px rounded cap and a square
+ * baseline · 2px lines with round joins · ≥8px markers carrying a 2px surface
+ * ring · hairline solid grid one step off the surface · a legend whenever there
+ * are two or more series and none when there is one** (the title already names a
+ * lone series, and a one-swatch box restates it).
+ *
+ * There is deliberately **no second y axis, ever**. Two measures of different
+ * scale are two charts or one indexed base — a dual-axis plot invents a
+ * correlation that is not in the data, and `NgisChartSpec` cannot express one.
+ */
+export declare function toChartOption(spec: NgisChartSpec, theme: NgisChartTheme, labels: NgisChartOptionLabels): EChartsCoreOption;

package/dist/src/components/plugin-ui/validation-messages.d.ts

@@ -0,0 +1,18 @@
+/**
+ * User-facing wording for the structured parts of `validate-execution`.
+ *
+ * The service still returns `parameter_errors` and most binding errors as free
+ * text, so those remain verbatim diagnostic detail. The two stable structured
+ * cases below must not leak backend English into the tool panel: users need an
+ * action (fill a parameter or bind an input), not an API-field name.
+ */
+import type { NgisExecutionValidation } from "../../types/analysis";
+export interface NgisValidationMessageLabels {
+    missingParameter: (name: string) => string;
+    requiredInputNotBound: (name: string) => string;
+}
+/**
+ * Formats only blocking server-validation messages. Blocking semantics remain
+ * in `isSubmitBlocked`; this function changes wording, never validation logic.
+ */
+export declare function displayBlockingValidationMessages(validation: NgisExecutionValidation, labels: NgisValidationMessageLabels): readonly string[];

package/dist/src/components/plugin-ui/w2-contracts.d.ts

@@ -0,0 +1,151 @@
+/**
+ * W2 shared contracts — authored at the **W2 kickoff**, read-only to Y3 and Y4.
+ *
+ * Stage 14's wave rule: every surface read by more than one session in a wave is
+ * authored at the kickoff, so neither agent needs live coordination with a
+ * sibling. Y3 owns `ParamForm`, Y4 owns `RunButton`/`TaskStatus`/`TaskList`/
+ * `ResultActions`/`AttributeTable`/`StatChart` — and the two meet at exactly
+ * three seams, all frozen here:
+ *
+ *   1. what a generated form hands a run action  ({@link NgisRunSubmission})
+ *   2. the flow port ids they publish and read   ({@link NGIS_W2_PORT_IDS})
+ *   3. which server messages block a submit      ({@link isSubmitBlocked})
+ *
+ * Nothing here is a component. Nothing here imports React. Keeping it that way
+ * is what lets both sessions unit-test their halves of the seam without a DOM
+ * and without each other — the `picker-model.ts` / `picker-data.ts` split Y2
+ * established, applied to a cross-session boundary.
+ *
+ * Contract: F14.2 (widget vocabulary), F14.3 (validation DTOs), F14.5 (ports),
+ * F14.8 (presets), F14.9 (form lifecycle), F14.10 (no `disabled` prop).
+ */
+import type { NgisExecutionValidation, NgisUiSchemaValueType, NgisWidgetKey } from "../../types/analysis";
+/**
+ * A single generated-form value. Narrower than `unknown` on purpose: F14.2's
+ * `value_type` is one of four scalars, and every widget in the registry either
+ * produces one of them or produces a `string` encoding (`resource-multi` is a
+ * comma-joined file-id list, `extent` is not a param at all).
+ */
+export type NgisParamValue = string | number | boolean | null;
+export type NgisParamValues = Readonly<Record<string, NgisParamValue>>;
+/**
+ * The wire form. `POST …/validate-execution` and the task API both take
+ * `params` as `Record<string, string>` (F14.3), so a form value crosses to the
+ * server through exactly this coercion and no other. Frozen here so Y3's
+ * pre-flight and Y4's submit cannot disagree about how `false` or `null` is
+ * spelled on the wire — the class of bug that makes a validate pass and the
+ * subsequent run fail.
+ */
+export declare function toWireParams(values: NgisParamValues): Record<string, string>;
+/** The inverse, for seeding a form from a preset or a saved recipe. */
+export declare function fromWireValue(raw: string, valueType: NgisUiSchemaValueType): NgisParamValue;
+/** One dataset binding, camelCase at the facet boundary (F14.3). */
+export interface NgisPortBinding {
+    readonly portName: string;
+    readonly fileIds: readonly string[];
+}
+/**
+ * What a generated form hands a run action. **The only Y3 → Y4 data contract.**
+ *
+ * `params` carries option-role values only; `bindings` carries input-role
+ * resource ports; `outputNames` carries `output-name` widget values keyed by
+ * param name. Splitting them here rather than at submit time is deliberate:
+ * `validate-execution` takes the three separately, so a component that merged
+ * them would have to re-split with a second copy of the role rules.
+ */
+export interface NgisRunSubmission {
+    readonly toolId: string;
+    readonly toolVersion: number;
+    readonly params: NgisParamValues;
+    readonly bindings: readonly NgisPortBinding[];
+    readonly outputNames: Readonly<Record<string, string>>;
+}
+/**
+ * Reserved port ids (F14.5's per-component table). A component's `id` prop
+ * overrides the *scope* id, never these member names.
+ */
+export declare const NGIS_W2_PORT_IDS: {
+    /** `ParamForm` out (`record`), and every picker's out port. */
+    readonly value: "value";
+    /** `RunButton` out (`task`); `TaskStatus`/`TaskList`/`ResultActions`/`StatChart` in. */
+    readonly taskId: "taskId";
+    /** `FieldSelect` in — the parent resource port (`parentPortId`). */
+    readonly parent: "parent";
+    /** `AttributeTable` in, and `StatChart`'s alternative in. */
+    readonly resource: "resource";
+};
+export type NgisW2PortId = (typeof NGIS_W2_PORT_IDS)[keyof typeof NGIS_W2_PORT_IDS];
+/**
+ * F14.10's single sanctioned publication out of a flow scope: the task id,
+ * written by the plugin as the bare key `taskId` and published by the host as
+ * `plugin:<pluginId>:taskId` (F14.11). Y4 writes it; nothing else publishes.
+ */
+export declare const NGIS_TASK_ID_CONTEXT_KEY = "taskId";
+/** F14.9's four names, frozen so Y3 does not invent a fifth. */
+export type NgisParamFormPhase = "initialize" | "mutate" | "validate-client" | "validate-server";
+export declare const NGIS_PARAM_FORM_PHASES: readonly NgisParamFormPhase[];
+/** F14.9: server validation is debounced 400 ms, and always runs once before submit. */
+export declare const NGIS_SERVER_VALIDATE_DEBOUNCE_MS = 400;
+/**
+ * Per-field state. `altered` is the edit-protection flag: F14.9's *mutate*
+ * phase repopulates dependent lists and **must never overwrite a field whose
+ * `altered` is true**. `visible` is `depends_on` visibility, not enablement —
+ * F14.10 forbids a `disabled` prop, and a hidden field is not a disabled one.
+ */
+export interface NgisFieldState {
+    readonly value: NgisParamValue;
+    readonly altered: boolean;
+    readonly hasBeenValidated: boolean;
+    readonly visible: boolean;
+    readonly errors: readonly string[];
+}
+export declare function initialFieldState(value: NgisParamValue): NgisFieldState;
+/**
+ * A widget registry is **total over the union with no fallback** (F14.2/F14.9).
+ * Expressed as a mapped type so a missing key is a compile error rather than a
+ * runtime `undefined` that renders nothing — the failure mode a `Partial` plus
+ * a default widget would have hidden.
+ */
+export type NgisWidgetRegistry<TWidget> = {
+    readonly [K in NgisWidgetKey]: TWidget;
+};
+/**
+ * F14.9: `parameter_errors` / `output_errors` / `missing_parameters` block a
+ * submit; `warnings` do not. Binding-level `errors` block too — an unresolved
+ * or `FAIL` port cannot run.
+ */
+export declare function blockingValidationMessages(validation: NgisExecutionValidation): readonly string[];
+export declare function isSubmitBlocked(validation: NgisExecutionValidation): boolean;
+/** Advisory only — never blocks (F14.9). */
+export declare function advisoryValidationMessages(validation: NgisExecutionValidation): readonly string[];
+/**
+ * `data-slot` names reserved for W2. Two reasons they live in one frozen table:
+ * `first-party-plugins/scripts/verify-externals.mjs` fingerprints plugin-ui by
+ * these strings, and a duplicate across components would make that check
+ * ambiguous.
+ */
+export declare const NGIS_W2_DATA_SLOTS: {
+    readonly paramForm: "ngis-param-form";
+    readonly paramField: "ngis-param-field";
+    readonly runButton: "ngis-run-button";
+    readonly taskStatus: "ngis-task-status";
+    readonly taskList: "ngis-task-list";
+    readonly resultActions: "ngis-result-actions";
+    readonly attributeTable: "ngis-attribute-table";
+    readonly statChart: "ngis-stat-chart";
+};
+/** F14.8: a preset value is a literal, an escaped literal, or a context read. */
+export declare const NGIS_PRESET_CONTEXT_PREFIX = "$context:";
+export type NgisPresetValue = {
+    readonly kind: "literal";
+    readonly value: string;
+} | {
+    readonly kind: "context";
+    readonly key: string;
+};
+/**
+ * `$$` escapes a literal `$`. A `$context:` reference resolving to `null`,
+ * `undefined` or `""` refuses the launch with a message naming the key — the
+ * caller's job, but the parse is frozen here so both callers parse alike.
+ */
+export declare function parsePresetValue(raw: string): NgisPresetValue;