Event contracts

This is the API surface between components. If a behavior crosses component boundaries, it must be an event.

Conventions

• Use CustomEvents.
• Event names use kweb:*.
• event.detail is JSON-serializable.
• Components should ignore unknown fields.
• Events bubble, and are composed: true so they can cross shadow DOM boundaries.
• “Preview” is hover-driven, “Commit” is click-driven.

Shared fields

Most events include:

• webId (string)
• source (string, e.g. graph, timeline, map, bio, search, trails, spheres, editor)
• at (ISO timestamp, optional)

Navigation and focus

kweb:navigate

Commit or preview navigation to a node.

detail:

• webId
• nodeId
• mode (preview | commit)
• source

kweb:selection-changed

Emitted by app shell after a commit.

detail:

• webId
• nodeId

kweb:hover-changed

Emitted by app shell after a preview change.

detail:

• webId
• nodeId (string or null)

kweb:focus-link

Highlight or focus a link.

detail:

• webId
• linkId
• mode (preview | commit)
• source

Time

kweb:time-range-set

Set an active time filter.

detail:

• webId
• start (ISO string or year string)
• end (ISO string or year string)
• mode (preview | commit)
• source

kweb:time-range-cleared

Clear time filter.

detail:

• webId
• source

Map

kweb:map-focus

Focus a geographic point.

detail:

• webId
• lat
• lon
• zoom (optional number)
• mode (preview | commit)
• source

Search

kweb:search-query

Search query changed.

detail:

• webId
• query
• source

kweb:search-select

User selected a search result.

detail:

• webId
• nodeId
• mode (preview | commit)
• source

Trails

kweb:trail-step

User navigated via trail.

detail:

• webId
• nodeId
• index
• mode (preview | commit)
• source

kweb:trail-save

Save current trail as a journey.

detail:

• webId
• title
• steps (array of node ids)

Authoring

kweb:node-create

detail:

• webId
• draft (node partial)

kweb:node-update

detail:

• webId
• nodeId
• patch (partial fields)

kweb:node-delete

detail:

• webId
• nodeId

kweb:link-create

detail:

• webId
• draft (link partial)

kweb:link-update

detail:

• webId
• linkId
• patch

kweb:link-delete

detail:

• webId
• linkId

kweb:web-create

detail:

• title
• description (optional)

kweb:web-switch

detail:

• webId

kweb:web-export

detail:

• webId
• format (zip | folder)

kweb:web-import

detail:

• format
• source (file picker / drag drop)

Diagnostics (optional)

kweb:log

A structured log event for the inspector.

detail:

• level (info | warn | error)
• message
• data (optional object)

Definition of done (events)

• [ ] Every cross-component interaction has an event contract here.
• [ ] Preview vs commit is consistent across views.
• [ ] Payloads are stable and documented.