@ngis/plugin-sdk 0.4.0

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

@@ -0,0 +1,158 @@
+/**
+ * Permission-scope enforcement over the 0.4 facade (Stage 13 X5, W3 — F13.5).
+ *
+ * **This file's type surface is frozen by the W3 kickoff.** X9 owns the *call
+ * site* — it applies the wrapper inside `createGisPluginHostFactory` — and X6's
+ * three dogfood plugins declare their `permissions` against
+ * {@link NGIS_SCOPE_MEMBERS}. Three sessions depend on these exact names and
+ * this exact member map, which is why the kickoff authored them rather than a
+ * session (the W1 `NgisResourceType` lesson, restated at the W2 kickoff).
+ *
+ * `withScopeEnforcement` **shipped as a labelled pass-through stub and X5 filled
+ * it in** (merged 2026-07-27); the header is corrected here rather than left
+ * describing a stub that no longer exists. The pass-through was deliberate over
+ * throwing, so X9 could wire and test the real host path against a compiling
+ * wrapper before X5 merged, and so the failure mode if X5 had been dropped was
+ * "nothing is enforced" — visible in X5's own tests — rather than "the
+ * workspace does not boot".
+ *
+ * ## What enforcement is, and is not
+ *
+ * Facade-level and **documented as such**. Plugin code shares the origin and the
+ * session; a determined bundle can reach `fetch` directly and bypass every line
+ * here. This layer makes the *declared* contract real and auditable — it is not
+ * a security boundary. `docs/frontend-map-sdk.md` §3.5's stored-XSS posture is
+ * re-stated by X5, not resolved. Hard isolation is Stage 15.
+ */
+import type { NgisPermissionScope } from "./contributions/types";
+import type { NgisHostAPI } from "./host-api";
+/**
+ * The refusal, verbatim from F13.5.
+ *
+ * Never an empty result: a silent empty list is indistinguishable from a real
+ * empty scene, and a plugin that cannot tell the two apart will render "no
+ * data" where it should render "not permitted".
+ */
+export declare class NgisScopeError extends Error {
+    readonly code: "scope-denied";
+    /** The scope that was missing. */
+    readonly scope: NgisPermissionScope;
+    /** Dotted facet member, e.g. `"tasks.run"` — a key of {@link NGIS_SCOPE_MEMBERS}. */
+    readonly member: string;
+    constructor(scope: NgisPermissionScope, member: string);
+}
+/**
+ * **The frozen member → scope map (F13.5).** Every gated member of the 0.4
+ * facade, spelled as `facet.member` (`storage` legs as `storage.user.get`).
+ *
+ * A member absent from this map is **ungated by decision, not by omission** —
+ * see {@link NGIS_UNGATED_MEMBERS}. X5 must not add or remove an entry: doing
+ * so silently changes what X6's manifests must declare and what XB1 validated
+ * at publish time.
+ */
+export declare const NGIS_SCOPE_MEMBERS: {
+    readonly "scene.get": "scene:read";
+    readonly "scene.onChange": "scene:read";
+    readonly "resources.list": "resources:read";
+    readonly "resources.get": "resources:read";
+    readonly "resources.fieldValues": "resources:read";
+    readonly "resources.onChange": "resources:read";
+    readonly "models.list": "models:read";
+    readonly "models.tree": "models:read";
+    readonly "models.get": "models:read";
+    readonly "models.schema": "models:read";
+    readonly "models.uiSchema": "models:read";
+    readonly "models.validate": "models:read";
+    readonly "models.search": "models:read";
+    readonly "tasks.run": "models:run";
+    readonly "tasks.get": "tasks:read";
+    readonly "tasks.list": "tasks:read";
+    readonly "tasks.watch": "tasks:read";
+    readonly "tasks.outputs": "tasks:read";
+    readonly "tasks.cancel": "tasks:cancel";
+    readonly "viz.addResultLayer": "viz:write";
+    readonly "storage.user.get": "storage:user";
+    readonly "storage.user.set": "storage:user";
+    readonly "storage.user.canWrite": "storage:user";
+    readonly "storage.user.onChange": "storage:user";
+    readonly "storage.scene.get": "storage:scene";
+    readonly "storage.scene.set": "storage:scene";
+    readonly "storage.scene.canWrite": "storage:scene";
+    readonly "storage.scene.onChange": "storage:scene";
+    readonly "ui.toast": "ui:notify";
+    readonly "ui.confirm": "ui:notify";
+    readonly "ui.quickPick": "ui:notify";
+    readonly "ui.progress": "ui:notify";
+};
+export type NgisGatedMember = keyof typeof NGIS_SCOPE_MEMBERS;
+/**
+ * Ungated on record, with the reason — F13.5's list, made executable so a test
+ * can assert the two sets partition the facade and nothing fell through.
+ *
+ * - `api.*` — **the back-compat rule.** A 0.3-era plugin declares no
+ *   `permissions`, is never prompted, and keeps working byte-for-byte.
+ * - `context.*` — host-published state the plugin's own contributions already
+ *   gate on; `set` cannot escape its `plugin:<pluginId>:` namespace (F14.11).
+ * - `commands.list` / `invoke` — the E7 registry is an explicitly-declared seam
+ *   already (XD15). **F14.16 confirms this and settles what it implies
+ *   (Stage 14, resolving `V-145`):** a command runs with the grants of the plugin
+ *   that **owns** it — the callee's, not the caller's and not the intersection —
+ *   so a plugin holding no scopes at all may invoke another plugin's command and
+ *   that command runs with its own. No `commands:invoke` scope is added. The
+ *   escalation this describes already existed via the module-scope host capture in
+ *   `activate()`; intersection would stop a plugin relying on its own grants
+ *   whenever a scope-less caller invoked it, and the caller's grants would run the
+ *   callee's code under scopes it never declared. Since Stage 14 Y4a
+ *   (`V-141`) all four invoke paths supply the **owner's** scope-enforced facade
+ *   as `ctx.host`, derived from the command id.
+ * - `viz.openTable` / `viz.fit` — no mutation, and `host.api.camera.flyTo` is
+ *   ungated; gating these would be inconsistent for no gain.
+ * - `viz.chart` — **F14.3, AMENDS F13.5.** Same reason as the two above: it
+ *   mutates nothing. The spec is declarative data the host renders.
+ */
+export declare const NGIS_UNGATED_MEMBERS: readonly ["api", "context.get", "context.getAll", "context.set", "context.evaluate", "context.onChange", "commands.list", "commands.invoke", "viz.openTable", "viz.fit", "viz.chart"];
+/** Reported to XB1's `POST /api/extensions/{extId}/scope-events` by X5. */
+export interface NgisScopeDenial {
+    pluginId: string;
+    scope: NgisPermissionScope;
+    member: string;
+}
+export interface NgisScopeEnforcementOptions {
+    pluginId: string;
+    /**
+     * Effective grants, **read at call time, not at construction**.
+     *
+     * Two reasons this is a thunk. Re-consent must take effect without rebuilding
+     * a facade the plugin already holds; and the value must be the *intersection*
+     * of the stored `granted_scopes` with the resolved version's declared
+     * `permissions`. `V-85` established that the backend column is not
+     * recomputed when a version **narrows** its `permissions`, so a stale grant
+     * outlives the declaration that justified it. Intersecting at read time is
+     * the only place that can be fixed on the client.
+     */
+    grants: () => ReadonlySet<NgisPermissionScope>;
+    /** Fire-and-forget; a failed audit POST must never turn into a second error
+     *  on the plugin's call path. */
+    onDenied?: (denial: NgisScopeDenial) => void;
+}
+/**
+ * Wraps a facade so every member in {@link NGIS_SCOPE_MEMBERS} checks its scope
+ * first.
+ *
+ * **Refusal shape is part of the contract, and it is not uniform.** The gated
+ * members are a mix of async and synchronous, and the wrapper must preserve
+ * each signature exactly:
+ *
+ * - async members (`scene.get`, `tasks.run`, `storage.user.set`, …) **reject**
+ *   with {@link NgisScopeError};
+ * - **synchronous** members — every `*.onChange` and `tasks.watch` — **throw**
+ *   it synchronously.
+ *
+ * Do not make a synchronous member async to make refusal uniform: `onChange`
+ * returns an unsubscribe function that call sites invoke in a `useEffect`
+ * cleanup, and `tasks.watch` returns a watcher handle. Turning either into a
+ * promise breaks shipped call sites and the F13.2 subscription contract.
+ *
+ * `host.pluginId` and `host.version` pass through untouched.
+ */
+export declare function withScopeEnforcement(host: NgisHostAPI, options: NgisScopeEnforcementOptions): NgisHostAPI;

package/dist/src/systems/renderer/DeckSceneRenderer.d.ts

@@ -0,0 +1,26 @@
+import type { Layer } from "@deck.gl/core";
+import type { Map as MapLibreMap } from "maplibre-gl";
+export interface DeckSceneSyncResult {
+    ok: boolean;
+    error: string | null;
+}
+/**
+ * MapLibre v6 moved the camera transform off the map instance — what used to be
+ * `map.transform` now lives on the private `map._camera.transform` — but
+ * `@deck.gl/mapbox` still reads `map.transform.height` (and `._nearZ`/`._farZ`)
+ * when it builds the deck viewport (`deck-utils.js` `getViewport`). With
+ * `transform` undefined the overlay throws "Cannot read properties of undefined
+ * (reading 'height')" from inside MapLibre's render loop (`map.ts` →
+ * `triggerRepaint` → `_render`) and no deck layer ever draws.
+ *
+ * No published deck.gl release handles v6 yet (checked through 9.3.7 and
+ * 9.4.0-alpha.1 — all still read `map.transform`), so bridge the two private
+ * APIs here. Remove once deck.gl supports MapLibre v6.
+ */
+export declare function applyDeckTransformCompat(map: MapLibreMap): void;
+export declare class DeckSceneRenderer {
+    private overlay;
+    /** Replace the full set of active deck.gl layers in one batched update. */
+    sync(map: MapLibreMap, layers: Layer[]): DeckSceneSyncResult;
+    destroy(): void;
+}

package/dist/src/systems/renderer/FlowFieldLayer.d.ts

@@ -0,0 +1,68 @@
+import type { CustomLayerInterface, CustomRenderMethodInput, Map as MapLibreMap } from "maplibre-gl";
+import type { SceneLayerStyle } from "../../domain/map/types";
+import type { AuthenticatedFetch } from "./authenticated-deck-load";
+export type FlowFieldLayerOptions = {
+    id: string;
+    flowFieldId: string;
+    opacity: number;
+    speedFactor: number;
+    particleCount: number;
+    paused: boolean;
+    fetchWithAuth: AuthenticatedFetch;
+    triggerRepaint: () => void;
+    onError?: (error: Error) => void;
+};
+/**
+ * MapLibre custom layer backed by one isolated WebGL2 particle simulation.
+ * Every program, texture, VAO, buffer and transform-feedback object belongs
+ * to this instance; removing one flow field cannot clear another instance.
+ */
+export declare class FlowFieldLayer implements CustomLayerInterface {
+    readonly id: string;
+    readonly type: "custom";
+    readonly renderingMode: "2d";
+    private opts;
+    private map;
+    private gl;
+    private abort;
+    private generation;
+    private visible;
+    private ready;
+    private assets;
+    private updateProgram;
+    private renderProgram;
+    private updateUniforms;
+    private renderUniforms;
+    private velocityTextures;
+    private seedTextures;
+    private validTextures;
+    private domainMaskTexture;
+    private projectionTexture;
+    private simulationBuffers;
+    private simulationVaos;
+    private transformFeedbacks;
+    private trailBuffers;
+    private renderVao;
+    private stateIndex;
+    private trailHead;
+    private trailCount;
+    private frameCounter;
+    private particleCount;
+    constructor(options: FlowFieldLayerOptions);
+    onAdd(map: MapLibreMap, gl: WebGLRenderingContext | WebGL2RenderingContext): void;
+    private load;
+    private createGpuResources;
+    private createParticleResources;
+    private runSimulation;
+    private bindTexture;
+    private bindRenderBuffers;
+    private drawFlow;
+    render(gl: WebGLRenderingContext | WebGL2RenderingContext, input: CustomRenderMethodInput): void;
+    update(style: SceneLayerStyle): boolean;
+    setVisible(visible: boolean): void;
+    onRemove(): void;
+    destroy(): void;
+    private invalidateAndRelease;
+    private destroyParticleResources;
+    private releaseGpuResources;
+}

package/dist/src/systems/renderer/LayerRendererRegistry.d.ts

@@ -0,0 +1,132 @@
+/**
+ * `LayerRendererRegistry` — the unified extension point behind the three
+ * scene-layer render paths (session C3, see
+ * docs/componentization_stage/session-C3-layer-renderer-registry-and-basemap.md
+ * and README.md "Target architecture" > L0/L2). Generalizes the old
+ * `DeckSceneRenderer`-local `deckLayerBuilders` map (SceneLayerTypeId ->
+ * builder) to cover native MapLibre layers and the custom raster-color WebGL
+ * layer too, so render-path selection is data-driven (one entry per
+ * `SceneLayerTypeId`) instead of if/else branching. This is what C8's SDK
+ * contracts will expose for plugin-contributed layer types next stage.
+ *
+ * `reconcileSceneLayers` is the registry-driven replacement for the old
+ * inline `syncSceneLayers` reconciliation loop that used to live in
+ * `SceneMapCanvas.tsx` (moved here + `SceneLayersController.tsx`, session
+ * C3). Its outer control flow (sort -> filter -> split deck/non-deck ->
+ * prune -> update-or-rebuild -> reposition -> flush deck) is unchanged from
+ * the proven, tested `domain/map/rendered-layers.ts#syncSceneLayers` (C1) —
+ * only the "how do I build/update/remove *one* layer" step now dispatches
+ * through a registered `LayerRendererEntry` instead of calling
+ * `buildMapLayer`/`buildCustomRasterColorLayer`/the deck builder map
+ * directly. `domain/map/rendered-layers.ts` itself is left byte-stable
+ * (owned/read by C6 this wave too) — its pure per-layer helpers
+ * (`applySceneLayerStyleUpdate`, `applyCustomRasterColorLayerStyleUpdate`,
+ * `removeRenderedSceneLayer`, `getSceneLayerBeforeId`,
+ * `moveSceneLayerToRenderSlot`) are reused unchanged, satisfying the design
+ * constraint that style-update diffing reuses that module.
+ *
+ * Deck entries are a deliberate special case, documented up front so future
+ * readers (and C8, wiring the SDK facade) aren't surprised:
+ *
+ * - Deck.gl layers are never added to the `RenderedSceneLayer[]` bookkeeping
+ *   (`mount`/`update` return `null`) — this matches `syncSceneLayers`'s
+ *   pre-existing behavior verified against `domain/map/query.ts`'s
+ *   `getQueryableLayers` (only `fill`/`line`/`circle` maplibre-tracked
+ *   layers were ever queryable; deck layers were not, before or after this
+ *   session).
+ * - Deck.gl layers are built fresh into a shared per-sync-pass accumulator
+ *   (`LayerRenderContext.deckLayers`) and flushed in ONE batched
+ *   `DeckSceneRenderer.sync` call at the end of `reconcileSceneLayers` —
+ *   exactly how the original code worked (deck.gl's own `MapboxOverlay`
+ *   props-diffing decides what actually re-renders; nothing here calls
+ *   `deckRenderer.sync` per-layer, which would churn the overlay control on
+ *   every layer). `mount` and `update` are therefore the same
+ *   implementation for deck entries, and `unmount` is a no-op: omitting a
+ *   layer from `deckLayers` before the flush *is* the removal.
+ */
+import type { Map as MapLibreMap } from "maplibre-gl";
+import type { Layer } from "@deck.gl/core";
+import type { NgisSceneLayer, SceneResourceDto } from "../../api/scenes";
+import type { SceneLayerTypeId } from "../../domain/models/scene-layer-type";
+import type { RenderedSceneLayer, SceneLayerStyle } from "../../domain/map/types";
+import type { TileRequestInitFactory } from "../../lib/raster-color-layer/TileGrid";
+import type { AuthenticatedFetch } from "./authenticated-deck-load";
+import type { DeckSceneRenderer } from "./DeckSceneRenderer";
+import { type SymbolLayerRendererDeps } from "./symbol/entries";
+/** Per-sync-pass state handed to every registry entry. */
+export interface LayerRenderContext {
+    map: MapLibreMap;
+    deckRenderer: DeckSceneRenderer;
+    getTileRequestInit: TileRequestInitFactory;
+    /**
+     * Deck.gl layer instances accumulated during this reconciliation pass —
+     * see module doc. `reconcileSceneLayers` creates this fresh per call and
+     * flushes it once via `deckRenderer.sync` at the end.
+     */
+    deckLayers: Layer[];
+    fetchWithAuth: AuthenticatedFetch;
+    triggerRepaint: () => void;
+    onLayerError?: (error: Error) => void;
+}
+/** One scene layer's resolved inputs, handed to `mount`/`update`. */
+export interface SceneLayerRenderInput {
+    sceneLayer: NgisSceneLayer;
+    resource: SceneResourceDto;
+    style: SceneLayerStyle;
+    /**
+     * Deck-family only: the first symbol-layer id, so deck features insert
+     * below basemap labels (matches native layer stacking). Computed once per
+     * sync pass by `reconcileSceneLayers`.
+     */
+    deckBeforeId?: string;
+}
+/**
+ * One render path's lifecycle for one `SceneLayerTypeId`. `mount`/`update`
+ * return the bookkeeping entry to track (or `null` when the render path
+ * manages its own state outside `RenderedSceneLayer[]` — see the deck note
+ * above). `update` returns `false` when it refuses to diff in place (e.g. a
+ * geometry-type change) — the caller must then `unmount` + `mount` fresh.
+ */
+export interface LayerRendererEntry {
+    readonly typeId: SceneLayerTypeId;
+    mount(ctx: LayerRenderContext, input: SceneLayerRenderInput): RenderedSceneLayer | null;
+    update(ctx: LayerRenderContext, input: SceneLayerRenderInput, prev: RenderedSceneLayer): boolean;
+    unmount(ctx: LayerRenderContext, prev: RenderedSceneLayer): void;
+}
+export interface LayerRendererRegistry {
+    /** Register (or replace) the entry for `entry.typeId`. Returns an unregister function. */
+    register(entry: LayerRendererEntry): () => void;
+    get(typeId: SceneLayerTypeId): LayerRendererEntry | undefined;
+    readonly size: number;
+}
+export declare function createEmptyLayerRendererRegistry(): LayerRendererRegistry;
+/**
+ * Build the registry with the three built-in render-path families
+ * registered. `fetchWithAuth` is threaded through to the deck family the
+ * same way `DeckSceneRenderer`/the raster loaders already do it (DI, not a
+ * module-level import) — see `authenticated-deck-load.ts`.
+ */
+export declare function createLayerRendererRegistry(fetchWithAuth: AuthenticatedFetch, symbolDeps?: SymbolLayerRendererDeps): LayerRendererRegistry;
+export interface ReconcileSceneLayersParams {
+    map: MapLibreMap;
+    layers: NgisSceneLayer[];
+    resources: SceneResourceDto[];
+    /** Mutated in place (push/splice) — same contract as the old `syncSceneLayers`. */
+    renderedLayers: RenderedSceneLayer[];
+    registry: LayerRendererRegistry;
+    deckRenderer: DeckSceneRenderer;
+    getTileRequestInit: TileRequestInitFactory;
+    onLayerError?: (error: Error) => void;
+}
+export interface ReconcileSceneLayersResult {
+    ok: boolean;
+    error: string | null;
+}
+/**
+ * Registry-driven scene-layer reconciler — see module doc. Behaviorally
+ * equivalent to `domain/map/rendered-layers.ts#syncSceneLayers` (same
+ * control flow, ported deliberately), except each layer's actual
+ * mount/update/unmount now dispatches through `registry` instead of being
+ * inline. `SceneLayersController` (session C3) is the sole caller.
+ */
+export declare function reconcileSceneLayers(params: ReconcileSceneLayersParams): ReconcileSceneLayersResult;

package/dist/src/systems/renderer/authenticated-deck-load.d.ts

@@ -0,0 +1,4 @@
+import { type Loader, type LoaderOptions } from "@loaders.gl/core";
+export type AuthenticatedFetch = (input: string, init?: RequestInit) => Promise<Response>;
+export declare function getDeckTileRetryDelayMs(retryAfter: string | null, retryCount: number): number;
+export declare function loadDeckDataWithAuth(fetchWithAuth: AuthenticatedFetch, url: string, loaders: Loader[], loadOptions?: LoaderOptions, signal?: AbortSignal): Promise<any>;

package/dist/src/systems/renderer/deck/deck-layer-builders.d.ts

@@ -0,0 +1,29 @@
+import type { Layer } from "@deck.gl/core";
+import { MVTLayer } from "@deck.gl/geo-layers";
+import { type ImplementedDeckSceneLayerTypeId } from "../../../domain/models/deck-layer-style";
+import { type AuthenticatedFetch } from "../authenticated-deck-load";
+import { type DeckFeatureProperties, type DeckSceneLayerInput } from "./deck-layer-helpers";
+import { MvtHeatmapLayer, MvtHexagonLayer } from "./mvt-point-aggregation-layer";
+export { getDeckPointFeatures as getColumnPointFeatures } from "./deck-layer-helpers";
+export type { DeckPointFeature as DeckColumnPointFeature } from "./deck-layer-helpers";
+export type DeckLayerBuilder = (input: DeckSceneLayerInput, fetchWithAuth: AuthenticatedFetch) => Layer | null;
+export interface DeckLayerBuilderRegistration {
+    typeId: ImplementedDeckSceneLayerTypeId;
+    build: DeckLayerBuilder;
+}
+export declare function buildExtrudedPolygonLayer(input: DeckSceneLayerInput, fetchWithAuth: AuthenticatedFetch): MVTLayer<DeckFeatureProperties, {
+    beforeId?: string;
+}> | null;
+export declare function buildColumnLayer(input: DeckSceneLayerInput, fetchWithAuth: AuthenticatedFetch): MVTLayer<DeckFeatureProperties, {
+    beforeId?: string;
+}> | null;
+export declare function buildHeatmapLayer(input: DeckSceneLayerInput, fetchWithAuth: AuthenticatedFetch): MvtHeatmapLayer | null;
+export declare function buildHexagonLayer(input: DeckSceneLayerInput, fetchWithAuth: AuthenticatedFetch): MvtHexagonLayer | null;
+export declare function buildGraduatedLineLayer(input: DeckSceneLayerInput, fetchWithAuth: AuthenticatedFetch): MVTLayer<DeckFeatureProperties, {
+    beforeId?: string;
+}> | null;
+/** Renderer catalog ordered and keyed by the shared Deck capability source. */
+export declare const BUILT_IN_DECK_LAYER_BUILDERS: {
+    typeId: "DECK_MVT_EXTRUDED_POLYGON" | "DECK_COLUMN" | "DECK_HEATMAP" | "DECK_HEXAGON" | "DECK_MVT_LINE";
+    build: typeof buildExtrudedPolygonLayer | typeof buildColumnLayer | typeof buildHeatmapLayer | typeof buildHexagonLayer | typeof buildGraduatedLineLayer;
+}[];

package/dist/src/systems/renderer/deck/deck-layer-helpers.d.ts

@@ -0,0 +1,21 @@
+import type { Feature, Geometry, Point } from "geojson";
+import type { SceneLayerTypeId } from "../../../domain/models/scene-layer-type";
+export type DeckColor = [number, number, number, number];
+export type DeckFeatureProperties = Record<string, unknown>;
+export type DeckPointFeature = Feature<Point, DeckFeatureProperties>;
+export interface DeckSceneLayerInput {
+    id: string;
+    layerType: SceneLayerTypeId;
+    tileUrl: string;
+    styleJson: string | null;
+    bounds?: [number, number, number, number];
+    minZoom?: number;
+    maxZoom?: number;
+    beforeId?: string;
+}
+export declare function getDeckFeatureNumber(feature: Feature<Geometry, DeckFeatureProperties>, field: string): number;
+export declare function getDeckFeatureValue(feature: Feature<Geometry, DeckFeatureProperties>, field: string): unknown;
+export declare function toDeckColor(hex: string): DeckColor;
+export declare function toDeckRgbColor(hex: string): [number, number, number];
+/** Convert non-binary MVT Point/MultiPoint features into one datum per point. */
+export declare function getDeckPointFeatures(data: unknown): DeckPointFeature[];

package/dist/src/systems/renderer/deck/mvt-point-aggregation-layer.d.ts

@@ -0,0 +1,107 @@
+import { HeatmapLayer, HexagonLayer } from "@deck.gl/aggregation-layers";
+import { type Layer } from "@deck.gl/core";
+import { MVTLayer } from "@deck.gl/geo-layers";
+import type { Feature, Geometry, Position } from "geojson";
+import type { DeckHeatmapStyle, DeckHexagonStyle } from "../../../domain/models/deck-layer-style";
+import { type DeckColor, type DeckFeatureProperties } from "./deck-layer-helpers";
+export type MvtTileIndex = {
+    x: number;
+    y: number;
+    z: number;
+};
+export interface MvtAggregationSourcePoint {
+    dedupeKey: string;
+    feature: Feature<Geometry, DeckFeatureProperties>;
+    position: [number, number, number];
+}
+export interface MvtAggregationDatum {
+    feature: Feature<Geometry, DeckFeatureProperties>;
+    position: [number, number, number];
+}
+export interface MvtAggregationTilePointSet {
+    id: string;
+    zoom: number;
+    points: MvtAggregationSourcePoint[];
+}
+export interface MvtPointAggregationExtraProps {
+    beforeId?: string;
+}
+type MvtAggregationBase = MVTLayer<DeckFeatureProperties, MvtPointAggregationExtraProps>;
+export type MvtAggregationTile = Parameters<MvtAggregationBase["_onTileLoad"]>[0];
+interface CachedMvtAggregationTile extends MvtAggregationTilePointSet {
+    content: unknown;
+    revision: number;
+}
+interface MvtAggregationCache {
+    nextRevision: number;
+    tiles: Map<string, CachedMvtAggregationTile>;
+    mergedKey: string;
+    mergedData: MvtAggregationDatum[];
+}
+type MvtAggregationState = MvtAggregationBase["state"] & {
+    aggregationCache?: MvtAggregationCache;
+};
+/** Convert the MVT loader's normalized tile coordinates to longitude/latitude. */
+export declare function tilePointToWgs84(coordinates: Position, tileIndex: MvtTileIndex): [number, number, number];
+/** Normalize one non-binary MVT tile into reusable geographic point records. */
+export declare function getMvtAggregationTilePoints(data: unknown, tileId: string, tileIndex: MvtTileIndex, uniqueIdProperty?: string): MvtAggregationSourcePoint[];
+/** Merge child-first visible tile records and remove parent/buffer duplicates. */
+export declare function mergeMvtAggregationTilePoints(tiles: readonly MvtAggregationTilePointSet[]): MvtAggregationDatum[];
+/**
+ * Shared MVT adapter for viewport-wide point aggregation layers.
+ *
+ * MVT remains responsible for loading, caching and refining visible tiles.
+ * The adapter converts and deduplicates their points, then asks the concrete
+ * layer to render exactly one viewport-wide aggregation result.
+ */
+export declare abstract class MvtPointAggregationLayer<ExtraProps extends object = object> extends MVTLayer<DeckFeatureProperties, ExtraProps & MvtPointAggregationExtraProps> {
+    static layerName: string;
+    state: MvtAggregationState;
+    initializeState(): void;
+    finalizeState(): void;
+    _onTileLoad(tile: MvtAggregationTile): void;
+    _onTileUnload(tile: MvtAggregationTile): void;
+    /** A viewport aggregation result is not owned by any one source tile. */
+    filterSubLayer(): boolean;
+    renderLayers(): Layer | null | [];
+    protected abstract renderAggregationLayer(data: readonly MvtAggregationDatum[]): Layer | null;
+    private getAggregationCache;
+    private cacheTile;
+    private getMergedData;
+}
+interface HeatmapLayerStyleProps {
+    aggregation: DeckHeatmapStyle["aggregation"];
+    colorDomain: DeckHeatmapStyle["colorDomain"];
+    colorRange: DeckColor[];
+    debounceTimeout: number;
+    intensity: number;
+    radiusPixels: number;
+    threshold: number;
+    weight: DeckHeatmapStyle["weight"];
+    weightsTextureSize: number;
+}
+interface MvtHeatmapExtraProps {
+    heatmapStyle: HeatmapLayerStyleProps;
+}
+export type HeatmapDatum = MvtAggregationDatum;
+export declare class MvtHeatmapLayer extends MvtPointAggregationLayer<MvtHeatmapExtraProps> {
+    static layerName: string;
+    protected renderAggregationLayer(data: readonly HeatmapDatum[]): HeatmapLayer<MvtAggregationDatum, {
+        beforeId?: string;
+    }>;
+}
+type HexagonLayerStyleProps = Omit<DeckHexagonStyle, "version" | "type" | "colorRange" | "opacity"> & {
+    colorRange: DeckColor[];
+};
+interface MvtHexagonExtraProps {
+    hexagonStyle: HexagonLayerStyleProps;
+}
+export type HexagonDatum = MvtAggregationDatum;
+/** One viewport-wide HexagonLayer backed by the shared visible-MVT adapter. */
+export declare class MvtHexagonLayer extends MvtPointAggregationLayer<MvtHexagonExtraProps> {
+    static layerName: string;
+    protected renderAggregationLayer(data: readonly HexagonDatum[]): HexagonLayer<MvtAggregationDatum, {
+        beforeId?: string;
+    }>;
+}
+export {};

package/dist/src/systems/renderer/flow-field/flow-field-resources.d.ts

@@ -0,0 +1,84 @@
+import type { AuthenticatedFetch } from "../authenticated-deck-load";
+export interface FlowFieldManifest {
+    schema: "ngis-flow-field/1" | "ngis-flow-field/2";
+    id: string;
+    datasetVersion: string;
+    renderer: "flow-field";
+    crs: string;
+    bounds: [number, number, number, number];
+    grid: {
+        width: number;
+        height: number;
+        encoding: string;
+        nodata: number;
+    };
+    frames: Array<{
+        id: string;
+        time?: string;
+        uv: string;
+        seed: string;
+        valid?: string;
+    }>;
+    clip?: {
+        mode: "bbox" | "vector-resource" | "inline-geojson" | string;
+        sourceFileId?: string | null;
+        sourceCrs?: string | null;
+        geometryType?: string | null;
+        geometryHash?: string | null;
+        rasterization: "pixel-center";
+        wgs84Bounds?: [number, number, number, number];
+    };
+    domainMask?: {
+        url: string;
+        width: number;
+        height: number;
+        encoding: "r8-binary";
+        bytes?: number;
+        sha256?: string;
+    };
+    assets?: Record<string, {
+        bytes: number;
+        sha256: string;
+    }>;
+    projection: {
+        url: string;
+        width: number;
+        height: number;
+        physicalWidth?: number;
+        encoding: string;
+    };
+    valueRange?: {
+        u?: [number, number];
+        v?: [number, number];
+        speed?: [number, number];
+    };
+    constraints?: {
+        maxParticles?: number;
+        maxSegments?: number;
+        maxTextureSize?: number;
+    };
+}
+export interface DecodedFlowFrame {
+    id: string;
+    velocity: Float32Array;
+    seed: Uint8Array;
+    valid: Uint8Array;
+}
+export interface DecodedFlowFieldAssets {
+    manifest: FlowFieldManifest;
+    frames: DecodedFlowFrame[];
+    projection: Float32Array;
+    domainMask: Uint8Array;
+    speedRange: [number, number];
+}
+interface RgbaImage {
+    width: number;
+    height: number;
+    pixels: Uint8Array;
+}
+export declare function digestFlowFieldAssetSha256(bytes: ArrayBuffer, subtle?: Pick<SubtleCrypto, "digest"> | null): Promise<string>;
+export declare function parseFlowFieldManifest(value: unknown): FlowFieldManifest;
+export declare function decodePackedFloatRgba(pixels: Uint8Array, physicalWidth: number, height: number, logicalWidth: number): Float32Array<ArrayBuffer>;
+export declare function decodeBinaryMask(image: RgbaImage, width: number, height: number, label: string): Uint8Array<ArrayBuffer>;
+export declare function loadFlowFieldAssets(fetchWithAuth: AuthenticatedFetch, fileId: string, signal: AbortSignal): Promise<DecodedFlowFieldAssets>;
+export {};

package/dist/src/systems/renderer/flow-field/flow-field-shaders.d.ts

@@ -0,0 +1,4 @@
+export declare const FLOW_UPDATE_VERTEX_SHADER = "#version 300 es\nprecision highp float;\n\nlayout(location = 0) in vec4 a_state;\n\nuniform sampler2D u_velocity0;\nuniform sampler2D u_velocity1;\nuniform sampler2D u_seed;\nuniform sampler2D u_domainMask;\nuniform sampler2D u_valid0;\nuniform sampler2D u_valid1;\nuniform vec2 u_gridSize;\nuniform float u_frameMix;\nuniform float u_speedFactor;\nuniform float u_dropRate;\nuniform float u_dropRateBump;\nuniform float u_randomSeed;\nuniform float u_maxAge;\nuniform float u_nodata;\nuniform vec2 u_speedRange;\n\nout vec4 v_state;\n\nfloat randomValue(vec2 value) {\n  return fract(sin(dot(value, vec2(12.9898, 78.233))) * 43758.5453123);\n}\n\nbool isDefinedVelocity(vec2 velocity) {\n  return !any(isnan(velocity)) && !any(isinf(velocity))\n    && abs(velocity.x - u_nodata) > 0.5\n    && abs(velocity.y - u_nodata) > 0.5;\n}\n\nvec2 readVelocity(vec2 uv) {\n  return mix(texture(u_velocity0, uv).rg, texture(u_velocity1, uv).rg, u_frameMix);\n}\n\nivec2 decodeSeedCell(vec4 packed) {\n  ivec4 bytes = ivec4(floor(packed * 255.0 + 0.5));\n  return ivec2(\n    (bytes.r << 8) + bytes.g,\n    (bytes.b << 8) + bytes.a\n  );\n}\n\nbool readMask(sampler2D maskTexture, vec2 uv) {\n  ivec2 size = textureSize(maskTexture, 0);\n  ivec2 cell = clamp(ivec2(floor(uv * vec2(size))), ivec2(0), size - ivec2(1));\n  return texelFetch(maskTexture, cell, 0).r > 0.5;\n}\n\nbool isFlowCell(vec2 uv) {\n  return readMask(u_domainMask, uv)\n    && readMask(u_valid0, uv)\n    && readMask(u_valid1, uv);\n}\n\nfloat normalizedSpeed(vec2 velocity) {\n  return clamp(\n    (length(velocity) - u_speedRange.x) / max(u_speedRange.y - u_speedRange.x, 1.0e-6),\n    0.0,\n    1.0\n  );\n}\n\nvec2 seedPosition(vec2 randomUv) {\n  vec2 cell = vec2(decodeSeedCell(texture(u_seed, randomUv)));\n  vec2 jitter = vec2(\n    randomValue(randomUv + vec2(1.31, u_randomSeed)),\n    randomValue(randomUv + vec2(u_randomSeed, 2.17))\n  );\n  return clamp((cell + jitter) / u_gridSize, vec2(0.0), vec2(1.0));\n}\n\nvec4 respawn(float salt) {\n  vec2 randomUv = vec2(\n    randomValue(vec2(float(gl_VertexID) + salt, u_randomSeed + 0.37)),\n    randomValue(vec2(u_randomSeed + 0.73, float(gl_VertexID) + salt))\n  );\n  vec2 uv = seedPosition(randomUv);\n  vec2 velocity = readVelocity(uv);\n  return vec4(uv, 0.0, isDefinedVelocity(velocity) ? normalizedSpeed(velocity) : 0.0);\n}\n\nvoid main() {\n  vec2 velocity = readVelocity(a_state.xy);\n  float speed = isDefinedVelocity(velocity) ? normalizedSpeed(velocity) : 0.0;\n  vec2 nextPosition = a_state.xy + velocity * u_speedFactor / u_gridSize;\n  bool outside = any(lessThan(nextPosition, vec2(0.0))) || any(greaterThan(nextPosition, vec2(1.0)));\n  float randomDrop = randomValue(a_state.xy + vec2(u_randomSeed, float(gl_VertexID) * 0.000001));\n  bool dropped = randomDrop < (u_dropRate + speed * u_dropRateBump);\n  bool expired = a_state.z >= u_maxAge;\n\n  if (!isDefinedVelocity(velocity) || !isFlowCell(a_state.xy) || outside || dropped || expired) {\n    v_state = respawn(a_state.z + 1.0);\n    return;\n  }\n\n  vec2 nextVelocity = readVelocity(nextPosition);\n  if (!isDefinedVelocity(nextVelocity) || !isFlowCell(nextPosition)) {\n    v_state = respawn(a_state.z + 2.0);\n    return;\n  }\n\n  v_state = vec4(nextPosition, a_state.z + 1.0, normalizedSpeed(nextVelocity));\n}\n";
+export declare const FLOW_UPDATE_FRAGMENT_SHADER = "#version 300 es\nprecision highp float;\nvoid main() {}\n";
+export declare const FLOW_RENDER_VERTEX_SHADER = "#version 300 es\nprecision highp float;\n\nlayout(location = 0) in vec4 a_fromState;\nlayout(location = 1) in vec4 a_toState;\n\nuniform sampler2D u_projection;\nuniform sampler2D u_domainMask;\nuniform sampler2D u_valid0;\nuniform sampler2D u_valid1;\nuniform mat4 u_matrix;\nuniform float u_alpha;\nuniform int u_points;\nuniform vec2 u_viewport;\n\nout float v_speed;\nout float v_alpha;\nout float v_edge;\n\nbool validProjection(vec2 projected) {\n  return !any(isnan(projected)) && !any(isinf(projected));\n}\n\nbool readMask(sampler2D maskTexture, vec2 uv) {\n  ivec2 size = textureSize(maskTexture, 0);\n  ivec2 cell = clamp(ivec2(floor(uv * vec2(size))), ivec2(0), size - ivec2(1));\n  return texelFetch(maskTexture, cell, 0).r > 0.5;\n}\n\nbool validCell(vec2 uv) {\n  return readMask(u_domainMask, uv)\n    && readMask(u_valid0, uv)\n    && readMask(u_valid1, uv);\n}\n\nbool validCellAt(ivec2 cell) {\n  ivec2 size = textureSize(u_domainMask, 0);\n  if (any(lessThan(cell, ivec2(0))) || any(greaterThanEqual(cell, size))) return false;\n  return texelFetch(u_domainMask, cell, 0).r > 0.5\n    && texelFetch(u_valid0, cell, 0).r > 0.5\n    && texelFetch(u_valid1, cell, 0).r > 0.5;\n}\n\nbool validSegment(vec2 start, vec2 end) {\n  if (any(lessThan(start, vec2(0.0))) || any(greaterThan(start, vec2(1.0)))\n      || any(lessThan(end, vec2(0.0))) || any(greaterThan(end, vec2(1.0)))) return false;\n  vec2 size = vec2(textureSize(u_domainMask, 0));\n  vec2 from = min(start * size, size - vec2(0.000001));\n  vec2 to = min(end * size, size - vec2(0.000001));\n  ivec2 cell = ivec2(floor(from));\n  ivec2 target = ivec2(floor(to));\n  vec2 delta = to - from;\n  ivec2 cellStep = ivec2(sign(delta));\n  vec2 tDelta = vec2(\n    delta.x == 0.0 ? 1.0e30 : abs(1.0 / delta.x),\n    delta.y == 0.0 ? 1.0e30 : abs(1.0 / delta.y)\n  );\n  vec2 nextBoundary = vec2(cell) + vec2(\n    cellStep.x > 0 ? 1.0 : 0.0,\n    cellStep.y > 0 ? 1.0 : 0.0\n  );\n  vec2 tMax = vec2(\n    delta.x == 0.0 ? 1.0e30 : (nextBoundary.x - from.x) / delta.x,\n    delta.y == 0.0 ? 1.0e30 : (nextBoundary.y - from.y) / delta.y\n  );\n  for (int visited = 0; visited < 256; visited += 1) {\n    if (!validCellAt(cell)) return false;\n    if (all(equal(cell, target))) return true;\n    bool advanceX = tMax.x <= tMax.y;\n    bool advanceY = tMax.y <= tMax.x;\n    if (advanceX) {\n      cell.x += cellStep.x;\n      tMax.x += tDelta.x;\n    }\n    if (advanceY) {\n      cell.y += cellStep.y;\n      tMax.y += tDelta.y;\n    }\n  }\n  return false;\n}\n\nvoid main() {\n  bool continuous = a_toState.z > a_fromState.z\n    && distance(a_fromState.xy, a_toState.xy) < 0.1;\n  vec2 fromProjected = texture(u_projection, clamp(a_fromState.xy, vec2(0.0), vec2(1.0))).rg;\n  vec2 toProjected = texture(u_projection, clamp(a_toState.xy, vec2(0.0), vec2(1.0))).rg;\n\n  if ((!continuous && u_points == 0)\n      || !validSegment(a_fromState.xy, a_toState.xy)\n      || !validProjection(fromProjected)\n      || !validProjection(toProjected)) {\n    gl_Position = vec4(2.0, 2.0, 2.0, 1.0);\n    v_speed = 0.0;\n    v_alpha = 0.0;\n    v_edge = 1.0;\n    return;\n  }\n\n  vec4 fromClip = u_matrix * vec4(fromProjected, 0.0, 1.0);\n  vec4 toClip = u_matrix * vec4(toProjected, 0.0, 1.0);\n  if (u_points == 1) {\n    gl_Position = toClip;\n    gl_PointSize = 1.5;\n    v_edge = 0.0;\n  } else {\n    vec2 fromScreen = fromClip.xy / fromClip.w;\n    vec2 toScreen = toClip.xy / toClip.w;\n    vec2 direction = normalize((toScreen - fromScreen) * u_viewport);\n    vec2 normal = vec2(-direction.y, direction.x);\n    float side = (gl_VertexID == 0 || gl_VertexID == 2) ? -1.0 : 1.0;\n    bool useTo = gl_VertexID >= 2;\n    vec4 base = useTo ? toClip : fromClip;\n    vec2 screen = base.xy / base.w;\n    vec2 offset = normal * side * 2.0 / u_viewport;\n    gl_Position = vec4((screen + offset) * base.w, base.z, base.w);\n    v_edge = side;\n  }\n  v_speed = a_toState.w;\n  v_alpha = u_alpha;\n}\n";
+export declare const FLOW_RENDER_FRAGMENT_SHADER = "#version 300 es\nprecision highp float;\n\nin float v_speed;\nin float v_alpha;\nin float v_edge;\nout vec4 fragColor;\n\nconst vec3 COLORS[8] = vec3[](\n  vec3(0.196, 0.533, 0.741),\n  vec3(0.400, 0.761, 0.647),\n  vec3(0.671, 0.867, 0.643),\n  vec3(0.902, 0.961, 0.596),\n  vec3(0.996, 0.878, 0.545),\n  vec3(0.992, 0.682, 0.380),\n  vec3(0.957, 0.427, 0.263),\n  vec3(0.835, 0.243, 0.310)\n);\n\nvec3 velocityColor(float speed) {\n  float scaled = clamp(speed, 0.0, 1.0) * 7.0;\n  int low = int(floor(scaled));\n  int high = min(low + 1, 7);\n  return mix(COLORS[low], COLORS[high], fract(scaled));\n}\n\nvoid main() {\n  float antialias = 1.0 - smoothstep(0.45, 1.0, abs(v_edge));\n  fragColor = vec4(velocityColor(v_speed), v_alpha * antialias);\n}\n";