Protocol overview
This section documents the messages that cross the boundary between a host page and an embedded map.
Most integrations do not need it. @waylocate/embed implements all of it, and
the control section describes the same capabilities in
terms of the handle. Read this if you are implementing a host in a language or
environment the package does not cover, debugging traffic you can see in a
console, or deciding whether a change on your side is safe.
Written against @waylocate/embed@0.2.1, which speaks wire protocol waylocate: 1.
Layers
An embed is built in four layers, each usable on its own.
| Layer | Mechanism | Purpose |
|---|---|---|
| 0 | Internal controller | The single funnel every intent passes through, including a visitor's clicks |
| 1 | URL parameters | Initial state, shareable, no JavaScript required |
| 2 | Message protocol | Live control and notification |
| 3 | @waylocate/embed | Typed wrapper over layer 2 |
Layer 3 adds no capability. It adds types, promises, correlation, timeouts, and subscription bookkeeping over exactly the messages documented here.
Design rules
The protocol follows six rules. They are listed because each one explains something about the message shapes that would otherwise look arbitrary.
One intent funnel. Host commands call the same internal functions a visitor's click calls. There is no parallel code path and no second source of truth, which is why a host cannot reach a state a visitor could not.
References are slugs, never internal identifiers. Buildings and floors have database identifiers, and none of them appear on the wire. Identifiers are unstable across data updates, and a protocol that exposed them would force integrations to depend on values nobody intends to keep.
Every command is acknowledged. Commands carry an identifier and results echo it. This is what allows a promise-based client, and what allows a host to tell a bad reference from a slow network.
Every event carries its source. So that a host can distinguish a visitor's action from the echo of its own command.
The protocol is versioned from the first message. The waylocate field is
both a namespace guard and a version. Fields are immutable once shipped: add,
never repurpose.
Visitors always win. Commands never lock the interface, and there is no controlled mode. A visitor's next interaction overrides whatever a host just set.
Sections
| Page | Covers |
|---|---|
| Envelope | The shape every message shares |
| Handshake | Connecting, and negotiating capabilities |
| Commands | Every command and its payload |
| Events | Every event and its payload |
| Errors | Wire-level error codes |
| Reference grammar | How places are addressed |
URL parameters are documented under configuration, since they are as much a part of an ordinary integration as they are of the protocol.
The protocol inspector shows this traffic against a live map.