@tileflow/dom 0.0.0-stage → 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,111 @@
-# Temporary Holding Version
+# @tileflow/dom
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Mount an interactive Tileflow map in any DOM element, without a framework. One function creates
+the map, loads its manifest and style, keeps its theme, colours, camera, annotations and
+interactions current, and takes everything down again. It draws nothing of its own around the map:
+marker, popup and tooltip views, loading and error states belong to your page.
+
+Use it for plain pages and web components. The React, Vue and Svelte packages are the easier way in
+those frameworks.
+
+> Related packages and guides: [documentation index](https://raw.githubusercontent.com/tileflow/tileflow-sdk/main/llms.txt).
+
+## Install
+
+Supported peers are MapLibre GL JS `>=6.4.1 <7`. The local build workflow below requires
+Node.js 22 or newer.
+
+```sh
+npm install @tileflow/dom@alpha @tileflow/core@alpha @tileflow/maps@alpha "maplibre-gl@^6.4.1"
+npm install --save-dev --save-exact tileflow@alpha
+```
+
+Build a map into `public/tileflow` with `npx tileflow build --out public/tileflow`, as the
+[React guide](https://github.com/tileflow/tileflow-sdk/blob/main/packages/react/README.md#prepare-a-map)
+shows.
+
+With Vite, the plugin from `@tileflow/vite` gives every map MapLibre's worker, in development and
+in production builds, so the application configures nothing. `tileflow()` prepares maps and adds
+the worker. When the CLI build or a hosted manifest provides the maps, add only the worker
+(`npm install --save-dev @tileflow/vite@alpha`):
+
+```ts
+import {defineConfig} from 'vite';
+import {tileflowMapLibreWorker} from '@tileflow/vite';
+
+export default defineConfig({plugins: [tileflowMapLibreWorker()]});
+```
+
+The worker comes from the same installed MapLibre as the map's main module.
+
+With another bundler, configure the worker once before the first map, with the URL at which the
+page serves `maplibre-gl/dist/maplibre-gl-worker.mjs`. An explicit configuration wins over the
+Vite plugin's:
+
+```ts
+import {configureTileflowMapLibre} from '@tileflow/dom';
+
+configureTileflowMapLibre({workerUrl: '/assets/maplibre-gl-worker.mjs'});
+```
+
+## Mount a map
+
+The container needs a size; the map fills it and follows its resizes.
+
+<!-- docs:check -->
+
+```ts
+import 'maplibre-gl/dist/maplibre-gl.css';
+import {createTileflowMap} from '@tileflow/dom';
+
+const container = document.querySelector<HTMLElement>('#map')!;
+const map = createTileflowMap(container, {
+  source: {map: 'madrid'},
+  theme: 'system',
+  annotations: [
+    {
+      ariaLabel: 'Prado Museum',
+      coordinate: [-3.6921, 40.4138],
+      id: 'prado',
+      kind: 'marker',
+      popup: {content: {kind: 'view', name: 'museum'}},
+    },
+  ],
+  views: {
+    popup(element, {close}) {
+      const button = document.createElement('button');
+      button.textContent = 'Close';
+      button.addEventListener('click', close);
+      element.append(button);
+    },
+  },
+  onError: ({code, error}) => console.warn(code, error),
+});
+
+await map.ready;
+map.setTheme('dark');
+map.setColors({water: 'var(--brand)'});
+map.destroy();
+```
+
+`createTileflowMap` returns at once. `ready` settles with the MapLibre map when it first loads.
+Each setter applies one option; `update` applies several and does no work for values that did not
+change, so an adapter can hand over all of its props on every render. The container carries
+`data-tileflow-state` (`loading`, `idle` or `error`) for capture, and `getStatus` with
+`onStatusChange` give the same readiness, the theme shown and interaction diagnostics to your own
+loading or error view.
+
+A view renderer fills the element it receives. It runs again on an emptied element when its context
+changes, unless it returns `update`; `destroy` runs when the view leaves the map. A marker view
+receives hover, focus and whether its popup is open in `state`.
+
+`mode: "image"` shows a static image of the map instead, without loading MapLibre; `ready` then
+settles with `null` once the image has loaded.
+
+See [REFERENCE.md](REFERENCE.md) for every option and controller method.
+
+## Next steps
+
+- [Show a popup on click](https://tileflow.dev/docs/examples/show-a-popup-on-click)
+- [Themes and tokens](https://tileflow.dev/docs/map-design/themes-and-tokens)
+- [Capture a map](https://github.com/tileflow/tileflow-sdk/blob/main/packages/capture/README.md)

package/REFERENCE.md

@@ -0,0 +1,80 @@
+# @tileflow/dom reference
+
+## `createTileflowMap(container, options, createOptions?)`
+
+Mounts a map in `container` and returns a controller at once. MapLibre loads lazily, after the
+manifest and style are ready. Throws a `TypeError` for an invalid `source`, `theme`, `timeOfDay`,
+`themeBlend` or `themeTransition`, and when both `views` and `renderTargets` are given.
+
+### Options
+
+Every option except `source` is optional and can change after mount through `update` or a setter.
+
+| Option                                           | Meaning                                                                                                   |
+| ------------------------------------------------ | --------------------------------------------------------------------------------------------------------- |
+| `source`                                         | `{map, manifestUrl?}`: the map by name, from the default manifest or `manifestUrl`.                       |
+| `theme`, `timeOfDay`                             | A concrete theme or `"system"`, which follows the page's colour scheme; an optional artistic preset.      |
+| `themeBlend`                                     | `{themes, position, hold?}`: a continuous blend of two to eight themes instead of `theme`.                |
+| `themeTransition`                                | `{duration}` in milliseconds, used for theme, blend, colour and emphasis changes.                         |
+| `colors`, `emphasis`                             | Colour token or knob overrides (CSS variables are read where the map sits); modules that recede.          |
+| `vegetation`, `viewMode`                         | 3D scene inputs; `viewMode` defaults to `"3d"`.                                                           |
+| `center`, `zoom`                                 | The view until `bounds` or `fitAnnotations` is given; a change moves the camera at once.                  |
+| `bounds`, `fitBoundsOptions`, `fitAnnotations`   | Bounds to show, how they are fitted, or a fit to all annotations. The first fit is immediate.             |
+| `interactive`, `navigationControl`               | Whether the map takes input; zoom and compass buttons, none unless asked.                                 |
+| `mapOptions`                                     | MapLibre options apart from `container` and `style`. A structurally different value recreates the map.    |
+| `analytics`                                      | Analytics fields merged with the style's own.                                                             |
+| `annotations`, `annotationClusters`              | Portable annotations and optional clustering.                                                             |
+| `dataSources`, `dataOverlays`                    | Application GeoJSON and the overlays drawn over it, keyed as in `defineMap`.                              |
+| `interactions`                                   | Semantic interaction bindings on map features.                                                            |
+| `interactionState` or `defaultInteractionState`  | The open popup, controlled or initial. Which of the two is used is fixed when the map is created.         |
+| `views`                                          | `{marker?, popup?, tooltip?}` renderers that fill a plain element.                                        |
+| `renderTargets`                                  | `{marker?, popup?, tooltip?, onChange}` for a framework that draws views itself; replaces `views`.        |
+| `onLoad`, `onError`, `onThemeChange`             | The loaded MapLibre map; `{code, error}` failures (`console.error` without a handler); theme transitions. |
+| `onInteractionEvent`, `onInteractionStateChange` | Pointer and popup events; requested popup state.                                                          |
+| `onInteractionDiagnostic`                        | Each distinct interaction diagnostic, once.                                                               |
+| `onStatusChange`                                 | Every change to the status `getStatus` returns.                                                           |
+| `mode`, `imageUrl`, `alt`, `imageLoading`        | `"image"` shows a static image instead of a map: `imageUrl`, or one the map's style resolves.             |
+| `image`                                          | In image mode, an `<img>` your page renders (or `null` until it does); otherwise the map adds its own.    |
+
+### Image mode
+
+With `mode: "image"` no MapLibre loads. The map shows `imageUrl`, or an image of the style at the
+view and container size, and is `idle` once that image has loaded and decoded. Annotations,
+interactions, interaction state, interaction callbacks and views are unavailable there and report
+`UNSUPPORTED_MODE`. A framework that renders on the server passes its own `<img>` as `image` and
+sets its `src` from `status.imageUrl`.
+
+### Create options
+
+Read once: `captureId` (written as `data-tileflow-capture-id`), `sessionSource` (names the
+integration in session analytics) and `statusElement` (the element that receives the capture
+attributes; the container unless given, none when `null`).
+
+### Views
+
+A renderer is `(element, context) => void | {update?, destroy?}`. It runs when the view appears,
+and again on an emptied element when its context changes, unless it returned `update`. `destroy`
+runs when the view leaves the map. A marker context has `state: {hovered, focused, selected}`;
+popup and tooltip contexts belong to an annotation or to a map feature and carry `close`. A kind
+with no renderer keeps the default view.
+
+## Controller
+
+| Member                                                   | Meaning                                                                                                                                            |
+| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ready`                                                  | Settles with the MapLibre map on its first load (`null` once an image shows); rejects when it cannot start or is destroyed first.                  |
+| `update(options)`                                        | Applies changed options; left-out keys keep their value, `undefined` clears one.                                                                   |
+| `setTheme`, `setThemeBlend`, `setColors`, `setEmphasis`  | One option each.                                                                                                                                   |
+| `setView({center, zoom})`, `setBounds(bounds, options?)` | Camera options.                                                                                                                                    |
+| `setAnnotations`, `setInteractions`, `setViews`          | Content options.                                                                                                                                   |
+| `setInteractionState(state)`                             | Opens or closes a popup; on a controlled map the same as passing `interactionState`.                                                               |
+| `getStatus()`                                            | `{readiness, theme, diagnostics, imageUrl}`: `loading`, `idle` or `error`, the theme shown, interaction diagnostics and, in image mode, the image. |
+| `getMap()`, `getThemeController()`                       | The MapLibre map and theme controller, `null` until the map exists and after it is taken down.                                                     |
+| `getInteractionState()`, `getRenderTargets()`            | The open popup; the view elements the map handed out.                                                                                              |
+| `destroy()`                                              | Takes the map down, removes the capture attributes and stops every listener. Later calls do nothing.                                               |
+
+## `getTileflowMapInitialStatus(options, controlledInteractionState?)`
+
+The status a map with these options has before it mounts: its declarative diagnostics, `error` or
+`loading`, the theme it names and, in image mode, `imageUrl`. It touches no DOM, so a framework can
+render capture attributes on the server and before the controller exists.

package/dist/index.d.ts

@@ -0,0 +1,198 @@
+import * as maplibre_gl from 'maplibre-gl';
+import { Map, MapOptions } from 'maplibre-gl';
+import { TileflowMapLibreOverlay, TileflowGeoJsonSource } from '@tileflow/core';
+import { TileflowThemeController, TileflowBounds, TileflowFitBoundsOptions, TileflowColorOverrides, TileflowEmphasis, TileflowBrowserThemeBlendSelection, TileflowThemeTransitionOptions, TileflowViewMode, TileflowNavigationControlInput, TileflowMapError, TileflowThemeTransition } from '@tileflow/core/browser';
+import { TileflowThemeSelection, TileflowRuntimeSource, TileflowTimeOfDay, TileflowAnalytics } from '@tileflow/core/runtime';
+import { TileflowAnnotation, TileflowAnnotationViewContext, TileflowInteractionViewContext, TileflowInteractionState, TileflowInteractionDiagnostic, TileflowInteractionBinding, TileflowInteractionEvent } from '@tileflow/interactions';
+import { TileflowMapLibreDomRenderTarget, TileflowMapLibreSemanticDomRenderTarget, TileflowAnnotationClusterOptions } from '@tileflow/interactions/maplibre';
+
+/**
+ * What a view renderer may return: `update` receives the next context instead of the view being
+ * rendered again from an empty element, and `destroy` runs when the view leaves the map.
+ */
+type TileflowMapViewInstance<TContext> = Readonly<{
+    destroy?: () => void;
+    update?: (context: TContext) => void;
+}>;
+/**
+ * Fills `element` with a view. It runs when the view appears and again, on an emptied element,
+ * whenever its context changes, unless it returned an `update`.
+ */
+type TileflowMapViewRenderer<TContext> = (element: HTMLElement, context: TContext) => TileflowMapViewInstance<TContext> | void;
+/** Views drawn into marker, popup and tooltip elements. Each kind left out keeps the default view. */
+type TileflowMapViews<TAnnotation extends TileflowAnnotation = TileflowAnnotation> = Readonly<{
+    marker?: TileflowMapViewRenderer<TileflowAnnotationViewContext<TAnnotation>>;
+    popup?: TileflowMapViewRenderer<TileflowInteractionViewContext<TAnnotation>>;
+    tooltip?: TileflowMapViewRenderer<TileflowInteractionViewContext<TAnnotation>>;
+}>;
+type TileflowMapRenderTargetList<TAnnotation extends TileflowAnnotation> = Readonly<{
+    annotations: readonly TileflowMapLibreDomRenderTarget<TAnnotation>[];
+    semantic: readonly TileflowMapLibreSemanticDomRenderTarget[];
+}>;
+
+/** MapLibre options a map passes through, apart from the container and style it owns. */
+type TileflowMapLibreOptions = Omit<MapOptions, 'container' | 'style'>;
+type TileflowMapReadiness = 'error' | 'idle' | 'loading';
+/**
+ * Where the map stands, for capture and for an application's own loading or error view. The map
+ * draws nothing for it: `diagnostics` are for the application to show.
+ */
+type TileflowMapStatus = Readonly<{
+    /** Interaction problems: invalid annotations, interactions or state, and runtime failures. */
+    diagnostics: readonly TileflowInteractionDiagnostic[];
+    /** `idle` once the map, its theme and its views have settled; `error` when one cannot. */
+    readiness: TileflowMapReadiness;
+    /** The concrete theme shown, once it is known. */
+    theme: string | undefined;
+    /** In image mode, the image to show, once it is known. */
+    imageUrl: string | undefined;
+}>;
+/**
+ * For a framework that draws views itself, such as through portals: the map leaves the elements of
+ * the kinds marked `true` empty and hands every element to `onChange`.
+ */
+type TileflowMapRenderTargetsOptions<TAnnotation extends TileflowAnnotation> = Readonly<{
+    marker?: boolean;
+    onChange: (targets: TileflowMapRenderTargetList<TAnnotation>) => void;
+    popup?: boolean;
+    tooltip?: boolean;
+}>;
+type TileflowMapInteractionStateOptions = Readonly<{
+    defaultInteractionState?: never;
+    interactionState?: TileflowInteractionState;
+}> | Readonly<{
+    defaultInteractionState?: TileflowInteractionState;
+    interactionState?: never;
+}>;
+type TileflowMapControllerOptions<TAnnotation extends TileflowAnnotation = TileflowAnnotation> = TileflowMapInteractionStateOptions & {
+    /** The map to show, by name, from the manifest at `manifestUrl` or the default one. */
+    source: TileflowRuntimeSource;
+    /**
+     * `image` shows a static image of the map instead of MapLibre: `imageUrl`, or one the map's
+     * static renderer makes for the container's size, `center`, `zoom` and theme.
+     */
+    mode?: 'image' | 'interactive';
+    imageUrl?: string;
+    /** The image's alternative text; empty unless given. */
+    alt?: string;
+    /** How the browser loads the image; `eager` unless given. */
+    imageLoading?: 'eager' | 'lazy';
+    /**
+     * The `<img>` a framework renders itself (with `imageUrl` from the status), so the image can be
+     * rendered on the server. Without it, the map adds its own image to the container.
+     */
+    image?: HTMLImageElement | null;
+    theme?: TileflowThemeSelection;
+    /** Optional artistic preset; ignored by maps without this capability. */
+    timeOfDay?: TileflowTimeOfDay;
+    /** Shows a continuous blend of the map's themes instead of `theme`. */
+    themeBlend?: TileflowBrowserThemeBlendSelection;
+    /** Cross-fades theme, blend, colour and emphasis changes. */
+    themeTransition?: TileflowThemeTransitionOptions;
+    /** Colour token or knob overrides, which may use CSS variables read where the map sits. */
+    colors?: TileflowColorOverrides;
+    /** Makes chosen modules of the map recede so the application's content reads first. */
+    emphasis?: TileflowEmphasis;
+    vegetation?: boolean;
+    viewMode?: TileflowViewMode;
+    center?: [number, number];
+    zoom?: number;
+    /** Shows these bounds; `center` and `zoom` set the view only until bounds are given. */
+    bounds?: TileflowBounds;
+    /** Fits the map to all annotations, and again whenever their positions change. */
+    fitAnnotations?: boolean | TileflowFitBoundsOptions;
+    fitBoundsOptions?: TileflowFitBoundsOptions;
+    interactive?: boolean;
+    /** Zoom and compass buttons; none unless asked. */
+    navigationControl?: TileflowNavigationControlInput;
+    mapOptions?: TileflowMapLibreOptions;
+    analytics?: TileflowAnalytics;
+    /** Group `annotations` into accessible cluster buttons. Up to 1,000 annotations. */
+    annotationClusters?: TileflowAnnotationClusterOptions;
+    annotations?: readonly TAnnotation[];
+    dataOverlays?: Readonly<Record<string, TileflowMapLibreOverlay>>;
+    dataSources?: Readonly<Record<string, TileflowGeoJsonSource>>;
+    interactions?: readonly TileflowInteractionBinding[];
+    /** Views drawn into marker, popup and tooltip elements. */
+    views?: TileflowMapViews<TAnnotation>;
+    /** Hands view elements to a framework that draws them; replaces `views`. */
+    renderTargets?: TileflowMapRenderTargetsOptions<TAnnotation>;
+    onError?: (event: TileflowMapError) => void;
+    onLoad?: (map: Map) => void;
+    onThemeChange?: (transition: TileflowThemeTransition) => void;
+    onInteractionDiagnostic?: (diagnostic: TileflowInteractionDiagnostic) => void;
+    onInteractionEvent?: (event: TileflowInteractionEvent<TAnnotation>) => void;
+    onInteractionStateChange?: (state: TileflowInteractionState) => void;
+    onStatusChange?: (status: TileflowMapStatus) => void;
+};
+/** Options read once, when the map is created. */
+type TileflowMapCreateOptions = Readonly<{
+    /** Names the map in deterministic capture, as `data-tileflow-capture-id`. */
+    captureId?: string;
+    /** Names the integration in session analytics; adapters pass their framework. */
+    sessionSource?: string;
+    /**
+     * Receives `data-tileflow-map`, `data-tileflow-theme`, `data-tileflow-state` and
+     * `data-tileflow-capture-id`; the container unless given, none when `null`.
+     */
+    statusElement?: HTMLElement | null;
+}>;
+type TileflowMapController<TAnnotation extends TileflowAnnotation = TileflowAnnotation> = Readonly<{
+    container: HTMLElement;
+    /**
+     * Settles with the MapLibre map when it first loads, or with `null` once an image-mode map has
+     * shown its image; rejects when it cannot start or when the controller is destroyed first.
+     */
+    ready: Promise<Map | null>;
+    /** Takes the map down, empties what it added to the container, and stops every listener. */
+    destroy(): void;
+    getInteractionState(): TileflowInteractionState;
+    /** The MapLibre map, or `null` before it is created and after it is taken down. */
+    getMap(): Map | null;
+    getRenderTargets(): TileflowMapRenderTargetList<TAnnotation>;
+    getStatus(): TileflowMapStatus;
+    /** Changes theme, colours and emphasis; `null` until the map exists or when it has no themes. */
+    getThemeController(): TileflowThemeController | null;
+    setAnnotations(annotations: readonly TAnnotation[] | undefined): void;
+    setBounds(bounds: TileflowBounds | undefined, options?: TileflowFitBoundsOptions): void;
+    setColors(colors: TileflowColorOverrides | undefined): void;
+    setEmphasis(emphasis: TileflowEmphasis | undefined): void;
+    setInteractions(interactions: readonly TileflowInteractionBinding[] | undefined): void;
+    /** Opens or closes a popup; on a controlled map it is the same as passing `interactionState`. */
+    setInteractionState(state: TileflowInteractionState): void;
+    setTheme(theme: TileflowThemeSelection | undefined): void;
+    setThemeBlend(themeBlend: TileflowBrowserThemeBlendSelection | undefined): void;
+    setView(view: Readonly<{
+        center?: [number, number];
+        zoom?: number;
+    }>): void;
+    setViews(views: TileflowMapViews<TAnnotation> | undefined): void;
+    /**
+     * Applies changed options. Keys left out keep their value; a key given as `undefined` clears it.
+     * Unchanged values do no work, so an adapter can pass all of its props on every render.
+     */
+    update(options: Partial<TileflowMapControllerOptions<TAnnotation>>): void;
+}>;
+/**
+ * Mounts a Tileflow map in `container` and returns its controller. The container should have a
+ * size; the map fills it and follows its resizes. Nothing is drawn around the map: loading,
+ * error and diagnostic views belong to the application, from `getStatus` and `onStatusChange`.
+ */
+declare function createTileflowMap<TAnnotation extends TileflowAnnotation = TileflowAnnotation>(container: HTMLElement, initialOptions: TileflowMapControllerOptions<TAnnotation>, createOptions?: TileflowMapCreateOptions): TileflowMapController<TAnnotation>;
+/**
+ * The status a map with these options has before it mounts: for server rendering and a framework's
+ * first render, so the page shows the same theme, diagnostics and image before and after mount.
+ * `controlledInteractionOwnership` is whether the map started with `interactionState`.
+ */
+declare function getTileflowMapInitialStatus<TAnnotation extends TileflowAnnotation = TileflowAnnotation>(options: TileflowMapControllerOptions<TAnnotation>, controlledInteractionOwnership?: boolean): TileflowMapStatus;
+
+type TileflowMapLibre = typeof maplibre_gl;
+type TileflowMapLibreConfiguration = Readonly<{
+    workerUrl: string;
+}>;
+/** Configure the application-owned worker before mounting an interactive Tileflow map. */
+declare function configureTileflowMapLibre(configuration: TileflowMapLibreConfiguration): void;
+/** Load the interactive renderer only after a browser map requests it. */
+declare function loadTileflowMapLibre(): Promise<TileflowMapLibre>;
+
+export { type TileflowMapController, type TileflowMapControllerOptions, type TileflowMapCreateOptions, type TileflowMapLibre, type TileflowMapLibreConfiguration, type TileflowMapLibreOptions, type TileflowMapReadiness, type TileflowMapRenderTargetList, type TileflowMapRenderTargetsOptions, type TileflowMapStatus, type TileflowMapViewInstance, type TileflowMapViewRenderer, type TileflowMapViews, configureTileflowMapLibre, createTileflowMap, getTileflowMapInitialStatus, loadTileflowMapLibre };