Tutorial Action Reference

Tutorial Action Links are interactive links embedded in documentation pages that trigger live actions in the Benchmrk app. This page is a complete reference for documentation authors and power users — it documents every registered action, the protocol syntax, the security model, and includes working clickable examples.

The benchmrk-action:// protocol

Tutorial Action Links use a custom protocol scheme: benchmrk-action://. When clicked inside the DocsPanel, these links trigger actions in the app instead of navigating to a URL.

Syntax

benchmrk-action://<action-name>
benchmrk-action://<action-name>?<key>=<value>&<key>=<value>

• action-name — A kebab-case identifier for the action (e.g. open-ledger, fly-to).
• Query string parameters — Optional key-value pairs passed as the action payload. Values must be URL-encoded.

Examples

[Open the Ledger](benchmrk-action://open-ledger)
[Search for TS 6844](benchmrk-action://focus-search?value=TS%206844)
[Fly to Sydney](benchmrk-action://fly-to?lat=-33.8688&lng=151.2093&zoom=12)

How it works

These links communicate with the app to trigger actions. When a user clicks a benchmrk-action:// link inside the DocsPanel, the app intercepts the click, parses the action name and parameters, and dispatches it to the app's action handler.

Security model

The action link system includes several security layers:

Origin validation

The app validates that action requests come from the documentation site and only allows registered actions to be triggered.

Action allowlist

Only actions that have been explicitly registered can be dispatched. If a message contains an unregistered action name, it is ignored — no code is executed.

This means:

• Arbitrary code cannot be injected.
• Only the six registered actions (listed below) can be triggered.
• New actions must be explicitly registered in the app code before they can be used in documentation.

Registered actions

The following six actions are registered in the Action Registry and available for use in documentation pages.

---

open-ledger

Opens the Ledger / My Snapshots panel in the sidebar.

Payload: None

Markdown syntax:

[Open the Ledger](benchmrk-action://open-ledger)

Try it: Click the link below to open the Ledger panel.

Open the Ledger

---

close-panels

Closes all open sidebar panels, returning to the default map-only view.

Payload: None

Markdown syntax:

[Close all panels](benchmrk-action://close-panels)

Try it: Click the link below to close all sidebar panels.

Close all panels

---

focus-search

Focuses the search input in the search bar. Optionally pre-fills the search field with a value.

Payload:

Parameter	Required	Description
value	No	A string to pre-fill in the search input (URL-encoded)

Markdown syntax:

<!-- Focus search with no pre-fill -->
[Focus the search bar](benchmrk-action://focus-search)

<!-- Focus search with a pre-filled value -->
[Search for TS 6844](benchmrk-action://focus-search?value=TS%206844)

Try it: Click the link below to focus the search bar.

Focus the search bar

Click this link to focus the search bar and pre-fill it with a sample mark ID.

Search for TS 6844

---

fly-to

Flies the map to a specific latitude and longitude, with an optional zoom level.

Payload:

Parameter	Required	Description
lat	Yes	Latitude in decimal degrees (e.g. -33.8688)
lng	Yes	Longitude in decimal degrees (e.g. 151.2093)
zoom	No	Map zoom level (e.g. 12). If omitted, the map uses a default zoom.

Markdown syntax:

[Fly to Sydney Harbour (-33.8688, 151.2093)](benchmrk-action://fly-to?lat=-33.8688&lng=151.2093&zoom=12)

Try it: Click the link below to fly the map to Sydney Harbour at coordinates -33.8688, 151.2093.

Fly to Sydney Harbour (-33.8688, 151.2093)

---

open-ai-mode

Activates AI Assist pin-drop mode, allowing the user to place an analysis pin on the map.

Payload: None

Markdown syntax:

[Activate AI Assist](benchmrk-action://open-ai-mode)

Try it: Click the link below to activate AI pin-drop mode.

Activate AI Assist

---

open-docs

Opens the DocsPanel. If the panel is already open, this is a no-op.

Payload: None

Markdown syntax:

[Open the docs panel](benchmrk-action://open-docs)

Try it: Click the link below to open the documentation panel (no effect if already open).

Open the docs panel

---

Writing tutorial action links

When adding benchmrk-action:// links to documentation pages, follow these guidelines:

1. Always include explanatory text before the link describing what it will do. Users should understand the effect before clicking.
2. Use descriptive link text — [Open the Ledger](benchmrk-action://open-ledger) is better than [Click here](benchmrk-action://open-ledger).
3. URL-encode payload values — Spaces become %20, special characters are encoded (e.g. TS%206844).
4. Only use registered actions — The six actions listed above are the only valid action names. Using an unregistered action name will fail silently.
5. Include coordinates in context for fly-to links — Always mention the location name and coordinates near the link so users know where the map will navigate.

warning

Tutorial Action Links only work inside the DocsPanel. If a user opens the documentation in a separate browser tab (outside the app), clicking these links will have no effect because there is no parent app to receive the action.