@ngis/plugin-sdk 0.4.0

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

@@ -0,0 +1,251 @@
+import type { ResourceShareMode } from "./resources";
+import type { ApiRequestOptions } from "../lib/api";
+export type SceneScope = "mine" | "shared" | "public";
+export type SceneType = "MAP" | "ANALYSIS" | "GIS";
+export type SceneMapSubCategory = "FREEFORM" | "TEMPLATE";
+export type SceneAnalysisSubCategory = "LAYER_ANALYSIS" | "WORKFLOW_ANALYSIS" | "CODING_ANALYSIS" | "INSIGHT_ANALYSIS";
+/**
+ * Moved to `@/types/common` (F1 / W1.2) — re-exported here so existing
+ * `import type { PageResult } from "@/api/scenes"` call sites keep working.
+ */
+export type { PageResult } from "../types/common";
+export interface NgisScene {
+    id: string;
+    ownerId: string;
+    name: string;
+    type?: SceneType | string | null;
+    description?: string | null;
+    thumbnailFileId?: string | null;
+    configJson?: 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;
+    generation?: number | null;
+    lastActiveAt?: string | null;
+    expiresAt?: string | null;
+    mapSubCategories?: SceneMapSubCategory[] | string[] | null;
+    analysisSubCategories?: SceneAnalysisSubCategory[] | string[] | null;
+    createdAt?: string | null;
+    updatedAt?: string | null;
+}
+export interface NgisPublicScene {
+    id: string;
+    sourceSceneId: string;
+    ownerId: string;
+    name: string;
+    configSnapshot?: string | null;
+    layersSnapshot?: string | null;
+    publishedAt?: string | null;
+}
+export interface PublicSceneSummary {
+    sceneId: string;
+    name: string;
+    ownerId?: string | null;
+    publishedAt?: string | null;
+}
+export interface PublicSceneDetail {
+    scene: NgisScene;
+    layers: NgisSceneLayer[];
+    resources: SceneResourceDto[];
+}
+export interface CreateSceneParams {
+    name: string;
+    type: SceneType;
+    description?: string;
+    mapSubCategories?: SceneMapSubCategory[];
+    analysisSubCategories?: SceneAnalysisSubCategory[];
+}
+export interface UpdateSceneParams {
+    name?: string;
+    description?: string;
+}
+export interface UpdateSceneCapabilitiesParams {
+    mapSubCategories?: SceneMapSubCategory[];
+    analysisSubCategories?: SceneAnalysisSubCategory[];
+}
+export interface SceneResourceDto {
+    id: string;
+    sceneId: string;
+    name: string;
+    originalFileId: string;
+    workingFileId?: string | null;
+    effectiveFileId: string;
+    snapshot?: boolean | null;
+    snapshotId?: string | null;
+    mode?: ResourceShareMode | string | null;
+    geometryType?: string | null;
+    bboxJson?: string | null;
+    addedAt?: string | null;
+    layerCount: number;
+    rendered: boolean;
+    datasetType?: string | null;
+    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.
+     */
+    selectionType?: string | null;
+    /** AVAILABLE | MISSING | UNAVAILABLE | UNKNOWN. */
+    metadataState?: string | null;
+    ready?: boolean;
+    renderable?: boolean;
+}
+export interface ListSceneResourcesOptions {
+    /** Ask the scene service to refresh its bounded, persisted dataset summaries. */
+    refresh?: boolean;
+    signal?: AbortSignal;
+}
+export interface RegisterSceneResourceParams {
+    fileId: string;
+    name?: string;
+}
+export interface NgisSceneLayer {
+    id: string;
+    sceneId: string;
+    resourceId?: string | null;
+    name: string;
+    layerType?: string | null;
+    styleJson?: string | null;
+    visible?: boolean | null;
+    sortOrder?: number | null;
+    groupId?: string | null;
+}
+export interface AddSceneLayerParams {
+    resourceId?: string;
+    fileId?: string;
+    name: string;
+    layerType?: string;
+    styleJson?: string;
+}
+export interface UpdateSceneLayerParams {
+    name?: string;
+    visible?: boolean;
+    sortOrder?: number;
+    styleJson?: string;
+    groupId?: string;
+}
+export interface NgisSceneLayerGroup {
+    id: string;
+    sceneId: string;
+    parentId?: string | null;
+    name: string;
+    orderIndex?: number | null;
+}
+export interface CreateLayerGroupParams {
+    name: string;
+    parentId?: string;
+    orderIndex?: number;
+}
+export interface UpdateLayerGroupParams {
+    name?: string;
+    orderIndex?: number;
+}
+export interface SceneListResult {
+    items: NgisScene[];
+    total: number;
+}
+/** Response of `GET /api/scenes/gis/workspace` — the user's scratch GIS scene. */
+export interface GisWorkspaceResponse {
+    scene: NgisScene;
+    layerCount: number;
+}
+export interface PluginUiLabResponse {
+    scene: NgisScene;
+    generation: number;
+    resourceCount: number;
+    layerCount: number;
+    lastActiveAt: string;
+    expiresAt: string;
+    cleanupState?: string | null;
+    cleanupOperationId?: string | null;
+    cleanupPhase?: string | null;
+    cleanupError?: string | null;
+}
+export interface PluginUiLabSample {
+    id: string;
+    version: string;
+    name: string;
+    description?: string | null;
+    dataKind: string;
+    datasetType: string;
+    geometryType?: string | null;
+    ready: boolean;
+    renderable: boolean;
+    available: boolean;
+    unavailableReason?: string | null;
+}
+export interface PluginUiLabSampleLoadRequest {
+    expectedGeneration: number;
+    sampleIds: string[];
+}
+export interface PluginUiLabSampleLoadItem {
+    sampleId: string;
+    sampleVersion?: string | null;
+    status: "LOADED" | "ALREADY_PRESENT" | "FAILED" | string;
+    resource?: SceneResourceDto | null;
+    layerId?: string | null;
+    error?: string | null;
+}
+export interface PluginUiLabSampleLoadResponse {
+    generation: number;
+    items: PluginUiLabSampleLoadItem[];
+}
+export declare const scenesApi: {
+    listMine(page?: number, size?: number): Promise<SceneListResult>;
+    listShared(): Promise<SceneListResult>;
+    listPublic(page?: number, size?: number): Promise<SceneListResult>;
+    getPublic(sceneId: string): Promise<PublicSceneDetail>;
+    get(sceneId: string): Promise<NgisScene>;
+    /**
+     * The caller's first saved scene of a type, in the listing order
+     * `/api/scenes` itself returns. Scratch/lab scenes are not saved scenes.
+     * Continue through the listing so a matching type beyond the first page is
+     * not mistaken for an empty workspace.
+     */
+    findFirstScene(type: SceneType): Promise<NgisScene | null>;
+    /** The caller's first saved GIS scene, or `null` when they have none. */
+    findFirstGisScene(): Promise<NgisScene | null>;
+    /**
+     * Get-or-create the caller's single scratch GIS workspace scene
+     * (`type=GIS`, `ephemeral=true`). Also resets its inactivity TTL.
+     */
+    getGisWorkspace(): Promise<GisWorkspaceResponse>;
+    getPluginUiLab(signal?: AbortSignal): Promise<PluginUiLabResponse>;
+    resetPluginUiLab(generation: number, signal?: AbortSignal): Promise<PluginUiLabResponse>;
+    discardPluginUiLab(signal?: AbortSignal): Promise<void>;
+    listPluginUiLabSamples(signal?: AbortSignal): Promise<PluginUiLabSample[]>;
+    loadPluginUiLabSamples(request: PluginUiLabSampleLoadRequest, signal?: AbortSignal): Promise<PluginUiLabSampleLoadResponse>;
+    /** Clear the scratch GIS workspace in place (same id, layers/config wiped). */
+    resetGisWorkspace(): Promise<NgisScene>;
+    /**
+     * Promote a scratch scene to a permanent one (`ephemeral` → false). Optional
+     * `name` renames it. After this, the next `getGisWorkspace()` returns a fresh
+     * empty scratch.
+     */
+    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>;
+    updateCapabilities(sceneId: string, params: UpdateSceneCapabilitiesParams): Promise<NgisScene>;
+    delete(sceneId: string): Promise<void>;
+    publish(sceneId: string): Promise<void>;
+    unpublish(sceneId: string): Promise<void>;
+    isPublished(sceneId: string): Promise<boolean>;
+    forkPublic(publicSceneId: string, folderId?: string | null): Promise<NgisScene>;
+    listResources(sceneId: string, options?: ListSceneResourcesOptions | AbortSignal): Promise<SceneResourceDto[]>;
+    registerResource(sceneId: string, params: RegisterSceneResourceParams, options?: ApiRequestOptions): Promise<SceneResourceDto>;
+    renameResource(sceneId: string, resourceId: string, name: string): Promise<SceneResourceDto>;
+    deleteResource(sceneId: string, resourceId: string, cascade?: boolean): Promise<void>;
+    updateResourceWorkingFile(sceneId: string, resourceId: string, fileId: string): Promise<SceneResourceDto>;
+    revertResourceWorkingFile(sceneId: string, resourceId: string): Promise<SceneResourceDto>;
+    listLayers(sceneId: string, signal?: AbortSignal): Promise<NgisSceneLayer[]>;
+    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>;
+    listLayerGroups(sceneId: string): Promise<NgisSceneLayerGroup[]>;
+    createLayerGroup(sceneId: string, params: CreateLayerGroupParams): Promise<NgisSceneLayerGroup>;
+    updateLayerGroup(sceneId: string, groupId: string, params: UpdateLayerGroupParams): Promise<NgisSceneLayerGroup>;
+    deleteLayerGroup(sceneId: string, groupId: string): Promise<void>;
+};

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

@@ -0,0 +1,22 @@
+export interface UserProfile {
+    id: string;
+    name?: string | null;
+    email?: string | null;
+    username?: string | null;
+    avatar?: string | null;
+    role?: string | null;
+}
+declare function fetchUserProfile(userId: string): Promise<UserProfile>;
+export declare function getUserDisplayName(profile: UserProfile | null, fallback: string): string;
+export declare const usersApi: {
+    /** The current authenticated user's profile. */
+    me(): Promise<UserProfile>;
+    /** Update the only editable text field exposed by the user service. */
+    updateMe(username: string): Promise<unknown>;
+    /** Upload the current user's avatar. The service returns its URL. */
+    uploadAvatar(file: File): Promise<string>;
+    /** Public profile for any user id (used to resolve owner names). */
+    getById: typeof fetchUserProfile;
+    getByIdSafe(userId: string): Promise<UserProfile | null>;
+};
+export {};

package/dist/src/domain/algorithms/deck-layer-style.d.ts

@@ -0,0 +1,34 @@
+import type { DeckColorMapping, DeckCategoryValue, DeckLayerStyle, DeckElevationStyle, DeckMvtLineStyle } from "../models/deck-layer-style";
+import type { SceneLayerTypeId } from "../models/scene-layer-type";
+export interface DeckStyleFieldDescriptor {
+    name: string;
+    kind?: string | null;
+    type?: string | null;
+}
+export declare function getDefaultDeckColorRampId(layerType: SceneLayerTypeId | DeckLayerStyle["type"]): "blues" | "ylorrd";
+export declare function isNumericDeckStyleField(field: DeckStyleFieldDescriptor): boolean;
+export declare function getNumericDeckStyleFields<T extends DeckStyleFieldDescriptor>(fields: readonly T[]): T[];
+export declare function createDefaultDeckLayerStyle(layerType: SceneLayerTypeId, fields: readonly DeckStyleFieldDescriptor[]): DeckLayerStyle | null;
+export declare function normalizeDeckLayerStyle(value: unknown, expectedType?: SceneLayerTypeId | null): DeckLayerStyle | null;
+export declare function parseDeckLayerStyleJson(styleJson: string | null | undefined, expectedType?: SceneLayerTypeId | null): DeckLayerStyle | null;
+export declare function serializeDeckLayerStyle(style: DeckLayerStyle): string;
+export declare function getDeckColorForValue(value: unknown, color: DeckColorMapping): string;
+export declare function getDeckElevationValue(value: number, elevation: DeckElevationStyle): number;
+export type DeckRangeColorMapping = Extract<DeckColorMapping, {
+    mode: "graduated" | "continuous";
+}>;
+export declare function applyDeckColorRamp(color: DeckRangeColorMapping, colors: readonly string[]): DeckRangeColorMapping;
+export declare function reverseDeckColorRamp(color: DeckRangeColorMapping): DeckRangeColorMapping;
+export declare function getDeckLineWidthForValue(value: number, width: DeckMvtLineStyle["width"]): number;
+export declare function buildGraduatedDeckColors(field: string, breaks: readonly number[], colors: readonly string[]): DeckColorMapping | null;
+export declare function buildContinuousDeckColors(field: string, inputs: readonly number[], colors: readonly string[]): DeckColorMapping | null;
+export declare function buildCategoricalDeckColors(field: string, values: readonly DeckCategoryValue[], colors: readonly string[], defaultColor?: string): DeckColorMapping | null;
+export declare function buildEqualIntervalDeckBreaks(min: number, max: number, classCount: number): number[];
+export declare function normalizeDeckClassificationBreaks(breaks: readonly number[], classCount: number): number[];
+export declare function applyDeckSharedFieldMapping(style: DeckLayerStyle, options: {
+    field: string;
+    min: number;
+    max: number;
+    colors: readonly string[];
+    widthRange?: readonly [number, number];
+}): DeckLayerStyle | null;

package/dist/src/domain/algorithms/maplibre-style.d.ts

@@ -0,0 +1,63 @@
+import { type RasterClassificationMethod, type RasterColorMode } from "../../lib/raster-color-layer/colorRamp";
+export type MapLibreSceneLayerType = "fill" | "line" | "circle" | "raster" | "symbol";
+export type MapLibreStyleRecord = Record<string, unknown>;
+/** The style types the vector/raster style editor can produce and edit. `symbol`
+ *  is excluded by construction (F24.9): a symbol layer's appearance is compiled
+ *  from its manifest, and the two functions below can never return it because
+ *  `symbol` is in neither MAPLIBRE_SCENE_LAYER_TYPES nor
+ *  `getCanonicalMapLibreStyleType`. Stating that in the type keeps the editor's
+ *  own unions closed instead of forcing a widening through five files. */
+export type MapLibreEditableLayerType = Exclude<MapLibreSceneLayerType, "symbol">;
+export declare const RASTER_TILE_PARAM_KEYS: Set<string>;
+/** The style types a user may pick for a vector/raster scene layer. `symbol` is
+ *  NOT a member: a symbol layer's appearance comes from its manifest, not from a
+ *  hand-edited MapLibre style record (F24.9). */
+export declare const MAPLIBRE_SCENE_LAYER_TYPES: MapLibreEditableLayerType[];
+export declare const MAPLIBRE_PAINT_PROPERTY_KEYS: Record<MapLibreSceneLayerType, Set<string>>;
+export declare const MAPLIBRE_LAYOUT_PROPERTY_KEYS: Record<MapLibreSceneLayerType, Set<string>>;
+/** F24.9 — `icon-image` values are restricted to registry-issued sprite ids.
+ *  The registry mints them through `symbolSpriteId` (symbol-compile.ts); this is
+ *  the shape check the style layer applies before an id reaches MapLibre, so a
+ *  hand-written style cannot name an arbitrary image in the basemap's sprite. */
+export declare const MAPLIBRE_SYMBOL_SPRITE_ID_PATTERN: RegExp;
+export declare function isRegistryIssuedSpriteId(value: unknown): value is string;
+export declare function isMapLibreStyleRecord(value: unknown): value is MapLibreStyleRecord;
+export declare function normalizeMapLibreLayerType(value: unknown): MapLibreEditableLayerType | undefined;
+export declare function getDefaultMapLibreLayerType(params: {
+    layerType?: string | null;
+    geometryType?: string | null;
+}): MapLibreEditableLayerType;
+export declare function isMapLibreLayerTypeCompatible(type: MapLibreSceneLayerType, params: {
+    layerType?: string | null;
+    geometryType?: string | null;
+}): boolean;
+export declare function getCompatibleMapLibreLayerType(params: {
+    layerType?: string | null;
+    geometryType?: string | null;
+    styleType?: unknown;
+}): MapLibreEditableLayerType;
+export declare function getDefaultMapLibrePaint(type: MapLibreSceneLayerType): MapLibreStyleRecord;
+export declare function filterMapLibreStyleRecord(value: unknown, type: MapLibreSceneLayerType, category: "paint" | "layout"): MapLibreStyleRecord;
+export declare function parseRasterRescale(value: unknown): [number, number] | null;
+export declare function parseRasterColorMode(value: unknown): RasterColorMode | null;
+export declare function parseRasterClassificationMethod(value: unknown): RasterClassificationMethod | null;
+export declare function parseRasterClassBreaks(value: unknown): number[] | null;
+export declare function filterRasterTileParams(value: unknown): MapLibreStyleRecord;
+export declare function sanitizeMapLibreStyleObjectForLayer(style: unknown, params: {
+    layerType?: string | null;
+    geometryType?: string | null;
+}): {
+    style: null;
+    changed: boolean;
+} | {
+    style: MapLibreStyleRecord;
+    changed: boolean;
+};
+export declare function parseMapLibreStyleJson(styleJson?: string | null): MapLibreStyleRecord | null;
+export declare function sanitizeMapLibreStyleJsonForLayer(styleJson: string | null | undefined, params: {
+    layerType?: string | null;
+    geometryType?: string | null;
+}): {
+    styleJson: string | null | undefined;
+    changed: boolean;
+};

package/dist/src/domain/algorithms/raster-color-ramps.d.ts

@@ -0,0 +1,37 @@
+export type RasterColorRampCategory = "sequential" | "diverging" | "terrain" | "qualitative";
+export type RasterColorRampLabelKey = "presets.gray" | "presets.blues" | "presets.ylgnbu" | "presets.ylorrd" | "presets.greens" | "presets.purples" | "presets.rdbu" | "presets.brbg" | "presets.rdylbu" | "presets.spectral" | "presets.terrain" | "presets.bathymetry" | "presets.landElevation" | "presets.slope" | "presets.precipitation" | "presets.temperature" | "presets.vegetation" | "presets.set2" | "presets.paired" | "presets.set3" | "presets.category10" | "presets.dark2" | "presets.tableau10";
+export interface RasterColorRampPreset {
+    id: string;
+    labelKey: RasterColorRampLabelKey;
+    category: RasterColorRampCategory;
+    colors: string[];
+    clientOnly?: boolean;
+}
+export declare const RASTER_COLOR_RAMP_PRESETS: RasterColorRampPreset[];
+export declare const DEFAULT_RASTER_COLOR_RAMP: string[];
+export declare function parseRasterColorRamp(value: unknown): string[] | null;
+export declare function getRasterColorRampPreset(id: unknown): RasterColorRampPreset | undefined;
+export declare function getDefaultRasterColorRamp(): string[];
+export declare function sampleRasterColorRamp(colors: string[], count: number): string[];
+export declare function cycleRasterColorRamp(colors: string[], count: number): string[];
+export declare function resolveRasterColorRamp(params: {
+    colorRamp?: unknown;
+    legacyPreset?: unknown;
+    sampleCount?: number;
+    sampleMode?: "interpolate" | "cycle";
+}): {
+    custom: boolean;
+    reversed: boolean;
+    id: string;
+    labelKey: RasterColorRampLabelKey;
+    category: RasterColorRampCategory;
+    colors: string[];
+    clientOnly?: boolean;
+} | {
+    id: string;
+    labelKey: null;
+    category: null;
+    colors: string[];
+    custom: boolean;
+    reversed: boolean;
+};

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

@@ -0,0 +1,25 @@
+import { type SceneLayerGeometryFamily, type SceneLayerTypeDefinition, type SceneLayerTypeId } from "../models/scene-layer-type";
+interface SceneLayerResourceFieldDescriptor {
+    kind?: string | null;
+    type?: string | null;
+}
+export interface SceneLayerResourceDescriptor {
+    type?: string | null;
+    geometry?: string | null;
+    geometryType?: string | null;
+    fields?: readonly SceneLayerResourceFieldDescriptor[] | null;
+}
+export interface SceneLayerTypeDescriptor {
+    layerType?: string | null;
+}
+export declare function getResourceGeometryFamily(resource: SceneLayerResourceDescriptor): SceneLayerGeometryFamily | null;
+export declare function isResolvedGeometryType(geometryType?: string | null): boolean;
+export declare function getSceneLayerTypeDefinition(layerType: string | null | undefined): SceneLayerTypeDefinition | undefined;
+export declare function getCompatibleSceneLayerTypes(resource: SceneLayerResourceDescriptor): SceneLayerTypeDefinition[];
+export declare function isSceneLayerTypeCompatible(layerType: string | null | undefined, resource: SceneLayerResourceDescriptor): boolean;
+export declare function isMapLibreSceneLayerType(layerType: string | null | undefined): boolean;
+export declare function isDeckSceneLayerType(layerType: string | null | undefined): boolean;
+export declare function isRasterSceneLayerType(layerType: string | null | undefined): boolean;
+export declare function getSceneLayerGeometryFamily(layerType: string | null | undefined): SceneLayerGeometryFamily | null;
+export declare function normalizeLegacySceneLayerType(layer: SceneLayerTypeDescriptor, resource: SceneLayerResourceDescriptor): SceneLayerTypeId | null;
+export {};

package/dist/src/domain/algorithms/symbol-compile.d.ts

@@ -0,0 +1,100 @@
+/**
+ * `compileSymbol` — the render-plan compiler (F24.8). Pure: no map, no DOM, no
+ * deck.gl import. It picks **one engine per scene layer** — MapLibre when every
+ * stack layer is MapLibre-expressible, deck.gl otherwise — and returns the plan
+ * the registry entry mounts.
+ *
+ * Two things it deliberately does not do:
+ *
+ *  - It does not fix the mixed-renderer z-order limitation
+ *    (`docs/deckgl/mixed-renderer-layer-order-risk.md`). A deck plan carries a
+ *    typed `deck-z-order-group` hint and the limitation stays inherited.
+ *  - It does not rewrite `styleJson`. F24.9's fallback semantics are "host
+ *    default for the geometry family + a typed reason, saved intent untouched",
+ *    so an unavailable symbol produces a *plan* carrying `fallbackReason` and
+ *    the stored style is never touched — assert byte equality on reload.
+ */
+import { type SymbolCapabilities, type SymbolFallbackReason, type SymbolGeometry, type SymbolManifest, type SymbolRef, type SymbolRenderPlan, type SymbolStyleJson } from "../models/symbol";
+import type { MapLibreEditableLayerType } from "./maplibre-style";
+/**
+ * The `builtin:` T0 renderers a MapLibre paint/layout pair can express on its
+ * own. Anything else — including every T2 shader and every T3 plugin renderer —
+ * forces the whole scene layer onto deck, because F24.8 picks one engine for the
+ * layer and not one per stack member.
+ */
+export declare const MAPLIBRE_EXPRESSIBLE_BUILTIN_RENDERERS: Set<string>;
+/** The sprite id the registry issues for one stack layer, and the only shape
+ *  `icon-image` accepts (F24.9, `isRegistryIssuedSpriteId`). */
+export declare function symbolSpriteId(symbolId: string, version: string, layerIndex: number, variant?: string): string;
+/**
+ * A `fallback` stack layer's index is offset past the main stack before it is
+ * minted into a sprite id.
+ *
+ * Without it `layers[0]` and `fallback[0]` mint the **same** id for two
+ * different assets, and the registry answers the second `ensure` with the first
+ * one's pixels — a wrong image, silently, on exactly the path that exists to
+ * degrade well. `SYMBOL_MAX_LAYERS` caps either stack, so the two ranges cannot
+ * overlap, and the id still matches `MAPLIBRE_SYMBOL_SPRITE_ID_PATTERN` (`\d+`).
+ */
+export declare const SYMBOL_FALLBACK_SPRITE_INDEX_OFFSET = 8;
+export declare function symbolFallbackSpriteIndex(index: number): number;
+/** The host default MapLibre layer type for a geometry family — what a fallback
+ *  plan renders (F24.9). */
+export declare function getSymbolHostDefaultLayerType(geometry: SymbolGeometry): MapLibreEditableLayerType;
+/** A stable key for a symbol reference — the string `resolve` echoes as `ref`. */
+export declare function symbolRefKey(ref: SymbolRef): string;
+/**
+ * Parse a scene layer's `styleJson` as a symbol style. Returns `null` for
+ * anything that is not one — including a MapLibre style record — so a caller can
+ * route without a try/catch. It never mutates or re-serializes: the string it
+ * was handed is what stays on the scene layer.
+ */
+export declare function parseSymbolStyleJson(styleJson: string | null | undefined): SymbolStyleJson | null;
+/**
+ * The plan for an unavailable or unusable symbol: the host default for the
+ * geometry family, plus the typed reason. No stack, nothing animated, and the
+ * caller's `styleJson` untouched.
+ */
+export declare function compileSymbolFallbackPlan(geometry: SymbolGeometry, reason: SymbolFallbackReason): SymbolRenderPlan;
+/** The reasons a manifest's own `fallback` stack can be reached under. */
+export declare const AUTHOR_FALLBACK_REASONS: readonly SymbolFallbackReason[];
+export interface CompileSymbolOptions {
+    /**
+     * The manifest a T0 preset extends. `compileSymbol` will not go and fetch it —
+     * a preset compiled without its target is `missing`, which is the honest
+     * answer rather than a silently empty stack.
+     */
+    presetTarget?: SymbolManifest | null;
+    /**
+     * A reason the caller already knows (from `resolve`: the symbol is forbidden,
+     * yanked, gone, or its T3 extension is not installed). Short-circuits to the
+     * fallback plan for the style's geometry.
+     */
+    unavailableReason?: SymbolFallbackReason | null;
+    /** Geometry to use for a fallback plan when there is no manifest to read it from. */
+    geometry?: SymbolGeometry;
+}
+/**
+ * `compileSymbol(manifest, style, capabilities) → SymbolRenderPlan`.
+ *
+ * `manifest` is `null` when the reference did not resolve; `options.geometry`
+ * then names the family whose host default to fall back to.
+ */
+export declare function compileSymbol(manifest: SymbolManifest | null, style: SymbolStyleJson | null, capabilities: SymbolCapabilities, options?: CompileSymbolOptions): SymbolRenderPlan;
+export interface SymbolMapLibreLayerSpec {
+    type: MapLibreEditableLayerType | "symbol";
+    paint: Record<string, unknown>;
+    layout: Record<string, unknown>;
+}
+/**
+ * The MapLibre layer shape a `maplibre`-engine plan mounts. Sprite-backed stack
+ * layers become the geometry's native MapLibre image layer: `symbol` for a
+ * point, `line-pattern` for a line and `fill-pattern` for a polygon. A plan
+ * with no usable sprite becomes the host default for the family so the features
+ * still appear.
+ *
+ * `availableSpriteIds` is what the caller's `SpriteRegistry` actually holds —
+ * naming a sprite MapLibre has never been given renders nothing and reports no
+ * error, which is the same silent-blank failure mode F24.8.1 warns about.
+ */
+export declare function buildSymbolMapLibreLayerSpec(plan: SymbolRenderPlan, availableSpriteIds?: ReadonlySet<string>): SymbolMapLibreLayerSpec;

package/dist/src/domain/algorithms/symbol-params.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Param and slot normalisation for symbols (F24.5) — pure, no map, no DOM.
+ *
+ * Three jobs, kept apart because the render-plan compiler needs them at
+ * different moments:
+ *
+ *  1. `normalizeSymbolParams` folds a scene layer's saved `params` onto the
+ *     manifest's declared defaults, refusing what the declaration does not
+ *     allow. It never throws and never drops the caller's intent silently — an
+ *     ignored value comes back as a `SymbolParamIssue`, because F24.9's "saved
+ *     intent untouched" rule means the wrong-looking value stays in `styleJson`
+ *     and the *reason* is what the UI has to show.
+ *  2. `resolveSymbolLayerParams` turns one stack layer's `params` aliases into
+ *     concrete values (the `P_<name>` uniforms the harness will carry).
+ *  3. `normalizeSymbolSlots` resolves the closed slot list against the scene
+ *     layer's bindings. The list does not grow this stage: a per-feature total
+ *     path length is not a slot (F24.5.1) and rides `data0..data3`.
+ */
+import { type SymbolManifest, type SymbolParamBindings, type SymbolParamValue, type SymbolParamValues, type SymbolSlot, type SymbolSlotBinding } from "../models/symbol";
+export type SymbolParamIssueCode = "unknown-param" | "wrong-type" | "out-of-range" | "not-in-enum" | "unknown-slot" | "unknown-alias-target" | "capacity-exceeded" | "preset-target-mismatch";
+export interface SymbolParamIssue {
+    code: SymbolParamIssueCode;
+    /** The param, alias or slot the issue is about. */
+    name: string;
+    detail: string;
+}
+export interface NormalizedSymbolParams {
+    values: SymbolParamValues;
+    issues: SymbolParamIssue[];
+}
+/**
+ * The manifest's declared defaults with the caller's overrides folded on top.
+ * An override naming a param the manifest does not declare is dropped with an
+ * `unknown-param` issue — never merged through, because it would then reach a
+ * uniform slot nothing allocated.
+ */
+export declare function normalizeSymbolParams(manifest: Pick<SymbolManifest, "params">, overrides?: SymbolParamValues | null): NormalizedSymbolParams;
+/**
+ * F24.5's fixed uniform block: 16 floats + 8 colours. A manifest declaring more
+ * is refused at validation server-side; the client check exists so the studio
+ * can say so before a publish round-trip.
+ */
+export declare function checkSymbolParamCapacity(manifest: Pick<SymbolManifest, "params">): SymbolParamIssue[];
+export interface ResolvedSymbolLayerParams {
+    values: Record<string, SymbolParamValue>;
+    issues: SymbolParamIssue[];
+}
+/**
+ * One stack layer's `params` map (alias → param reference or literal) resolved
+ * against already-normalized symbol params. See `SymbolParamBindings` for why a
+ * bare string is a reference when it names a declared param and a literal
+ * otherwise.
+ */
+export declare function resolveSymbolLayerParams(manifest: Pick<SymbolManifest, "params">, bindings: SymbolParamBindings | undefined, values: SymbolParamValues): ResolvedSymbolLayerParams;
+export type SymbolSlotSource = "binding" | "manifest-default" | "undeclared";
+export interface NormalizedSymbolSlot {
+    slot: SymbolSlot;
+    source: SymbolSlotSource;
+    /** Present when the slot resolves to a fixed value rather than a per-feature read. */
+    value?: SymbolParamValue;
+    /** Present when the scene layer bound the slot. */
+    binding?: SymbolSlotBinding;
+    /** A `field`/`host` binding is read per feature; a `const` or default is not. */
+    perFeature: boolean;
+}
+export interface NormalizedSymbolSlots {
+    slots: NormalizedSymbolSlot[];
+    byName: Partial<Record<SymbolSlot, NormalizedSymbolSlot>>;
+    issues: SymbolParamIssue[];
+}
+/**
+ * The manifest's declared slots resolved against the scene layer's bindings.
+ * A binding for a slot the manifest does not declare is dropped with an issue —
+ * the closed list is the contract's, but *which* of the nine a symbol reads is
+ * the manifest's, and binding one it never reads is silently inert otherwise.
+ */
+export declare function normalizeSymbolSlots(manifest: Pick<SymbolManifest, "slots" | "params">, bindings: Partial<Record<SymbolSlot, SymbolSlotBinding>> | undefined, values: SymbolParamValues): NormalizedSymbolSlots;
+export interface ResolvedSymbolPreset {
+    manifest: SymbolManifest;
+    issues: SymbolParamIssue[];
+}
+/**
+ * A T0 preset (`extends`) resolved against the manifest it extends: the target's
+ * stack, slots, animation and fallback, with the preset's identity and the
+ * target's param defaults overridden by the preset's choices. The preset's
+ * params must be a subset of the target's declarations (F24.3) — one that is not
+ * comes back as an issue and is dropped, so a stale preset degrades to the
+ * target's defaults instead of failing to render.
+ */
+export declare function resolveSymbolPreset(preset: SymbolManifest, target: SymbolManifest): ResolvedSymbolPreset;

package/dist/src/domain/map/bounds.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Resource-bounds parsing + bounds-driven camera focus. Extracted mechanically
+ * from `SceneMapCanvas.tsx` (session C1) — no behavior change.
+ */
+import type { Map as MapLibreMap } from "maplibre-gl";
+import type { ResourceBounds } from "./types";
+export declare function parseResourceBounds(bboxJson?: string | null): ResourceBounds | undefined;
+export declare function focusMapOnBounds(map: MapLibreMap, bounds: ResourceBounds, eventData?: Record<string, unknown>): void;