Instances

Internal instance anatomy and orchestration boundaries.

Anatomy at a glance

createInstance({ map, document? }) first validates the consumer-injected map, then normalises input via normaliseInstanceDocument(...), then delegates the resulting canonical InstanceDocument to createInstanceCore(map, ...), which assembles one runtime core for one injected map.

Key components:

Internal orchestration boundaries

• Public boundary: createInstance({ map, document? }) in src/entry.js returns WaymarkInstancePublicApi only.
• Runtime boundary: lifecycle phase, registry entries, and event-wiring handles stay internal.
• InstanceDocument boundary: toJSON() is canonical serialisable output; it is separate from runtime lifecycle state.

Map injection details are documented separately:

• Map boundaries

core.modules boundary

core.modules in createInstanceCore(...) groups teardown-capable internals:

• geoJSON (source/layer lifecycle, type-based render planning, feature interaction via createFeatureInteractionModule.js)
• debug (console event logging)

This grouping is internal lifecycle wiring, not part of the consumer API.

Module state boundaries

• Runtime mutable state lives in core.runtimeState (state module snapshot + dispatch) and covers debug and type visibility only.
• core.baseline keeps stable authored/default intent (debug, types) for delta generation.
• Serialisation emits a stable config baseline and a minimal state delta in toJSON() (unchanged branches omitted), using runtime-state snapshots as the current source. There is no map/camera/basemap slice.
• Internal mutators (for example, runtimeState.dispatch(...)) are runtime wiring and not public API.
• The geoJSON module owns a nested featureInteraction module that observes Waymark-owned layers and emits feature interaction events. It is not part of the public API surface: consumers receive waymark:feature.* events and core.modules.geoJSON.destroy() detaches its listeners.

Lifecycle order

Create flow:

1. Validate the injected map (src/entry.js) and normalise the incoming document.
2. Check the WeakMap registry in src/runtime/runtimeRegistry.js; if the map already has a runtime, throw.
3. Resolve config (debug) and install the event bus on map.getContainer().
4. Create the GeoJSON module: build render plans, register load/style.load mount handlers, and wire the feature interaction module (click/mousemove/mouseout).
5. Create runtime state (createInstanceState(...)) with initial debug and type-visibility state.
6. Build the InstanceDocument adapter and public API.
7. Register the runtime against the map in the WeakMap and emit waymark:instance.created on the map container.

Destroy flow:

1. Mark lifecycle destroyed and emit waymark:instance.destroyed.
2. Run geoJSON.destroy() (remove Waymark-owned layers/sources, detach load/style.load, destroy the feature interaction module and detach its click/mousemove/mouseout handlers) and debug.destroy().
3. Delete the runtime registry entry for the map.

The consumer's map and container are never removed or modified by Waymark.

Extension notes

When adding internals to createInstanceCore(...):

• Keep dependencies explicit.
• Keep teardown deterministic.
• Keep ID-scoped names collision-safe.
• Keep the public API stable unless intentionally documented and tested.

For module-level behaviour, update these docs alongside runtime changes:

• docs/4.map.md