ofs-object 0.1.1 → 0.1.4

package/dist/index.d.ts

@@ -272,6 +272,15 @@ export declare abstract class BaseGLAdapter implements IMapAdapter {
     protected whenStyleLoaded(map: any): Promise<void>;
     bindDataSource(dataSource: OFSDataSource, thematicEngine?: OFSThematicEngine): void;
     protected syncAllLayers(): void;
+    /**
+     * Put a raster or vector tile layer on the map, or bring an existing one up to date.
+     *
+     * Tile layers are registered in the same `glLayers` table as feature layers, so removal, stacking
+     * and the clean hand-back in `removeOwnLayers` treat both kinds alike without knowing which is
+     * which. What they do not share is the data path: there is no GeoJSON to send, so nothing here
+     * touches sources after the first creation except to rebuild when the styling changes.
+     */
+    syncTileLayer(layer: OFSTileLayer): void;
     syncLayer(layer: OFSLayerData): void;
     /** Reordering several layers emits one update per layer; restack once */
     private scheduleLayerOrder;
@@ -308,9 +317,22 @@ export declare abstract class BaseGLAdapter implements IMapAdapter {
      * whole source has to be resent (every feature's label text changes at once).
      */
     protected syncLabelSource(layer: OFSLayerData): boolean;
+    /** Extra options for a layer's new GeoJSON source; an engine that needs some overrides this */
+    protected sourceOptionsFor(_layer: OFSLayerData): Record<string, unknown>;
+    /**
+     * Whether changes to this layer's source can be sent as a diff instead of the whole collection.
+     * The default is MapLibre's, whose `updateData` takes a diff on any GeoJSON source. Mapbox's
+     * takes something else and only on some sources, so MapboxAdapter overrides this and the next.
+     */
+    protected supportsPartialUpdate(_layer: OFSLayerData, source: any): boolean;
+    /** Send a diff worked out by `updateSourceData`, in the form the engine takes it */
+    protected sendPartialUpdate(source: any, diff: {
+        add: Feature<Geometry, any>[];
+        remove: (string | number)[];
+    }): void;
     /**
-     * Send changes of a layer to its map source. Uses GeoJSONSource.updateData (MapLibre) with only
-     * the added / changed / removed features when possible, otherwise falls back to setData.
+     * Send changes of a layer to its map source: only the added / changed / removed features when the
+     * engine can take a diff (see `supportsPartialUpdate`), otherwise the whole collection via setData.
      * Changed features are detected by object identity: OFSLayerData replaces the stored object on
      * every add or update.
      */
@@ -773,6 +795,16 @@ export declare function colorRampGradientCss(name: string, reverse?: boolean): s
  */
 export declare type ColorRampType = 'sequential' | 'diverging' | 'qualitative';
 
+/**
+ * The colours a theme actually puts on the map, for a layer of the given geometry.
+ *
+ * A simple theme is one colour, but which one depends on the geometry: the fill of a polygon (or
+ * its outline when it is drawn unfilled), the stroke of a line, the marker of a point. A
+ * categorised or graduated theme puts every class colour it shows on the map. (New layers do not
+ * avoid those: see `OFSThematicEngine.defaultColorFor`.)
+ */
+export declare function colorsOfTheme(theme: ThematicDefinition, geometry: LayerGeometryType): string[];
+
 export declare interface CommandArgSpec {
     /** Schema properties filled from the words before any --option, in order */
     positional?: string[];
@@ -1111,6 +1143,9 @@ export declare interface DistanceMeasure {
     closingMeters: number;
 }
 
+/** Below this CIEDE2000 distance two map colours are easy to confuse at a glance */
+export declare const DISTINCT_DELTA_E = 20;
+
 /** Save an exported image in the browser */
 export declare function downloadMapImage(image: MapImage): void;
 
@@ -1478,6 +1513,12 @@ export declare function findIntersectingFeature(dataSource: OFSDataSource, targe
     feature: Feature<Geometry, any>;
 } | null;
 
+/**
+ * The engine to build a map with, or null when the caller has not supplied one.
+ * `options` wins over the global: passing a library explicitly should always be what gets used.
+ */
+export declare function findMapEngine(global: MapEngineGlobal, options?: Record<string, any>): any | null;
+
 export declare function forEachPosition(geometry: Geometry, fn: (c: Position) => void): void;
 
 /** Degrees as "45°30'20"" (bearing) or "45.5056°" */
@@ -1983,6 +2024,21 @@ export declare interface LandAreaMeasure {
     raiNganWa: string;
 }
 
+/**
+ * Chosen by greedy max-min selection in CIEDE2000 over the Tailwind 400-800 chromatic families,
+ * starting from a blue. Every pair is at least 20 apart and every colour is at least 22 from the
+ * reserved colours below.
+ *
+ * The blue is `#2563eb`, not the `#3b82f6` every layer used to get: that one is only 16.8 from the
+ * slate grey used for "all other values", which is too close to tell apart in a legend.
+ *
+ * It stops at 11 because that is where the space runs out: the twelfth pick is already under 20
+ * from its nearest neighbour, and every pick after it is closer still. Past this many layers the
+ * picker generates colours instead (see `pickLayerColor`), and they are as far apart as the space
+ * allows rather than clearly distinct.
+ */
+export declare const LAYER_COLOR_PALETTE: readonly string[];
+
 export declare type LayerGeometryType = 'point' | 'line' | 'polygon' | 'circle' | 'symbol';
 
 /** Legend group of layers; groups can be nested */
@@ -2015,6 +2071,11 @@ export declare interface LayerMetadata {
     sourceFile?: string;
     /** Attribute schema in source order (kept for export; edited through OFSAttributeTools) */
     fields?: FieldSchema[];
+    /**
+     * Colour to draw the layer with (any CSS colour). Left out, the layer gets one chosen to stand
+     * apart from the layers already on the map - see `pickLayerColor`.
+     */
+    color?: string;
     [key: string]: unknown;
 }
 
@@ -2040,7 +2101,11 @@ export declare interface LegendGroupViewModel {
 export declare interface LegendLayerViewModel {
     id: string;
     name: string;
-    type: LayerGeometryType;
+    /**
+     * Geometry for a feature layer, or the tile kind for one served from a tile server. Tile layers
+     * carry no features and no symbology, so `items` is empty and `featureCount` is zero for them.
+     */
+    type: LayerGeometryType | 'raster' | 'vector';
     visible: boolean;
     /** Visible and all parent groups visible */
     rendered: boolean;
@@ -2156,6 +2221,33 @@ export declare function listExpressionVariables(): string[];
 
 export declare function listMarkerIcons(): string[];
 
+/**
+ * Read a project back onto the map.
+ *
+ * Layers go in before groups are wired up and before the themes are applied, so that a theme never
+ * arrives for a layer that is not there yet.
+ */
+export declare function loadProject(dataSource: OFSDataSource, thematicEngine: OFSThematicEngine, project: OFSProjectFile, options?: LoadProjectOptions): LoadProjectResult;
+
+export declare interface LoadProjectOptions {
+    /**
+     * Clear what is already loaded first (default). Turning this off merges the project in, which
+     * replaces any layer whose id it also defines.
+     */
+    replace?: boolean;
+}
+
+export declare interface LoadProjectResult {
+    layers: string[];
+    tileLayers: string[];
+    groups: number;
+    features: number;
+    themes: number;
+    view?: ProjectView;
+    /** Layers the file described but carried no data for */
+    emptyLayers: string[];
+}
+
 export declare function localName(name: string): string;
 
 export declare type LocationPredicate = 'intersects' | 'within' | 'contains' | 'disjoint' | 'touches' | 'crosses' | 'within-distance';
@@ -2169,8 +2261,66 @@ export declare function looksGeographic(bounds: [number, number, number, number]
  */
 export declare function makeCurve(vertices: Coordinate[], bulges: number[], sagToleranceMeters?: number): OfsCurveMeta | null;
 
+/**
+ * Largest layer given a dynamic source by default. A judgement call rather than a measurement - see
+ * the class comment - and adjustable per adapter through `dynamicSourceMaxFeatures`.
+ */
+export declare const MAPBOX_DYNAMIC_MAX_FEATURES = 5000;
+
+/**
+ * Mapbox GL adapter.
+ *
+ * ## Sending only what changed
+ *
+ * MapLibre's `updateData` takes a diff on any GeoJSON source. Mapbox's is a different thing: it
+ * takes a FeatureCollection to merge in by id (a feature with a null geometry deletes), and only on a
+ * source created with `dynamic: true` - on any other source it fires an error event and the update is
+ * silently lost.
+ *
+ * And `dynamic: true` does not just switch that method on. It replaces geojson-vt, which cuts the data
+ * into tiles and simplifies it for low zooms, with an index that scans every feature for every tile
+ * and does not simplify at all; Mapbox's own source calls it the mode for "small data, frequently
+ * updated". For a layer of tens of thousands of parcels that makes every zoomed-out tile carry every
+ * parcel at full detail - far worse than resending the data.
+ *
+ * So a layer gets a dynamic source only while it is small (`dynamicSourceMaxFeatures`) - the drawing
+ * and editing layers that change on every drag, which is what the mode is for - and every other layer
+ * keeps the default source and `setData`. A dynamic layer that grows past the limit, or gains a
+ * GeometryCollection (which dynamic mode cannot take), has its source rebuilt in the default mode. It
+ * is not switched back if it shrinks: `setData` on a small layer is cheap anyway.
+ */
 export declare class MapboxAdapter extends BaseGLAdapter {
     readonly engineName: "mapbox";
+    /** Layers larger than this keep the default source (0 turns dynamic sources off) */
+    dynamicSourceMaxFeatures: number;
+    /** Layers whose source was created with `dynamic: true` */
+    private dynamicSources;
+    protected sourceOptionsFor(layer: OFSLayerData): Record<string, unknown>;
+    protected supportsPartialUpdate(layer: OFSLayerData, source: any): boolean;
+    /** Mapbox merges features in by id; a feature with no geometry is how it is told to delete one */
+    protected sendPartialUpdate(source: any, diff: {
+        add: Feature<Geometry, any>[];
+        remove: (string | number)[];
+    }): void;
+    syncLayer(layer: OFSLayerData): void;
+    protected updateSourceData(layer: OFSLayerData): void;
+    removeLayer(layerId: string): void;
+    private outgrewDynamicSource;
+    /**
+     * Replace a layer's source with one in the default mode. A source cannot change mode in place, and
+     * its GL layers cannot outlive it, so all of them are removed and built again; feature state goes
+     * with the old source, so the selection is put back afterwards.
+     */
+    private rebuildSource;
+    private fitsDynamicSource;
+    /** Mapbox before 3.4 has neither the option nor the method; `peerDependencies` allows >= 3.0 */
+    private engineHasDynamicSources;
+    /**
+     * Build a map in `container`.
+     *
+     * `mapbox-gl` is not imported by this package - see `resolve-engine.ts` - so pass the library in
+     * as `options.mapboxgl`, or load it from a script tag.
+     */
     init(container: HTMLElement | string, options?: Record<string, any>): Promise<void>;
 }
 
@@ -2189,6 +2339,22 @@ export declare interface MapClickEvent {
     originalEvent: MouseEvent;
 }
 
+/**
+ * Finding the map engine an adapter should build its map with.
+ *
+ * Neither `maplibre-gl` nor `mapbox-gl` is imported anywhere in this package, and that is
+ * deliberate. Both are optional peer dependencies, but a static `import` of one is a hard
+ * dependency for every consumer regardless of what they actually use: the import sits in the
+ * bundle, the bundler has to resolve it, and an application built on Mapbox that never installed
+ * `maplibre-gl` fails at build time with "Can't resolve 'maplibre-gl'" before a line of code runs.
+ * It failed even for applications that create their own map and hand it over with `attach()`, where
+ * the engine is never needed at all.
+ *
+ * So the engine is handed to the adapter rather than imported: through `options`, or from the global
+ * a CDN script tag leaves on `window`.
+ */
+export declare type MapEngineGlobal = 'maplibregl' | 'mapboxgl';
+
 export declare class MapEngineNotInitializedError extends OFSError {
     constructor(message?: string);
 }
@@ -2220,6 +2386,13 @@ export declare interface MapImage {
 
 export declare class MapLibreAdapter extends BaseGLAdapter {
     readonly engineName: "maplibre";
+    /**
+     * Build a map in `container`.
+     *
+     * `maplibre-gl` is not imported by this package - see `resolve-engine.ts` for why - so pass the
+     * library in as `options.maplibregl`, or load it from a script tag. An application that creates
+     * its own map does not come through here at all; it calls `attach()`.
+     */
     init(container: HTMLElement | string, options?: Record<string, any>): Promise<void>;
 }
 
@@ -2608,6 +2781,14 @@ export declare interface OfsCurveMeta {
 
 export declare class OFSDataSource extends TypedEventEmitter<OFSDataSourceEvents> {
     private layers;
+    /**
+     * Tile layers are kept apart from feature layers on purpose. Everything that reads
+     * `getAllLayers()` - snapping, topology, export, the attribute table, the AI context - wants
+     * features, and a tile layer has none to give. Mixing them into that list would mean auditing
+     * every one of those callers for a case that can only ever be "skip this". `getDisplayLayers()`
+     * brings the two back together for the things that do treat them alike: the legend and the stack.
+     */
+    private tileLayers;
     private groups;
     private activeLayerId;
     private selectionStore;
@@ -2635,6 +2816,7 @@ export declare class OFSDataSource extends TypedEventEmitter<OFSDataSourceEvents
      * Remove a layer by ID
      */
     removeLayer(layerId: string): boolean;
+    private detachLayer;
     /**
      * Get layer by ID
      */
@@ -2648,7 +2830,36 @@ export declare class OFSDataSource extends TypedEventEmitter<OFSDataSourceEvents
      */
     getAllLayers(): OFSLayerData[];
     /**
-     * Set layer visibility
+     * Add a raster or vector tile layer.
+     *
+     * ```ts
+     * ds.addTileLayer({ id: 'ortho', name: 'Aerial', kind: 'raster',
+     *   tiles: ['https://tiles.example/{z}/{x}/{y}.png'], tileSize: 256, zIndex: -1 });
+     * ```
+     *
+     * A vector tile set also needs `styles`, naming which layer inside the tile to draw and how; a
+     * vector tile carries no styling of its own, so there is nothing to fall back on.
+     */
+    addTileLayer(metadata: TileLayerMetadata): OFSTileLayer;
+    getTileLayer(layerId: string): OFSTileLayer | undefined;
+    /** Tile layers, lowest in the stack first */
+    getTileLayers(): OFSTileLayer[];
+    removeTileLayer(layerId: string): boolean;
+    /** Replace the drawing instructions of a vector tile layer */
+    setTileLayerStyles(layerId: string, styles: OFSTileLayer['styles']): void;
+    /**
+     * Every layer that appears on the map, tile and feature alike, lowest first.
+     *
+     * This is what the legend lists and what decides the drawing order, so a raster basemap at
+     * zIndex -1 sits under the parcels without either side knowing about the other.
+     */
+    getDisplayLayers(): (OFSLayerData | OFSTileLayer)[];
+    /** A layer of either kind, for the settings the two have in common */
+    private findAnyLayer;
+    /** Tell the right listeners that a layer changed, whichever kind it is */
+    private emitLayerChanged;
+    /**
+     * Set layer visibility. Works on tile layers too, so one legend toggle drives both kinds.
      */
     setLayerVisibility(layerId: string, visible: boolean): void;
     /**
@@ -2691,7 +2902,7 @@ export declare class OFSDataSource extends TypedEventEmitter<OFSDataSourceEvents
     moveLayerToGroup(layerId: string, groupId: string | null): void;
     /** True when the layer is inside the group, directly or through sub-groups */
     isLayerInGroup(layerId: string, groupId: string): boolean;
-    /** A layer is drawn when it and all of its parent groups are visible */
+    /** A layer of either kind is drawn when it and all of its parent groups are visible */
     isLayerRendered(layerId: string): boolean;
     setActiveLayer(layerId: string | null): void;
     getActiveLayerId(): string | null;
@@ -2810,12 +3021,27 @@ export declare interface OFSDataSourceEvents {
     'layer:added': {
         layer: OFSLayerData;
     };
+    /**
+     * `replaced` is true when the layer went because `addLayer` was given its id again: the same layer
+     * is coming straight back with new data, so whatever is kept per layer (its styling, say) should
+     * stay. False when it was removed for good.
+     */
     'layer:removed': {
         layerId: string;
+        replaced: boolean;
     };
     'layer:updated': {
         layer: OFSLayerData;
     };
+    'tile-layer:added': {
+        layer: OFSTileLayer;
+    };
+    'tile-layer:removed': {
+        layerId: string;
+    };
+    'tile-layer:updated': {
+        layer: OFSTileLayer;
+    };
     'feature:added': {
         layerId: string;
         feature: Feature<Geometry, any>;
@@ -3465,7 +3691,25 @@ export declare interface OFSFeatureMetadata {
 
 export declare class OFSFileIO {
     private dataSource;
-    constructor(dataSource: OFSDataSource);
+    private thematicEngine?;
+    /**
+     * `thematicEngine` is only needed for projects, which carry the styling of each layer. File
+     * import and export never touch it, so it stays optional and `saveProject` says so if it is
+     * missing rather than silently writing a project with no symbology in it.
+     */
+    constructor(dataSource: OFSDataSource, thematicEngine?: OFSThematicEngine | undefined);
+    /** Attach the styling engine after construction, when the two are built in that order */
+    useThematicEngine(engine: OFSThematicEngine): void;
+    private requireThemes;
+    /**
+     * Write the whole map out as a project: the layers and their data, the tile layers, the groups,
+     * the styling and the drawing order. See `project.ts`.
+     */
+    saveProject(options?: SaveProjectOptions): OFSProjectFile;
+    /** Read a project back onto the map, from an object or from the text of a `.ofsproj` file */
+    loadProject(project: OFSProjectFile | string, options?: LoadProjectOptions): LoadProjectResult;
+    /** A project as a file ready to be downloaded or written to disk */
+    exportProject(name?: string, options?: SaveProjectOptions): ExportedFile;
     /** Parse and add files as new layers */
     import(files: InputFile[], options?: ImportOptions): ImportToDataSourceResult;
     /** Browser File objects (from <input type="file"> or drag & drop) */
@@ -3580,6 +3824,11 @@ export declare class OFSLayerData {
     sourceCrs?: string;
     sourceFile?: string;
     fields?: LayerMetadata['fields'];
+    /**
+     * The colour the layer was added with, if one was given. This is the starting point only: once
+     * the layer is on the map its colour lives in its theme, and restyling it does not update this.
+     */
+    readonly color?: string;
     private featuresMap;
     private spatialIndex;
     private indexItems;
@@ -3795,6 +4044,8 @@ export declare class OFSObject {
     private dynamicInput;
     /** Map handed over by the host application (config.map), attached on init() */
     private readonly hostMap;
+    /** Defaults for the map init() builds; the engine itself is usually passed here */
+    private readonly mapOptions;
     constructor(config?: OFSObjectConfig);
     /**
      * Initialize map adapter and bind data source.
@@ -3816,12 +4067,29 @@ export declare class OFSObject {
     /**
      * Clean up all resources
      */
+    /**
+     * Save the whole map as a project: layers and their data, tile layers, groups, styling, drawing
+     * order, and where the map is looking. `ofs.io.saveProject()` does the same without the view.
+     */
+    saveProject(options?: SaveProjectOptions): OFSProjectFile;
+    /** Reopen a saved project, and move the map back to where it was looking */
+    loadProject(project: OFSProjectFile | string, options?: LoadProjectOptions): LoadProjectResult;
+    /** Where the map is looking, or undefined before there is a map to ask */
+    private currentView;
     destroy(): void;
 }
 
 export declare interface OFSObjectConfig {
     mapAdapter?: IMapAdapter;
     container?: HTMLElement | string;
+    /**
+     * Options for the map `init()` builds, merged under the ones passed to `init()` itself.
+     *
+     * This is where the map engine goes. Neither `maplibre-gl` nor `mapbox-gl` is imported by this
+     * package, so that an application using one need not install the other, which means the library
+     * has to be handed in: `{ mapOptions: { maplibregl } }` after `import maplibregl from
+     * 'maplibre-gl'`. A map the host creates itself needs none of this - pass it as `map` below.
+     */
     mapOptions?: Record<string, any>;
     /**
      * A MapLibre / Mapbox map the host application created and keeps owning (Angular, React, Vue).
@@ -3839,6 +4107,23 @@ export declare interface OFSObjectConfig {
     console?: IOFSConsole;
 }
 
+export declare interface OFSProjectFile {
+    format: typeof PROJECT_FORMAT;
+    version: number;
+    savedAt: string;
+    /** False when the file describes the layers and their styling but carries no feature data */
+    includesFeatures: boolean;
+    activeLayerId: string | null;
+    groups: LayerGroup[];
+    layers: ProjectLayer[];
+    /** Tile layers are always small - a URL and some numbers - so they are always written in full */
+    tileLayers: TileLayerMetadata[];
+    themes: ThematicDefinition[];
+    view?: ProjectView;
+    /** Anything the host application wants to keep with the map */
+    extra?: Record<string, unknown>;
+}
+
 declare class OFSSelectionOverlay {
     private dataSource;
     private mapAdapter;
@@ -3909,7 +4194,34 @@ export declare class OFSSymbologyPanel {
 
 export declare class OFSThematicEngine extends TypedEventEmitter<ThematicEvents> {
     private themes;
-    constructor();
+    private readonly random;
+    private dataSource;
+    private unbindDataSource;
+    constructor(options?: ThematicEngineOptions);
+    /**
+     * Let the engine see the layers on the map.
+     *
+     * Without this it cannot know what colours are already in use, so every layer added without a
+     * colour comes out the same default blue. With it, such a layer gets a colour that stands apart
+     * from the others (see `pickLayerColor`), and a colour given in `addLayer({ color })` is applied.
+     *
+     * It also lets the engine forget the theme of a layer that is removed. An engine that is not bound
+     * cannot see removals, and keeps every theme until `removeTheme` is called.
+     *
+     * OFSObject, the map adapter and the legend all call this, so it rarely needs calling by hand.
+     * Binding the data source that is already bound does nothing.
+     */
+    bindDataSource(dataSource: OFSDataSource): void;
+    /**
+     * Give a new layer its theme as it is added rather than when it is first drawn. Colours are then
+     * chosen in the order layers arrive - not the order some view happens to render them - and they
+     * are in the theme from the start, so a project saved before the map has drawn still keeps them.
+     *
+     * When `addLayer` replaces a layer with the same id, the theme is still there. A colour passed to
+     * `addLayer` is explicit, so it wins; without one, the layer keeps the styling it had - refreshing
+     * a layer's data should not undo the way someone classified it.
+     */
+    private styleNewLayer;
     /**
      * Get current theme definition for a layer
      */
@@ -3969,6 +4281,17 @@ export declare class OFSThematicEngine extends TypedEventEmitter<ThematicEvents>
     private classList;
     private requireTheme;
     private defaultTheme;
+    /**
+     * Colour for a layer that has no theme yet: the one it was added with; otherwise, when the engine
+     * can see the map, one clear of the colours the other layers show; otherwise the default blue.
+     *
+     * Only layers still on the map count, which is why this walks the layers rather than the themes.
+     *
+     * Only simple (single-colour) layers count, too. A categorised or graduated layer is read by its
+     * legend - its colours stand for values, not for the layer - and a single ramp can take up most
+     * of the palette, which would leave every new layer with a leftover colour.
+     */
+    private defaultColorFor;
     /**
      * Theme of a layer, creating the default simple theme silently (no event) when it has none
      */
@@ -3979,6 +4302,38 @@ export declare class OFSThematicEngine extends TypedEventEmitter<ThematicEvents>
     compile(layer: OFSLayerData): CompiledLayerStyle;
 }
 
+export declare class OFSTileLayer {
+    readonly id: string;
+    readonly kind: TileLayerKind;
+    name: string;
+    zIndex: number;
+    visible: boolean;
+    opacity: number;
+    pinned: boolean;
+    tag?: string;
+    groupId?: string;
+    readonly tiles: string[];
+    readonly url?: string;
+    readonly tileSize: number;
+    readonly scheme: 'xyz' | 'tms';
+    readonly minzoom?: number;
+    readonly maxzoom?: number;
+    readonly bounds?: BoundingBox;
+    readonly attribution?: string;
+    styles: VectorTileStyle[];
+    readonly metadata: TileLayerMetadata;
+    constructor(metadata: TileLayerMetadata);
+    /** The source definition a GL map engine expects. Undefined keys are dropped, not sent as null. */
+    toSourceSpec(): Record<string, any>;
+    /**
+     * The GL layers to draw this tile set with, bottom first.
+     *
+     * Opacity is folded into the paint properties rather than applied to the layer as a whole,
+     * because GL styles have no layer-wide opacity: each type names its own.
+     */
+    toLayerSpecs(): Record<string, any>[];
+}
+
 export declare class OFSTopologyPanel {
     private readonly dataSource;
     private readonly topology;
@@ -4265,6 +4620,9 @@ export declare function parseLngLat(raw: string): Coordinate | null;
 /** Parse a number, or null when the text is not a finite number */
 export declare function parseNumber(text: string): number | null;
 
+/** Parse a project from the text of a `.ofsproj` file */
+export declare function parseProject(text: string): OFSProjectFile;
+
 export declare function parseWkb(bytes: Uint8Array, offset?: number): {
     geometry: Geometry;
     end: number;
@@ -4277,6 +4635,30 @@ export declare function parseXml(source: string): XmlElement;
 /** Boundary paths: polygon rings or line parts */
 export declare function pathsOf(geometry: Geometry): Position[][];
 
+/**
+ * A colour for a new layer that is clearly different from the layers already on the map.
+ *
+ * In order, it takes a random palette colour that is distinct from:
+ *   1. every layer on the map, visible or hidden;
+ *   2. every visible layer (it may match a hidden one);
+ * and when neither exists - more than about eleven layers - the colour furthest from the visible layers, out of the palette and a batch of random
+ * colours. It always returns a colour: a layer that looks like another is a nuisance, a layer that
+ * cannot be added is a failure.
+ */
+export declare function pickLayerColor(options?: PickLayerColorOptions): string;
+
+export declare interface PickLayerColorOptions {
+    /** Colours of the layers currently shown. The new colour keeps clear of these first. */
+    visible?: readonly string[];
+    /**
+     * Colours of layers that are loaded but hidden. Avoided as well while that is possible - a hidden
+     * layer is one click from being shown - but given up before the visible ones are.
+     */
+    hidden?: readonly string[];
+    /** Source of randomness in [0, 1); pass a seeded one to make the choice reproducible */
+    random?: () => number;
+}
+
 export declare interface PlanarArc {
     center: PlanarPoint;
     radius: number;
@@ -4346,9 +4728,27 @@ export declare function printImportResult(consoleService: IOFSConsole, result: I
 /** Print an import / export report: summary lines, then issues grouped by code */
 export declare function printIssues(consoleService: IOFSConsole, issues: ImportIssue[], limit?: number): void;
 
+export declare const PROJECT_FORMAT = "ofs-project";
+
+export declare const PROJECT_VERSION = 1;
+
 /** Plane to do the arc maths on, centred on the curve so distances come out in ground meters */
 export declare function projectionForVertices(vertices: Coordinate[]): PlanarProjection;
 
+export declare interface ProjectLayer {
+    metadata: LayerMetadata;
+    /** Left out when the project was saved without feature data */
+    features?: Feature<Geometry, any>[];
+}
+
+/** Where the map was looking when the project was saved */
+export declare interface ProjectView {
+    center: Coordinate;
+    zoom: number;
+    bearing?: number;
+    pitch?: number;
+}
+
 export declare class PromptBuilder {
     /**
      * Summarize current map state for LLM prompt context.
@@ -4425,6 +4825,16 @@ export declare function renderSymbolSwatchSvg(symbol: SymbolStyle, geomType: Lay
 /** Report an error that was caught and recovered from */
 export declare function reportInternalError(scope: string, error: unknown): void;
 
+/** The engine to build a map with, or an error saying how to supply one */
+export declare function requireMapEngine(global: MapEngineGlobal, options?: Record<string, any>): any;
+
+/**
+ * Colours a layer must never be given, whatever else is on the map: the selection highlight (a
+ * yellow layer hides what is selected on it), the grey used for "all other values" in a categorised
+ * layer, and white and black, which vanish against light and dark basemaps.
+ */
+export declare const RESERVED_LAYER_COLORS: readonly string[];
+
 /**
  * Resolves all selected features across all layers in the dataset,
  * prioritizing active layer features first, followed by other layers,
@@ -4548,6 +4958,21 @@ export declare function runTopologyChecks(features: AnyFeature[], layer: {
     name?: string;
 }, options?: TopologyOptions): Generator<TopologyProgress, TopologyReport, void>;
 
+/** Write the current map out as a project */
+export declare function saveProject(dataSource: OFSDataSource, thematicEngine: OFSThematicEngine, options?: SaveProjectOptions): OFSProjectFile;
+
+export declare interface SaveProjectOptions {
+    /**
+     * Write the features into the file (default). Turning this off keeps the layers, their styling
+     * and their order but leaves the data out, for a project meant to be reconnected to a database
+     * or to files that live elsewhere - and for a project of 98,000 parcels, which is 60 MB of
+     * GeoJSON nobody wants in version control.
+     */
+    features?: boolean;
+    view?: ProjectView;
+    extra?: Record<string, unknown>;
+}
+
 export declare interface ScaleBarPlan {
     /** Ground distance the bar represents, in meters */
     meters: number;
@@ -5001,6 +5426,14 @@ export declare interface ThematicDefinition {
     label?: LabelSettings;
 }
 
+export declare interface ThematicEngineOptions {
+    /**
+     * Randomness behind the colours given to layers added without one, in [0, 1). Pass a seeded
+     * function to get the same colours every run (tests, screenshots, demos).
+     */
+    random?: () => number;
+}
+
 export declare interface ThematicEvents {
     'theme:changed': {
         layerId: string;
@@ -5023,6 +5456,40 @@ export declare interface ThematicEvents {
  */
 export declare type ThematicType = 'simple' | 'categorical' | 'graduated';
 
+export declare type TileLayerKind = 'raster' | 'vector';
+
+export declare interface TileLayerMetadata {
+    id: string;
+    name: string;
+    kind: TileLayerKind;
+    /**
+     * Tile URL templates with `{z}`, `{x}` and `{y}` placeholders. Several entries are read as
+     * mirrors of the same tile set, which is how a server spreads load across subdomains.
+     */
+    tiles?: string[];
+    /** A TileJSON document describing the tile set, as an alternative to `tiles` */
+    url?: string;
+    /** Raster tile edge in pixels; 512 for the retina tiles many providers serve */
+    tileSize?: number;
+    /** `tms` counts rows from the bottom, the opposite of the usual `xyz` */
+    scheme?: 'xyz' | 'tms';
+    minzoom?: number;
+    maxzoom?: number;
+    /** Area the tile set covers; outside it the map does not ask for tiles */
+    bounds?: BoundingBox;
+    /** Credit line the provider requires; map engines show it in the corner */
+    attribution?: string;
+    /** Required for `vector`, meaningless for `raster` */
+    styles?: VectorTileStyle[];
+    zIndex?: number;
+    visible?: boolean;
+    opacity?: number;
+    pinned?: boolean;
+    tag?: string;
+    groupId?: string;
+    [key: string]: unknown;
+}
+
 /** Split on whitespace, keeping "quoted text" together */
 export declare function tokenizeArgs(raw: string): string[];
 
@@ -5299,6 +5766,14 @@ export declare function validateFieldName(name: string, existing: FieldSchema[])
  */
 export declare function validateGeometry(geometry: Geometry | null | undefined, index: number, issues: ImportIssue[], ctx?: ValidationContext): Geometry | null;
 
+/**
+ * Check that a value really is a project this build can open, and say what is wrong when it is not.
+ *
+ * A file from a newer release is refused rather than half-read: reading the parts that happen to
+ * look familiar and quietly dropping the rest produces a map that looks plausible and is wrong.
+ */
+export declare function validateProject(value: unknown): OFSProjectFile;
+
 export declare interface ValidationContext {
     file?: string;
     closeRings?: boolean;
@@ -5306,6 +5781,27 @@ export declare interface ValidationContext {
     geographic?: boolean;
 }
 
+/**
+ * How one named layer inside a vector tile should be drawn.
+ *
+ * Vector tiles carry several layers ("roads", "buildings", "parcels") and no instructions for
+ * drawing any of them, so the caller says which to draw and how. Nothing is guessed: a tile set
+ * whose styling is left out renders nothing, which is a silent blank map, so it is refused instead.
+ */
+export declare interface VectorTileStyle {
+    /** Name of the layer inside the tile, as the tile server publishes it */
+    sourceLayer: string;
+    type: 'fill' | 'line' | 'circle' | 'symbol';
+    /** GL paint properties, passed through as given */
+    paint?: Record<string, any>;
+    layout?: Record<string, any>;
+    filter?: any[];
+    minzoom?: number;
+    maxzoom?: number;
+    /** Suffix for the GL layer id; needed when one source layer is drawn more than once */
+    id?: string;
+}
+
 export declare type WorkflowStatus = 'idle' | 'running' | 'waiting_input' | 'completed' | 'failed' | 'cancelled';
 
 /** Convert a world math angle (radians, CCW from East) to a user angle in the frame's convention [0, 360) */