@ngis/plugin-ui 0.4.0

package/dist/src/components/plugin-ui/Flow.d.ts

@@ -0,0 +1,256 @@
+/**
+ * `<Flow>` — the typed-port scope (Stage 14 Y5b, **F14.4 / F14.5 / F14.10**).
+ *
+ * A React context holding one registry of nodes and their out-port values,
+ * re-resolving whenever either changes, and rendering `data-slot="ngis-flow"`.
+ * `useFlowScope()` reads the scope; `useFlowPort()` is how each of the eleven
+ * smart components declares its ports, publishes its outputs and reads back its
+ * resolved inputs and its derived enablement.
+ *
+ * ## Flow state is component-local, and exactly one value leaves (F14.10)
+ *
+ * The registry is plain React state in this provider. Nothing here calls
+ * `host.context.set`, and the rationale is from source rather than taste: every
+ * `set` notifies the dependency index and re-evaluates every compiled expression
+ * whose read-set intersects, so publishing each port value would put
+ * per-keystroke traffic through the global index — the "enablement performance"
+ * risk design-v2 §8 names. The **one** sanctioned publication is the task id,
+ * written by `RunButton` through `publishTaskId` as the bare key `taskId`, and
+ * there must never be a second.
+ *
+ * ## Why the scope holds no React state in its *contract*
+ *
+ * Everything the resolver reads is declarative data — `NgisFlowNode[]` plus an
+ * out-port value map — which is what keeps every component **host-renderable
+ * from declarative data** and therefore survivable into Stage 15's worker tier.
+ * A scope whose contract included a setter or an element would quietly destroy
+ * that property. The pure core lives in `flow-model.ts` (Y5a); on this branch it
+ * is stubbed in `flow-core-stub.ts`, which the merge deletes.
+ *
+ * ## Not a reactive system, and not an editor
+ *
+ * DAG data flow plus derived enablement, per the stage's binding cuts: no
+ * signals, no observables, no effect graph. The escape hatch stays plain React
+ * plus facets. The inspector inspects; it does not edit.
+ */
+import { type ReactNode } from "react";
+import type { NgisBounds } from "../../sdk/map-api";
+import type { NgisPickerNotice } from "./PickerField";
+import { type NgisFlowDefect, type NgisFlowState } from "./flow-model";
+import { type NgisFlowNode, type NgisFlowNodeConfig, type NgisFlowRef, type NgisFlowSnapshot, type NgisInputBinding, type NgisNodeEnablement, type NgisPortResolution, type NgisPortSpec, type NgisResolvedValue } from "./w3-contracts";
+/**
+ * What a `<Flow>` scope offers its children. Data plus three registry calls;
+ * deliberately no way to *edit* the graph from outside a node's own declaration,
+ * because the graph is the JSX.
+ */
+export interface NgisFlowScope {
+    readonly nodes: readonly NgisFlowNode[];
+    readonly outputs: NgisFlowState["outputs"];
+    /** Keyed by {@link ngisPortRef}, over in-ports and spread directives alike. */
+    readonly resolved: Readonly<Record<string, NgisPortResolution>>;
+    readonly enablement: Readonly<Record<string, NgisNodeEnablement>>;
+    /** Last-wins on `id`; a second live claim on one id is a dev-mode error. */
+    register(node: NgisFlowNode, token: object): void;
+    unregister(nodeId: string, token: object): void;
+    /** An out port's current value. Scope-local state — never `host.context`. */
+    publish(nodeId: string, portId: string, value: NgisResolvedValue | null): void;
+    snapshot(): NgisFlowSnapshot;
+}
+/** The enclosing scope, or `null` when a component is rendered outside one. */
+export declare function useFlowScope(): NgisFlowScope | null;
+export interface FlowProps {
+    children: ReactNode;
+    className?: string;
+    /**
+     * Render the dev flow-graph inspector beneath the children.
+     *
+     * **Not a production-stripping gate.** `NODE_ENV` folds away but a
+     * `NEXT_PUBLIC_*` read is a runtime property read, so a dev-gated branch
+     * survives minification either way; this is an author-facing switch that is
+     * simply off by default, and the inspector is inert — it reads the registry
+     * and writes nothing.
+     */
+    inspect?: boolean;
+    /** Called with a fresh snapshot whenever the graph or a resolution changes.
+     *  Y6's recipe serializer is the consumer this exists for (F14.6). */
+    onSnapshot?: (snapshot: NgisFlowSnapshot) => void;
+}
+export declare function Flow({ children, className, inspect, onSnapshot }: FlowProps): import("react/jsx-runtime").JSX.Element;
+export interface NgisFlowPortDeclaration {
+    /** The component's `id` prop — the **node** id (YD41). */
+    readonly id?: string;
+    /** The `data-slot` this component renders. See `flow-ports.ts`' correction. */
+    readonly slot: string;
+    readonly ports: readonly NgisPortSpec[];
+    /** In-port bindings plus spread directives, exactly as F14.4 spells them. */
+    readonly inputs?: Readonly<Record<string, NgisInputBinding>>;
+    /** This node's out-port values right now, keyed by member name. */
+    readonly outputs?: Readonly<Record<string, NgisResolvedValue | null>>;
+    /**
+     * **W4 KICKOFF ADDITION (YD49).** The tool this node runs, when it runs one.
+     * Rides the registry into the snapshot for Y6's serializer and Y7's batch
+     * config; the engine never reads it.
+     */
+    readonly config?: NgisFlowNodeConfig;
+}
+export interface NgisFlowPortState {
+    readonly nodeId: string;
+    /** `false` when the component is rendered outside any `<Flow>`. */
+    readonly inScope: boolean;
+    readonly enablement: NgisNodeEnablement;
+    /** By member name (and by spread key), for this node only. */
+    readonly resolutions: Readonly<Record<string, NgisPortResolution>>;
+    /** The satisfied subset of {@link NgisFlowPortState.resolutions}. */
+    readonly values: Readonly<Record<string, NgisResolvedValue>>;
+    /** `data-flow-node` / `data-port-in` / `data-port-out`, ready to spread. */
+    readonly nodeAttributes: Readonly<Record<string, string>>;
+}
+/**
+ * Declare this component's node, publish its outputs, read back its inputs.
+ *
+ * Called unconditionally by all eleven components, in or out of a scope: the
+ * ports are a static property of the component, so they are declared either way
+ * and `data-port-*` renders either way. Outside a scope nothing resolves and the
+ * node is trivially `ready`, which is precisely W2's behaviour — a component that
+ * took its values from props keeps working exactly as it did.
+ */
+export declare function useFlowPort(declaration: NgisFlowPortDeclaration): NgisFlowPortState;
+/**
+ * The DOM attributes one node renders.
+ *
+ * **CORRECTION.** `NGIS_PORT_ATTRIBUTES` gives one attribute per direction, and
+ * W2's three `data-port-*` sites each happen to have exactly one port, so the
+ * question never arose — but F14.5 gives `ParamForm` and `RunButton` **many** in
+ * ports. The value is therefore a space-separated member list, which is how every
+ * other multi-valued HTML attribute (`class`, `headers`, `aria-labelledby`) reads
+ * and what an e2e `[data-port-in~="ELEV"]` selector already understands.
+ * `data-flow-node` is present only inside a scope, because outside one there is
+ * no node to address.
+ */
+export declare function flowNodeAttributes(nodeId: string, ports: readonly NgisPortSpec[], inScope: boolean): Readonly<Record<string, string>>;
+/**
+ * F14.10's three states, rendered.
+ *
+ * `pending` is the only one that **dims**; `blocked` renders normally with its
+ * action disabled and its reason shown. Opacity and nothing else — no colour, so
+ * this is safe outside `.gis-theme` where `bg-warning` resolves to nothing at
+ * all, and `motion-safe:` because a state change should not animate for a reader
+ * who asked it not to.
+ */
+export declare function flowDimClass(enablement: NgisNodeEnablement): string | undefined;
+/**
+ * The generated reason as a notice line.
+ *
+ * The reason arrives as **data** — a message key plus its placeholders — because
+ * a pure model cannot hold a `useTranslations` and F14.10 requires the reason
+ * generated rather than authored. This is the only place it becomes a sentence,
+ * and `GIS.flow.reason.more` is appended rather than nested so the two locales
+ * can punctuate the join differently.
+ */
+export declare function useFlowReason(enablement: NgisNodeEnablement): NgisPickerNotice | null;
+/** The generated reason first: it is why the control cannot be used yet. */
+export declare function withFlowReason(notices: readonly NgisPickerNotice[] | undefined, reason: NgisPickerNotice | null): readonly NgisPickerNotice[];
+/**
+ * Splits a prop that may be a **binding reference** from one that is a value.
+ *
+ * F14.22 writes `<TaskStatus taskId="@run.taskId" />`, and `taskId` is typed
+ * `string | null` — so today that string is used as a literal task id and the
+ * component watches a task that does not exist. There is no type that can tell
+ * the two apart (F14.4 form 1 is any JSON literal, so `string` is already in the
+ * union), which is why the `@` sigil is a **runtime** discrimination and why
+ * `"@@"` opens a literal. This is the one place that decision is made, so no
+ * component makes it differently.
+ */
+export interface NgisFlowPropBinding {
+    /** Present when the prop named an upstream output. */
+    readonly binding?: NgisFlowRef;
+    /**
+     * The prop **verbatim** — what the in port's binding carries. A plain id is
+     * F14.4's form 1, a static JSON literal, so an author who passes a real task id
+     * has *bound* that port and the node is satisfied; only an absent value leaves
+     * it unbound. Verbatim and not unescaped, because `unescapeNgisStatic` runs at
+     * resolution and doing it twice would turn `"@@dem"` into the reference
+     * `"@dem"`.
+     */
+    readonly raw: string | null;
+    /** The value to use when there is no scope, with `"@@"` already unescaped. */
+    readonly literal: string | null;
+}
+export declare function flowPropBinding(value: string | null | undefined): NgisFlowPropBinding;
+/**
+ * The same split for a prop that is a **list** of ids, which is `TaskList`'s.
+ *
+ * F14.5 gives `TaskList` one in port and notes that "a single bound port
+ * contributes a one-element list", so at most one entry may be a reference — a
+ * node's port ids are member names unique within the node, so there is exactly
+ * one `taskId` member to bind. Any further reference in the list is ignored
+ * rather than silently watched as a task id, and the caller surfaces that.
+ */
+export interface NgisFlowListBinding extends NgisFlowPropBinding {
+    /** Every non-reference entry, `"@@"` unescaped — watched directly. */
+    readonly literals: readonly string[];
+    /** References beyond the first — an author error worth showing. */
+    readonly extraRefs: readonly string[];
+}
+export declare function flowListBinding(values: readonly string[]): NgisFlowListBinding;
+/** The in port's binding: the prop verbatim, or nothing when there is no value. */
+export declare function flowPropInputs(portId: string, binding: NgisFlowPropBinding): Readonly<Record<string, NgisInputBinding>>;
+/**
+ * A resolved port value read as a string, or the prop's literal.
+ *
+ * A `task` port carries the whole `NgisTaskRefValue`, so `taskId="@run"` — the
+ * default output port, bare — arrives as the handle rather than as an id. Reading
+ * the `taskId` member off it here is what makes the bare and the
+ * `"@run.taskId"` spellings agree, and it is a *rendering* concern rather than a
+ * resolution one: the resolver's answer is correct either way.
+ */
+export declare function flowString(values: Readonly<Record<string, NgisResolvedValue>>, portId: string, fallback: string | null): string | null;
+/** A resolved `resources` port read as a list, or the prop's own array. */
+export declare function flowStrings(values: Readonly<Record<string, NgisResolvedValue>>, portId: string, fallback: readonly string[]): readonly string[];
+/** A resolved `extent` port read as `NgisBounds`. */
+export declare function flowBounds(values: Readonly<Record<string, NgisResolvedValue>>, portId: string, fallback: NgisBounds | null): NgisBounds | null;
+/**
+ * The flow-graph dev inspector.
+ *
+ * It shows every node, its ports, the binding on each in port, what that binding
+ * resolved to, and the node's disclosure state and reason. **It inspects and does
+ * not edit** — a visual drag-and-drop pipeline editor is a binding cut for v1, so
+ * there is nothing here that writes to the registry.
+ *
+ * Not on `@ngis/plugin-ui`'s export table and not in either barrel: `<Flow
+ * inspect>` is how it is reached, because a name not on the ownership table is
+ * not this session's to publish.
+ *
+ * ## Stage 15 W4 (Z7) — the polish pass, and the one thing it deliberately did
+ * not do
+ *
+ * Three additions, each showing something the resolver already computed and the
+ * panel threw away:
+ *
+ * - **A state tally.** "4 nodes" does not answer the question an author has,
+ *   which is whether anything is blocked. The tally counts F14.10's three
+ *   disclosure states.
+ * - **Defects, verbatim.** `NgisFlowDefect.message` is by contract *"a
+ *   developer-facing English sentence, never a message key and never rendered to
+ *   an end user"* — F13.11 keeps plugin strings literal and F14.10 requires
+ *   user-facing reasons to be **generated**, so the two channels stay apart. Until
+ *   now the developer channel went only to `console.error`. A dev inspector,
+ *   reached by an explicit `<Flow inspect>`, is exactly the surface it belongs on,
+ *   and rendering it raw is *correct* rather than a missing translation.
+ * - **The node's tool.** `NgisFlowNode.config` (`{toolId, toolVersion}`, YD49)
+ *   rides the registry into the snapshot and the engine never reads it, so a
+ *   wrong or stale pin is invisible everywhere else. Shown as `toolId@version`.
+ *   Note the pin is **advisory once published**: `pinToolVersions` re-resolves
+ *   and overwrites every node's version at publish time.
+ *
+ * **No new message keys.** A "problems only" toggle wanted one, and
+ * `GIS.flow.*`'s closed-set gate lives in `flowMessages.test.ts`, which is not
+ * this session's file. Everything above renders from keys that already exist, a
+ * numeral, or a developer-channel string that must not be translated. The toggle
+ * is recorded as `V15-347` rather than smuggled in.
+ */
+export declare function FlowInspector({ scope, defects, }: {
+    scope: NgisFlowScope;
+    /** `resolveFlow`'s own findings. Developer-channel English — never translated. */
+    defects?: readonly NgisFlowDefect[];
+}): import("react/jsx-runtime").JSX.Element;

package/dist/src/components/plugin-ui/ModelSelect.d.ts

@@ -0,0 +1,36 @@
+import type { NgisModelSearchRequest } from "../../sdk/facets/types";
+import type { NgisHostAPI } from "../../sdk/host-api";
+export interface ModelSelectBaseProps {
+    host: NgisHostAPI;
+    /** The flow port id (F14.5). Also seeds the control's DOM id. */
+    id?: string;
+    /** Plugin-authored; rendered **literally** (F13.11). */
+    label?: string;
+    /** The tool id, or `null`. */
+    value: string | null;
+    onChange: (value: string | null) => void;
+    className?: string;
+    /** Class for the portalled `<Select>` content — see `ResourceSelect`. */
+    contentClassName?: string;
+}
+/**
+ * The two legs, as a union (YD54). `search` and the three `list` filters exclude
+ * each other with `never`, because `search` cannot express `category` or
+ * `modelboxId` and a component that accepted both would have to drop one in
+ * silence. `ResourceSelectProps`' single/multiple split is the same shape.
+ */
+export type ModelSelectProps = ModelSelectBaseProps & ({
+    /** F14.3's server-side facet query. `inputTypes`/`outputTypes` are the
+     *  whole reason the leg exists — client-side filtering cannot express them. */
+    search: NgisModelSearchRequest;
+    provider?: never;
+    category?: never;
+    modelboxId?: never;
+} | {
+    search?: undefined;
+    /** Server-side narrowing, straight through to `host.models.list` (F13.2). */
+    provider?: string;
+    category?: string;
+    modelboxId?: string;
+});
+export declare function ModelSelect({ host, id, label, value, onChange, search, provider, category, modelboxId, className, contentClassName, }: ModelSelectProps): import("react/jsx-runtime").JSX.Element;

package/dist/src/components/plugin-ui/ParamForm.d.ts

@@ -0,0 +1,63 @@
+import type { NgisHostAPI } from "../../sdk/host-api";
+import type { NgisWidgetKey } from "../../types/analysis";
+import type { NgisInputBinding } from "./w3-contracts";
+import { type NgisRunSubmission } from "./w2-contracts";
+/** What the form publishes on every pass. The `record` out port's payload (F14.5). */
+export interface NgisParamFormChange {
+    /** `null` until the schema has loaded. */
+    readonly submission: NgisRunSubmission | null;
+    /** Client rules (F14.9) refuse the submit. */
+    readonly blockedByClient: boolean;
+    /** The server's blocking messages, if it has answered. */
+    readonly blockingMessages: readonly string[];
+    /** `warnings` — never blocks (F14.9). */
+    readonly advisoryMessages: readonly string[];
+    /**
+     * F14.9: server validation **always runs once before submit**. Resolves
+     * `false` when either half refuses. Stable across renders, so a caller may
+     * hold it.
+     */
+    readonly validateBeforeSubmit: () => Promise<boolean>;
+}
+export interface ParamFormProps {
+    /** The 0.4 facade — always the one `createGisPluginHostFactory` minted. */
+    host: NgisHostAPI;
+    /** The flow port id (F14.5, `record` out port). Also seeds the field DOM ids. */
+    id?: string;
+    /** Plugin-authored; rendered **literally** (F13.11). */
+    label?: string;
+    /** The tool whose UI schema this form is generated from. */
+    toolId: string;
+    /**
+     * Param names the form does not render — already bound by a flow port
+     * (F14.22's `hide={["ELEV"]}`). **An unknown name survives and is surfaced**,
+     * never dropped (F14.9, the `ExtensionSettingsForm` rule).
+     */
+    hide?: readonly string[];
+    /**
+     * Flow bindings for params hidden because another node supplies them. The
+     * values are resolved for this node's required in-ports; the form's record
+     * output still contains only the fields it owns, so a RunButton should keep
+     * its explicit binding for the same param.
+     */
+    inputs?: Readonly<Record<string, NgisInputBinding>>;
+    /**
+     * Param name → widget key. The only way to reach `textarea`, `extent` and
+     * `field-select`, which YB1 never emits. **Unknown names are surfaced.**
+     */
+    widgets?: Readonly<Record<string, NgisWidgetKey>>;
+    /**
+     * Wire-shaped seed values, applied over `default_value` — F14.8's preset
+     * `params` with `$context:` already resolved, or a saved recipe's bindings.
+     */
+    values?: Readonly<Record<string, string>>;
+    onChange?: (change: NgisParamFormChange) => void;
+    /** Forwarded to `host.models.validate` (F14.3). */
+    sceneId?: string;
+    className?: string;
+    /** Class for every portalled `<Select>` content — see `ResourceSelect`. */
+    contentClassName?: string;
+    /** Reports the exact layer chosen from a duplicate-named resource option. */
+    onSameNamedLayerSelect?: (layerId: string) => void;
+}
+export declare function ParamForm({ host, id, label, toolId, hide, inputs, widgets, values: seed, onChange, sceneId, className, contentClassName, onSameNamedLayerSelect, }: ParamFormProps): import("react/jsx-runtime").JSX.Element;

package/dist/src/components/plugin-ui/PickerField.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The shared chrome of the four W1 pickers (Stage 14 Y2): a label, a control,
+ * and the notice lines beneath it.
+ *
+ * The notice slot is not decoration — it is where F14's "surfaced, never
+ * masked" rule is actually implemented. Type widening (F14.1), a field the new
+ * parent does not carry (F14.9), a parent that left the scene, a mode with no
+ * map bound: every one of those renders here rather than collapsing into an
+ * empty control. Factored out so all four say it the same way and no component
+ * can quietly choose not to.
+ *
+ * `label` is **plugin-authored and rendered literally** (F13.11). Everything in
+ * `notices` is a host string the caller has already translated under
+ * `GIS.pluginUi.pick` — this component holds no `useTranslations` of its own,
+ * so it cannot invent copy the caller did not ask for.
+ */
+import type { ReactNode } from "react";
+export type NgisPickerNoticeTone = "info" | "warn";
+export interface NgisPickerNotice {
+    /** Stable within one field — used as the React key. */
+    id: string;
+    /** Already-translated host text. */
+    text: string;
+    tone: NgisPickerNoticeTone;
+}
+export interface PickerFieldProps {
+    /** Control id; also `<label for>`. */
+    controlId?: string;
+    /** Plugin string, literal (F13.11). Omitted when the author gave none. */
+    label?: string;
+    /** Visual required marker for a schema-defined mandatory field. */
+    required?: boolean;
+    /** Lets a context such as ParamForm promote its field label without changing
+     * the compact, muted label language of every other picker. */
+    labelClassName?: string;
+    notices?: readonly NgisPickerNotice[];
+    className?: string;
+    /**
+     * `data-flow-node` / `data-port-in` / `data-port-out` for this component's node
+     * (Stage 14 Y5b, W3), from `flowNodeAttributes`. Spread onto the root because
+     * all eleven components render through this chrome, so every node's ports become
+     * visible in the DOM from one hunk rather than eleven — and because they are the
+     * only way an e2e spec can see a port at all.
+     */
+    flowAttributes?: Readonly<Record<string, string>>;
+    children: ReactNode;
+}
+export declare function PickerField({ controlId, label, required, labelClassName, notices, className, flowAttributes, children, }: PickerFieldProps): import("react/jsx-runtime").JSX.Element;
+/** Terse, token-only placeholder for "there is nothing to choose from". */
+export declare function PickerEmpty({ text }: {
+    text: string;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/src/components/plugin-ui/ResourceSelect.d.ts

@@ -0,0 +1,37 @@
+import type { NgisDataType } from "../../sdk/facets/types";
+import type { NgisHostAPI } from "../../sdk/host-api";
+export interface ResourceSelectBaseProps {
+    /** The 0.4 facade — always the one `createGisPluginHostFactory` minted. */
+    host: NgisHostAPI;
+    /** The flow port id (F14.5). Also seeds the control's DOM id. */
+    id?: string;
+    /** Plugin-authored; rendered **literally** (F13.11). */
+    label?: string;
+    /** Canonical `NgisDataType` (F14.1). Omit for "any resource". */
+    types?: readonly NgisDataType[];
+    className?: string;
+    /**
+     * Class for the portalled `<Select>` content. Radix portals to
+     * `document.body`, **outside** `.gis-theme` — pass `"gis-theme"` when this is
+     * mounted inside the GIS workspace, or the listbox picks up the app-level
+     * palette. The `VersionPolicyControl` / `ExtensionSettingsForm` precedent.
+     * Unused in `multiple` mode, which renders in-tree.
+     */
+    contentClassName?: string;
+    /**
+     * Reports an exact scene layer when a duplicate-named layer is chosen. The
+     * bound value remains the file id; hosts may use this only for transient UI
+     * feedback such as locating the matching row in a layer list.
+     */
+    onSameNamedLayerSelect?: (layerId: string) => void;
+}
+export type ResourceSelectProps = (ResourceSelectBaseProps & {
+    multiple?: false;
+    value: string | null;
+    onChange: (value: string | null) => void;
+}) | (ResourceSelectBaseProps & {
+    multiple: true;
+    value: readonly string[];
+    onChange: (value: readonly string[]) => void;
+});
+export declare function ResourceSelect(props: ResourceSelectProps): import("react/jsx-runtime").JSX.Element;

package/dist/src/components/plugin-ui/ResultActions.d.ts

@@ -0,0 +1,48 @@
+import type { NgisChartSpec, NgisHostAPI } from "../../sdk/host-api";
+export interface ResultActionsProps {
+    /** The 0.4 facade — always the one `createGisPluginHostFactory` minted. */
+    host: NgisHostAPI;
+    /** The flow port id (F14.5). Also seeds the control's DOM id. */
+    id?: string;
+    /** Plugin-authored; rendered **literally** (F13.11). */
+    label?: string;
+    /** The `taskId` in port's current value (`task` kind). */
+    taskId: string | null;
+    /** Offer the post-hoc `host.viz.addResultLayer` path (`viz:write`). */
+    addLayer?: boolean;
+    /** Offer `host.viz.openTable` over the output's scene resource (ungated). */
+    table?: boolean;
+    /**
+     * Offer `host.viz.chart` (ungated). A fixed `chartSpec` supports task-level
+     * summaries. Without one, ResultActions reads field frequencies through
+     * `host.resources` and builds a public default bar chart.
+     */
+    chart?: boolean;
+    /**
+     * Fixed task-level summary. Without it the component owns output/field
+     * selection and uses the host-backed default field-frequency chart.
+     */
+    chartSpec?: NgisChartSpec;
+    /**
+     * Optional custom chart builder for the selected output and field. Omit it to
+     * use the public field-frequency bar chart; supply it only for a different
+     * statistical interpretation.
+     */
+    buildChartSpec?: (request: NgisResultChartRequest) => NgisChartSpec | Promise<NgisChartSpec>;
+    className?: string;
+    /** Class for the portalled field selector content. */
+    contentClassName?: string;
+}
+export interface NgisResultChartRequest {
+    output: NgisResultChartOutput;
+    field: string;
+}
+/** Stable public chart target; deliberately excludes ResultActions' internal
+ * scene-join projection beyond the fields a chart adapter can rely on. */
+export interface NgisResultChartOutput {
+    readonly fileId: string;
+    readonly name: string | null;
+    readonly primary: boolean;
+    readonly resourceId: string | null;
+}
+export declare function ResultActions({ host, id, label, taskId: taskIdProp, addLayer, table, chart, chartSpec, buildChartSpec, className, contentClassName, }: ResultActionsProps): import("react/jsx-runtime").JSX.Element;

package/dist/src/components/plugin-ui/RunButton.d.ts

@@ -0,0 +1,49 @@
+import type { NgisHostAPI } from "../../sdk/host-api";
+import type { NgisTaskHandle } from "../../sdk/facets/types";
+import type { NgisExecutionValidation } from "../../types/analysis";
+import { type NgisRunOptions } from "./run-data";
+import { type NgisRunSubmission } from "./w2-contracts";
+import type { NgisInputBinding } from "./w3-contracts";
+export interface RunButtonBaseProps extends NgisRunOptions {
+    host: NgisHostAPI;
+    /** The **node** id within the `<Flow>` scope (YD41). Also seeds the DOM id. */
+    id?: string;
+    /** Plugin-authored; rendered **literally** (F13.11). */
+    label?: string;
+    /** Plugin-authored action text, literal. Defaults to the host string. */
+    actionLabel?: string;
+    /**
+     * F14.10's single sanctioned publication: the task id, written as the **bare**
+     * key `taskId` and namespaced by the host. Opt out when the plugin declares no
+     * status item that reads it — nothing else about flow state leaves the scope.
+     */
+    publishTaskId?: boolean;
+    onSubmitted?: (handle: NgisTaskHandle) => void;
+    onValidated?: (validation: NgisExecutionValidation) => void;
+    className?: string;
+}
+/**
+ * The two shapes, as a union rather than two optional props, so that "`inputs`
+ * without a `toolId`" and "both at once" are compile errors instead of runtime
+ * surprises. The `ResourceSelectProps` precedent, in this same package.
+ */
+export type RunButtonProps = (RunButtonBaseProps & {
+    /**
+     * What a generated form produced. `null` while there is nothing runnable —
+     * rendered as a reason, never as an unexplained inert button (F14.10).
+     */
+    submission: NgisRunSubmission | null;
+    toolId?: never;
+    inputs?: never;
+}) | (RunButtonBaseProps & {
+    submission?: never;
+    /** The tool to run; its UI schema supplies each bound input's role,
+     *  requiredness and label — F14.10's provenance chain, unaltered. */
+    toolId: string;
+    /**
+     * F14.4's bindings, keyed by tool parameter name, plus any number of
+     * `...ngisFlowSpread("@ref")` directives. Needs an enclosing `<Flow>`.
+     */
+    inputs: Readonly<Record<string, NgisInputBinding>>;
+});
+export declare function RunButton(props: RunButtonProps): import("react/jsx-runtime").JSX.Element;

package/dist/src/components/plugin-ui/StatChart.d.ts

@@ -0,0 +1,66 @@
+import type { NgisChartSpec, NgisHostAPI } from "../../sdk/host-api";
+import { type NgisChartTheme } from "./stat-chart-model";
+/**
+ * Why there is nothing to draw. `"ready"` is the only arm that renders a chart;
+ * every other arm renders a reason, never a dead or empty plot (F14.10).
+ */
+export type NgisStatChartGate = {
+    readonly kind: "ready";
+}
+/** No spec at all — the author has not computed one yet. */
+ | {
+    readonly kind: "no-spec";
+}
+/** A `taskId` in port was declared and is unsatisfied. */
+ | {
+    readonly kind: "no-task";
+}
+/** A `resource` in port was declared and is unsatisfied. */
+ | {
+    readonly kind: "no-resource";
+}
+/** A spec with no plottable numbers — distinct from having no spec at all. */
+ | {
+    readonly kind: "empty";
+};
+export interface NgisStatChartPorts {
+    /** `undefined` = this component declares no `taskId` port. `null` = declared
+     *  and unsatisfied. F14.5's table says `taskId` **or** `resource`. */
+    readonly taskId?: string | null;
+    readonly resource?: string | null;
+}
+/**
+ * The gate, in declaration order: an unsatisfied *port* outranks a missing spec,
+ * because "the upstream has not produced anything" is the more useful answer than
+ * "you gave me no numbers" when both are true and one causes the other.
+ */
+export declare function statChartGate(spec: NgisChartSpec | null | undefined, ports: NgisStatChartPorts): NgisStatChartGate;
+export interface StatChartProps {
+    /** The 0.4 facade — always the one `createGisPluginHostFactory` minted.
+     *  `StatChart` reads nothing through it: the spec is the data, and that is the
+     *  point (see the header). It is prop #1 because every `@ngis/plugin-ui`
+     *  component takes it there, and because a component that quietly did not need
+     *  a host would be the first place a plugin stopped being host-renderable. */
+    host: NgisHostAPI;
+    /** The flow port id (F14.5). Also seeds the control's DOM id. */
+    id?: string;
+    /** Plugin-authored; rendered **literally** (F13.11). */
+    label?: string;
+    spec: NgisChartSpec | null;
+    /** The `taskId` in port's value. Omit the prop entirely to declare no such port. */
+    taskId?: string | null;
+    /** The `resource` in port's value. Omit the prop entirely to declare no such port. */
+    resource?: string | null;
+    /** Plot height in px; the container includes the axis band. Default 220. */
+    height?: number;
+    className?: string;
+}
+export declare function StatChart({ host, id, label, spec, taskId: taskIdProp, resource: resourceProp, height, className, }: StatChartProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * The Tenon dark palette lives under `.dark .gis-theme`, so `resolvedTheme` is
+ * the right signal and not a media query. ECharts paints to a canvas and cannot
+ * resolve a CSS custom property, which is why the palette is hex in
+ * `stat-chart-model.ts` rather than `var(--…)` — and why the theme has to be
+ * read in JS at all.
+ */
+export declare function useChartTheme(): NgisChartTheme;

package/dist/src/components/plugin-ui/TaskChrome.d.ts

@@ -0,0 +1,35 @@
+import type { NgisTaskStage, NgisTaskStatus } from "../../sdk/facets/types";
+import type { NgisTaskLifecycle } from "./run-model";
+export type NgisTaskChipTone = "idle" | "active" | "done" | "failed";
+/**
+ * `status` alone decides the tone. The *stage* is the rail's job, and folding a
+ * pending integration into the chip would collapse the very distinction the pair
+ * exists to show.
+ */
+export declare function taskChipTone(status: NgisTaskStatus): NgisTaskChipTone;
+export interface TaskStatusChipProps {
+    status: NgisTaskStatus;
+    /** Already-translated `GIS.pluginUi.run.task.status.*`. */
+    label: string;
+    className?: string;
+}
+export declare function TaskStatusChip({ status, label, className }: TaskStatusChipProps): import("react/jsx-runtime").JSX.Element;
+export interface TaskStageRailProps {
+    lifecycle: NgisTaskLifecycle;
+    /** Already-translated `GIS.pluginUi.run.task.stage.*`, per stage. */
+    stageLabel: (stage: NgisTaskStage) => string;
+    className?: string;
+}
+/**
+ * Decorative by construction: `aria-hidden`, because the stage it encodes is
+ * rendered as text beside it. A rail that were the *only* carrier of the stage
+ * would be a screen-reader dead end.
+ */
+export declare function TaskStageRail({ lifecycle, stageLabel, className }: TaskStageRailProps): import("react/jsx-runtime").JSX.Element;
+/** One `label: value` line, mono-set on the value. Ids and stage names are
+ *  machine facts and are spelled in the machine's own type. */
+export declare function TaskFactLine({ label, value, className, }: {
+    label: string;
+    value: string;
+    className?: string;
+}): import("react/jsx-runtime").JSX.Element;