@tileflow/svelte 0.1.0-alpha.23 → 0.1.0-alpha.25

package/README.md

@@ -1,211 +1,199 @@
 # @tileflow/svelte
 
-Svelte component for rendering Tileflow maps with MapLibre.
+Svelte components for interactive Tileflow maps, annotations, and existing-image display.
+The component consumes prepared assets; it does not compile executable map configuration in the
+browser.
 
-Install `maplibre-gl` alongside the package and import its CSS once in your app.
+> Related packages and guides: [documentation index](https://raw.githubusercontent.com/tileflow/tileflow-sdk/main/llms.txt).
 
-```svelte
-<script lang="ts">
-  import {TileflowMap} from '@tileflow/svelte';
-  import 'maplibre-gl/dist/maplibre-gl.css';
-</script>
+## Install
 
-<TileflowMap
-  source={{kind: 'tileflow', map: 'madrid'}}
-  theme="system"
-  center={[-3.7038, 40.4168]}
-  zoom={12}
-  mapOptions={{
-    cooperativeGestures: true,
-    maxZoom: 18,
-  }}
-/>
+Use an existing Svelte 5 application. Supported peers are Svelte `>=5 <6` and MapLibre GL JS
+`>=6.4.1 <7`. The local build workflow below requires Node.js 22 or newer.
+
+```sh
+npm install @tileflow/svelte@alpha @tileflow/core@alpha @tileflow/maps@alpha "maplibre-gl@^6.4.1"
+npm install --save-dev --save-exact tileflow@alpha
 ```
 
-## MapLibre 6 worker
+## Prepare a map
 
-With MapLibre GL JS 6, configure the application-owned worker once before mounting an interactive
-map. The worker URL must come from the same `maplibre-gl` package installed by the application.
+Create `tileflow.config.ts` at the application root:
+
+<!-- docs:check -->
 
 ```ts
-// main.ts
-import workerUrl from 'maplibre-gl/dist/maplibre-gl-worker.mjs?worker&url';
-import {configureTileflowMapLibre} from '@tileflow/svelte';
+import {defineMap} from '@tileflow/core';
+import {streets} from '@tileflow/maps';
+
+export default defineMap({
+  id: 'madrid',
+  version: 1,
+  extends: streets,
+  view: {center: [-3.7038, 40.4168], zoom: 12},
+});
+```
 
-configureTileflowMapLibre({workerUrl});
+For a Vite application serving `public/` at the URL root:
+
+```sh
+npx tileflow build --out public/tileflow
 ```
 
-This is the Vite setup. Run it before `mount(...)`; `mode="image"` remains MapLibre-free. MapLibre
-GL JS 6.4.1-6.x is supported. Use the `@tileflow/next` or `@tileflow/webpack` README for their
-worker-delivery recipes.
+SvelteKit serves static files from `static/` by default; for that setup, build to `static/tileflow`
+instead. Set the component's manifest URL to the final public URL when a base path changes it.
+Rebuild after config/asset changes or use the
+[Vite integration](https://github.com/tileflow/tileflow-sdk/blob/main/packages/vite/README.md)
+for watched development and production output. Local preparation needs no API key; rendering can
+still fetch configured remote resources.
+
+## Configure the worker
 
-`mapOptions` accepts native MapLibre options except `container` and `style`, which
-Tileflow resolves from `source`. Direct
-Tileflow props such as `center`, `zoom`, and `interactive` take priority when
-provided. Camera resolution is the same in interactive and image modes: direct props, then
-`mapOptions`, then the published manifest view, then Tileflow's shared runtime defaults.
+In a Vite client entry, add the following before mounting the application:
+
+```ts
+import workerUrl from 'maplibre-gl/dist/maplibre-gl-worker.mjs?worker&url';
+import {configureTileflowMapLibre} from '@tileflow/svelte';
 
-Every map has exactly one discriminated `source`. Use `kind: 'tileflow'` with `map` and an optional
-`manifestUrl` for published delivery. `kind: 'maplibre'` is an unmanaged escape hatch for one direct
-style object or URL; it has no Tileflow theme identity, `system` selection, switching, or manifest
-traceability. Browser components do not compile `tileflow.config.ts`.
+configureTileflowMapLibre({workerUrl});
+```
 
-Without `manifestUrl`, the exact default is `/tileflow/manifest.json`. If a bundler, framework base
-path, reverse proxy, or Tileflow plugin publishes it elsewhere, set the final public URL explicitly;
-the component does not guess it. Manifest 404s, unknown map IDs, unresolved styles, and unresolved
-image URLs enter `data-tileflow-state="error"`.
+Configure once before an interactive map mounts. In SvelteKit, place client-only setup in the
+application's client initialization path rather than running browser setup in a server load
+function. The `?worker&url` syntax is Vite-specific. Webpack users need the
+[Webpack worker recipe](https://github.com/tileflow/tileflow-sdk/blob/main/packages/webpack/README.md).
+The worker and shared module must match the application's installed MapLibre version.
 
-`theme` selects a published theme name. Omission uses `defaultTheme`; `"system"` requires the map's
-explicit light/dark mapping. Switching preserves the MapLibre instance, camera, and interactions,
-and rolls back a failed style. `onThemeChange` receives transition state.
+## Render a map
 
 ```svelte
-<TileflowMap
-  source={{
-    kind: 'tileflow',
-    map: 'madrid',
-    manifestUrl: 'https://cdn.example.com/tileflow/manifest.json',
-  }}
-/>
+<script lang="ts">
+  import 'maplibre-gl/dist/maplibre-gl.css';
+  import {TileflowMap} from '@tileflow/svelte';
+</script>
 
 <TileflowMap
-  source={{
-    kind: 'maplibre',
-    style: 'https://cdn.example.com/tileflow/styles/madrid/dark.json',
-  }}
+  source={{map: 'madrid'}}
+  theme="system"
+  center={[-3.7038, 40.4168]}
+  zoom={12}
+  mapOptions={{cooperativeGestures: true, maxZoom: 18}}
 />
 ```
 
-`mode="image"` resolves an explicit or published image URL and renders an `<img>` without loading
-or evaluating MapLibre. All environments follow the same published manifest contract.
+Coordinates are `[longitude, latitude]`. `source` is one object, `{map, manifestUrl?}`.
+`source.map` matches the config's portable ID, not a hosted `map_...` identifier. The default
+manifest URL is exactly `/tileflow/manifest.json`. Set `source.manifestUrl` for a subpath or external
+host; the browser does not infer bundler configuration.
+
+Omitting `theme` uses `defaultTheme`. `system` needs an explicit light/dark mapping, which Streets
+supplies. Theme changes keep the MapLibre instance, camera, and interactions, and roll back on
+failure. `onThemeChange` reports transitions.
+
+`mapOptions` accepts native MapLibre options except `container` and `style`. Direct props win over
+those options, then the manifest view, then shared defaults. `TileflowMap` always selects a Tileflow
+map through its manifest; it has no renderer discriminator or direct-style mode. The obsolete
+source fields `kind` and `style` are rejected. For a completely unmanaged map, use `maplibre-gl`
+directly rather than a Tileflow component.
 
-Hosted maps automatically preflight a short-lived commercial session grant before eligible
-resources. Setting `analytics={{enabled: false}}` disables the optional beacon only; it does not
-remove hosted authorization or override a user `mapOptions.transformRequest` callback.
-Use `analytics={{surfaceId: 'store-locator'}}` when the same Map is embedded in several stable
-product locations. Missing or invalid Surface IDs become `default`; do not use URLs, branches,
-random instance IDs, or user IDs.
-Direct Tileflow World maps keep early `GRACE` silent, show a compact accessible owner-action pill
-when late `GRACE` is activated, and show a stronger banner in `MANAGED_REQUIRED`. Missing tiles and
-MapLibre failures do not remove that recovery path.
+## Add annotations and native popup UI
 
-## Annotations and overlays
+Install the contract types used below:
 
-Use `annotations` for keyed markers with optional tooltips and popups. Tileflow supplies accessible,
-text-only defaults; Svelte snippets can replace any surface and are mounted into the DOM containers
-owned by the shared MapLibre interaction runtime.
+```sh
+npm install @tileflow/interactions@alpha
+```
+
+This Svelte 5 component uses the worker and CSS setup above:
 
 ```svelte
 <script lang="ts">
-  import {TileflowMap} from '@tileflow/svelte';
   import type {
     TileflowAnnotation,
-    TileflowInteractionBinding,
     TileflowInteractionState,
+    TileflowInteractionViewContext,
   } from '@tileflow/interactions';
+  import {TileflowMap} from '@tileflow/svelte';
 
-  const annotations: TileflowAnnotation[] = [
+  const annotations = [
     {
-      ariaLabel: 'Madrid',
-      coordinate: [-3.7038, 40.4168],
       id: 'madrid',
       kind: 'marker',
-      marker: {content: {kind: 'text', text: 'Madrid'}},
+      coordinate: [-3.7038, 40.4168],
+      ariaLabel: 'Madrid',
+      tooltip: {content: {kind: 'text', text: 'View Madrid'}},
       popup: {content: {kind: 'view', name: 'city-card'}},
-      tooltip: {content: {kind: 'text', text: 'Open Madrid'}},
-    },
-  ];
-
-  const interactions: TileflowInteractionBinding[] = [
-    {
-      id: 'poi-details',
-      popup: {content: {kind: 'view', name: 'poi-card'}},
-      target: {categories: ['food-drink'], domain: 'poi', kind: 'semantic-feature'},
-      tooltip: {content: {field: 'name', fallback: 'Restaurant', kind: 'field'}},
     },
-  ];
+  ] satisfies readonly TileflowAnnotation[];
 
-  let interactionState: TileflowInteractionState = {popup: null};
+  let state = $state<TileflowInteractionState>({popup: null});
 </script>
 
-{#snippet marker(context)}
-  <span>{context.annotation.ariaLabel}</span>
-{/snippet}
-
-{#snippet tooltip(context)}
+{#snippet popup(context: TileflowInteractionViewContext)}
   {#if context.target.kind === 'annotation'}
-    <span>{context.target.annotation.ariaLabel}</span>
-  {:else}
-    <span>Point of interest</span>
-  {/if}
-{/snippet}
-
-{#snippet popup(context)}
-  <article>
-    {#if context.target.kind === 'annotation'}
+    <article>
       <h2>{context.target.annotation.ariaLabel}</h2>
-    {:else if context.target.kind === 'semantic-feature'}
-      <h2>POI details</h2>
-    {/if}
-    <button type="button" onclick={context.close}>Close</button>
-  </article>
+      <button type="button" onclick={context.close}>Close</button>
+    </article>
+  {/if}
 {/snippet}
 
 <TileflowMap
-  source={{kind: 'tileflow', map: 'madrid'}}
+  source={{map: 'madrid'}}
   {annotations}
-  {interactions}
-  {interactionState}
-  onInteractionStateChange={(next) => (interactionState = next)}
-  onInteractionEvent={(event) => console.log(event.type)}
-  onInteractionDiagnostic={(diagnostic) => console.error(diagnostic)}
-  {marker}
-  {tooltip}
+  interactionState={state}
+  onInteractionStateChange={(next) => (state = next)}
+  onInteractionDiagnostic={(diagnostic) => console.error(diagnostic.code)}
   {popup}
 />
 ```
 
-`annotations` is the only application-owned marker input. Controlled `interactionState` and
-uncontrolled `defaultInteractionState` are mutually exclusive. `interactions` binds tooltips and
-popups to semantic POIs exposed by the compiled style metadata; applications select the stable
-`poi` domain and optional categories rather than physical style-layer IDs.
+Annotations need a stable `id`, singular `coordinate`, and non-empty `ariaLabel`; optional data must
+be JSON-safe. `marker` receives annotation-only context. `tooltip` and `popup` receive the shared
+interaction context; narrow `target.kind` before reading annotation or semantic feature data.
 
-Snippet callbacks are read at the time an interaction occurs, and adding or removing a snippet
-switches between custom and default rendering without recreating the map or its keyed markers.
-`marker` receives the annotation-only context. `tooltip` and `popup` receive the general interaction
-context and therefore handle both annotation and semantic-feature targets. Each context includes
-resolved content, the target, optional view name, and `close()`.
+Use `interactions` with `target: {kind: 'semantic-feature', domain: 'poi'}` for POIs already rendered
+by the style. Optional categories use Tileflow's taxonomy, such as `food-drink` or `retail`, not raw
+source classes. Semantic bindings require compatible style metadata and avoid one DOM marker per
+feature. Annotation and semantic overlays share one popup state.
 
-Both runtimes are controlled by one interaction-state coordinator. Replacing an annotation popup
-with a POI popup (or the reverse) closes the previous owner before opening the next one, so event
-order remains `popup:close` followed by `popup:open`.
+Controlled `interactionState` and uncontrolled `defaultInteractionState` are mutually exclusive.
+Do not change ownership during the component's lifetime. Updating annotations, bindings, state, or
+snippets reconciles existing runtimes rather than recreating MapLibre.
 
-Annotations and semantic interactions are interactive-only. The TypeScript API excludes
-annotations, interactions, interaction state, snippets, and interaction callbacks from the
-`mode="image"` branch. Untyped JavaScript that supplies them still receives an
-`UNSUPPORTED_MODE` diagnostic and capture readiness `error`, rather than pretending the static image
-contains live overlays.
+Text/field descriptors render as text. A `view` names an application snippet; it is not serialized
+HTML. Keep tooltips non-interactive and put buttons, links, and forms in popups.
 
-## Headless capture readiness
+## Display an existing image
 
-Use `captureId` to disambiguate repeated named maps:
+`mode="image"` displays an explicit `imageUrl` or derives an image URL from the selected manifest
+map's `mapId`, `apiUrl`, concrete theme and view, without loading MapLibre. It still requires a valid
+Tileflow source. A local style build does not generate that image. This mode does not submit or poll
+a Static Maps operation; use the server-side
+[Static Maps client](https://github.com/tileflow/tileflow-sdk/blob/main/packages/static/README.md)
+for new renders, keeping privileged credentials off the browser.
 
-```svelte
-<TileflowMap source={{kind: 'tileflow', map: 'madrid'}} captureId="checkout-map" />
-```
+Annotations, semantic bindings, interaction state, and interaction snippets are interactive-only.
+Untyped callers that pass them to image mode receive `UNSUPPORTED_MODE` and capture readiness
+`error`, not simulated live overlays.
+
+## Capture, authorization, and troubleshooting
 
-The root exposes `data-tileflow-map`, optional `data-tileflow-capture-id`, and
-`data-tileflow-state="loading|idle|error"`. It becomes idle only after MapLibre idle plus two
-animation frames and, for custom interaction snippets, the Svelte DOM commit plus two current
-animation frames. It returns to loading when either surface changes and marks map or interaction
-errors. In image mode, readiness follows image decode/load when no interaction configuration is
-present. Application capture selects exactly one ready target.
+Use `captureId` to disambiguate repeated maps. The root exposes `data-tileflow-map`, resolved
+`data-tileflow-theme`, optional `data-tileflow-capture-id`, and
+`data-tileflow-state="loading|idle|error"`. Readiness includes MapLibre/image loading and committed
+Svelte interaction views. Application capture needs exactly one ready target and the application's
+normal loopback server.
 
-## Compatibility
+For an error or blank map, check the manifest URL, map/theme IDs, imported CSS, and matching
+worker/shared assets. The component does not guess a new manifest location after a 404.
 
-The supported peer window is Svelte 5.x and MapLibre GL JS 6.4.1-6.x. Compatibility smoke tests
-install Svelte 5.0.0 with the exact lower bound and selected current release from packed Tileflow
-tarballs, typecheck the public declarations, and compile real Svelte consumers. Future Svelte majors
-stay outside the peer range until that matrix passes.
+Hosted maps acquire a short-lived session grant before eligible resource requests.
+`analytics={{enabled: false}}` disables the optional beacon, not authorization. Use a stable product
+`surfaceId`, not a URL or user identifier. Direct World maps can show owner-action notices when
+managed delivery is required. Imports and the image path remain SSR-safe; interactive rendering
+requires a browser with WebGL.
 
-Docs: https://tileflow.dev/docs
+See the [interaction guide](https://github.com/tileflow/tileflow-sdk/blob/main/packages/interactions/README.md)
+and [browser runtime contract](https://github.com/tileflow/tileflow-sdk/blob/main/docs/contracts/framework-browser-runtime.md).
+Use the installed declarations and README for release-specific behavior; `main` may be newer than npm.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tileflow/svelte",
-  "version": "0.1.0-alpha.23",
+  "version": "0.1.0-alpha.25",
   "license": "Apache-2.0",
   "description": "Svelte component for rendering Tileflow maps with MapLibre.",
   "type": "module",
@@ -44,8 +44,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@tileflow/core": ">=0.1.0-alpha.24 <0.1.0-beta.0",
-    "@tileflow/interactions": ">=0.1.0-alpha.3 <0.1.0-beta.0"
+    "@tileflow/core": ">=0.1.0-alpha.27 <0.1.0-beta.0",
+    "@tileflow/interactions": ">=0.1.0-alpha.4 <0.1.0-beta.0"
   },
   "peerDependencies": {
     "maplibre-gl": ">=6.4.1 <7",

package/src/TileflowMap.svelte

@@ -23,7 +23,6 @@
     resolveTileflowRuntimeTheme,
     resolveTileflowRuntimeView,
     resolveTileflowStaticImageUrl,
-    shouldLoadTileflowManifest,
     type TileflowRuntimeManifestMap,
   } from '@tileflow/core/runtime';
   import {
@@ -144,7 +143,7 @@
   let manifestMap: TileflowRuntimeManifestMap | null = null;
   let manifestLoadId = 0;
   let manifestResolutionKey = '';
-  let manifestResolutionState: 'error' | 'loading' | 'not-needed' | 'ready' = 'loading';
+  let manifestResolutionState: 'error' | 'loading' | 'ready' = 'loading';
   let mapLoadId = 0;
   let mounted = false;
   let refreshRunId = 0;
@@ -170,23 +169,11 @@
   $: assertTileflowMapStyleInputs({source, theme});
   $: resolvedCaptureId = normalizeTileflowCaptureId(captureId);
   $: isImageMode = resolvedMode === 'image';
-  $: mapName = source?.kind === 'tileflow' ? source.map : undefined;
-  $: manifestUrl =
-    source?.kind === 'tileflow'
-      ? (source.manifestUrl ?? defaultTileflowManifestUrl)
-      : defaultTileflowManifestUrl;
-  $: shouldLoadManifest = shouldLoadTileflowManifest({
-    source,
-  });
-  $: manifestRequestKey = shouldLoadManifest
-    ? JSON.stringify([manifestUrl, mapName])
-    : 'not-needed';
+  $: mapName = source.map;
+  $: manifestUrl = source.manifestUrl ?? defaultTileflowManifestUrl;
+  $: manifestRequestKey = JSON.stringify([manifestUrl, mapName]);
   $: currentManifestResolutionState =
-    manifestResolutionKey === manifestRequestKey
-      ? manifestResolutionState
-      : shouldLoadManifest
-        ? 'loading'
-        : 'not-needed';
+    manifestResolutionKey === manifestRequestKey ? manifestResolutionState : 'loading';
   $: manifestMap =
     manifestResolutionKey === manifestRequestKey && manifestResolutionState === 'ready'
       ? loadedManifestMap
@@ -194,7 +181,6 @@
   $: themeResolution = resolveThemeSelection({
     colorScheme: systemColorScheme,
     manifestMap,
-    source,
     theme,
   });
   $: resolvedThemeName = themeResolution.name;
@@ -237,7 +223,6 @@
     isImageMode,
     runtimeImageUrl,
     runtimeStyle,
-    shouldLoadManifest,
     themeResolutionError: themeResolution.error,
   });
   $: currentMapCaptureState =
@@ -384,17 +369,7 @@
   }
 
   async function refreshManifest() {
-    const shouldLoad = shouldLoadManifest;
     const requestKey = manifestRequestKey;
-
-    if (!shouldLoad) {
-      manifestLoadId += 1;
-      loadedManifestMap = null;
-      manifestResolutionKey = requestKey;
-      manifestResolutionState = 'not-needed';
-      return;
-    }
-
     const loadId = ++manifestLoadId;
     loadedManifestMap = null;
     manifestResolutionKey = requestKey;
@@ -1228,16 +1203,12 @@
   function resolveThemeSelection(input: {
     colorScheme: 'dark' | 'light';
     manifestMap: TileflowRuntimeManifestMap | null;
-    source: TileflowMapProps['source'];
     theme: TileflowMapProps['theme'];
   }): Readonly<{error: boolean; name: string | undefined}> {
-    if (!input.manifestMap || input.source.kind !== 'tileflow') {
+    if (!input.manifestMap) {
       return {
         error: false,
-        name:
-          input.source.kind === 'tileflow' && input.theme && input.theme !== 'system'
-            ? input.theme
-            : undefined,
+        name: input.theme && input.theme !== 'system' ? input.theme : undefined,
       };
     }
 
@@ -1252,16 +1223,15 @@
   }
 
   function resolveRuntimeResolutionState(input: {
-    currentManifestResolutionState: 'error' | 'loading' | 'not-needed' | 'ready';
+    currentManifestResolutionState: 'error' | 'loading' | 'ready';
     imageSize: {height: number; width: number} | null;
     imageUrl: string | undefined;
     isImageMode: boolean;
     runtimeImageUrl: string | undefined;
     runtimeStyle: ReturnType<typeof resolveTileflowRuntimeStyle>;
-    shouldLoadManifest: boolean;
     themeResolutionError: boolean;
   }): 'error' | 'idle' | 'loading' {
-    if (input.shouldLoadManifest && input.currentManifestResolutionState !== 'ready') {
+    if (input.currentManifestResolutionState !== 'ready') {
       return input.currentManifestResolutionState === 'error' ? 'error' : 'loading';
     }
     if (input.themeResolutionError) return 'error';

package/src/style-source.js

@@ -16,12 +16,6 @@ export function validateTileflowMapStyleInputs(input) {
   if (input.theme !== undefined && !validateTileflowThemeSelection(input.theme)) {
     return {error: 'theme must be a concrete portable theme name or "system"', ok: false};
   }
-  if (
-    input.theme !== undefined &&
-    /** @type {{kind?: unknown}} */ (input.source).kind !== 'tileflow'
-  ) {
-    return {error: 'theme is only valid with a tileflow source', ok: false};
-  }
   return {ok: true};
 }