@ngis/plugin-sdk 0.4.0 → 0.4.1

package/dist/index.cjs

@@ -14,7 +14,7 @@ function hostValue(name) {
   }
   return sdk[name];
 }
-exports.NGIS_MAP_API_VERSION = "0.4.0";
+exports.NGIS_MAP_API_VERSION = "0.4.1";
 exports.defineNgisPlugin = function defineNgisPlugin(plugin) {
   return plugin;
 };

package/dist/index.d.ts

@@ -42,7 +42,7 @@
  * ## Versions are locked, not aligned (F14.13, closing `V-162`)
  *
  * ```
- * @ngis/plugin-sdk version === @ngis/plugin-ui version === NGIS_MAP_API_VERSION === "0.4.0"
+ * @ngis/plugin-sdk version === @ngis/plugin-ui version === NGIS_MAP_API_VERSION === "0.4.1"
  * ```
  *
  * One string. The types below are traced from the live program, so any
@@ -62,10 +62,26 @@ export { type GisRailInvokeContext, type GisRailApi, type GisRailStoreHandle, ty
 export { type CommandInvokeContext, type CommandRegistration, } from "./src/sdk/commands";
 export { type NgisPlugin, type NgisPluginCapabilities, type NgisPluginDisposer, type NgisPluginHost, type NgisPluginManifest, } from "./src/sdk/plugin";
 export { type NgisHostAPI, type NgisVizFacet, type NgisChartKind, type NgisChartSeries, type NgisChartSpec, type NgisStorageFacet, type NgisStorageLeg, type NgisStorageWriteFailure, type NgisHostContextFacet, type NgisHostContextValue, type NgisUiFacet, type NgisQuickPickItem, type NgisProgressHandle, type NgisCommandsFacet, type NgisCommandSummary, } from "./src/sdk/host-api";
+export { type NgisResolvedToolDependency, type NgisToolDependencyDeclaration, type NgisToolDependencyReference, type NgisToolDependencyRequiredContract, type NgisToolDependencyUnavailableReason, } from "./src/types/extensions";
 export { NGIS_DATA_TYPES, NGIS_DATA_TYPE_TO_RESOURCE_TYPES, type NgisDataType, type NgisSceneFacet, type NgisSceneInfo, type NgisResourcesFacet, type NgisResourceSummary, type NgisResourceDetail, type NgisResourceField, type NgisResourceType, type NgisModelsFacet, type NgisModelSummary, type NgisModelboxNode, type NgisModelSchema, type NgisModelValidateRequest, type NgisModelSearchRequest, type NgisModelSearchResult, type NgisTasksFacet, type NgisTaskRunRequest, type NgisTaskHandle, type NgisTaskState, type NgisTaskStatus, type NgisTaskStage, type NgisTaskOutput, type NgisTaskWatcher, } from "./src/sdk/facets/types";
 /** `NgisSceneInfo.type`. Declared in the app's scene client, reachable from the
  *  facade, and therefore nameable here — the whole point of the F14.13 rule. */
 export { type SceneType } from "./src/api/scenes";
+/**
+ * **Stage 25 (F25.1 / F25.9).** `NgisResourceSummary.crs` — the same F14.13 rule
+ * as `SceneType` above: the type is declared in the app's domain model, is
+ * reachable from the facade, and is therefore nameable here.
+ *
+ * **Types only.** `formatCrs` / `formatCrsKey` are where G-CRS lives, but this
+ * package's exported **values** are a closed list that its own build enforces —
+ * adding one must land in `installPluginExternals()` and
+ * `public/plugin-externals/plugin-sdk.mjs` in the same commit. That is an F14.13
+ * amendment and three files outside this session's carve; it is recorded as
+ * `S25-V344` rather than taken. A plugin has `ref.key` in the meantime, which is
+ * `"EPSG:<code>"` or `"custom:<ulid>"` and never the bare integer the formatter
+ * exists to prevent.
+ */
+export { type NgisCrsRef, type NgisCrsSource, } from "./src/domain/models/crs";
 export { type NgisToolUiSchema, type NgisToolUiParam, type NgisUiSchemaChoice, type NgisUiSchemaDependency, type NgisUiSchemaValueType, type NgisWidgetKey, type NgisParamRole, type NgisExecutionValidation, type NgisExecutionVerdict, type NgisExecutionMode, type NgisOutputMode, type NgisBindingValidation, type NgisBindingValidationEntry, type NgisBindingVerdict, type NgisDatasetBindingWire, } from "./src/types/analysis";
 export { NGIS_MAX_STATUS_ITEMS_PER_PLUGIN, NGIS_MAX_VISIBLE_STATUS_ITEMS, NGIS_MAX_MENU_ITEMS_PER_PLUGIN_PER_SLOT, NGIS_MAX_SYMBOL_RENDERERS_PER_PLUGIN, type NgisContributes, type NgisActivationEvent, type NgisGatedContribution, type NgisMenuContributions, type NgisMenuGroup, type NgisMenuItemContribution, type NgisMenuSlot, type NgisPermissionScope, type NgisSettingsContribution, type NgisSettingsProperty, type NgisSettingsPropertyType, type NgisSettingsScope, type NgisStatusItemContribution, type NgisSymbolRendererContribution, type NgisSymbolRendererGeometry, type NgisSymbolRendererParam, type NgisSymbolRendererParamType, type NgisSymbolRendererSlot, type NgisToolContribution, type NgisToolPreset, type NgisViewContribution, type NgisViewSlot, } from "./src/sdk/contributions/types";
 export type { NgisSymbolLayerDescriptor, NgisSymbolRenderContext, NgisSymbolRendererFn, NgisSymbolRendererModule, } from "./src/sdk/contributions/symbol-renderers";

package/dist/index.mjs

@@ -12,7 +12,7 @@ function hostValue(name) {
   }
   return sdk[name];
 }
-export const NGIS_MAP_API_VERSION = "0.4.0";
+export const NGIS_MAP_API_VERSION = "0.4.1";
 export function defineNgisPlugin(plugin) {
   return plugin;
 }

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

@@ -1,3 +1,4 @@
+import { type ApiRequestOptions } from "../lib/api";
 import type { NgisBindingValidation, NgisExecutionValidation, NgisToolSearchResponse, NgisToolUiSchema, NgisValidateBindingsBody, NgisValidateExecutionBody } from "../types/analysis";
 import type { PageResult } from "../types/common";
 export interface AnalysisModelboxNode {
@@ -18,6 +19,19 @@ export interface AnalysisTool {
     enabled?: boolean | null;
     modelbox_id?: string | null;
     capability_key?: string | null;
+    /**
+     * Caller-specific access metadata. The server derives this from the
+     * authenticated principal; it is a display affordance, never authorization.
+     */
+    can_manage_access?: boolean;
+    /** `null` for platform-built tools, which have no mutable audience. */
+    visibility?: "PUBLIC" | "PRIVATE" | null;
+    /** Stable semantic identity; `id` remains an opaque implementation id. */
+    reference?: {
+        namespace: string;
+        toolKey: string;
+        contractVersion: string;
+    } | null;
 }
 export interface AnalysisToolSchemaProperty {
     title?: string | null;
@@ -57,6 +71,27 @@ export interface CreateAnalysisTaskParams {
     expected_scene_generation?: number;
     output_mode?: AnalysisTaskOutputMode;
     target_resource_id?: string;
+    /**
+     * **Stage 25 (F25.4) — the submit body's half of "the parameter reaches the
+     * run"** (exit criterion 6).
+     *
+     * An `NgisCrsRef` key (`"EPSG:32650"` / `"custom:<ulid>"`), never an integer.
+     * **camelCase in a snake_case body on purpose:** the W2 dispatch fixes the
+     * REST spelling as `outputCrs` while the proto carries `output_crs`, and
+     * matching the neighbours here would send a field the server does not read.
+     *
+     * Absent = compute in the primary input's own CRS. Nothing on this path
+     * invents a value for it.
+     *
+     * **`S25-V232` closed (S25-32, W3).** This field and
+     * `analysis-task-runtime.ts`'s parameter were added by S25-23 as a forced
+     * spillover — the last two hops to `POST /api/analysis/tasks`, owned by no W2
+     * session, without which exit criterion 6 had no wire to assert on. The W3
+     * dispatch assigned both files to S25-32; reviewed, unchanged, and pinned by
+     * `run-host.test.ts`'s assertion through the real `createGisPluginHostFactory`
+     * → `createGisTasksSource` → `startTrackedAnalysisTask` → `analysisApi` chain.
+     */
+    outputCrs?: string;
 }
 export interface AnalysisTask {
     id: string;
@@ -106,8 +141,10 @@ export declare const analysisApi: {
         capability_key?: string;
         modelbox_id?: string;
         recursive?: boolean;
+        /** Caller-relative catalog partition; defaults to the normal ACL-visible set. */
+        scope?: "ALL" | "MINE" | "PUBLIC" | "SHARED";
     }, signal?: AbortSignal): Promise<PageResult<AnalysisTool>>;
-    getTool(toolId: string, signal?: AbortSignal): Promise<AnalysisTool>;
+    getTool(toolId: string, signal?: AbortSignal | ApiRequestOptions): Promise<AnalysisTool>;
     getToolSchema(toolId: string, signal?: AbortSignal): Promise<AnalysisToolSchema>;
     createTask(params: CreateAnalysisTaskParams, signal?: AbortSignal): Promise<AnalysisTask>;
     getTask(taskId: string, signal?: AbortSignal): Promise<AnalysisTask>;

package/dist/src/api/resources.d.ts

@@ -1,4 +1,14 @@
+import type { NgisCrsRef } from "../domain/models/crs";
+import { type NgisDatasetDimensions, type NgisDatasetKind, type NgisDatasetLineage, type NgisKindCapabilities, type NgisTemporalExtent } from "../domain/models/dataset-kind";
 export type ResourceScope = "mine" | "shared" | "public" | "trash";
+/**
+ * **SURVIVES Stage 29, narrowed in meaning (F29.1 row 1).** It answers *"what
+ * shape of file is this"*, **not** *"what kind of dataset is this"* — it is
+ * derived from `fileType` (the extension) at {@link toResourceType}, so its
+ * `"table"` means *spreadsheet-shaped file* and has nothing to do with a dataset
+ * model (F29.2). The dataset kind is {@link NgisDatasetKind}. Keeping its name
+ * and its lowercase spelling is deliberate; renaming it is out of contract.
+ */
 export type ResourceType = "vector" | "raster" | "flow-field" | "table" | "file";
 export type ResourceStatus = "ready" | "processing" | "failed";
 export type ResourceAccess = "private" | "shared" | "team" | "public";
@@ -209,21 +219,125 @@ export interface DatasetInfo {
     snapshot?: boolean | null;
     snapshotId?: string | null;
     mode?: ResourceShareMode | string | null;
-    datasetType: "VECTOR" | "RASTER" | "GENERIC" | string;
-    status: "PENDING" | "PROCESSING" | "DONE" | "FAILED" | "NOT_REGISTERED" | "N/A" | string;
+    /**
+     * **Stage 29 (F29.1 row 2 / F29.3):** this field's own hand-written union is
+     * **RETIRED into {@link NgisDatasetKind}** — it was already the wire field, so
+     * the retirement is of the *second spelling*, not of the field.
+     *
+     * `"GENERIC"` is **removed**: a non-geo file now reports `null` with
+     * `status: "N/A"`, and `null` therefore carries exactly one meaning — *no kind
+     * resolved* (`status: "NEEDS_KIND"`, `fx-ds-0003`). A flow field that used to
+     * report `null` or `"GENERIC"` on two REST surfaces now reports `"FLOW_FIELD"`
+     * on all four (`fx-ds-0004`); that is a contract change, not a tidy-up.
+     *
+     * The union is **open** — do not write a test asserting the set of kinds.
+     */
+    datasetType: NgisDatasetKind | null;
+    /**
+     * **Stage 25 (F25.1):** `"NEEDS_CRS"` joins the union. It is a *state*, not a
+     * failure — the bytes are intact and every other fact about the dataset is
+     * known; what is missing is the one declaration nothing can be derived without.
+     *
+     * **Stage 29 (F29.7 R2):** `"READY"`, `"NEEDS_KIND"` and
+     * `"NEEDS_TEMPORAL_EXTENT"` join it, and the vocabulary is **OPEN**. A consumer
+     * that does not recognise a status renders the **raw token**, never `UNKNOWN` —
+     * the hazard is live rather than hypothetical, because `ngis-file` already
+     * normalises `NEEDS_CRS` to `UNKNOWN` on the library listing (`S29-V041`).
+     */
+    status: "PENDING" | "PROCESSING" | "DONE" | "READY" | "FAILED" | "NOT_REGISTERED" | "NEEDS_CRS" | "NEEDS_KIND" | "NEEDS_TEMPORAL_EXTENT" | "N/A" | string;
+    /**
+     * **Stage 25 (F25.1), replacing `vector.srid` / `raster.srid`.**
+     *
+     * One CRS per dataset, in one place, with an identity (`key`) rather than an
+     * integer. `null` means the server does not know — never `EPSG:4326`, and
+     * never `0`. The two numeric fields it replaces are gone from the wire as
+     * well as from this type: they were per-subtype, so a caller had to know
+     * whether it held a vector or a raster before it could ask a question that has
+     * the same answer either way, and neither could express "unknown" except as a
+     * falsy number every consumer read as a CRS.
+     */
+    crs?: NgisCrsRef | null;
+    /**
+     * Server-computed from the extent and **never stored** — what the dataset
+     * *would* sensibly be projected into. Present only when it would differ from
+     * `crs`; it is a suggestion the user may take, not a value in effect.
+     */
+    suggestedProjectedCrs?: NgisCrsRef | null;
+    /**
+     * **`S29-V039`, second half — a client defect, fixed here.** The server has
+     * emitted this field since Stage 26 (`DatasetService.java:410`) and the guide
+     * documented it, but **no TypeScript type in this repo declared it**, so every
+     * consumer that wanted it had to reach for `unknown`. It carries in six places
+     * in `__fixtures__/dataset-kind/dataset-spine.states.json`.
+     *
+     * It is the CRS the backfill *proposes* for a `NEEDS_CRS` dataset — a
+     * candidate, not a value in effect — and it is distinct from
+     * {@link DatasetInfo.suggestedProjectedCrs}, which proposes a **projection for
+     * a dataset whose CRS is already known**. A row may carry either, both or
+     * neither; they are never interchangeable.
+     */
+    crsCandidate?: NgisCrsRef | null;
+    /**
+     * **Stage 29 (F29.4).** The **kind's** declared capability block.
+     *
+     * **Three states, not two.** An absent flag means *the server has not said*;
+     * `{supported: false, reasonKey}` means *this kind cannot*. Read it with
+     * `datasetKindCapability` and never with `caps?.[flag]?.supported ?? false` —
+     * coalescing absent into `false` re-introduces the defect Stage 26 paid to
+     * learn. `{}` is the **empty** block (no kind resolved, `fx-ds-0003`) and is
+     * different again from an absent block.
+     *
+     * It describes the **kind**, not this row's readiness: a `NEEDS_CRS` vector is
+     * still `tileable: true`; it is {@link DatasetInfo.ready} that stops it
+     * rendering.
+     */
+    capabilities?: NgisKindCapabilities;
+    /**
+     * **Stage 29 (F29.7).** Never a bare range, and never absent-meaning-static —
+     * a defaulted range is a contract violation, not a fallback (`D29-3`). `null`
+     * is the fourth state and means *the server has not said*, which is distinct
+     * from `NOT_APPLICABLE` (*this kind has no time axis*).
+     */
+    temporalExtent?: NgisTemporalExtent | null;
+    /**
+     * **Stage 29 (F29.7).** Declared, and `null` for every kind this stage
+     * registers — `D29-S1` defers the array plane. Typed as the `null` literal on
+     * purpose: **a session that builds a time slider off this field is out of
+     * contract**, and this makes that a compile error.
+     */
+    dimensions?: NgisDatasetDimensions;
+    /** **Stage 29 (F29.7 / `D29-5`).** Where this dataset came from. */
+    lineage?: NgisDatasetLineage | null;
+    /**
+     * **Stage 29 (F29.6).** Server-computed: `status ∈ kind.readyStates`. Keeps its
+     * name and stays server-computed; it is **not** derived client-side.
+     *
+     * `undefined` ("the server has not said") and `false` ("this row is not ready")
+     * must never render the same.
+     */
+    ready?: boolean;
+    /**
+     * **Stage 29 (F29.6).** Server-computed:
+     * `ready && geometryType != null && capabilities.tileable.supported === true`.
+     *
+     * **This is a property of a DATASET.** Stage 28 ships an unrelated
+     * `capabilities.renderable` on a **symbol template**; the two share a field
+     * name and nothing else (`S29-V073`). `renderable` is not a member of
+     * `NgisCapabilityFlag`, so a symbol template's block is not an
+     * `NgisKindCapabilities`.
+     *
+     * `undefined` and `false` must never render the same.
+     */
+    renderable?: boolean;
     vector?: {
         geometryType?: string | null;
         featureCount?: number | null;
-        srid?: number | null;
-        nativeSrid?: number | null;
-        workingSrid?: number | null;
         fieldsSchema?: DatasetField[] | string | null;
         pgTableName?: string | null;
         errorMessage?: string | null;
     } | null;
     raster?: {
         cogVariantId?: string | null;
-        srid?: number | null;
         bandCount?: number | null;
         noDataValue?: number | null;
         pixelSizeX?: number | null;
@@ -296,7 +410,7 @@ export interface DatasetAttributeClassifyResult {
     classes: number;
     breaks: number[];
 }
-export type DatasetAttributeWhereOp = "=" | "!=" | ">" | ">=" | "<" | "<=" | "like" | "in" | "between";
+export type DatasetAttributeWhereOp = "=" | "!=" | ">" | ">=" | "<" | "<=" | "like";
 export interface DatasetAttributeQueryParams {
     select?: string[];
     filter?: {
@@ -317,6 +431,8 @@ export interface DatasetAttributeQueryParams {
         cursor?: string;
     };
     includeGeometry?: boolean;
+    /** Enumerated stable feature ids, combined with any filter/sort before paging. */
+    ids?: string[];
 }
 /** One feature row from `attributes/query`. `id` is a stable per-feature UUID,
  * returned on every row regardless of `select`, and usable for selection. */
@@ -400,7 +516,13 @@ export interface ResourceListItem {
     sizeBytes: number;
     size: string;
     features: string;
-    srid: string;
+    /**
+     * **Stage 25 (F25.1):** was `srid: string`, a pre-formatted label that
+     * rendered "unknown" and "not applicable" identically as `"-"`. It is now the
+     * ref itself, so the row can draw the CRS chip, the unit sigil and the
+     * "No projection" badge from one value instead of parsing a string back apart.
+     */
+    crs: NgisCrsRef | null;
     geometry: string;
     format: string;
     bbox: string;
@@ -417,10 +539,29 @@ export interface ResourceListItem {
     readMode: ResourceReadMode;
     snapshotId?: string | null;
     shareMode: ResourceShareMode;
+    /**
+     * **Stage 29 (F29.4).** The kind's declared capability block, carried through
+     * unchanged so the row can render *why* a control is refused instead of hiding
+     * it (`S29-V030`, owned by `S29-15`).
+     *
+     * **Three states.** `undefined` is *the server has not said*; `{}` is *no kind
+     * resolved, therefore no declared capabilities*; a present flag is the answer.
+     * The `can*` booleans below collapse all three into a decision, which is what a
+     * boolean is for — this field is what carries the reason the boolean cannot.
+     */
+    capabilities?: NgisKindCapabilities;
     canCopy: boolean;
     canDelete: boolean;
     canManageSharing: boolean;
     canRepublish: boolean;
+    /**
+     * **Keeps its kind branch, with a stated reason (F29.4).** Retry is not one of
+     * F29.4's six flags and no kind declares it, so there is nothing to delegate
+     * to. The branch is a *pipeline* fact — a flow field's build is retried through
+     * its own builder, not through the dataset re-ingest this control calls — and
+     * inventing a seventh flag to carry it would be exactly the "invent a
+     * vocabulary" move this stage exists to stop. Carried as `S29-V111`.
+     */
     canRetry: boolean;
 }
 export interface ResourceListResult {
@@ -489,6 +630,10 @@ export declare const resourcesApi: {
     cancelUpload(uploadId: string): Promise<void>;
     copyToLibrary(fileId: string, folderId?: string | null): Promise<NgisFileRef>;
     listGroups(): Promise<NgisUserGroup[]>;
+    /** Existing permission evaluator: layer WRITE differs from owner-only config. */
+    checkSceneWritePermission(sceneId: string): Promise<{
+        allowed: boolean;
+    }>;
     listSharingPermissions(resourceId: string, resourceType?: SharingResourceType): Promise<NgisResourcePermission[]>;
     grantSharingPermission(params: GrantSharingParams): Promise<NgisResourcePermission>;
     revokeSharingPermission(resourceId: string, principalType: SharingPrincipalType, principalId?: string | null, resourceType?: SharingResourceType): Promise<void>;
@@ -499,7 +644,7 @@ export declare const resourcesApi: {
     getDatasetAttributeMeta(fileId: string): Promise<DatasetAttributeMeta>;
     queryDatasetAttributes(fileId: string, params: DatasetAttributeQueryParams, signal?: AbortSignal): Promise<DatasetAttributeQueryResult>;
     /** Exact count of rows matching `filter` (omit/`{}` → unfiltered total). */
-    countDatasetAttributes(fileId: string, filter?: DatasetAttributeFilter, signal?: AbortSignal): Promise<DatasetAttributeCountResult>;
+    countDatasetAttributes(fileId: string, filter?: DatasetAttributeFilter, ids?: string[], signal?: AbortSignal): Promise<DatasetAttributeCountResult>;
     /** Stream the selection as a CSV / GeoJSON file download. */
     exportDatasetAttributes(fileId: string, params: ExportDatasetAttributesParams): Promise<ExportDatasetAttributesResult>;
     /** Materialize the selection into a new derived dataset (import pipeline). */
@@ -508,7 +653,26 @@ export declare const resourcesApi: {
     getDatasetAttributeStats(fileId: string, field: string): Promise<DatasetAttributeStats>;
     classifyDatasetAttribute(fileId: string, params: ClassifyDatasetAttributeParams): Promise<DatasetAttributeClassifyResult>;
     uploadFile(file: File, options?: UploadFileOptions): Promise<NgisFile>;
-    download(fileId: string, scope: ResourceScope): Promise<Response>;
+    /**
+     * **Stage 25 (F25.5 / F25.12):** the download leg takes an optional
+     * `format` · `crs` pair — the two fields of the "Download as…" dialog.
+     *
+     * Both are **omitted when they are the default**: no `format` means the
+     * original bytes, and no `crs` means the dataset's own. That is what keeps
+     * this call byte-identical to the pre-stage one for every caller that does not
+     * ask for a conversion, and it is why the caller decides — `downloadQuery` in
+     * `resource-library-crs.ts` — rather than this function defaulting anything.
+     *
+     * `crs` is a **`CrsRef` key** (`"EPSG:4547"` / `"custom:<ulid>"`), never an
+     * integer: an integer cannot name a custom CRS, which is the whole reason the
+     * key exists. `?srid=` survives the stage only as a deprecated alias the
+     * server accepts from older clients; nothing here emits it.
+     */
+    download(fileId: string, scope: ResourceScope, options?: {
+        format?: string;
+        crs?: string;
+        signal?: AbortSignal;
+    }): Promise<Response>;
 };
 export declare const storageQuotaApi: {
     get(): Promise<StorageQuota>;

package/dist/src/api/scenes.d.ts

@@ -1,4 +1,6 @@
 import type { ResourceShareMode } from "./resources";
+import type { NgisCrsRef } from "../domain/models/crs";
+import type { NgisDatasetKind, NgisKindCapabilities } from "../domain/models/dataset-kind";
 import type { ApiRequestOptions } from "../lib/api";
 export type SceneScope = "mine" | "shared" | "public";
 export type SceneType = "MAP" | "ANALYSIS" | "GIS";
@@ -17,6 +19,7 @@ export interface NgisScene {
     description?: string | null;
     thumbnailFileId?: string | null;
     configJson?: string | null;
+    configRevision?: string | null;
     /** True for an unsaved scratch scene (auto-deleted after the TTL window). */
     ephemeral?: boolean | null;
     purpose?: "STANDARD" | "GIS_WORKSPACE" | "PLUGIN_UI_LAB" | string | null;
@@ -78,17 +81,91 @@ export interface SceneResourceDto {
     addedAt?: string | null;
     layerCount: number;
     rendered: boolean;
-    datasetType?: string | null;
+    /**
+     * **Stage 29 (F29.1 row 2).** The registered kind id — the one derivation chain
+     * for a dataset's kind. `null` means *no kind resolved* and is the only meaning
+     * `null` carries after F29.3; `"GENERIC"` is gone from the wire.
+     *
+     * The union is **open** (`D29-1` makes a kind registered data), so a client
+     * shipped today must render a kind registered tomorrow. Do not assert its
+     * membership.
+     */
+    datasetType?: NgisDatasetKind | null;
+    /**
+     * **Stage 29 (F29.7 R2): an OPEN vocabulary.** A consumer that does not
+     * recognise a status renders the **raw token**, never `UNKNOWN`.
+     */
     datasetStatus?: string | null;
     /**
      * Selection-safe projection supplied by the scene service: VECTOR | RASTER |
      * FILE. Resource pickers must use this rather than fan out to Dataset APIs.
+     *
+     * **SURVIVES Stage 29, server-derived (F29.1 row 5).** It is a picker-routing
+     * hint, not a kind: it keeps its name and its three values, and after F29.3 the
+     * server derives it from the kind id rather than from the old three-value
+     * string. It is deliberately *coarser* than `datasetType` — a picker needs to
+     * know which control to draw, not which kind it is looking at.
      */
     selectionType?: string | null;
     /** AVAILABLE | MISSING | UNAVAILABLE | UNKNOWN. */
     metadataState?: string | null;
+    /**
+     * **Stage 29 (F29.6).** Server-computed: `status ∈ kind.readyStates`. Kept,
+     * not deprecated, and **not** derived client-side.
+     *
+     * Its defect was never a kind carve-out — `SceneResourceDto.java` hardcoded
+     * `"DONE".equals(s) || "READY".equals(s)` for *every* kind, a **status**
+     * vocabulary carve-out granted to all kinds because `READY` was added for one
+     * (FE C2, corrected by F29.6). The kind now declares its own `readyStates`.
+     *
+     * **Read by nothing in this client today.** Starting to consume it is
+     * `S29-V029b` (`S29-15`), and it is new UI behaviour with its own copy:
+     * `undefined` ("the server has not said") and `false` ("this row is not ready")
+     * must never render the same.
+     */
     ready?: boolean;
+    /**
+     * **Stage 29 (F29.6).** Server-computed:
+     * `ready && geometryType != null && capabilities.tileable.supported === true`.
+     * The hardcoded VECTOR/RASTER/FLOW_FIELD list it used to carry lives in
+     * `ngis-scene` and is a **backend** deliverable (FE C1) — the client never saw
+     * the list and cannot swap it.
+     *
+     * **This is a property of a DATASET, and `PluginUiLabSample.renderable` below
+     * is a different object entirely.** Stage 28 additionally ships a
+     * `capabilities.renderable` on a **symbol template** (`S29-V073`); dataset
+     * `renderable` is a top-level boolean on this spine and `renderable` is not a
+     * member of `NgisCapabilityFlag`, so neither shape can resolve against the
+     * other. Two unrelated objects, one field name — do not unify them.
+     *
+     * **Read by nothing in this client today** (`S29-V029b`, `S29-15`).
+     */
     renderable?: boolean;
+    /**
+     * **Stage 29 (F29.4).** The **kind's** declared capability block, carried on
+     * the scene resource as well as on `GET /api/datasets/{fileId}` — both, and
+     * deliberately **not** a third `GET /api/datasets/{id}/capabilities` endpoint,
+     * which would be an N+1 against data the caller already has.
+     *
+     * **Three states, not two.** Read a flag with `datasetKindCapability`: absent
+     * means *the server has not said*, `{supported: false}` means *this kind
+     * cannot*, and they must never render the same. `{}` is the empty block.
+     */
+    capabilities?: NgisKindCapabilities;
+    /**
+     * **Stage 25 (F25.8).** The source dataset's one CRS, enriched onto the scene
+     * resource by `ngis-scene` (S25-30, `V17__scene_resource_crs.sql`).
+     *
+     * `null` is the `NEEDS_CRS` state and is a *value*, not a gap: the kickoff's
+     * `CrsDto.fromProto` returns `null` on a blank `key` precisely because proto3
+     * scalars have no presence, so a field-for-field mapper would have put
+     * `EPSG:0` on the layer list. `undefined` is the third state — a server that
+     * has not shipped S25-30 yet — and the layer row draws no chip at all for it
+     * rather than drawing the absent-CRS sigil, because "the server did not say"
+     * and "the dataset has no projection" are different facts and G-CRS is the
+     * rule that they never render the same.
+     */
+    crs?: NgisCrsRef | null;
 }
 export interface ListSceneResourcesOptions {
     /** Ask the scene service to refresh its bounded, persisted dataset summaries. */
@@ -107,8 +184,14 @@ export interface NgisSceneLayer {
     layerType?: string | null;
     styleJson?: string | null;
     visible?: boolean | null;
+    /** S28-15: content lock for a plotting layer. */
+    locked?: boolean | null;
     sortOrder?: number | null;
     groupId?: string | null;
+    /** S28-15: optimistic revision required for plotting-layer mutations. */
+    revision?: number | null;
+    popupJson?: Record<string, unknown> | null;
+    dynamicLineJson?: Record<string, unknown> | null;
 }
 export interface AddSceneLayerParams {
     resourceId?: string;
@@ -116,13 +199,18 @@ export interface AddSceneLayerParams {
     name: string;
     layerType?: string;
     styleJson?: string;
+    dynamicLineJson?: Record<string, unknown>;
 }
 export interface UpdateSceneLayerParams {
     name?: string;
     visible?: boolean;
+    locked?: boolean;
     sortOrder?: number;
     styleJson?: string;
     groupId?: string;
+    revision?: number;
+    popupJson?: Record<string, unknown> | null;
+    dynamicLineJson?: Record<string, unknown> | null;
 }
 export interface NgisSceneLayerGroup {
     id: string;
@@ -161,6 +249,17 @@ export interface PluginUiLabResponse {
     cleanupPhase?: string | null;
     cleanupError?: string | null;
 }
+/**
+ * A Plugin UI Lab sample row.
+ *
+ * **Its `ready` / `renderable` / `datasetType` are NOT the dataset spine's
+ * (`S29-V073`, F29.6).** They belong to `PluginUiLabSampleDto`, a lab fixture
+ * row, and F29.6 explicitly declined to deprecate `renderable` partly because
+ * this surface has no stake in the stage. Do not route this shape through
+ * anything that expects {@link SceneResourceDto} or `NgisDatasetSpine`, and do
+ * not widen `datasetType` here to {@link NgisDatasetKind}: this row's value is a
+ * lab sample's declared type, not a registered kind id.
+ */
 export interface PluginUiLabSample {
     id: string;
     version: string;
@@ -225,7 +324,7 @@ export declare const scenesApi: {
     promoteScene(sceneId: string, name?: string): Promise<NgisScene>;
     create(params: CreateSceneParams): Promise<NgisScene>;
     update(sceneId: string, params: UpdateSceneParams): Promise<NgisScene>;
-    updateConfig(sceneId: string, config: string | object): Promise<NgisScene>;
+    updateConfig(sceneId: string, config: string | object, configRevision?: string | null): Promise<NgisScene>;
     updateCapabilities(sceneId: string, params: UpdateSceneCapabilitiesParams): Promise<NgisScene>;
     delete(sceneId: string): Promise<void>;
     publish(sceneId: string): Promise<void>;
@@ -242,8 +341,8 @@ export declare const scenesApi: {
     addLayer(sceneId: string, params: AddSceneLayerParams, options?: ApiRequestOptions): Promise<NgisSceneLayer>;
     updateLayer(sceneId: string, layerId: string, params: UpdateSceneLayerParams, options?: ApiRequestOptions): Promise<NgisSceneLayer>;
     renameLayer(sceneId: string, layerId: string, name: string): Promise<NgisSceneLayer>;
-    deleteLayer(sceneId: string, layerId: string, options?: ApiRequestOptions): Promise<void>;
-    reorderLayers(sceneId: string, layerIds: string[], options?: ApiRequestOptions): Promise<void>;
+    deleteLayer(sceneId: string, layerId: string, revisionOrOptions?: number | ApiRequestOptions, options?: ApiRequestOptions): Promise<void>;
+    reorderLayers(sceneId: string, layerIds: string[], revisionsOrOptions?: Record<string, number> | ApiRequestOptions, options?: ApiRequestOptions): Promise<void>;
     listLayerGroups(sceneId: string): Promise<NgisSceneLayerGroup[]>;
     createLayerGroup(sceneId: string, params: CreateLayerGroupParams): Promise<NgisSceneLayerGroup>;
     updateLayerGroup(sceneId: string, groupId: string, params: UpdateLayerGroupParams): Promise<NgisSceneLayerGroup>;

package/dist/src/domain/algorithms/flow-field-style.d.ts

@@ -0,0 +1,68 @@
+import type { FlowFieldStyle } from "../models/flow-field-style";
+export declare const FLOW_FIELD_STYLE_VERSION: 1;
+export declare const FLOW_FIELD_COLOR_RAMP_TEXTURE_SIZE = 256;
+export declare const FLOW_FIELD_MAX_PARTICLES = 262144;
+/**
+ * Practical ranges for the style editor. These are intentionally narrower
+ * than the parser's safety bounds so normal operation has useful low-end
+ * precision, without invalidating richer styles saved by earlier releases.
+ */
+export declare const FLOW_FIELD_STYLE_CONTROL_RANGES: {
+    readonly lineWidth: {
+        readonly min: 0.5;
+        readonly max: 2.5;
+        readonly step: 0.25;
+    };
+    readonly speedFactor: {
+        readonly min: 0.1;
+        readonly max: 1.4;
+        readonly step: 0.05;
+    };
+    readonly frameDurationMs: {
+        readonly min: 250;
+        readonly max: 1750;
+        readonly step: 50;
+    };
+    readonly particleCount: {
+        readonly min: 1000;
+        readonly max: 11000;
+        readonly step: 500;
+    };
+    readonly trailLength: {
+        readonly min: 2;
+        readonly max: 10;
+        readonly step: 1;
+    };
+    readonly maxParticleAge: {
+        readonly min: 30;
+        readonly max: 150;
+        readonly step: 1;
+    };
+    readonly dropRate: {
+        readonly min: 0.001;
+        readonly max: 0.007;
+        readonly step: 0.001;
+    };
+    readonly dropRateBump: {
+        readonly min: 0;
+        readonly max: 0.004;
+        readonly step: 0.001;
+    };
+};
+export declare const DEFAULT_FLOW_FIELD_COLORS: readonly ["#3288bd", "#66c2a5", "#abdda4", "#e6f598", "#fee08b", "#fdae61", "#f46d43", "#d53e4f"];
+export declare const DEFAULT_FLOW_FIELD_STYLE: Readonly<FlowFieldStyle>;
+export declare function createDefaultFlowFieldStyle(): FlowFieldStyle;
+export declare function parseFlowFieldColors(value: unknown): string[] | null;
+/**
+ * Migrates every pre-v1 flow style into the v1 contract and removes unknown
+ * properties so a layer style remains a safe, portable JSON payload.
+ */
+export declare function parseFlowFieldStyle(value: unknown): FlowFieldStyle;
+export declare function parseFlowFieldStyleJson(styleJson: string | null | undefined): FlowFieldStyle;
+export declare function serializeFlowFieldStyle(value: unknown): string;
+export declare function sanitizeFlowFieldStyleJson(styleJson: string | null | undefined): {
+    styleJson: string;
+    changed: boolean;
+};
+export declare function isFlowFieldStyle(value: unknown): boolean;
+export declare function sampleFlowFieldColorRamp(colors: readonly string[], count?: number): Uint8Array<ArrayBuffer>;

package/dist/src/domain/algorithms/scene-layer-type.d.ts

@@ -1,3 +1,4 @@
+import { type NgisDatasetKind } from "../models/dataset-kind";
 import { type SceneLayerGeometryFamily, type SceneLayerTypeDefinition, type SceneLayerTypeId } from "../models/scene-layer-type";
 interface SceneLayerResourceFieldDescriptor {
     kind?: string | null;
@@ -8,6 +9,17 @@ export interface SceneLayerResourceDescriptor {
     geometry?: string | null;
     geometryType?: string | null;
     fields?: readonly SceneLayerResourceFieldDescriptor[] | null;
+    /**
+     * `DatasetInfo.datasetType` / `SceneResourceDto.datasetType` — the registered
+     * kind id, and **the answer** (F29.1 row 6).
+     *
+     * Optional because the callers that build this descriptor
+     * (`SceneWorkspaceLayers.tsx`, `resource-library-ui.tsx`,
+     * `useSceneLayerResourcePanel.tsx`) are not this session's files. Absent means
+     * *the caller has not said* and falls back to the legacy signals — it does not
+     * mean *this resource has no kind*.
+     */
+    datasetType?: NgisDatasetKind | null;
 }
 export interface SceneLayerTypeDescriptor {
     layerType?: string | null;

package/dist/src/domain/map/rendered-layers.d.ts

@@ -27,4 +27,5 @@ export declare function removeRenderedSceneLayers(map: MapLibreMap, renderedLaye
 export declare function applyCustomRasterColorLayerStyleUpdate(map: MapLibreMap, rendered: RenderedSceneLayer, style: SceneLayerStyle): boolean;
 export declare function applySceneLayerStyleUpdate(map: MapLibreMap, rendered: RenderedSceneLayer, mapLayer: LayerSpecification): boolean;
 export declare function getSceneLayerBeforeId(map: MapLibreMap): string | undefined;
+/** Call in ascending scene order: each layer goes above the previous one. */
 export declare function moveSceneLayerToRenderSlot(map: MapLibreMap, layerId: string): void;