@ngis/plugin-ui 0.4.0

package/dist/src/sdk/map-api.d.ts

@@ -0,0 +1,288 @@
+/**
+ * `NgisMapAPI` — the typed facade a plugin programs against (L3 SDK contract).
+ *
+ * This is the "GeoLibre `GeoLibreAppAPI`" equivalent (see
+ * `../../GEOLIBRE_VS_NGIS.md` §3, one level up from the repo). It is a **binding
+ * layer, not a fourth subsystem**: every method delegates to something that
+ * already exists —
+ *
+ *   - the scene controllers' imperative surface (draw / measure / camera),
+ *     reached today through the composed `GisMapHandle` the shell exposes
+ *     (which itself reads the *live* scene-map-context method registry
+ *     `SceneMapHandleRegistry` — see `components/scenes/map/scene-map-context.ts`,
+ *     C2/C4/C5 — so the facade never captures a stale controller instance);
+ *   - the GIS scene store (`store/gis-scene.ts`) — the `layers` facet;
+ *   - the `WorkspacePanelRegistry` (`sdk/panels.ts`, C7) — the `panels` facet;
+ *   - workspace-owned highlight + view state — the `selection.highlight` and
+ *     `camera` facets.
+ *
+ * The facade introduces **zero new direct `maplibregl.Map` access**. The one
+ * raw touch it exposes — `getMap()` — is a deliberately-unstable escape hatch
+ * that stays `null` until the host wires a raw-map getter into it (the one-line
+ * `SceneMapCanvas.tsx` provider hookup applied after C5 lands; see
+ * `docs/componentization_stage/session-C8-map-api-facade.md`).
+ *
+ * GeoLibre's proven decisions, adopted verbatim in shape:
+ *   1. **Every subscription returns an unsubscribe function** (`onX(cb) => () => void`).
+ *   2. **Newer / not-yet-proven methods are optional-typed** (`api.x?.()`) so
+ *      plugin code written against v0 keeps compiling as the surface grows.
+ *      As of 0.2.0 (session P3, plugin-runtime stage) every method is either
+ *      **real and required** or was deleted; the lone remaining optional member
+ *      is `draw.snapshot` (see its doc for the stated reason).
+ *   3. **A raw-MapLibre escape hatch** (`getMap()`), documented as unstable.
+ *
+ * Framework-agnostic on purpose: this module imports no React and only
+ * type-imports its domain types, so the pure binding/bookkeeping logic is
+ * unit-tested directly with `node:test` (`map-api.test.ts`).
+ */
+import type { Map as MapLibreMap } from "maplibre-gl";
+import type { SceneLayerHighlight, SceneMapView } from "../domain/map/types";
+import type { GisDrawMode, GisMeasureKind } from "../types/gis";
+import type { WorkspacePanelRegistry } from "./panels";
+/** Current facade contract version — bumped when the frozen surface changes.
+ * A plugin's `minNgisVersion` (`docs/frontend-map-sdk.md` §3) is
+ * checked against this. Pre-1.0: the surface may still grow (additively).
+ *
+ * 0.2.0 (plugin-runtime stage, P3): promoted `camera.flyTo`/`fitBounds`,
+ * `layers.onChange` and `draw.onDrawChange` to required; deleted the never-
+ * implemented `selection.get`/`clear`/`onChange` (+ the `"selectionchange"`
+ * event) per decision D10; bound `draw.snapshot` through the imperative
+ * handle (kept optional — see its doc). See `docs/frontend-map-sdk.md` §2.
+ *
+ * 0.3.0 (Stage 11 E7, design doc §19, ED19): added the `commands` capability
+ * (`src/sdk/commands.ts`) — a plugin-declared, externally-invocable seam the
+ * codeenv SDK bridge's plugin-invocation executor calls by id. Contract-safe
+ * in both directions (the runtime's unknown-capability refusal covers an old
+ * runtime seeing a `commands`-declaring plugin; `minNgisVersion` covers a new
+ * plugin requiring a runtime this old). The bump lands atomically with this
+ * capability's only consumer, per ED19 — never staged ahead of it.
+ *
+ * 0.4.0 (Stage 13, X4b; F13.13 + ED19): the **`NgisHostAPI` capability
+ * contract**. `NgisPluginHost` widens from `{ api }` to the full nine-facet
+ * facade (`src/sdk/host-api.ts`), the runtime's first-wins `register` gains an
+ * `unregister`/`replace` seam (F13.8), and `contributes` v1 + derived
+ * activation events land beside `capabilities`. **`host.api` — this whole
+ * module — is unchanged and stays ungated**, which is the back-compat rule: a
+ * 0.3-era plugin declares `minNgisVersion: "0.3.0"`, negotiates identically,
+ * and keeps working byte-for-byte.
+ *
+ * Bumped atomically with its consumers per ED19: `plugin.ts`'s alias,
+ * `plugin-runtime.ts`, `GisWorkspace.tsx`'s host construction and the loader
+ * path all land in the same commit. Note the reverse leg of F13.13 —
+ * a 0.4-requiring manifest on a 0.3 host is refused by the `minNgisVersion`
+ * semver compare, **not** by the unknown-capability check: `contributes` and
+ * `permissions` are top-level manifest siblings, and a 0.3 runtime inspects
+ * only `manifest.capabilities`. */
+export declare const NGIS_MAP_API_VERSION = "0.4.0";
+/** A scene layer as the SDK exposes it — a stable projection of the store's
+ * `NgisSceneLayer`, so plugins never depend on the store's internal shape. */
+export interface NgisLayerSummary {
+    id: string;
+    name: string;
+    /** Scene layer type id (e.g. `"MAPLIBRE_FILL"`); `null` when unset. */
+    type: string | null;
+    visible: boolean;
+}
+/** Camera state — identical shape to the scene's persisted `SceneMapView`. */
+export type NgisMapView = SceneMapView;
+/** Geographic bounds `[west, south, east, north]`. */
+export type NgisBounds = [number, number, number, number];
+/** An unsubscribe function — the return value of every `onX` subscription. */
+export type NgisUnsubscribe = () => void;
+/** `layers` facet — list / inspect / focus / toggle scene layers. */
+export interface NgisLayersFacet {
+    list(): NgisLayerSummary[];
+    get(id: string): NgisLayerSummary | null;
+    /** Fit/ease the camera to a layer's extent (the layer-list "focus" action). */
+    focus(id: string): void;
+    /** Show/hide a layer (persists via the scene store, like the layer list). */
+    setVisibility(id: string, visible: boolean): void;
+    /** Notified when the effective layer set changes (add/remove/reorder/
+     * visibility *and* live style-draft edits — anything that replaces the
+     * store's `effectiveLayers` array). The host's binding equality-guards the
+     * subscription so listeners only fire on real changes, never on unrelated
+     * store updates. Required since 0.2.0. */
+    onChange(listener: () => void): NgisUnsubscribe;
+}
+/** `camera` facet — read/move the viewport + observe view changes. */
+export interface NgisCameraFacet {
+    /** Current view, or `null` when the raw map isn't bound yet (`getMap()`). */
+    getView(): NgisMapView | null;
+    /** Subscribe to camera moves (drives view persistence). Returns unsubscribe. */
+    onViewChange(listener: (view: NgisMapView) => void): NgisUnsubscribe;
+    zoomIn(): void;
+    zoomOut(): void;
+    /** Ease back to the scene's default/initial view. */
+    zoomHome(): void;
+    /** Fly to an explicit view. Escape-hatch-backed: delegates to the raw map,
+     * so it is a documented **no-op while `getMap()` returns `null`** (i.e.
+     * until the host binds a raw-map getter — the first-party canvas does via
+     * `useBindNgisRawMap`). Required since 0.2.0. */
+    flyTo(view: NgisMapView): void;
+    /** Fit the camera to bounds. Escape-hatch-backed — same getMap-null no-op
+     * behavior as `flyTo`. Required since 0.2.0. */
+    fitBounds(bounds: NgisBounds): void;
+}
+/** Enumerated feature highlight — identical to the scene's `SceneLayerHighlight`. */
+export type NgisHighlight = SceneLayerHighlight;
+/** The highlight sub-facet under `selection` — set/clear the feature-state
+ * highlight the attribute table and layer list drive. */
+export interface NgisHighlightFacet {
+    get(): NgisHighlight | null;
+    set(highlight: NgisHighlight | null): void;
+    clear(): void;
+    onChange(listener: (highlight: NgisHighlight | null) => void): NgisUnsubscribe;
+}
+/** `selection` facet — feature highlight only.
+ *
+ * 0.2.0 deleted the declared-but-dead drawn-feature-selection surface
+ * (`get?`/`clear?`/`onChange?` + the `"selectionchange"` event): nothing ever
+ * implemented or emitted it (decision D10 — contract-safe pre-1.0), and the
+ * one cheap first-party emit source (`SelectionController`'s feature-select
+ * enable/disable) signals an interaction-mode toggle, not a selection-set
+ * change. If a real Terra Draw selection source lands, the members return
+ * additively. */
+export interface NgisSelectionFacet {
+    highlight: NgisHighlightFacet;
+}
+/** `draw` facet — Terra Draw mode + one-shot geometry actions. */
+export interface NgisDrawFacet {
+    setMode(mode: GisDrawMode): void;
+    /** Leave the active mode, back to idle. */
+    cancelMode(): void;
+    getActiveMode(): string | null;
+    /** Remove every drawn feature. */
+    clear(): void;
+    /** Delete the currently selected drawn feature(s). */
+    deleteSelection(): void;
+    undo(): void;
+    redo(): void;
+    /** Download the drawn features as GeoJSON. */
+    export(): void;
+    /** Snapshot the raw Terra Draw features. Bound (0.2.0) through the
+     * imperative handle's optional `getDrawSnapshot` — returns `[]` when the
+     * handle is absent or doesn't expose the service.
+     *
+     * **Live since Stage 14 (F14.18).** The first-party shell's composed
+     * `GisMapHandle` now surfaces `getDrawSnapshot`, so in the shipping host this
+     * returns the real feature list rather than always `[]`. The member **stays
+     * optional-typed** because the 0.3 surface is frozen and a host is still
+     * allowed to bind a handle without the service; callers keep writing
+     * `snapshot?.() ?? []`. */
+    snapshot?(): unknown[];
+    /** Observe draw changes (drawn-feature/query-result changes and draw-mode
+     * transitions). Wired since 0.2.0: the host feeds its draw-result/draw-mode
+     * handlers into `NgisMapAPIHandle.emitDrawChange`. Required. */
+    onDrawChange(listener: () => void): NgisUnsubscribe;
+}
+/** `measure` facet — the ephemeral distance/area overlay. (Not in GeoLibre's
+ * original facet list; added because the rail's measure tools are a real v0
+ * consumer — measuring is a sibling Terra Draw control, never a drawn feature.) */
+export interface NgisMeasureFacet {
+    start(kind: GisMeasureKind): void;
+    clear(): void;
+}
+/** Named lifecycle events a plugin can observe generically.
+ * (`"selectionchange"` was deleted in 0.2.0 alongside the dead
+ * drawn-feature-selection surface — see `NgisSelectionFacet`.) */
+export type NgisMapEventName = "viewchange" | "highlightchange" | "drawchange";
+/** `events` facet — a generic named-event bus over the same emitters the typed
+ * facet subscriptions use (a forward-compat convenience for plugins). */
+export interface NgisEventsFacet {
+    on(event: NgisMapEventName, listener: () => void): NgisUnsubscribe;
+}
+/**
+ * The typed facade. v0 — the surface a plugin (and, today, the three first-party
+ * consumers) program against. Concrete methods are frozen; optional-typed
+ * methods may light up as the map subsystems expose more.
+ */
+export interface NgisMapAPI {
+    readonly version: string;
+    layers: NgisLayersFacet;
+    camera: NgisCameraFacet;
+    selection: NgisSelectionFacet;
+    draw: NgisDrawFacet;
+    measure: NgisMeasureFacet;
+    /** The C7 workspace panel registry, re-exposed so a plugin registers UI slots
+     * through the same SDK object. */
+    panels: WorkspacePanelRegistry;
+    events: NgisEventsFacet;
+    /** Raw MapLibre instance — the **unstable escape hatch**. `null` until the
+     * host binds a getter (post-C5 `SceneMapCanvas` hookup). Anything a plugin
+     * does with this is outside the stability contract. */
+    getMap(): MapLibreMap | null;
+}
+/** The imperative surface the facade delegates draw/measure/camera to — a
+ * structural subset of the shell's `GisMapHandle`, kept structural so this
+ * module doesn't import the (large) `SceneMapCanvas` component. */
+export interface NgisMapImperativeHandle {
+    setDrawMode(mode: GisDrawMode): void;
+    cancelMode(): void;
+    getActiveMode(): string | null;
+    clearDraw(): void;
+    deleteSelection(): void;
+    undo(): void;
+    redo(): void;
+    exportDraw(): void;
+    startMeasure(kind: GisMeasureKind): void;
+    clearMeasure(): void;
+    zoomIn(): void;
+    zoomOut(): void;
+    zoomHome(): void;
+    /** Raw Terra Draw feature snapshot (the scene-map-context `getDrawSnapshot`
+     * service). **The first-party shell supplies it since Stage 14 (F14.18)**, so
+     * `draw.snapshot` returns real data there; it stays optional so a host may
+     * still bind a handle without the service. */
+    getDrawSnapshot?(): unknown[];
+}
+/** The layer operations the `layers` facet needs (a thin adapter over the
+ * scene store, supplied by the host so the SDK stays store-agnostic). */
+export interface NgisLayersBinding {
+    list(): NgisLayerSummary[];
+    focus(id: string): void;
+    setVisibility(id: string, visible: boolean): void;
+    /** Store-change subscription backing `layers.onChange`. The host must
+     * equality-guard it (fire only when the effective layer set really changed).
+     * Required since 0.2.0 — `onChange` is part of the frozen surface. */
+    subscribe(listener: () => void): NgisUnsubscribe;
+}
+/** The highlight sink — the workspace-owned highlight state (the exact data
+ * path the attribute table uses today: this ultimately calls `setHighlight`). */
+export interface NgisHighlightBinding {
+    set(highlight: NgisHighlight | null): void;
+    /** Initial value (defaults to `null`). */
+    initial?: NgisHighlight | null;
+}
+export interface NgisMapAPIBindings {
+    /** Live composed imperative handle (`mapRef.current`), or `null` before ready. */
+    getHandle(): NgisMapImperativeHandle | null;
+    layers: NgisLayersBinding;
+    panels: WorkspacePanelRegistry;
+    highlight: NgisHighlightBinding;
+    /** Raw-map getter for `getMap()`. Usually omitted at construction and wired
+     * later via `NgisMapAPIHandle.bindRawMap` (the post-C5 hookup). */
+    getRawMap?(): MapLibreMap | null;
+}
+/**
+ * The factory's return value: the public `api` plus the host-side "driver"
+ * controls (feed-in points the host wires that are *not* part of the public
+ * plugin surface).
+ */
+export interface NgisMapAPIHandle {
+    api: NgisMapAPI;
+    /** Feed a camera-view change into the facade (called from the canvas's
+     * `onViewChange` prop today; from `CameraController` post-hookup). */
+    emitViewChange(view: NgisMapView): void;
+    /** Feed a draw change into the facade — drives `draw.onDrawChange` and the
+     * `"drawchange"` event. The host calls this from its draw-result and
+     * draw-mode handlers (0.2.0's first-party emit source). */
+    emitDrawChange(): void;
+    /** Bind (or replace) the raw-map getter behind `getMap()` — the one-line
+     * `SceneMapCanvas` provider hookup applied after rebasing onto merged C5. */
+    bindRawMap(getter: () => MapLibreMap | null): void;
+}
+/**
+ * Build a facade over the supplied bindings. Pure and framework-agnostic —
+ * create it once per workspace (the host memoizes it) and keep it stable.
+ */
+export declare function createNgisMapAPI(bindings: NgisMapAPIBindings): NgisMapAPIHandle;

package/dist/src/sdk/panels.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Workspace panel registry — the plugin-readiness seam for GIS workspace UI
+ * "slots" (today: the right dock and the bottom docks). Formalizes what used
+ * to be a hand-wired `GisRightMode` enum plus three independent booleans
+ * (`attributeOpen`/`workflowOpen`/`codeOpen`) into a generic registration API:
+ *
+ *   const unregister = registerPanel({ id, slot, icon, labelKey, render });
+ *
+ * Design notes (see `docs/componentization_stage/session-C7-*.md`):
+ * - `render(container, ctx)` is a **DOM-based, framework-agnostic** contract —
+ *   modeled on GeoLibre's lesson that forcing every panel to hand back a React
+ *   element makes a registry impossible for a future non-React plugin loader
+ *   to target. A real plugin only needs to mutate a `container: HTMLElement`
+ *   and (optionally) return a cleanup function.
+ * - `reactPanel()` below is the React *adapter* the design doc calls for.
+ *   First-party panels stay ordinary React components; the adapter's returned
+ *   `render` function still matches the generic signature (so a naive host
+ *   invoking it imperatively still works, via an internal `createRoot`
+ *   fallback), but it also carries a `reactNode` escape hatch that a
+ *   React-aware host (`GisPanelHost`) uses to mount the panel as a normal
+ *   child in the app's own React tree — preserving context (next-intl, theme)
+ *   and ordinary prop-driven reactivity, which an isolated `createRoot` tree
+ *   cannot (separate roots don't share React context).
+ * - A slot still shows only one active panel at a time, but it also tracks the
+ *   panels opened during the current workspace session. Both GIS docks present
+ *   that list as tabs and keep inactive opened bodies mounted so local UI state
+ *   survives tab switches.
+ */
+import { type ReactNode } from "react";
+/** Slots this stage. Order matters only for future additions, not behavior. */
+export type PanelSlot = "right" | "bottom";
+export interface PanelRenderContext {
+    /** Close this panel in its slot (and its tab, when the host presents tabs). */
+    close: () => void;
+}
+export type PanelDisposer = () => void;
+/**
+ * The framework-agnostic render contract. A real (future) plugin panel would
+ * implement this directly: mutate `container`, return a cleanup function.
+ */
+export type PanelRenderFn = (container: HTMLElement, ctx: PanelRenderContext) => PanelDisposer | void;
+/** `reactPanel()`'s return type — same call signature, plus the fast path. */
+export interface ReactPanelRenderFn extends PanelRenderFn {
+    /** Build the React node for this panel "live" — called on every render of
+     * the React-aware host, so ordinary prop/state reactivity works exactly
+     * like a normal child component. */
+    reactNode: (ctx: PanelRenderContext) => ReactNode;
+}
+export interface PanelRegistration {
+    id: string;
+    slot: PanelSlot;
+    /** Plain string identifier (e.g. a lucide icon name) — kept string-typed,
+     * not a React node, so the registration shape never requires React. The
+     * consuming UI (e.g. `GisCommandRail`'s right-panel entries) resolves it. */
+    icon?: string;
+    /** i18n key (e.g. `"GIS.panels.ai"`) resolved by the consumer's `t()`. */
+    labelKey?: string;
+    /** Literal label, for callers without an i18n key (e.g. a future plugin). */
+    label?: string;
+    /** Lower sorts first. Ties fall back to registration order. */
+    order?: number;
+    render: PanelRenderFn;
+}
+type Listener = () => void;
+/**
+ * A registry instance. `panels.ts` exports a process-wide singleton
+ * (`workspacePanelRegistry`) for the app to use, but the class is exported too
+ * so tests (or a future second workspace) can build an isolated instance.
+ */
+export declare class WorkspacePanelRegistry {
+    private readonly panelsBySlot;
+    private readonly orderedCache;
+    private readonly activeBySlot;
+    private readonly openBySlot;
+    private readonly listeners;
+    private seq;
+    private readonly seqById;
+    constructor(slots?: readonly PanelSlot[]);
+    /** Register a panel into its slot. Returns an unregister function — the
+     * same "every registration returns an unregister function" convention the
+     * `NgisMapAPI` facade (C8) uses. */
+    registerPanel(def: PanelRegistration): PanelDisposer;
+    /** Registered panels in a slot, sorted by `order` then registration order.
+     * Cached so repeated calls between mutations return the same array
+     * reference (required for `useSyncExternalStore`'s snapshot contract). */
+    getPanels(slot: PanelSlot): PanelRegistration[];
+    getPanel(slot: PanelSlot, id: string): PanelRegistration | null;
+    getActive(slot: PanelSlot): string | null;
+    /** Panel ids opened in this slot, in first-opened order. The returned array
+     * is referentially stable until the open set changes. */
+    getOpenPanelIds(slot: PanelSlot): readonly string[];
+    /** Open a registered panel and make it active. Reopening an existing panel
+     * only activates it; it does not duplicate or reorder its tab. */
+    open(slot: PanelSlot, id: string): void;
+    setActive(slot: PanelSlot, id: string | null): void;
+    /** Close one opened panel. When it was active, prefer the nearest tab on
+     * its left, then the nearest tab on its right. */
+    close(slot: PanelSlot, id: string): void;
+    /** Invoking the already-active panel closes it — the "toggle-off" parity
+     * every rail tool and dock icon relies on. */
+    toggle(slot: PanelSlot, id: string): void;
+    subscribe(listener: Listener): PanelDisposer;
+    private slotMap;
+    private invalidate;
+    private removeOpenPanel;
+    private notify;
+}
+/** Process-wide registry for the `/gis` workspace. */
+export declare const workspacePanelRegistry: WorkspacePanelRegistry;
+/**
+ * React adapter: wraps a `(ctx) => ReactNode` factory as a `PanelRenderFn`.
+ * First-party panels use this. See the module doc comment for why the
+ * returned function carries both an imperative `createRoot` fallback (the
+ * literal, framework-agnostic contract) and a `reactNode` fast path
+ * (`GisPanelHost` uses this one, to stay inside the app's own React tree).
+ */
+export declare function reactPanel(factory: (ctx: PanelRenderContext) => ReactNode): ReactPanelRenderFn;
+export declare function isReactPanelRenderFn(fn: PanelRenderFn): fn is ReactPanelRenderFn;
+/** Convenience: build a `reactPanel` from a fixed element (no live `ctx`
+ * dependency needed) — most first-party panels want the factory form instead
+ * so they can pass `ctx.close`, but this keeps trivial cases terse. */
+export declare function staticReactPanel(node: ReactNode): ReactPanelRenderFn;
+/** Reactive list of a slot's registered panels, sorted — for building things
+ * like `GisCommandRail`'s right-panel entry group generically. */
+export declare function usePanels(registry: WorkspacePanelRegistry, slot: PanelSlot): readonly PanelRegistration[];
+/** Reactive active-panel id for a slot (`null` when the slot is closed). */
+export declare function usePanelActive(registry: WorkspacePanelRegistry, slot: PanelSlot): string | null;
+/** Reactive first-opened list for hosts that present a slot as tabs. */
+export declare function useOpenPanelIds(registry: WorkspacePanelRegistry, slot: PanelSlot): readonly string[];
+export {};

package/dist/src/types/analysis.d.ts

@@ -0,0 +1,205 @@
+/**
+ * Analysis types.
+ *
+ * Two halves, and they are different in kind:
+ *
+ * 1. **UI-surface types** (`WorkSurface`, `RightDockMode`, …) — pre-existing,
+ *    local to the analysis workspace.
+ * 2. **The Stage 14 UI-schema + validation wire DTOs** — **F14.2 / F14.3
+ *    verbatim**, authored at the W1 kickoff and **read-only to every W1
+ *    session** (`docs/components_flow_stage/README.md` → F14.24). YB1 serves
+ *    these shapes, YB2 serves the validation/search ones, Y3/Y4 consume them.
+ *    A session that needs a change here **stops and raises it** — YB1's Python
+ *    tests and Y3's TS tests must round-trip the *same* fixtures
+ *    (`src/sdk/__fixtures__/ui-schema/` ≡ `ngis-geoanalysis/tests/fixtures/ui_schema/`,
+ *    byte-identical, divergence is a wave-close blocker).
+ *
+ * **The wire is snake_case and so is the type.** Any camelCase remap would be a
+ * second normalization — the exact thing this stage exists to kill — and would
+ * break the byte-identical fixture rule. One spelling, one serializer, two
+ * transports (HTTP + the `GetToolUiSchema` gRPC leg).
+ *
+ * The `import type` of `NgisDataType` from `@/sdk/facets/types` is deliberate
+ * and type-only in both directions: that module imports `NgisToolUiSchema` back
+ * from here for `NgisModelsFacet.uiSchema`. Both edges are erased at compile
+ * time, so there is no runtime cycle. F14.1 fixes the vocabulary's home in
+ * `src/sdk/facets/types.ts`; F14.2 fixes the schema family's home here.
+ */
+import type { NgisDataType } from "../sdk/facets/types";
+export type WorkSurface = "workflow" | "insight" | "code";
+export type RightDockMode = "none" | "ai";
+export type MapFocusMode = "split" | "map" | "work";
+export type LayerSourcePanelMode = "closed" | "resources" | "style";
+export type NgisUiSchemaValueType = "string" | "number" | "integer" | "boolean";
+export type NgisParamRole = "input" | "option" | "output";
+/**
+ * Total, frozen. **There is NO fallback widget:** an unknown key is a
+ * render-time error surfaced in place, never a silently-degraded text input.
+ * A Y3 widget registry missing any of the twelve is a defect.
+ *
+ * `field-select`, `extent` and `textarea` are **never emitted by YB1 in v1** —
+ * no builtin schema expresses a field, a bbox or a long-text parameter. They
+ * are in the union because the registry must be total over it, and because an
+ * author's `ParamForm` `widgets` override and a recipe's promoted inputs can
+ * select them.
+ */
+export type NgisWidgetKey = "resource-select" | "resource-multi" | "select" | "multi-select" | "switch" | "number" | "integer" | "text" | "textarea" | "output-name" | "field-select" | "extent";
+export interface NgisUiSchemaChoice {
+    value: string;
+    label: string;
+}
+/** Derived from `x-rely-on`. Empty array when the parameter has no declared dependency. */
+export interface NgisUiSchemaDependency {
+    /** The `name` of the parameter whose value gates this one. */
+    param: string;
+    /** Shown only when the parent's value, stringified, is one of these. */
+    equals: readonly string[];
+}
+export interface NgisToolUiParam {
+    /** The wire name — exactly the key `POST /api/analysis/tasks` takes. */
+    name: string;
+    /** `x-display-name` -> `title` -> `name`. The generated-reason text source (F14.10). */
+    label: string;
+    description: string | null;
+    role: NgisParamRole;
+    value_type: NgisUiSchemaValueType;
+    /** Canonical (F14.1). `null` for role "option". */
+    data_type: NgisDataType | null;
+    widget: NgisWidgetKey;
+    /** `name in required[]` OR `x-optional === false`. Both halves, always. */
+    required: boolean;
+    /** `x-multiple === true`. Multi-valued inputs are comma-joined on submit. */
+    multiple: boolean;
+    default_value: string | number | boolean | null;
+    /** `enum` first, else `x-constraints.choices[].value` with `.label`. `[]` when none. */
+    choices: readonly NgisUiSchemaChoice[];
+    /** `minimum` first, else `x-constraints.min`. Same for max. */
+    minimum: number | null;
+    maximum: number | null;
+    depends_on: readonly NgisUiSchemaDependency[];
+    /** Advisory. `x-vector-geom` canonicalized to "point" | "line" | "polygon", else null. */
+    geometry: string | null;
+    /** `x-output-ext`. `null` unless role === "output". */
+    output_extension: string | null;
+    /** Every `x-*` key of the source property, verbatim and unmodified — the escape
+     *  hatch, and the reason no consumer ever needs the raw endpoint. Includes keys
+     *  this contract does not name (`x-flags`, `x-grass-element`, `x-required-srid`,
+     *  `x-required-fields`, `x-primary`, `x-vector-layer`, `x-entry-file`, `x-runtime`). */
+    extensions: Readonly<Record<string, unknown>>;
+}
+export interface NgisToolUiSchema {
+    /** Literal 1 in this stage. A consumer that reads a version it does not know
+     *  refuses; it never best-efforts a newer shape. */
+    ui_schema_version: 1;
+    tool_id: string;
+    /** `ngis_model_tool.version`. The value to pass as `expected_tool_version`. */
+    tool_version: number;
+    /** `owner_id IS NULL`. Never stored; always derived. */
+    is_builtin: boolean;
+    provider: string;
+    name: string;
+    description: string | null;
+    /** Diagnostic only. Clients MUST NOT branch on it. */
+    source_shape: "properties" | "inputs";
+    params: readonly NgisToolUiParam[];
+}
+/**
+ * The `ui_schema_version` this build understands. A reader that sees anything
+ * else **refuses** — it never best-efforts a newer shape (F14.2, and the same
+ * rule `recipeVersion` carries in F14.6).
+ */
+export declare const NGIS_UI_SCHEMA_VERSION: 1;
+/** `PASS | ADAPTABLE | UNKNOWN | FAIL`, passed through verbatim. */
+export type NgisBindingVerdict = "PASS" | "ADAPTABLE" | "UNKNOWN" | "FAIL";
+/** `READY | NEEDS_CONFIGURATION | NOT_EXECUTABLE`, passed through verbatim. */
+export type NgisExecutionVerdict = "READY" | "NEEDS_CONFIGURATION" | "NOT_EXECUTABLE";
+export type NgisExecutionMode = "DIRECT" | "WORKFLOW";
+export type NgisOutputMode = "ADD_LAYER" | "UPDATE_RESOURCE";
+/** `DatasetBinding` — the wire form. */
+export interface NgisDatasetBindingWire {
+    port_name: string;
+    file_ids: readonly string[];
+}
+/** `BindingValidation`, field-for-field. */
+export interface NgisBindingValidationEntry {
+    port_name: string;
+    file_id: string;
+    expected_data_type: string;
+    actual_dataset_type: string;
+    dataset_status: string;
+    verdict: NgisBindingVerdict;
+    reason: string;
+    geometry_type: string;
+    srid: number;
+    native_srid: number;
+    working_srid: number;
+    access_mode: string;
+    executable: boolean;
+}
+/** `ValidateToolBindingsResponse`, field-for-field. */
+export interface NgisBindingValidation {
+    tool_id: string;
+    tool_version: number;
+    verdict: NgisBindingVerdict;
+    bindings: readonly NgisBindingValidationEntry[];
+    unresolved_ports: readonly string[];
+    errors: readonly string[];
+    warnings: readonly string[];
+}
+/** `ValidateToolExecutionResponse`, field-for-field, with `normalized_params_json`
+ *  replaced by the decoded `normalized_params` object (the one divergence). */
+export interface NgisExecutionValidation {
+    tool_id: string;
+    tool_version: number;
+    verdict: NgisExecutionVerdict;
+    binding_validation: NgisBindingValidation | null;
+    missing_parameters: readonly string[];
+    parameter_errors: readonly string[];
+    output_errors: readonly string[];
+    warnings: readonly string[];
+    direct_executable: boolean;
+    execution_mode: NgisExecutionMode;
+    /** Decoded. The proto's `normalized_params_json` string is never sent to a browser. */
+    normalized_params: Readonly<Record<string, string>>;
+}
+/** `POST /api/analysis/tools/{tool_id}/validate-execution` body. */
+export interface NgisValidateExecutionBody {
+    expected_tool_version?: number;
+    bindings?: readonly NgisDatasetBindingWire[];
+    /** Decoded, not `params_json`. */
+    params?: Readonly<Record<string, string>>;
+    scene_id?: string;
+    expected_scene_generation?: number;
+    output_mode?: NgisOutputMode;
+    target_resource_id?: string | null;
+    target_srid?: number;
+}
+/** `POST /api/analysis/tools/{tool_id}/validate-bindings` body. */
+export interface NgisValidateBindingsBody {
+    expected_tool_version?: number;
+    bindings?: readonly NgisDatasetBindingWire[];
+}
+/** `ToolSearchResult`, field-for-field. */
+export interface NgisToolSearchResult {
+    tool_id: string;
+    version: number;
+    kind: string;
+    name: string;
+    provider: string;
+    summary: string;
+    domains: readonly string[];
+    operation_types: readonly string[];
+    input_types: readonly string[];
+    output_types: readonly string[];
+    modelbox_path: string;
+    score: number;
+    semantic_match: boolean;
+    lexical_match: boolean;
+}
+/** `SearchToolsResponse`, field-for-field. `GET /api/analysis/tools/search`.
+ *  `limit` default 10, server maximum 50. */
+export interface NgisToolSearchResponse {
+    tools: readonly NgisToolSearchResult[];
+    search_degraded: boolean;
+    degradation_reason: string;
+}

package/dist/src/types/common.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Cross-domain API shapes shared by more than one client module.
+ *
+ * `PageResult<T>` moved here verbatim from `src/api/scenes.ts` (F1 / W1.2) so the
+ * extension market does not fork a second pagination interface. `scenes.ts`
+ * re-exports it, so every existing `import { PageResult } from "@/api/scenes"`
+ * keeps working.
+ */
+export interface PageResult<T> {
+    content: T[];
+    totalElements: number;
+    totalPages: number;
+    size: number;
+    number: number;
+    first?: boolean;
+    last?: boolean;
+}