@ngis/plugin-ui 0.4.0

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

@@ -0,0 +1,29 @@
+import type { NgisHostAPI } from "../../sdk/host-api";
+import { type NgisTaskVariant } from "./TaskStatus";
+export interface TaskListProps {
+    host: NgisHostAPI;
+    /** The flow port scope id (F14.5). Also seeds the DOM id. */
+    id?: string;
+    /** Plugin-authored; rendered **literally** (F13.11). */
+    label?: string;
+    /**
+     * The tasks to show. Empty renders a reason, not a blank panel.
+     *
+     * Inside a `<Flow>`, **one** entry may be a reference (`"@run.taskId"`): F14.5
+     * gives this component a single `taskId` in port, and a bound port contributes a
+     * one-element list, so the resolved value joins the literal ids. A second
+     * reference has no port to bind to and is surfaced rather than watched.
+     */
+    taskIds: readonly string[];
+    /** Defaults to `full` — the point of the list is the detail. */
+    variant?: NgisTaskVariant;
+    /**
+     * Hide rows whose lifecycle has finished. **`SUCCESS` while integration is
+     * still pending is not finished** ({@link isTerminalTaskState}), so such a row
+     * survives this filter — collapsing it would be the `complete`/`integrated`
+     * conflation the whole facet is built to prevent.
+     */
+    activeOnly?: boolean;
+    className?: string;
+}
+export declare function TaskList({ host, id, label, taskIds: taskIdsProp, variant, activeOnly, className, }: TaskListProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,55 @@
+import type { NgisHostAPI } from "../../sdk/host-api";
+import type { NgisTaskState } from "../../sdk/facets/types";
+export type NgisTaskVariant = "compact" | "full";
+export interface NgisWatchedTasks {
+    /** Keyed by task id; absent until the first update for that id arrives. */
+    readonly states: Readonly<Record<string, NgisTaskState>>;
+    /** A `watch` that threw synchronously — a scope refusal, most likely. */
+    readonly error: unknown;
+}
+/**
+ * One watcher per id, opened on mount and closed on change or unmount.
+ *
+ * `watch` is synchronous and returns the watcher, so a scope refusal
+ * (`tasks:read`) throws *here* rather than rejecting later — caught and reported,
+ * because an unhandled throw in an effect takes the whole panel down and tells the
+ * author nothing.
+ *
+ * The dependency is the **joined** id list: `taskIds` is typically a fresh array
+ * literal every render, and depending on its identity would tear every watcher
+ * down and rebuild it on each keystroke elsewhere in the panel.
+ */
+export declare function useWatchedTaskStates(host: NgisHostAPI, taskIds: readonly string[]): NgisWatchedTasks;
+export interface TaskStateViewProps {
+    host: NgisHostAPI;
+    state: NgisTaskState;
+    variant: NgisTaskVariant;
+    className?: string;
+}
+/**
+ * The presentation of one `NgisTaskState`, shared by both surfaces so
+ * `<TaskList>` is genuinely `<TaskStatus>` repeated rather than a second
+ * rendering of the same facts. Not on `@ngis/plugin-ui`'s export table — it is an
+ * internal of this pair.
+ */
+export declare function TaskStateView({ host, state, variant, className }: TaskStateViewProps): import("react/jsx-runtime").JSX.Element;
+export interface TaskStatusProps {
+    host: NgisHostAPI;
+    /** The flow port scope id (F14.5). Also seeds the DOM id. */
+    id?: string;
+    /** Plugin-authored; rendered **literally** (F13.11). */
+    label?: string;
+    /**
+     * The bound `taskId` port value. `null` renders a reason, not an empty box.
+     *
+     * Inside a `<Flow>` this may be a **reference** — F14.22 writes
+     * `taskId="@run.taskId"` — which is resolved through the `taskId` in port.
+     * Outside a scope, or for a string that is not a reference, it is the task id
+     * itself; `"@@"` opens a literal.
+     */
+    taskId: string | null;
+    variant?: NgisTaskVariant;
+    onStateChange?: (state: NgisTaskState) => void;
+    className?: string;
+}
+export declare function TaskStatus({ host, id, label, taskId: taskIdProp, variant, onStateChange, className, }: TaskStatusProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,442 @@
+/**
+ * `<BatchTable>`'s pure half (Stage 14 Y7 — **F14.21**, F14.9, F14.4).
+ *
+ * The seam this stage has now used five times — `picker-model`/`picker-data`,
+ * `param-form-model`, `run-model`, `flow-model`, and here. Nothing below imports
+ * React, a host, an API client or the DOM, and for batch that is load-bearing
+ * rather than stylistic: **two of F14.21's three hard rules are statements about
+ * scheduling**, and a rule that lives in a `useEffect` cannot be asserted.
+ *
+ * | F14.21 rule | where it lives here |
+ * |---|---|
+ * | one `host.tasks.run` per row | {@link runBatchQueue}, one `submit` call per row id |
+ * | a **concurrency cap of 3** | {@link batchQueueDispatch} + {@link NGIS_BATCH_CONCURRENCY} |
+ * | **a failed row does not cancel the rest** | {@link settleBatchQueueRow} — see below |
+ * | one row per run, same generated widgets | {@link batchColumns} + one {@link NgisParamFormState} per row |
+ * | JSON-saveable | {@link toBatchConfig} / {@link parseBatchConfig} / {@link fromBatchConfig} |
+ *
+ * **"A failed row does not cancel the rest" is expressed as an absence.** The
+ * queue has no notion of success or failure at all: {@link settleBatchQueueRow}
+ * moves a row from `running` to `settled` and takes no outcome, so there is no
+ * arm in which it could stop. A queue that read the outcome and *chose* to
+ * continue would be one edit away from choosing not to; a queue that cannot see
+ * the outcome cannot regress. {@link runBatchQueue} therefore catches everything
+ * `submit` can do — resolve, reject, or throw synchronously — and turns each into
+ * a per-row result rather than a rejected batch.
+ *
+ * **The cap is not a tuning knob** (F14.21, and the seam says so again at
+ * `w4-contracts.ts:614-621`): the task fabric and the `UsageLimiter` windows are
+ * shared and nothing below this line bounds concurrency. {@link runBatchQueue}
+ * measures its own {@link NgisBatchRunReport.peakInFlight} so the cap is
+ * assertable from the runner's own report rather than from a test's
+ * instrumentation of the callback it passed in.
+ *
+ * ## Each row is a whole `ParamForm` lifecycle, not a row of raw strings
+ *
+ * F14.21's *"the same generated widgets per cell"* means the cell values are
+ * subject to the same four phases as a single-run form (F14.9), including the one
+ * hard rule — *a repopulate never overwrites a field whose `altered` is `true`* —
+ * and including `depends_on` visibility, which is **per row**: two rows of one
+ * tool can legitimately disagree about whether a parameter applies. So a row
+ * holds an {@link NgisParamFormState} and every mutation goes through
+ * `param-form-model.ts`. Nothing here re-implements a phase.
+ *
+ * ## Expression-driven row generation is OUT for v1
+ *
+ * F14.21, verbatim. {@link fillBatchColumnDown} is *not* that: it copies the
+ * first row's value into the others, which is QGIS's own "fill down" and involves
+ * no expression, no grammar and no new vocabulary. Anything that computed a value
+ * would need a third grammar, which F14.4 forbids outright.
+ */
+import type { NgisToolUiParam, NgisToolUiSchema } from "../../types/analysis";
+import { type NgisParamFormError, type NgisParamFormState } from "./param-form-model";
+import type { NgisRunOutcome } from "./run-data";
+import type { NgisParamValue, NgisRunSubmission } from "./w2-contracts";
+import { type NgisBatchConfig, type NgisRecipe } from "./w4-contracts";
+/**
+ * The kickoff seam's rows, re-exported here so the barrels take them from this
+ * module and `w4-contracts.ts` stays a wave artifact — the same rule
+ * `flow-model.ts` keeps for `w3-contracts.ts` (and `w4-contracts.ts:26-31` states
+ * for itself). Nothing is re-declared: these are the seam's own definitions.
+ *
+ * **`recipeColumns` is deliberately NOT re-exported here — `recipe-model.ts`
+ * publishes it, and this module only imports it.** Found at the W4 merge, and it
+ * is the shape of defect the merge exists to catch: it is the one seam function
+ * *both* W4 sessions read, so each re-exported it from its own labelled hunk in
+ * the host barrel, the two hunks are disjoint so the merge was textually clean,
+ * and the result was `error TS2300: Duplicate identifier 'recipeColumns'` that
+ * **neither branch could produce alone**. The rule the kickoff should have
+ * carved and did not: a *shared* seam row is published by exactly one owner, and
+ * for a recipe function that owner is the session that owns recipes. Y7's own
+ * `recipeBatchColumns` — which composes it with the batch's column projection —
+ * is unaffected and is genuinely Y7's.
+ */
+export { NGIS_BATCH_CONCURRENCY, NGIS_BATCH_VERSION, ngisBatchCellId, } from "./w4-contracts";
+export type { NgisBatchConfig } from "./w4-contracts";
+/**
+ * Something the table found in its own inputs. **Surfaced, never masked** — the
+ * `ExtensionSettingsForm` rule that F14.9 already applies to an author's
+ * `widgets`/`hide` overrides, applied to a saved config and to a recipe's
+ * promoted inputs.
+ *
+ * None of these is a refusal. The only refusal is an unknown `batchVersion`, and
+ * it is an arm of {@link NgisBatchConfigParse} rather than a defect, because
+ * F14.21 carries F14.2's rule verbatim: a reader that does not know the version
+ * **refuses**; it never best-efforts.
+ */
+export interface NgisBatchDefect {
+    readonly kind: 
+    /** A column that is not a parameter of the loaded schema. */
+    "unknown-column"
+    /** The config was authored against a different tool. */
+     | "tool-mismatch"
+    /** Same tool, different `tool_version`. */
+     | "version-mismatch"
+    /**
+     * A saved value F14.9's *mutate* replaced on load — off the parameter's
+     * current `choices`, or uncoercible to its `value_type`.
+     *
+     * **This is the one silent data loss a batch config can suffer, and finding
+     * it is why the defect exists.** `initializeParamForm` seeds with
+     * `altered: false` (F14.9's text is explicit), and *mutate* drops an
+     * unaltered value the current option list no longer offers — so a config
+     * carrying `MODE: "legacy"` for a tool whose choices are now
+     * `simple|advanced|expert` loads as `"simple"` with nothing on screen. The
+     * rule is right and is not changed here; what was missing was anybody saying
+     * so. `subject` is the parameter, `detail` the value that was dropped.
+     */
+     | "dropped-value";
+    readonly subject: string;
+    readonly detail: string | null;
+}
+/** One run. */
+export interface NgisBatchRow {
+    /**
+     * Stable for the row's whole life, minted from {@link
+     * NgisBatchTableState.nextRowId} and **never reused** — it is the React key,
+     * and a reused key would carry one row's widget state onto another.
+     *
+     * Deliberately *not* the cell-id seed: {@link ngisBatchCellId} takes a **row
+     * index**, and that spelling is the seam's (CORRECTION 10). See
+     * {@link batchCellId}.
+     */
+    readonly id: string;
+    /** F14.9's state for this row, in full. */
+    readonly form: NgisParamFormState;
+    /**
+     * Values from a loaded config whose keys name no parameter of the current
+     * schema. Carried verbatim so a load-then-save cannot silently delete an
+     * author's data — the same reason F14.9 keeps unknown override keys.
+     */
+    readonly extras: Readonly<Record<string, string>>;
+}
+export interface NgisBatchTableState {
+    readonly toolId: string;
+    readonly toolVersion: number;
+    /** UI-schema param names, in display order (F14.21). */
+    readonly columns: readonly string[];
+    readonly rows: readonly NgisBatchRow[];
+    readonly outputMode: "ADD_LAYER" | "UPDATE_RESOURCE";
+    readonly sceneId: string | null;
+    readonly defects: readonly NgisBatchDefect[];
+    /** Next row-id ordinal. Monotonic, so ids are unique across removals. */
+    readonly nextRowId: number;
+}
+export interface NgisBatchInit {
+    /** How many empty rows to open with. Clamped to at least one. */
+    readonly rows?: number;
+    /**
+     * The column order to prefer over the schema's own — a published recipe's
+     * promoted inputs (F14.21, via {@link recipeColumns}), or a saved config's
+     * columns. Names the schema does not know become `unknown-column` defects.
+     */
+    readonly columns?: readonly string[];
+    readonly outputMode?: "ADD_LAYER" | "UPDATE_RESOURCE";
+    readonly sceneId?: string | null;
+    /** Wire-shaped seed applied to every opening row. */
+    readonly seed?: Readonly<Record<string, string>>;
+}
+export interface NgisBatchColumns {
+    readonly columns: readonly string[];
+    /** Preferred names the schema does not declare. Reported, never dropped. */
+    readonly unknown: readonly string[];
+}
+/**
+ * The columns, and which requested names the tool does not have.
+ *
+ * With no `preferred`, the order is the schema's own — which is F14.21's
+ * "display order" and is the order the server served. With a `preferred` list,
+ * the known names lead in *that* order and the remaining parameters follow, so a
+ * recipe's or a config's ordering is honoured without ever hiding a parameter
+ * the tool actually takes. A parameter absent from the table is a parameter that
+ * silently submits its `default_value` on every row, which is the batch version
+ * of the `V-224` failure.
+ */
+export declare function batchColumns(schema: NgisToolUiSchema, preferred?: readonly string[]): NgisBatchColumns;
+/**
+ * A published recipe's batch columns (F14.21), through the seam's own function.
+ *
+ * Thin on purpose: {@link recipeColumns} is the one function both W4 sessions
+ * read, so the recipe → column mapping exists once. What this adds is the
+ * *reconciliation* — a recipe input id that is not a parameter of the published
+ * tool's UI schema becomes a defect here rather than a missing column nobody
+ * mentions.
+ */
+export declare function recipeBatchColumns(schema: NgisToolUiSchema, recipe: NgisRecipe): NgisBatchColumns;
+export declare function initializeBatchTable(schema: NgisToolUiSchema, init?: NgisBatchInit): NgisBatchTableState;
+export declare function addBatchRow(schema: NgisToolUiSchema, state: NgisBatchTableState, seed?: Readonly<Record<string, string>>): NgisBatchTableState;
+/**
+ * Copy a row, values and all.
+ *
+ * The copy's fields keep the source's `altered` flags, because the values really
+ * were chosen by a user and F14.9's repopulation rule protects exactly that. A
+ * duplicate whose fields claimed `altered: false` would have its values dropped
+ * by the next `mutate` that repopulated a list.
+ */
+export declare function duplicateBatchRow(state: NgisBatchTableState, rowId: string): NgisBatchTableState;
+/** Removing the last row leaves the table empty; it does not re-seed one. A
+ *  batch with no rows is a real state and the caller says so. */
+export declare function removeBatchRow(state: NgisBatchTableState, rowId: string): NgisBatchTableState;
+/**
+ * One cell edit, through F14.9's `setParamValue` — which sets `altered` and
+ * re-runs *mutate* for that row only.
+ *
+ * `optionLists` is per row for the same reason visibility is: `field-select`
+ * follows a sibling resource cell, and two rows pointing at different datasets
+ * have different field lists.
+ */
+export declare function setBatchCell(schema: NgisToolUiSchema, state: NgisBatchTableState, rowId: string, name: string, value: NgisParamValue, optionLists?: Readonly<Record<string, readonly string[]>>): NgisBatchTableState;
+/**
+ * QGIS's fill-down: the first row's value for one column, copied into every
+ * other row.
+ *
+ * **Not expression-driven row generation** (F14.21 puts that out of v1) — no
+ * value is computed, and the source is a value a user already typed. It goes
+ * through {@link setBatchCell}, so each target row runs its own *mutate* and a
+ * column whose value the target row's option list does not offer is handled by
+ * F14.9's rule rather than by a second one written here.
+ */
+export declare function fillBatchColumnDown(schema: NgisToolUiSchema, state: NgisBatchTableState, name: string): NgisBatchTableState;
+export declare function setBatchOutput(state: NgisBatchTableState, output: {
+    readonly outputMode?: "ADD_LAYER" | "UPDATE_RESOURCE";
+    readonly sceneId?: string | null;
+}): NgisBatchTableState;
+/**
+ * A cell's node/DOM id — **the seam's spelling, never a local one**
+ * (`ngisBatchCellId`, CORRECTION 10).
+ *
+ * Four of the twelve widgets delegate to components that are themselves flow
+ * nodes keyed by their `id` prop, and the flow registry is last-wins on node id,
+ * so N rows rendering one parameter under one id collapse to a single node and
+ * N−1 cells bind to nothing.
+ *
+ * **It takes a row *index*, not a row id, and that is worth stating.** Removing a
+ * row therefore renumbers every cell below it, and the surviving rows'
+ * widget-level nodes re-register under their new ids. That is correct — the
+ * registry keys on the id it is given and a vanished id unregisters — but it also
+ * means a cell id is not a durable handle for anything outside one render. Use
+ * {@link NgisBatchRow.id} for identity and this for the DOM.
+ */
+export declare function batchCellId(scopeId: string, rowIndex: number, name: string): string;
+export interface NgisBatchGate {
+    /** Row ids whose client validation passed. Submitted, in this order. */
+    readonly ready: readonly string[];
+    /** Row id → its client errors. Never submitted; a reason is rendered instead. */
+    readonly blocked: Readonly<Record<string, readonly NgisParamFormError[]>>;
+}
+/**
+ * F14.9's *validate (client)*, per row.
+ *
+ * Blocked rows are **partitioned out before anything is submitted**, rather than
+ * being enqueued and refused later. Both would honour F14.9, but a fifty-row
+ * batch where six rows are incomplete should say "six rows can't run yet" before
+ * it spends the other forty-four's worth of task-fabric budget — and a blocked
+ * row that occupied a concurrency slot for the duration of a refusal would make
+ * the cap of 3 mean something slightly different from what F14.21 says.
+ */
+export declare function gateBatchRows(schema: NgisToolUiSchema, state: NgisBatchTableState): NgisBatchGate;
+/**
+ * Fold the client errors back onto every row's fields, marking them
+ * `hasBeenValidated` — F14.9's `applyClientErrors`, applied row-wise so each
+ * cell can render its own message.
+ */
+export declare function applyBatchClientErrors(schema: NgisToolUiSchema, state: NgisBatchTableState, render: (error: NgisParamFormError) => string): NgisBatchTableState;
+/** The `NgisRunSubmission` for one row — `toSubmission`, unchanged. */
+export declare function batchRowSubmission(schema: NgisToolUiSchema, row: NgisBatchRow): NgisRunSubmission;
+/** Whether a cell applies to its row at all (`depends_on`, F14.9). Per row. */
+export declare function batchCellVisible(row: NgisBatchRow, name: string): boolean;
+export type NgisBatchRowPhase = 
+/** Never submitted. */
+"idle"
+/** Waiting for a concurrency slot. */
+ | "queued"
+/** Submitted; the task is in flight. */
+ | "running"
+/** Client validation, or the server's pre-flight verdict, refused it. */
+ | "blocked"
+/** Submitted successfully — there is a task id. */
+ | "submitted"
+/** The validate or the run call itself rejected. */
+ | "failed";
+export interface NgisBatchRowResult {
+    readonly phase: "blocked" | "submitted" | "failed";
+    readonly taskId: string | null;
+    /**
+     * Why, on this row. F14.21 says a failed row does not cancel the rest, so this
+     * is the only per-row signal there is — which is why the caller resolves it
+     * through `readApiErrorMessage` (F14.15) rather than off `Error.message`.
+     */
+    readonly messages: readonly string[];
+}
+/**
+ * One row's `NgisRunOutcome`, projected.
+ *
+ * The three arms map one-for-one and deliberately do not collapse: `blocked` is
+ * *the server answered and said no*, `failed` is *we could not ask* (a scope
+ * refusal, a transport failure, a facet stub). Those are different things to tell
+ * an author, and `run-data.ts:121-124` keeps them apart for the same reason.
+ *
+ * `message` is the caller's already-extracted server message — `null` when the
+ * error carried none, in which case the caller renders its own generic string
+ * (F14.15). This module never touches `ApiError`, which is what keeps it pure.
+ */
+export declare function batchRowResultOf(outcome: NgisRunOutcome, message: string | null): NgisBatchRowResult;
+/** A row refused before any host call, from its client errors. */
+export declare function blockedBatchRowResult(messages: readonly string[]): NgisBatchRowResult;
+export interface NgisBatchQueueState {
+    readonly pending: readonly string[];
+    readonly running: readonly string[];
+    readonly settled: readonly string[];
+}
+export declare function startBatchQueue(rowIds: readonly string[]): NgisBatchQueueState;
+/**
+ * The whole of F14.21's concurrency rule: which rows may start **now**.
+ *
+ * `concurrency` is a parameter only so the property can be tested at other
+ * values; every call site passes {@link NGIS_BATCH_CONCURRENCY} and no prop
+ * exposes it. A value below 1 is clamped to 1 rather than deadlocking the queue.
+ */
+export declare function batchQueueDispatch(queue: NgisBatchQueueState, concurrency?: number): {
+    readonly queue: NgisBatchQueueState;
+    readonly start: readonly string[];
+};
+/**
+ * A row left `running`. **Takes no outcome, on purpose.**
+ *
+ * F14.21's *"a failed row does not cancel the rest"* is implemented as an
+ * absence: this function cannot see whether the row succeeded, so there is no
+ * arm in which it could drain `pending`. A queue that inspected the outcome and
+ * chose to continue would be one edit away from choosing not to.
+ */
+export declare function settleBatchQueueRow(queue: NgisBatchQueueState, rowId: string): NgisBatchQueueState;
+export declare function batchQueueDone(queue: NgisBatchQueueState): boolean;
+export interface NgisBatchRunReport {
+    readonly results: Readonly<Record<string, NgisBatchRowResult>>;
+    /**
+     * The most submissions the runner ever had in flight at once. Reported by the
+     * runner rather than measured by the caller, so *"the cap of 3 is respected"*
+     * is a property of the code under test and not of the test's own bookkeeping.
+     */
+    readonly peakInFlight: number;
+    readonly submitted: readonly string[];
+    readonly blocked: readonly string[];
+    readonly failed: readonly string[];
+}
+/**
+ * Rows whose last submission failed before a task existed, or whose submitted
+ * task later reached a failed/cancelled lifecycle. Successful and still-active
+ * rows are deliberately excluded so a retry cannot duplicate healthy work.
+ */
+export declare function retryableBatchRowIds(rowIds: readonly string[], results: Readonly<Record<string, NgisBatchRowResult>>, taskStages: Readonly<Record<string, string | undefined>>): readonly string[];
+export declare const NGIS_BATCH_COLUMN_DEFAULT_WIDTH = 192;
+export declare const NGIS_BATCH_COLUMN_MIN_WIDTH = 160;
+export declare const NGIS_BATCH_COLUMN_MAX_WIDTH = 480;
+export declare const NGIS_BATCH_COLUMN_KEYBOARD_STEP = 16;
+/** Keep pointer and keyboard resizing inside the table's readable range. */
+export declare function clampBatchColumnWidth(width: number): number;
+export interface NgisBatchRunOptions {
+    readonly concurrency?: number;
+    readonly onStart?: (rowId: string) => void;
+    readonly onSettle?: (rowId: string, result: NgisBatchRowResult) => void;
+}
+/**
+ * Drive N rows through `submit` at most {@link NGIS_BATCH_CONCURRENCY} at a time,
+ * and report every row.
+ *
+ * `submit` is injected rather than called through a host, which is what keeps
+ * this module React- and host-free while still being *the* implementation the
+ * component runs: `BatchTable` passes a closure over
+ * `runSubmission(host, submission, options)` and the offline proof passes a
+ * deferred stub. One scheduler, two callers — the alternative is a scheduler in a
+ * `useEffect` and a second one in a test, which is the shape that let `V-224`
+ * ship.
+ *
+ * **Every way `submit` can fail is a per-row `failed`, never a rejected batch:**
+ * a rejected promise, a synchronous throw, and a resolved `failed` result all
+ * land in `results`. The returned promise resolves once every row has settled and
+ * does not reject.
+ */
+export declare function runBatchQueue(rowIds: readonly string[], submit: (rowId: string) => Promise<NgisBatchRowResult>, options?: NgisBatchRunOptions): Promise<NgisBatchRunReport>;
+/**
+ * F14.21's JSON, from the current table.
+ *
+ * Two decisions worth naming:
+ *
+ * 1. **A cell that is currently hidden still saves.** `toSubmission` drops a
+ *    hidden field, because F14.9 says a parameter the schema declares
+ *    inapplicable must not be submitted — but a *config* is the author's
+ *    document, and a value that vanished because a sibling cell was toggled and
+ *    did not come back when it was toggled again would be data loss with a very
+ *    confusing cause.
+ * 2. **`extras` are re-emitted.** Keys a load could not place are written back
+ *    exactly as they arrived, so round-tripping a config authored against a newer
+ *    tool version is lossless.
+ */
+export declare function toBatchConfig(state: NgisBatchTableState): NgisBatchConfig;
+export type NgisBatchConfigParse = {
+    readonly kind: "ok";
+    readonly config: NgisBatchConfig;
+}
+/** F14.21 carries F14.2's rule: an unknown version **refuses**. */
+ | {
+    readonly kind: "unsupported-version";
+    readonly version: number;
+} | {
+    readonly kind: "malformed";
+    readonly field: string;
+};
+/**
+ * Parse a saved config out of `unknown`.
+ *
+ * Separate from {@link fromBatchConfig} because the two failures are different
+ * kinds: this one is *the document is not a batch config we understand*, which is
+ * a refusal; the other is *this config was written for a different tool*, which is
+ * a defect the author can look at and act on. Collapsing them would make a
+ * version bump and a typo'd tool id read the same on screen.
+ *
+ * The version check comes **first**, before any field is inspected. A v2 config
+ * whose `columns` moved would otherwise be reported as malformed, which names the
+ * wrong problem.
+ */
+export declare function parseBatchConfig(raw: unknown): NgisBatchConfigParse;
+/**
+ * A parsed config, against the schema actually loaded.
+ *
+ * A mismatched `toolId` or `toolVersion` is a **defect, not a refusal**: the
+ * server re-resolves and overwrites a pinned tool version at publish
+ * (`w4-contracts.ts:166-173`), so a config authored a version ago is the normal
+ * case rather than an error, and refusing it would make every republished tool
+ * orphan its saved batches. The values load, the mismatch is on screen, and the
+ * author decides.
+ *
+ * Every row's cells are seeded through F14.9's *initialize*, so `default_value`
+ * fills any column the config omitted and `fromWireValue` coerces the strings —
+ * which is what keeps a saved config and a form value from disagreeing about how
+ * `false` is spelled.
+ */
+export declare function fromBatchConfig(schema: NgisToolUiSchema, config: NgisBatchConfig): NgisBatchTableState;
+/** A column's header text — the parameter's `label`, F14.10's provenance chain
+ *  (`x-display-name` → `title` → `name`). A plugin string, rendered literally. */
+export declare function batchColumnParams(schema: NgisToolUiSchema, state: NgisBatchTableState): readonly NgisToolUiParam[];
+/** The values of one row, for a caller that wants them flat. */
+export declare function batchRowValues(row: NgisBatchRow): Readonly<Record<string, NgisParamValue>>;

package/dist/src/components/plugin-ui/flow-inputs.d.ts

@@ -0,0 +1,61 @@
+/**
+ * `RunButton`'s `toolId` + `inputs` → the one {@link NgisRunSubmission}
+ * (Stage 14 Y5b, **F14.4 / F14.5**).
+ *
+ * ## Additive over the same submit path, not a second one
+ *
+ * W2 shipped `RunButton` taking an **already-resolved** `submission`, deliberately:
+ * `"@dem"` is a reference form only a `<Flow>` scope can resolve, and taking
+ * `inputs` before `<Flow>` existed would have shipped a prop that silently did
+ * nothing. W3 adds the pair, and it lands *here* rather than in `run-data.ts`
+ * because everything downstream is unchanged: `runSubmission` still validates then
+ * submits, and `toWireParams` is still the single coercion. **A differing coercion
+ * is exactly what makes a validate pass and the run fail**, so there is not a
+ * second one.
+ *
+ * ## The role split is Y3's, reused rather than copied
+ *
+ * A tool's params are `input` (→ `bindings`), `output` (→ `outputNames`) or
+ * `option` (→ `params`), and `toSubmission` already owns those rules. So resolved
+ * port values are turned into **wire-shaped seed values** and handed to
+ * `initializeParamForm` → `toSubmission`: the same two functions a rendered
+ * `<ParamForm>` goes through, which is why a flow-bound run and a form-driven run
+ * cannot disagree about how a boolean or a multi-valued input is spelled. A second
+ * role-splitter here would be the `toWireParams` lesson in a new place.
+ *
+ * A consequence worth stating: seeding through `initializeParamForm` also applies
+ * each param's `default_value`, so a tool option the author did not bind is
+ * submitted with its declared default rather than omitted. That is what a
+ * generated dialog does, and a flow that behaved differently would run a different
+ * tool invocation than the dialog for the same graph.
+ */
+import type { NgisToolUiSchema } from "../../types/analysis";
+import type { NgisRunSubmission } from "./w2-contracts";
+import { type NgisResolvedValue } from "./w3-contracts";
+/** Resolved in-port values, by member name. */
+export type NgisFlowInputValues = Readonly<Record<string, NgisResolvedValue>>;
+/**
+ * One resolved port value in the wire spelling the seed takes.
+ *
+ * `null` means "not a scalar a param can carry" — a `record`, which is a spread
+ * source rather than a value, and is flattened by the caller before it gets here.
+ * A `resources` list and an `extent` both comma-join, because that is what
+ * `toSubmission` splits an `input` param on and what F14.2's `extent` widget
+ * produces.
+ */
+export declare function flowValueToWire(value: NgisResolvedValue): string | null;
+/**
+ * Flattens one node's satisfied in-port values: every spread's record contents,
+ * then the explicitly-bound ports written over them.
+ *
+ * F14.4: **later explicit keys win over spread keys**, which is why the spreads
+ * are laid down first. Both kinds of key live in the same resolution map, because
+ * `NgisFlowNode.inputs` holds both.
+ */
+export declare function flattenFlowInputs(values: NgisFlowInputValues): NgisFlowInputValues;
+/** The submission a flow-bound `RunButton` submits. */
+export declare function submissionFromFlowInputs(schema: NgisToolUiSchema, values: NgisFlowInputValues): NgisRunSubmission;
+/** `inputs` keys that name an in port, i.e. everything but a spread directive. */
+export declare function flowInputNames(inputs: Readonly<Record<string, unknown>> | undefined): readonly string[];
+/** `inputs` keys the tool's schema does not know — surfaced, never dropped. */
+export declare function unknownFlowInputNames(schema: NgisToolUiSchema | null, names: readonly string[]): readonly string[];