API stability contract

This document defines what @waylocate/embed promises to keep stable across releases.

The goal: customers declare intent once; we change transport behind them.

Three tiers

Tier 1 — stable, transport-free

Package: @waylocate/embed (root) and @waylocate/embed/react

API	Role
mount()	Hand over a container and campus intent; receive a WaylocateMap handle
<CampusMap> / useCampusMap()	React bindings over mount()
WaylocateMap	Typed handle: selection, camera, directions, ui, on(), destroy()
Payload types	MapState, SelectionChangedPayload, CameraPosition, etc.
WaylocateError	Typed errors with a stable code discriminant
SDK_VERSION	Version string for support and telemetry

Stability promise: Signatures and semantics are additive within a major line (0.x until 1.0). No Tier 1 identifier may name a transport concept (iframe, origin, postMessage, etc.).

Tier 2 — stable, transport-coupled

API	Role
buildEmbedUrl()	Construct the embed URL
connect()	Attach to an existing frame element

These remain supported. If we replace iframes, these may shift internally, but we will not remove them without a major version and a migration path.

Tier 3 — unstable internals

Package: @waylocate/embed/protocol

Wire protocol helpers, the raw host client, origin parsing, and message builders. May change on any release.

Versioning rules (0.x)

• Patch (0.2.1): bug fixes, docs, internal refactors with no Tier 1 change.
• Minor (0.3.0): additive Tier 1 API.
• Breaking Tier 1 change: avoid before 1.0.0; if unavoidable, document in CHANGELOG and bump minor with a migration note.

What customers should import

import { mount } from "@waylocate/embed";
import { CampusMap } from "@waylocate/embed/react";
import { buildEmbedUrl, connect } from "@waylocate/embed";
// Only for protocol implementers:
import { createEmbedHostClient } from "@waylocate/embed/protocol";

Map-side backward compatibility

The SDK version customers pin and the map version we deploy are independent. Compatibility is maintained by:

1. Additive wire protocol — never remove or rename commands, events, or payload fields.
2. capabilities in map.ready — hosts feature-detect before calling.
3. host.hello handshake — older maps that lack it still connect via map.ready.