Events

Events carry no correlation identifier and are not answered. Each carries a source naming what caused it.

Event	Payload	Delivery
map.ready	{ protocol, campus, capabilities, build? }	Default
map.loaded	WaylocateState	Default
map.error	{ code, message }	Default
state.changed	WaylocateState	Default
selection.changed	{ building, floor, room }	Default
directions.changed	{ from, to, mode, status } or null	Default
expand.requested	{ url }	Default
camera.changed	CameraOptions	Subscription required, about 10 Hz
camera.idle	CameraOptions	Subscription required
camera.pathEnded	{ reason }	Default

reason on camera.pathEnded is completed, cancelled, or replaced.

Why two events need subscription

A single pan gesture produces hundreds of camera updates. Delivering those to every host by default would make the common case pay for the rare one, so camera.changed and camera.idle are sent only after events.subscribe.

State snapshot

Carried by map.loaded and state.changed, and returned by map.getState.

interface WaylocateState {
  ready: boolean;            // false until campus data resolves
  campus: string;
  building: string | null;   // slug
  floor: string | null;      // slug, relative to the building
  room: string | null;       // reference, relative to the building
  directions: {
    from: string | null;
    to: string | null;
    mode: "preview" | "live";
  } | null;
  camera: CameraOptions | null;  // null while the map is not rendering
  url: string;               // canonical full-map URL for this state
}

url is included so that a host can build its own share control, deep link, or expand button without reconstructing the URL grammar.

Fields that cannot be expressed as a reference degrade to null rather than failing. A route endpoint the visitor tapped on the map has no reference, and a building with no slug encodes as null even while selected.

camera is read from the map on each snapshot rather than cached, and does not participate in change detection. A pan gesture therefore does not raise state.changed.

expand.requested

When a visitor uses the expand control, the map's behaviour depends on whether the host has subscribed.

Subscribed, the map emits { url } carrying the canonical full-map address and does not open a tab, leaving the decision to the host. Not subscribed, the map opens a tab exactly as the standalone map would.

The fallback exists so that enabling the expand control and forgetting to listen produces working behaviour rather than a button that does nothing.

Event sources

Source	Meaning
user	A visitor gesture
host	A host command
system	The map's own behaviour

For camera events the source is decided when motion starts and held for the whole gesture, because only the gesture-start events carry enough information to attribute it. A camera fly caused by selecting a building is system rather than host, even when a host command caused the selection.

camera.idle

Derived from the end of movement plus a short settle window, rather than from the rendering library's own idle signal. The map's overlay layers request repaints while animations are live, and the library's idle event only fires once rendering has fully quiesced, which on a busy campus may be never. A host awaiting it would hang.

Next

• Errors for the failure codes.
• Reference grammar for the values in these payloads.