@ngis/plugin-ui 0.4.0 → 0.4.1

package/dist/index.cjs

@@ -14,7 +14,7 @@ function hostComponent(name) {
   }
   return ui[name];
 }
-exports.NGIS_PLUGIN_UI_VERSION = "0.4.0";
+exports.NGIS_PLUGIN_UI_VERSION = "0.4.1";
 exports.ResourceSelect = function ResourceSelect(props) {
   return hostComponent("ResourceSelect")(props);
 };

package/dist/index.d.ts

@@ -19,7 +19,7 @@
  * ## Versions are contractually locked, not conventionally aligned (F14.13)
  *
  * ```
- * @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"
  * ```
  *
  * ## Distribution (F14.14)
@@ -78,7 +78,7 @@
  * aligned). One string; any divergence is a lie about what the tarball
  * contains.
  */
-export declare const NGIS_PLUGIN_UI_VERSION = "0.4.0";
+export declare const NGIS_PLUGIN_UI_VERSION = "0.4.1";
 export { ResourceSelect } from "./src/components/plugin-ui/ResourceSelect";
 export type { ResourceSelectBaseProps, ResourceSelectProps, } from "./src/components/plugin-ui/ResourceSelect";
 export { ModelSelect } from "./src/components/plugin-ui/ModelSelect";

package/dist/index.mjs

@@ -12,7 +12,7 @@ function hostComponent(name) {
   }
   return ui[name];
 }
-export const NGIS_PLUGIN_UI_VERSION = "0.4.0";
+export const NGIS_PLUGIN_UI_VERSION = "0.4.1";
 export function ResourceSelect(props) {
   return hostComponent("ResourceSelect")(props);
 }

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/crs.d.ts

@@ -0,0 +1,110 @@
+import type { ApiRequestOptions } from "../lib/api";
+import type { NgisCrsRef, NgisCrsRequirement } from "../domain/models/crs";
+/**
+ * The CRS oracle client (Stage 25, **F25.2 / F25.13**).
+ *
+ * Four legs, and every one of them answers the same question — *what is this
+ * coordinate reference system?* — from a different starting point: a search
+ * string, a definition the user pasted, an extent, or a dataset that has none.
+ *
+ * ## Verb-first, deliberately
+ *
+ * F25.13 froze `searchCrs` / `resolveCrs` / `suggestCrs` / `assignDatasetCrs`
+ * rather than the design's bare `search` / `resolve` / `suggest`. Two reasons.
+ * It matches the house style of every other module here (`listScenes`,
+ * `getResource`), and a bare `search` collides with `models.search` at any call
+ * site that imports both — which the analysis surfaces do.
+ *
+ * ## The oracle never answers permissively
+ *
+ * An unreachable oracle must not be indistinguishable from "the CRS is 4326"
+ * (G-CRS). None of these legs has a fallback: a failed call rejects with the
+ * `ApiError` `@/lib/api` built, and the caller renders that. `resolveCrs`
+ * returning `null` means *the server read the definition and it is not a CRS* —
+ * a verdict, not a transport failure — which is why it is a distinct arm rather
+ * than a rejection the picker would have to guess at.
+ */
+/** One row of `GET /api/geo/crs/search`. The blurb is server-authored copy. */
+export interface NgisCrsSearchHit {
+    readonly crs: NgisCrsRef;
+    /** e.g. `"Between 114°E and 120°E, northern hemisphere"`. `null` when the oracle has none. */
+    readonly areaOfUse: string | null;
+}
+/** One row of `POST /api/geo/crs/suggest`, best first. */
+export interface NgisCrsSuggestion extends NgisCrsSearchHit {
+    /**
+     * Why this one fits — `"Best fit for this extent"`. Server-authored, because
+     * the ranking rule lives in the oracle and a client that restated it would
+     * drift from the ranking it is labelling.
+     */
+    readonly reason: string | null;
+}
+/** `[west, south, east, north]` in EPSG:4326, the one form the suggest leg takes. */
+export type NgisCrsBbox = readonly [number, number, number, number];
+/** What `POST /api/geo/crs/resolve` made of a pasted definition. */
+export type NgisCrsResolution = {
+    readonly kind: "resolved";
+    readonly crs: NgisCrsRef;
+}
+/** The server read it and it is not a usable CRS. A verdict, not a failure. */
+ | {
+    readonly kind: "rejected";
+    readonly reason: string | null;
+};
+/**
+ * The body of `PUT /api/datasets/{fileId}/crs`. **Exactly one of the two**, per
+ * F25.5: a registry key for a known CRS, or a WKT2 definition the server
+ * registers as a custom one. There is no third form and no numeric `srid`.
+ */
+export type NgisAssignCrsBody = {
+    readonly key: string;
+} | {
+    readonly wkt2: string;
+};
+/**
+ * `202` — the assign was accepted and the re-import is dispatched. The dataset
+ * shows the pipeline state until `DONE`; the assign **declared** the CRS and did
+ * not move a coordinate (G-A).
+ */
+export interface NgisAssignCrsAccepted {
+    readonly fileId: string;
+    readonly status: string;
+    readonly crs: NgisCrsRef | null;
+}
+export declare const crsApi: {
+    /**
+     * Free-text search over the EPSG registry plus the caller's saved custom
+     * CRSs. `kind` narrows to the tool's `x-crs-requirement`, server-side — the
+     * picker says so in one line rather than silently returning fewer results
+     * (F25.2).
+     */
+    searchCrs(query: string, options?: {
+        kind?: NgisCrsRequirement;
+        limit?: number;
+    } & ApiRequestOptions): Promise<readonly NgisCrsSearchHit[]>;
+    /**
+     * Read a pasted WKT2 / PROJ string / `urn:` and report what it is — **without
+     * saving anything.** The picker previews `name` / kind / unit before "Use
+     * this", so the user commits to a definition they have seen resolved rather
+     * than to text they hope parses.
+     */
+    resolveCrs(definition: string, options?: ApiRequestOptions): Promise<NgisCrsResolution>;
+    /**
+     * What fits this extent, best first. The server already knows which zone the
+     * data sits in; making the user type "utm" to discover that is the ergonomic
+     * defect this stage removes, which is why Suggested is the picker's default
+     * tab whenever a caller supplies an extent (F25.2).
+     */
+    suggestCrs(bbox: NgisCrsBbox, options?: {
+        kind?: NgisCrsRequirement;
+    } & ApiRequestOptions): Promise<readonly NgisCrsSuggestion[]>;
+    /**
+     * Declare what a dataset's coordinates already are (F25.5). **This does not
+     * reproject** — G-A keeps the assign flow and the output-CRS parameter from
+     * ever sharing a verb, a label or a component mode.
+     *
+     * The body carries `{ key }` or `{ wkt2 }` under a `crs` envelope and never a
+     * numeric srid. Answers `202`; the row shows its pipeline state until `DONE`.
+     */
+    assignDatasetCrs(fileId: string, crs: NgisAssignCrsBody, options?: ApiRequestOptions): Promise<NgisAssignCrsAccepted>;
+};

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