@ngis/plugin-sdk 0.4.0

package/dist/src/systems/renderer/symbol/SpriteRegistry.d.ts

@@ -0,0 +1,34 @@
+export interface SpriteImageData {
+    width: number;
+    height: number;
+    data: Uint8Array | Uint8ClampedArray;
+}
+export interface SpriteImageOptions {
+    /** An SDF sprite is recoloured per feature by `icon-color` (S24-01 finding 14). */
+    sdf?: boolean;
+    pixelRatio?: number;
+}
+/** The slice of a MapLibre `Map` this registry needs. */
+export interface SpriteImageHost {
+    hasImage(id: string): boolean;
+    addImage(id: string, image: SpriteImageData, options?: SpriteImageOptions): void;
+    removeImage(id: string): void;
+}
+export interface SpriteRegistry {
+    /**
+     * Register `spriteId` if it is not already on the host, and take a reference.
+     * Returns false — without touching the host — for an id this registry did not
+     * mint.
+     */
+    ensure(spriteId: string, image: SpriteImageData, options?: SpriteImageOptions): boolean;
+    /** Drop one reference; the image is removed from the host at zero. */
+    release(spriteId: string): void;
+    has(spriteId: string): boolean;
+    /** The ids currently registered — what `buildSymbolMapLibreLayerSpec` filters on. */
+    availableIds(): ReadonlySet<string>;
+    refCount(spriteId: string): number;
+    /** Drop every reference and image (a style swap that discarded the sprite sheet). */
+    clear(): void;
+    readonly size: number;
+}
+export declare function createSpriteRegistry(host: SpriteImageHost): SpriteRegistry;

package/dist/src/systems/renderer/symbol/entries.d.ts

@@ -0,0 +1,67 @@
+/**
+ * `SceneLayerTypeId` → `LayerRendererEntry` for the three symbol layer types
+ * (F24.9). This is where the pure render plan meets the real map.
+ *
+ * The engine a plan picked decides the shape of the mount:
+ *
+ *  - **maplibre** — a source plus one layer, tracked in `RenderedSceneLayer[]`
+ *    with `renderMode: "maplibre"` so the existing reconciler prunes, diffs and
+ *    repositions it exactly as it does a fill/line/circle layer. Nothing new was
+ *    needed in `rendered-layers.ts` for that, which is the point of reusing the
+ *    render mode rather than inventing a fourth one.
+ *  - **deck** — the layer instances go into the per-pass accumulator and the
+ *    entry tracks nothing, matching the deck family's documented special case.
+ *    The builder itself is **S24-14's** (`SymbolShaderExtension` and the three
+ *    harness texts). Until it is injected, a deck plan mounts nothing rather
+ *    than quietly rendering something that is not the symbol the author
+ *    published — see `S24-V113`.
+ *
+ * Resolution is injected too. This session owns no fetching: `resolveSymbol`
+ * comes from the scene-binding layer (S24-20), and with no resolver every symbol
+ * reference compiles to the `missing` fallback — the host default for the
+ * geometry family, with the reason typed and the caller's `styleJson`
+ * untouched (F24.9).
+ */
+import type { Layer } from "@deck.gl/core";
+import type { SymbolCapabilities, SymbolFallbackReason, SymbolGeometry, SymbolManifest, SymbolRef, SymbolRenderPlan } from "../../../domain/models/symbol";
+import type { LayerRendererEntry, SceneLayerRenderInput } from "../LayerRendererRegistry";
+import type { SpriteRegistry } from "./SpriteRegistry";
+export declare const SYMBOL_SCENE_LAYER_TYPE_IDS: readonly ["SYMBOL_POINT", "SYMBOL_LINE", "SYMBOL_POLYGON"];
+export type SymbolSceneLayerTypeId = (typeof SYMBOL_SCENE_LAYER_TYPE_IDS)[number];
+export declare function isSymbolSceneLayerType(layerType: string | null | undefined): layerType is SymbolSceneLayerTypeId;
+export declare function getSymbolSceneLayerGeometry(typeId: SymbolSceneLayerTypeId): SymbolGeometry;
+/** What a resolved (or refused) symbol reference looks like to the entries. */
+export interface SymbolResolution {
+    manifest?: SymbolManifest | null;
+    /** The manifest a T0 preset extends, when the reference resolved to one. */
+    presetTarget?: SymbolManifest | null;
+    /** Set when the reference did not resolve: forbidden, yanked, gone, no extension. */
+    reason?: SymbolFallbackReason | null;
+}
+export interface SymbolLayerRendererDeps {
+    /** Synchronous by design: a reconcile pass cannot await. The scene-binding
+     *  layer resolves references ahead of the pass and answers from its cache. */
+    resolveSymbol?: (ref: SymbolRef, refKey: string) => SymbolResolution | null;
+    /** The sprites currently registered on this map, if a registry is wired. */
+    spriteRegistry?: Pick<SpriteRegistry, "availableIds"> | null;
+    /**
+     * The live scene binding owns asynchronous symbol resources. Until it says a
+     * referenced symbol is render-ready, do not mount a host-default substitute:
+     * a normal T1/T2 load is not a missing-symbol fallback.
+     */
+    isSymbolResourcesReady?: (styleJson: string | null | undefined, plan: SymbolRenderPlan) => boolean;
+    /** S24-14's deck builder. Absent in W1 — a deck plan then mounts nothing. */
+    buildDeckLayers?: (plan: SymbolRenderPlan, input: SceneLayerRenderInput) => Layer[];
+    /** Device/user capabilities. Resolved per map by the scene controller. */
+    getCapabilities?: () => SymbolCapabilities;
+    /** Called with each mounted plan so the map's clock can count animated layers. */
+    onPlan?: (sceneLayerId: string, plan: SymbolRenderPlan) => void;
+}
+/**
+ * Compile one scene layer's saved style into a plan. Exported because the layer
+ * list needs the same answer — including `fallbackReason`, which is what the
+ * typed message under `Scene.symbolFallback` is keyed on.
+ */
+export declare function planSymbolSceneLayer(typeId: SymbolSceneLayerTypeId, styleJson: string | null | undefined, deps?: SymbolLayerRendererDeps): SymbolRenderPlan;
+/** The three entries `createLayerRendererRegistry` registers (F24.9). */
+export declare function createSymbolLayerRendererEntries(deps?: SymbolLayerRendererDeps): LayerRendererEntry[];

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;
+}