Get started

Hooks

Each hook is listed under the narrowest entry point that exports it.

@mountaya/client-react

React bindings for the Mountaya API client.

useMountayaCustomQuery

useMountayaCustomQuery runs a read of your own as a query under a key you build, reporting its failure as a MountayaError, as useMountayaQuery does.

useMountayaCustomQuery<TQueryFnData, TData>(queryKey, queryFn, options?)

queryKey

QueryKey

required

The entry the read caches under.

queryFn

(options: RequestOptions) => Promise<TQueryFnData>

required

The read, handed TanStack's AbortSignal to pass on to each call.

options

MountayaQueryOptions<TQueryFnData, TData>

TanStack's options for the read. retry defaults to false, because the client already retries. enabled joins the hold on a pending scope.

Returns UseQueryResult<TData, MountayaError>: TanStack's result, with error typed as a MountayaError.

useMountayaKeys

useMountayaKeys returns mountayaKeys with the provider's credential already bound.

useMountayaKeys()

Returns MountayaKeys

all

() => QueryKey

required

Every Mountaya query, under any credential.

operation

<S extends Surface, Op extends OperationIdOf<S>>(surface: S, operationId: Op, args?: OperationArgsOf<S, Op>, select?: OperationSelectionOf<S, Op>) => QueryKey

required

One operation under this credential, optionally narrowed by its arguments and, on the Data API, by its field selection.

scope

() => QueryKey

required

This credential's reads, for a sign-out or a rotated share token.

surface

(surface: Surface) => QueryKey

required

useMountayaMutation

useMountayaMutation runs a client call as a mutation, reporting its failure as a MountayaError, as useMountayaQuery does.

useMountayaMutation<TData, TVariables>(mutationFn, options?)

mutationFn

(variables: TVariables) => Promise<TData>

required

The write, called with the variables mutate is handed.

options

Omit<UseMutationOptions<TData, MountayaError, TVariables>, "mutationFn">

TanStack's options for the mutation. retry defaults to false.

Returns UseMutationResult<TData, MountayaError, TVariables>: TanStack's mutation result, with error typed as a MountayaError.

useMountayaQuery

useMountayaQuery<S, Op, Sel, TData>(surface, operationId, args?, options?)

surface

S

required
operationId

Op

required
args

OperationArgsOf<S, Op>

The operation's arguments, or its input on the Data API. Omitted for an operation that takes none.

options

MountayaQueryOptions<OperationAnswerOf<S, Op, Sel>, TData> & { readonly request?: OperationRequestOptions<S, Sel> | undefined }

TanStack's options for the read, and the Data API call's request. retry defaults to false, because the client already retries. enabled joins the hold the read keeps while the credential scope is pending.

Returns UseQueryResult<TData, MountayaError>: TanStack's result, with error typed as a MountayaError.

useCollection

useCollection is collectionQueryOptions bound to the provider's client.

useCollection<TData>(collectionId, options?)

collectionId

string | undefined

required

The collection to read. The read stays idle while it is undefined or empty.

options

MountayaResourceQueryOptions<RestSchema.Collection, TData>

TanStack's options: enabled joins the id's gate, and select is handed the record.

Returns UseQueryResult<TData, MountayaError>

useCollectionSpecification

useCollectionSpecification is collectionSpecificationQueryOptions bound to the provider's client.

useCollectionSpecification<TData>(collectionId, options?)

collectionId

string | undefined

required

The collection whose specification to read. The read stays idle while it is undefined or empty.

options

MountayaResourceQueryOptions<TileSchema.TileSpecification, TData> & { readonly query?: Parameters<typeof collectionSpecificationQueryOptions>[2] | undefined }

TanStack's options: enabled joins the id's gate, and select is handed the specification. query names the layers the specification declares, each the organization's default where it is left out.

Returns UseQueryResult<TData, MountayaError>

useCollections

useCollections is collectionsInfiniteQueryOptions bound to the provider's client.

useCollections<TData>(query?, options?)

query

Parameters<typeof collectionsInfiniteQueryOptions>[1]

The listing's filters, its sort and its page size. Omitted, every collection the credential reaches, most recently changed first.

options

MountayaListingQueryOptions<RestSchema.Collection[], TData>

TanStack's options: enabled gates the read, and select is handed the rows.

Returns UseInfiniteQueryResult<TData, MountayaError>

useItineraries

useItineraries is itinerariesInfiniteQueryOptions bound to the provider's client.

useItineraries<TData>(query?, options?)

query

Parameters<typeof itinerariesInfiniteQueryOptions>[1]

The listing's filters, its sort and its page size. Omitted, every itinerary the credential reaches, most recently changed first.

options

MountayaListingQueryOptions<RestSchema.Itinerary[], TData>

TanStack's options: enabled gates the read, and select is handed the rows.

Its fields are listed under useCollections.

Returns UseInfiniteQueryResult<TData, MountayaError>

useItinerary

useItinerary is itineraryQueryOptions bound to the provider's client.

useItinerary<TData>(itineraryId, options?)

itineraryId

string | undefined

required

The itinerary to read. The read stays idle while it is undefined or empty.

options

MountayaResourceQueryOptions<RestSchema.ItineraryWithDetails, TData> & ItineraryReadOptions

TanStack's options, with surface beside them: the draft by default, or "published" for the last publication. enabled joins the id's gate, and select is handed the record.

Returns UseQueryResult<TData, MountayaError>

useItinerarySpecification

useItinerarySpecification is itinerarySpecificationQueryOptions bound to the provider's client.

useItinerarySpecification<TData>(itineraryId, options?)

itineraryId

string | undefined

required

The itinerary whose specification to read. The read stays idle while it is undefined or empty.

options

MountayaResourceQueryOptions<TileSchema.TileSpecification, TData>

TanStack's options: enabled joins the id's gate, and select is handed the specification.

Its fields are listed under useCollection.

Returns UseQueryResult<TData, MountayaError>

useZone

useZone is zoneQueryOptions bound to the provider's client.

useZone<TData>(zoneId, options?)

zoneId

string | undefined

required

The zone to read. The read stays idle while it is undefined or empty.

options

MountayaResourceQueryOptions<RestSchema.Zone, TData> & ZoneReadOptions

TanStack's options: enabled joins the id's gate, and select is handed the record. surface reads the last publication instead of the draft.

Returns UseQueryResult<TData, MountayaError>

useZones

useZones is zonesInfiniteQueryOptions bound to the provider's client.

useZones<TData>(query?, options?)

query

Parameters<typeof zonesInfiniteQueryOptions>[1]

The listing's filters, its sort and its page size. Omitted, every zone the credential reaches, most recently changed first.

options

MountayaListingQueryOptions<RestSchema.Zone[], TData>

TanStack's options: enabled gates the read, and select is handed the rows.

Its fields are listed under useCollections.

Returns UseInfiniteQueryResult<TData, MountayaError>

useActivities

useActivities reads the activity catalog: every outdoor activity type grouped by category, with the routing capabilities and tile sources each one carries.

useActivities<TData>(options?)

options

MountayaResourceQueryOptions<RestSchema.CategoryActivities[], TData>

Its fields are listed under useCollection.

Returns UseQueryResult<TData, MountayaError>

useLayers

useLayers<TData>(organizationId?, options?)

organizationId

string

The organization whose studio scope the manifest is read for. Omitted or empty, the read names none.

options

MountayaResourceQueryOptions<RestSchema.Layers, TData>

TanStack's options: enabled joins the read's own, and select is handed the manifest.

Its fields are listed under useCollection.

Returns UseQueryResult<TData, MountayaError>

useSessionToken

useSessionToken keeps a session token fresh, and hands the client a session that waits for the first one.

useSessionToken(options)

options

UseSessionTokenOptions

required

The mint, and whether to mint at all.

Returns UseSessionTokenResult

error

unknown

required

The last mint failure: whatever your mint rejected with, which is why it is unknown. Minting is retried on schedule regardless.

expiresAt

Date | undefined

required

When the current token expires, which can be an instant already PAST when the server hands one back that way: the hook answers that by backing off between mints rather than re-minting on a fixed floor.

getToken

() => string | undefined

required

Reads the current token at the moment it is called, for a caller that wants the string itself: a header of your own, a request outside the client.

isLoading

boolean

required

Whether a token is on its way: true from the first render while enabled, until the first mint lands, and again while a later mint is out with no token held.

refresh

() => void

required

Mint now, replacing any pending refresh, or join the mint already out, so repeated calls during one mint cost one call to your endpoint.

session

SessionTokenSource

required

The session, for the client's credential: new Mountaya({ credential: { publishableKey, sessionToken: session } }).

token

string | undefined

required

The current token, or undefined before the first mint completes.

useMountaya

useMountaya returns the client from the nearest provider.

useMountaya()

Returns Mountaya: The client the nearest MountayaProvider hands down.

admin

ReturnType<typeof bindRest>["admin"]

required

The Map Studio API's organization half: keys, settings, members, usage and webhooks. Each method resolves to the response envelope, with the payload at data.

agent

ReturnType<typeof bindRest>["agent"]

required

The AI agent: starting a run, answering it, rating it. Each method resolves to the response envelope, with the payload at data; a run's events are read through createAgentTransport of @mountaya/client/events.

data

ReturnType<typeof bindData>

required

The GraphQL Data API: directions, search, terrain, isochrones, matrices. Each method resolves to the operation's own field, with no envelope.

studio

ReturnType<typeof bindRest>["studio"]

required

The Map Studio API's map half: itineraries, zones, collections, and their catalogs. Each method resolves to the response envelope, with the payload at data.

tiles

ReturnType<typeof bindTiles>

required

The Tile API's style specifications. Each method resolves to the response envelope.

transport

MountayaTransport

required

The transport every method calls through: for a call this client binds no method for, and for the openers of @mountaya/client/events.

useMountayaOrNull

useMountayaOrNull returns the client from the nearest provider, or null when there is none.

useMountayaOrNull()

Returns Mountaya | null

Its fields are listed under useMountaya.

@mountaya/elements-react

useBearing

Just the bearing.

useBearing()

Returns number: The bearing in degrees, and 0 with no map and in a server render.

useCamera

The whole camera, refreshed when the map settles after a move.

useCamera()

Returns Camera

center

[number, number]

required
zoom

number

required
bearing

number

required
pitch

number

required

useZoom

Just the zoom, on the same terms as useBearing.

useZoom()

Returns number: The zoom level, and 0 with no map and in a server render.

useZoomAtLeast

Whether the zoom has reached a threshold: true at the threshold and above it.

useZoomAtLeast(threshold)

threshold

number

required

The zoom to reach. A threshold that is not a number is never reached.

Returns boolean: true while the provider's map is at threshold or closer in, false below it.

useMountayaLayers

useMountayaLayers reads the layers manifest and drives the map's terrain and overlay slots, for the map on the nearest provider.

useMountayaLayers()

Returns LayersState

setTerrain

(slug: string) => void

required

Selects the terrain with this slug and switches the map's base to it.

setOverlay

(slug: string | null) => void

required

Passing the slug already selected clears it, which is what a second press means.

toggleEnrichment

(slug: string) => void

required

Turns the enrichment with this slug on when it is off, and off when it is on.

manifest

RestSchema.Layers | null

required

The manifest, or null until it has been read from the current map.

terrains

readonly RestSchema.Terrain[]

required

The manifest's terrains, in its order; empty until it has been read.

classicCategories

readonly RestSchema.CategoryOverlays[]

required

The categories whose overlays replace one another, in the manifest's order.

enrichmentCategories

readonly RestSchema.CategoryOverlays[]

required

The categories whose overlays stack, in the manifest's order.

terrain

string | null

required

The selected terrain's slug, or null while none is selected. When the manifest is read and nothing is selected yet, it states the terrain the map reports it shows (getTerrain), and stays null for a map that reports none, so a picker marks what the map draws and never a guess; a terrain selected earlier is kept.

overlay

string | null

required

The selected classic overlay's slug, or null while none is selected.

enrichments

readonly string[]

required

The selected enrichments' slugs, in the order they were turned on.

error

Error | null

required

The outcome of the latest manifest read or command to settle: the failure it met, or null once one succeeds, and null while none has settled since the current map was configured. A failure is the Error the map rejected or threw with, or, for a failure that is no Error, a MountayaElementsRejectionError that names what failed and holds the value as its cause.

useMountayaLayersManifest

useMountayaLayersManifest reads the layers catalogue the map already holds.

useMountayaLayersManifest()

Returns UseMountayaLayersManifestResult

manifest

Layers | null

required

The catalogue of the provider's map, or null until it has been read from that map.

error

Error | null

required

Why the read failed, so a caller can show a real reason rather than a blank, and null while this map's read has not failed.

useMountayaScopedStrings

useMountayaScopedStrings reads the sections one element renders, with that element's own overrides folded on.

useMountayaScopedStrings<K>(sections, overrides?)

sections

readonly K[]

required

The sections the element renders, and the only ones an override may name.

overrides

ScopedElementStrings<K>

The element's own strings prop, folded onto the nearest scope's bundle or the provider's. A section outside sections is dropped, whatever the type let through.

Returns Pick<ElementsStrings, K>: The sections, with the overrides folded on.

useSearch

useSearch binds SearchEngine to a component: props in, a snapshot out, React's own subscription in between.

useSearch(input)

input

UseSearchOptions

required

Returns UseSearchResult

retry

() => void

required

Re-runs the current query from the top: what a failed section's retry is wired to.

snapshot

SearchSnapshot

required

useSearchKeyboard

useSearchKeyboard owns ↑/↓/Enter/Escape over the rows a search is showing.

useSearchKeyboard(options)

options

UseSearchKeyboardOptions

required

Returns UseSearchKeyboardResult

onKeyDown

(event: KeyboardEvent<HTMLInputElement>) => void

required
rowCount

number

required

How many rows the cursor can reach, for a caller rendering the highlight.

@mountaya/elements-react/editor

React over a map a host drives through a MapClient.

useMapLanguage

useMapLanguage writes the base map's label language through client.setMapLanguage, and writes it again whenever the client or the resolved language changes.

useMapLanguage(client, language)

client

MapClient | null

required

The client <EditorMapView> or <ViewerMapView> handed out, or null before it has.

language

string | undefined

required

A BCP 47 tag, or undefined for English.

useTilesAccessRequired

useTilesAccessRequired reports whether the Tile API is refusing the map's tile fetches for want of access.

useTilesAccessRequired(client)

client

MapClient | null

required

Returns boolean: true while a refusal of access stands for this client, and false while none does and while client is null.

@mountaya/elements-react/elements

The elements that need no map.

useElevationSeries

useElevationSeries reads an itinerary's profile out of its GeoJSON, once per itinerary.

useElevationSeries(input)

input

ProfileInput | null | undefined

required

The itinerary's GeoJSON. null and undefined are both taken, because that is what a resolving element holds: the resource answers null while it is in flight and the geometry is undefined before a caller has one, and a hook that took only one of them would push a coalesce onto every call site.

Returns ProfileSeries: The series and the domain its curve is drawn against, one object for as long as input is the same object.

series

ElevationSeries

required
domain

ReturnType<typeof profileDomain>

required

useItineraryResource

useItineraryResource resolves an itinerary by id, through the client on the provider.

useItineraryResource(options)

options

UseItineraryResourceOptions

required

Returns ItineraryResource

geojson

ProfileInput | null

required

The itinerary's geometry, ready to profile, or null until it has resolved.

characteristics

ItineraryCharacteristics | null

required

The server's own figures, folded from the chain, or null until it has resolved.

segments

readonly ItinerarySegmentInput[] | null

required

The authored chain with its groups collapsed: a table's rows and a chart's chips.

waypoints

readonly Waypoint[] | null

required

The itinerary's own waypoints: the pins on the curve and the names under the axis.

resolving

boolean

required

Whether the itinerary is being read.

error

Error | null

required

Why the itinerary could not be read, or null while nothing has failed.

useItinerarySegmentRows

useItinerarySegmentRows derives a table's rows, and the one curve every row lights part of.

useItinerarySegmentRows(options)

options

UseItinerarySegmentRowsOptions

required

Returns UseItinerarySegmentRowsResult

rows

readonly ItinerarySegmentRow[]

required
polyline

string

required

The whole itinerary's curve, built ONCE and shared by every row's sparkline.

area

string

required

useMapFeatureHover

useMapFeatureHover reports what the pointer is over on the map, if there is a map.

useMapFeatureHover(enabled?)

enabled

boolean

default: true

Whether to listen, true by default. false attaches no handler, so the map hit-tests nothing on this hook's account.

Returns MapFeatureHover

segmentId

string | null

required

The leg under the cursor, or null when the pointer is not on the route.

waypointId

string | null

required

The place under the cursor, or null.

useProfileMarker

useProfileMarker shows the hovered point of a profile on the map, if there is a map.

useProfileMarker(point, options?)

point

ElevationPoint | null

required

The hovered point, or null to take the pin down.

options

UseProfileMarkerOptions

default: {}

How the pin is drawn and the id it is held under.

useProfileRange

useProfileRange holds the stretch of itinerary a chart is drawn over.

useProfileRange(options)

options

UseProfileRangeOptions

required

Returns UseProfileRangeResult

range

ProfileRange

required
setRange

(next: ProfileRange) => void

required

useSegmentEmphasis

useSegmentEmphasis lights the leg a reader is pointing at, if there is a map.

useSegmentEmphasis(geometry, options?)

geometry

GeoJSON.Geometry | null

required

The leg to light, or null to take the lit stretch down.

options

UseSegmentEmphasisOptions

default: {}

How the lit stretch is drawn.

useWaypointCard

useWaypointCard derives everything a card about one place states, and renders nothing.

useWaypointCard(options)

options

UseWaypointCardOptions

required

Returns UseWaypointCardResult

amenities

readonly WaypointCardAmenity[]

required
contact

readonly WaypointContactRow[]

required
empty

boolean

required

True when the place states no FACTS at all.

headline

string | null

required

The author's description, or a sentence assembled from what the place records.

links

readonly WaypointCardLink[]

required

Every media link the place records, in the author's order: what waypointMediaLinks of @mountaya/elements/profile answers for the place.

photos

readonly WaypointPhotoDetail[]

required

The photos a renderer may load, in the author's order: what waypointMediaPhotos of @mountaya/elements/profile answers for the place.

properties

readonly WaypointCardProperty[]

required
timing

readonly WaypointCardRow[]

required

useProfilePlot

useProfilePlot reads the plot a component is being drawn into.

useProfilePlot()

Returns ProfilePlot

totalDistance

number

required

The itinerary's total length in meters.

range

ProfileRange

required

The stretch of itinerary the plot is drawn over, in meters from its start.

x

(distance: number) => number

required

Where a distance sits horizontally, as a percentage of the plot.

y

(elevation: number) => number

required

Where an elevation sits vertically, as a percentage of the plot.

curveAt

(distance: number) => PlotPosition | null

required

Where a distance lands on the curve, or null where the curve has no sample.

scrubTo

(distance: number | null) => void

required

Moves the profile's cursor to a distance, or clears it with null.

@mountaya/elements-react/headless

The context these elements read, and the lifecycle primitives they are built on, with no renderer attached.

useLatestRef

useLatestRef mirrors value into a ref as each render commits, so a closure built once (a listener attached at mount, a subscription's observer, a handler handed to something long-lived) reads the current value at call time instead of the one captured on the render that built it. Without it, those closures have to be rebuilt whenever the value changes, and rebuilding one means tearing down the live thing it was attached to.

useLatestRef<T>(value)

value

T

required

Returns RefObject<T>

useSettledBundle

useSettledBundle answers the bundle of the first render that worded what this one words, for the readers that call no formatter.

useSettledBundle<TOverrides, TResolved>(language, overrides, following, source)

language

MapLanguage

required

The language following was resolved for.

overrides

TOverrides | undefined

required

The overrides as the render wrote them.

following

TResolved

required

The bundle resolved for this render.

source

unknown

required

What following was resolved through, compared by identity: a new one settles again whatever the overrides word.

Returns TResolved: One object across the renders whose overrides word the same thing in one language, through one source.

useStableBundle

useStableBundle resolves a copy bundle, and keeps the SAME object while the overrides say the same thing.

useStableBundle<TOverrides, TResolved>(language, overrides, resolve)

language

MapLanguage

required

The language the bundle is resolved for. A different one resolves again, whatever the overrides say.

overrides

TOverrides | undefined

required

The overrides as the render wrote them, compared through sameOverrides.

resolve

(language: MapLanguage, overrides: TOverrides | undefined) => TResolved

required

Resolves the bundle, called only when the language, what the overrides say or the function itself has changed. A resolver that closes over the translations a host handed over is held for as long as they stand, so a new set of translations resolves again.

Returns TResolved: One object across the renders whose language, overrides and resolver say the same thing.

useMountayaClient

The client an element resolves an id through, or null when the tree holds none.

useMountayaClient()

Returns ItinerarySource | null

studio

{ readonly itineraries: { getItinerary: (args: { readonly itinerary_id: string; readonly query?: { readonly surface?: "published" | undefined } | undefined }, options?: { readonly signal?: AbortSignal | undefined }) => Promise<{ readonly data: ItineraryWithDetails }> } }

required

useMountayaControlIcons

The glyph set the map controls draw with: the provider's controlIcons.

useMountayaControlIcons()

Returns IconProvider

name

string

required

Identifies the set in diagnostics and in the sprite image ids.

paint

GlyphPaint

required

Whether the caller paints these glyphs by filling their shapes or by stroking their outlines. Getting this wrong renders nothing, silently.

strokeWidth

number

required

Stroke width in viewBox units. Meaningful only when paint is "stroke".

viewBox

number

required

The square viewBox the markup is authored against.

has

(glyph: string) => boolean

required

Whether this set can draw the named glyph.

markup

(glyph: string) => string | undefined

required

The inner SVG markup for a glyph, or undefined when the set has no such glyph.

names

() => readonly string[]

required

Every glyph name this set can draw, sorted.

useMountayaLanguage

useMountayaLanguage()

Returns MapLanguage

useMountayaLocale

The locale the provider selected, for everything that WRITES a number rather than a word.

useMountayaLocale()

Returns string

useMountayaMap

The map the controls drive, or null before it is ready and when there is no map.

useMountayaMap()

Returns MountayaMap | null

useMountayaMarkerIcons

The glyph set the places on a curve are drawn with: the provider's markerIcons, and the bundled MARKER family by default.

useMountayaMarkerIcons()

Returns IconProvider

Its fields are listed under useMountayaControlIcons.

useMountayaPaint

The paint overrides the provider was given, or null.

useMountayaPaint()

Returns MapPaintOverrides | null

itinerary

{ readonly casingColor: string; readonly casingOpacity: number; readonly casingWidthStops: readonly number[]; readonly dashArray: readonly number[]; readonly dashedOpacity: number; readonly lineWidthStops: readonly number[] }

The itinerary stroke and the halo under it.

layerRanks

Readonly<Record<string, LayerRank>>

Which band each tile source-layer's layers draw in.

segments

{ readonly defaultColor: string; readonly palette: readonly string[] }

The colours a SEGMENT is drawn in: the wheel a new one is assigned from, and the neutral a segment with none of its own falls back to.

useMountayaStrings

The copy the elements render. English unless the provider was given overrides.

useMountayaStrings()

Returns ElementsStrings

amenities

AmenityStrings

required
controls

ControlStrings

required
layers

LayersStrings

required
pois

PoiStrings

required
preferences

PreferencesStrings

required
profile

ProfileStrings

required
search

SearchStrings

required
streetView

StreetViewStrings

required
table

TableStrings

required
tooltips

TooltipStrings

required
videoOverlay

VideoOverlayStrings

required
waypointCard

CardStrings

required
waypoints

WaypointStrings

required

useMountayaTokens

The token overrides the provider was given, as the style record an element root merges.

useMountayaTokens()

Returns Record<string, string>

useMountayaUiIcons

useMountayaUiIcons()

Returns IconProvider

Its fields are listed under useMountayaControlIcons.

@mountaya/studio-react

Mountaya's map studio, as components.

useAgentThreads

useAgentThreads()

Returns AgentThreadsValue: The value the nearest AgentThreadsProvider hands down.

answerQuestion

(entryId: string, label: string) => void

required

Settles a question card with the answer picked, and sends its label as the next turn.

chooseSuggestion

(entryId: string, seed: number, label: string) => void

required

Applies one suggested route of a suggestions card, and sends the pick as the next turn.

previewCandidate

(seed: number) => void

required

Paints one staged route on the map, by its seed.

closeAiTab

(tabId: string) => void

required

Closes a conversation's tab, through the tool bus.

newAiTab

() => void

required

Opens a new conversation in a tab of its own, through the tool bus.

resolveConfirmation

(approved: boolean) => void

required

Settles the in-chat approval card with the reader's decision.

stopActive

() => void

required

Aborts the active conversation's run. The one control left live while the agent drives.

store

AgentThreadsStoreApi

required

The per-mount threads store, read with narrow selectors.

submit

(message: string) => void

required

Opens the active conversation's run with a message, or continues it.

switchTab

(tabId: string) => void

required

Makes a tab the active one, through the tool bus.

usePeerLockLabels

usePeerLockLabels()

Returns ((lockHolderId: string) => string)

useItineraryUsage

useItineraryUsage resolves how many itineraries the viewer owns in the scope organizationId names against that scope's itinerary ceiling, for the proactive create, import, duplicate and suggest gates. It counts the itineraries of the listing and reports atLimit only when a ceiling is in force and the count has reached it.

useItineraryUsage(organizationId?)

organizationId

string | null

The scope a create targets, as useAgreementLimits takes it.

Returns ItineraryUsage

atLimit

boolean

required
count

number

required

How many distinct itineraries the viewer owns in the scope. Zero while the listing loads, and zero where no ceiling is in force, since the listing is then never asked for.

limit

number | null

required

useLayerCatalogOptions

useLayerCatalogOptions reads the tile-layer manifest and shapes it into the option lists a catalog-bound picker binds to: the terrains as flat slug/label options and the category overlays as grouped slug/label options.

useLayerCatalogOptions(language, organizationId?)

language

string

required

The UI language the labels resolve in.

organizationId

string

The organization whose scope the catalog is read for, or nothing for the read that names none.

Returns LayerCatalogOptions: The option lists and the load flags: isLoading mirrors the manifest query, so a field can show a loading placeholder, and isEmpty flags a loaded-but-empty catalog, so a field can show an empty hint instead of an unusable open dropdown. isEmpty is false until a manifest has arrived, so a read that failed is never told as an empty catalog.

isEmpty

boolean

required

Whether a manifest arrived holding no layer. False until one has arrived.

isLoading

boolean

required

Whether the manifest is still loading.

overlayGroups

CatalogOptionGroup[]

required

The overlays, grouped under their category.

terrainOptions

CatalogOption[]

required

The terrains, as slug/label options.

useStudioHostRegistry

useStudioHostRegistry reads the map-lifecycle registry the studio host owns.

useStudioHostRegistry()

Returns StudioHostRegistry

bus

ToolBus<StudioToolContext, StudioToolInputs, StudioToolOutputs>

required

The studio's bus, whole.

client

MapClient | null

required

The studio's live map, or null before one mounts and after it tears down.

onClientDestroy

() => void

required

Clears the studio's map.

onClientReady

(client: MapClient) => void

required

Publishes the studio's map.

registerCollab

(seam: CollabSeam) => void

required

Publishes the live collaboration session, so lock-aware verbs can consult it.

registerTabs

(surface: TabSurface) => void

required
registerVideoMap

(client: MapClient) => void

required

Publishes the video wizard's recording map, distinct from the studio's own.

unregisterCollab

() => void

required

Clears the collaboration session; lock-aware verbs fall back to the single-editor path.

unregisterTabs

() => void

required
unregisterVideoMap

() => void

required

Clears the video wizard's map; a video verb then answers a structured failure.

useItinerarySubject

useItinerarySubject derives a header subject from an itinerary record the caller ALREADY HOLDS.

useItinerarySubject(itinerary, loading?)

itinerary

ItineraryWithDetails | null | undefined

required
loading

boolean

default: false

Returns ItinerarySubject | null

ascent

string

required
distance

string

required
name

string

required
slug

ActivitySlug | null

required

useStudioItinerary

useStudioItinerary reads one itinerary with every segment's analysis arrays normalized.

useStudioItinerary(itineraryId, surface?)

itineraryId

string | undefined

required
surface

"draft" | "published"

Returns UseQueryResult<ItineraryWithDetails, MountayaError>

usePublishableScope

usePublishableScope answers whether a resource's owning organization can produce published output: isPublishableScope bound to the host's own notion of personal scope, read from the organizations roster the studio is mounted with.

usePublishableScope(organizationId)

organizationId

string | null | undefined

required

The organization that owns the resource: null for a personal resource, and undefined while the resource has not loaded.

Returns boolean: True for an organization the host's roster does not read as a personal scope, and false for an absent or empty id.

usePublishedItinerary

usePublishedItinerary reads the copy of an itinerary that the public is served, plus the state that says how far the editor has moved past it.

usePublishedItinerary(itineraryId)

itineraryId

string | undefined

required

The itinerary whose publication is read. While it is undefined neither read is made, and the state stays loading.

Returns PublishedItinerary: The published copy and the publication state, as PublishedItinerary states them.

failed

boolean

required

The published read was attempted and refused.

itinerary

ItineraryWithDetails | null

required
loading

boolean

required
organizationId

string | null | undefined

required

The DRAFT's owning organization: null for a personal itinerary, which belongs to none, and undefined until the draft read has answered.

publication

PublicationState

required

@mountaya/studio-react/headless

The studio's state, lifecycle and actions, with no markup of any kind.

useActiveCollabResources

useActiveCollabResources()

Returns readonly CollabResource[]

useActiveItineraryResource

useActiveItineraryResource()

Returns CollabResource | null: The open itinerary's handle, or null when no itinerary is open.

id

string

required
kind

"itineraries" | "zones"

required

useActiveZoneResource

useActiveZoneResource()

Returns CollabResource | null: The open zone's handle, or null when no zone is open.

Its fields are listed under useActiveItineraryResource.

useAgentDriving

useAgentDriving reports whether an agent run drives the studio, so a control can render inert for the duration.

useAgentDriving()

Returns boolean: true while an agent run drives the studio, false otherwise.

useBeginSegmentEdit

useBeginSegmentEdit(activitySlug?)

activitySlug

string

The router's profile for the itinerary's activity, the one thing this hook cannot resolve. A directions edit routes under it, and without it the edit draws no line. Which activity an itinerary belongs to, and what the router calls it, is the host's catalog to answer: activityForId in @mountaya/studio is the lookup.

Returns BeginSegmentEdit: The BeginSegmentEdit callback, stable while the store and the slug are.

useBeginWaypointEdit

useBeginWaypointEdit()

Returns BeginWaypointEdit: The BeginWaypointEdit callback, one function for the caller's life.

useCapability

useCapability(capability)

capability

ToolCapability

required

The class of action asked about.

Returns boolean: Whether the studio above grants it; false outside a provider.

useCollectionScope

useCollectionScope reads the active collection scope from the URL: the organization whose folders the sidenav tree is showing, or undefined for the personal scope. The personal view is the ABSENCE of the key, matching how the listing endpoints spell it. The scope lives in the URL rather than in component state so it survives a reload and a link carries it.

useCollectionScope()

Returns string | undefined: The organization id of the scope, or undefined for the personal scope.

useCopilotAvailability

useCopilotAvailability reports whether the co-pilot may run for a resource's organization.

useCopilotAvailability(organizationId)

organizationId

string | undefined

required

The resource's organization, or undefined for a personal resource.

Returns CopilotAvailability: The host's CopilotAvailability for it, or one unavailable and settled where no host binding is mounted.

canConfigure

boolean

required

Whether the viewer may configure a provider themselves: an owner or an admin.

configured

boolean

required

A provider is configured for this organization.

loading

boolean

required

Neither answer has arrived; every flag above defaults false while this is true.

notConfigured

boolean

required

A provider is definitively NOT configured, which is not the same as not yet knowing.

writable

boolean

required

The viewer may write to this organization.

useCopilotModelLine

useCopilotModelLine names the provider and model a configured co-pilot runs on.

useCopilotModelLine(organizationId)

organizationId

string | undefined

required

Returns string | null

useCopilotSetupAction

useCopilotSetupAction reads the control that opens the host's provider configuration.

useCopilotSetupAction(organizationId)

organizationId

string | undefined

required

Returns ReactNode

useCopilotWithheldNotice

useCopilotWithheldNotice reads what the host shows in place of the conversation where it withholds the co-pilot from this organization, or null where it withholds nothing.

useCopilotWithheldNotice(organizationId)

organizationId

string | undefined

required

Returns ReactNode

useDeferredClick

useDeferredClick defers a single-click action so a double-click can cancel it.

useDeferredClick()

Returns DeferredClick

cancel

() => void

required

Drops the action a single click scheduled, if it has not run.

schedule

(action: () => void, delayMs?: number) => void

required

Arms action to run once the double-click window has passed, replacing any action still pending. delayMs defaults to the studio's double-click window.

useEditActions

useEditActions drives the Save for a segment geometry edit or a waypoint authoring session.

useEditActions(options?)

options

UseEditActionsOptions

default: {}

The scope of the save and the source of a segment's draft; see UseEditActionsOptions.

Returns EditActionsModel: The EditActionsModel of the open session.

canSave

boolean

required

Whether the open session may be committed: enough handles, or a placed coordinate.

family

"segment" | "waypoint" | null

required

Which authoring session is open, or null when none is.

save

() => Promise<ToolResultOf<StudioToolOutputs, "studio.itinerary.segment.editCommit" | "studio.itinerary.waypoint.editCommit"> | null>

required

Commits the open session, and resolves to the answer of its family's commit verb, typed by that verb.

useEscapeKey

useEscapeKey runs handler whenever the Escape key is pressed, for as long as enabled is true.

useEscapeKey(handler, enabled?)

handler

(event: KeyboardEvent) => void

required

Runs with the keydown event, so it can preventDefault.

enabled

boolean

default: true

Whether the listener is attached.

useInlineRename

useInlineRename is rename-in-place: open on a name, commit on Enter, cancel on Escape or blur. An Enter or an Escape pressed inside an input method's composition confirms or cancels the composition and does neither.

useInlineRename(options)

options

UseInlineRenameOptions

required

The name, the commit and the guards; see UseInlineRenameOptions.

Returns InlineRename: The InlineRename state machine, a new object only when editing or value changes.

cancel

() => void

required

Closes the field and puts the current name back.

commit

() => void

required

Commits the typed name, by the rules UseInlineRenameOptions states.

editing

boolean

required

Whether the field is open.

inputProps

{ readonly onBlur: () => void; readonly onChange: (event: { readonly currentTarget: { readonly value: string } }) => void; readonly onKeyDown: (event: KeyboardEvent<HTMLInputElement>) => void; readonly value: string }

required

The handlers and the value to spread onto a DOM <input>.

setValue

(value: string) => void

required

Replaces what the field holds, for an input that is not a DOM <input>.

start

() => void

required

start opens the field on the current name, and does nothing while the rename is locked. A row whose single click does something else cancels that action itself, as useSegmentRow's startRename does.

value

string

required

What the field holds: the text as typed while it is open.

useLiveAwareSegments

useLiveAwareSegments overlays the in-flight segment edit onto a persisted segment chain so the header totals, the segment rows and the elevation chart all read the same live-edit metrics.

useLiveAwareSegments(segments)

segments

ItineraryViewSource["segments"]

required

The persisted chain, as the open itinerary holds it.

Returns ItineraryViewSource["segments"]: The chain with the live edit or the peers' drafts folded in, or segments itself when there is nothing to fold.

useMapHoveredRow

useMapHoveredRow tells one editor row whether the pointer is over ITS feature on the map, and scrolls it into view when it becomes so. It is the receiving half of the map→list hover: the map records which segment or waypoint the pointer entered, and each row reads only whether that record names it.

useMapHoveredRow<TElement>(kind, id)

kind

ItinerarySelection["kind"]

required

Whether the row stands for a segment or a waypoint.

id

string

required

The id of the entity the row stands for.

Returns MapHoveredRow<TElement>: Whether the row's feature is hovered, and the ref to hang on the row.

hovered

boolean

required

Whether the pointer is over this row's feature on the map.

rowRef

RefObject<TElement | null>

required

The ref to hang on the row element, which is scrolled into view as its feature lights.

usePeerLockHolderId

usePeerLockHolderId reports the id of the PEER holding one entity's soft-lock in the given editor resource, or null when it is unheld.

usePeerLockHolderId(resource, kind, id)

resource

CollabResource | null

required

Its fields are listed under useActiveItineraryResource.

kind

CollabLockKind

required
id

string | null

required

Returns string | null

usePlatformViewer

usePlatformViewer is the viewer of a person whose memberships the client reads, ready for data.viewer on MountayaStudioHost: what they may use of the studio, and how many itineraries they may keep, as Mountaya answers it for each scope, with where the read stands.

usePlatformViewer(options)

options

UsePlatformViewerOptions

required

The client, the query cache, the scope in view, the personal space's answer and the rest of the viewer.

Returns PlatformViewerState: The viewer to hand MountayaStudioHost as data.viewer, and the read's status and error.

error

MountayaError | null

required

The read's last failure, as the client raised it: a 402 for an organization that does not hold Embedded Studio, a 403 for a key without the studio-embedded scope, a 5xx where the API failed. Null while nothing has failed.

status

"error" | "pending" | "success"

required

Where the memberships read stands:

viewer

StudioViewer

required

The viewer to hand MountayaStudioHost as data.viewer.

usePluginSlot

usePluginSlot reads what is installed in one slot, gated and ordered, ready to render.

usePluginSlot<TSlot>(slot, target)

slot

TSlot

required

The slot to read, as a plugin names it.

target

StudioPluginTarget<TSlot> | null

required

What the contributions act on, or null to draw nothing.

Returns readonly StudioPluginItem<TSlot>[]: The contributions that pass their gates, in order, one array while they stand.

useSegmentList

useSegmentList is everything a segment list is except its markup: the chain folded into the models its rows and gutters read, the verbs neither of them owns, and the flags that decide whether a new edit may begin at all.

useSegmentList(options)

options

UseSegmentListOptions

required

The itinerary, its committed chain and the list's callbacks; see UseSegmentListOptions.

Returns SegmentListModel: The SegmentListModel a list renders from.

actions

SegmentListActions

required

The verbs the list dispatches that a row does not.

agentDriving

boolean

required

True while a run drives the workspace: every entry point into a new edit stands down.

chainEnds

SegmentChainEnds

required

The ends of the committed chain, which decide what a row at either end offers.

groupRuns

ReadonlyMap<string, SegmentGroupRun>

required

The grouping fold, keyed by segment id.

isEditing

boolean

required

True while ANY authoring engine owns the map: segment, waypoint or zone.

liveSegments

ItineraryViewSource["segments"]

required

The committed chain with the in-flight edit overlaid: what the list RENDERS.

lockHolderIds

ReadonlyMap<string, string>

required

Who holds each locked segment, keyed by segment id. Absent means free.

merges

SegmentChainMerges

required

The merges the committed chain allows, read by the gutters and the row menus alike.

seams

readonly SegmentSeamModel[]

required

One model per rendered row, positional over liveSegments.

seamsEnabled

boolean

required

True when a gutter may offer its accelerators at all.

useSegmentRow

useSegmentRow<TElement>(options)

options

UseSegmentRowOptions

required

Returns SegmentRow<TElement>: The SegmentRow a renderer draws from.

active

boolean

required

True while the pointer or the keyboard is on the row, or its menu is open.

actions

SegmentRowActions

required

The row's verbs, each bound to its itinerary and segment.

editGeometry

() => void

required

Opens the geometry editor, deferred so a double-click can cancel it.

mapHovered

boolean

required

True while the pointer is over THIS segment's line on the map.

menuOpen

boolean

required

Whether the row's menu is open, which pins its trigger visible.

pluginTarget

StudioPluginTarget<"segment.menu">

required

What a segment.menu plugin contribution acts on, held stable.

posture

SegmentRowPostureState

required

What the row is allowed to be, as one closed choice.

rename

InlineRename

required

The inline rename of the segment's name. Its commit is gated by the display name's rule (displayNameSchema of @mountaya/studio): a name the rule refuses leaves editing true and value as typed, and nothing is dispatched.

rowProps

{ readonly onBlur: (event: FocusEvent<HTMLElement>) => void; readonly onFocus: () => void; readonly onMouseEnter: () => void; readonly onMouseLeave: () => void; readonly ref: RefObject<TElement | null> }

required

Spread onto the row element: hover, focus and the ref the map hover scrolls.

setMenuOpen

(open: boolean) => void

required

Opens or closes the row's menu.

startRename

() => void

required

Opens the inline rename, cancelling the geometry edit the first click scheduled.

useSegmentRowActions

useSegmentRowActions binds one segment row's verbs to the studio's bus, each dispatched with the itinerary and segment the row is scoped to.

useSegmentRowActions(options)

options

UseSegmentRowActionsOptions

required

Returns SegmentRowActions

exportSegment

() => void

required

Opens the export dialog scoped to this segment.

merge

(segmentId: string) => Promise<void>

required

Folds segmentId into its successor: this row's id merges with the next segment.

lastFailure

SegmentRowFailure | null

required

The last refusal, naming the verb it came from, or null.

recolor

(color: string) => Promise<void>

required

Recolours the segment.

remove

() => Promise<void>

required

Deletes the segment, once the reader confirms.

rename

(name: string) => Promise<void>

required

Renames the segment.

setMode

(mode: SegmentEditMode) => Promise<void>

required

Changes the engine the segment is drawn with.

setSpeed

(speed: number | null) => Promise<void>

required

Sets the segment's speed in km/h, or null for the activity's default.

splitPick

() => Promise<void>

required

Arms the pick on the map where the segment is split.

toggleImportMode

() => void

required

Toggles a proposed segment between its routed and its freehand candidate.

useShallowSelector

useShallowSelector wraps a selector so its result is compared by members rather than by identity.

useShallowSelector<TState, TSlice>(selector)

selector

(state: TState) => TSlice

required

The selector to wrap, which may be written inline.

Returns ((state: TState) => TSlice): The wrapped selector, to hand to useUiStore, useStoreSlice or useStudioStore.

useStoreSlice

useStoreSlice subscribes to a slice of a store.

useStoreSlice<TState, TSlice>(store, selector)

store

ReadableStore<TState>

required
selector

(state: TState) => TSlice

required

Returns TSlice: The slice the selector reads, read again at each notification of the store.

useStreetViewCorridor

useStreetViewCorridor(bounded)

bounded

boolean

required

Whether a drop is bounded to the open itinerary. An editor passes false, accepts any covered drop, and reads no itinerary at all for it.

Returns StreetViewCorridor: The StreetViewCorridor to spread onto <StreetViewControl>.

bounds

StreetViewBounds | undefined

required

The itinerary a drop is bounded to, or undefined where nothing bounds it.

onDragEnd

() => void

required

Takes the coverage raster and the corridor band down, on every path that ends a drag.

onDragStart

() => void

required

Shows the coverage raster, and the corridor band where a drop is bounded.

onOpen

(lngLat: [number, number]) => void

required

Opens the panorama at an accepted drop, longitude first.

useStudioActivities

useStudioActivities reads the activity catalog the host resolved.

useStudioActivities()

Returns readonly CategoryActivities[]

useStudioActivityIconUrl

useStudioActivityIconUrl resolves an activity's silhouette to an image URL.

useStudioActivityIconUrl()

Returns ((slug: string) => string | undefined)

useStudioApi

useStudioApi()

Returns StudioApi | undefined

cache

StudioCache

required
client

Mountaya

required
persistence

StudioPersistence

required

persistence is where a committed write GOES, as distinct from what a read comes back through.

useStudioAppOrigin

useStudioAppOrigin answers the origin a link that leaves this tab is built from.

useStudioAppOrigin()

Returns string

useStudioBillingGate

useStudioBillingGate(organizationId)

organizationId

string | null

required

Returns StudioBillingGate: The host's gate for it, or a gate that places no prompt and takes no refusal where no host binding is mounted.

limitPrompt

ReactNode

What the host wants to say where a create would exceed the itinerary ceiling of its scope, or undefined. On Mountaya's platform that ceiling is the personal space's, which no agreement changes.

publicationPrompt

ReactNode

What the host wants to say where a resource has NO ORGANIZATION to bill at all, or undefined.

handleRefusal

(result: ToolResult, retry: () => void, subject: StudioBillingSubject) => boolean

required

handleRefusal takes a finished dispatch the host may be able to recover.

useStudioCache

useStudioCache is createStudioCache with the provider's credential already bound.

useStudioCache(queryClient)

queryClient

QueryClient

required

Returns StudioCache

evict

(key: ResourceRef) => void

Remove a resource's entry, so a later get of it answers undefined.

get

<Kind extends keyof StudioCacheValues>(key: StudioCacheRef<Kind>) => StudioCacheValues[Kind] | undefined

required

The value currently cached for a resource, or undefined when nothing has read it yet.

invalidate

(...keys: readonly ResourceRef[]) => Promise<void>

required

Mark these resources stale, so the next read fetches the persisted truth.

set

<Kind extends keyof StudioCacheValues>(key: StudioCacheRef<Kind>, value: StudioCacheValues[Kind]) => void

required

Seed a resource with a value the handler already has.

useStudioClock

Where a product-meaningful moment or delay comes from.

useStudioClock()

Returns Clock

after

(delayMs: number, run: () => void) => () => void

required

Schedules run after delayMs, and returns the cancel. Calling it twice is safe.

now

() => number

required

The current instant, in epoch milliseconds.

useStudioContext

useStudioContext<TCtx, TInputs, TOutputs>()

Returns StudioContextValue<TCtx, TInputs, TOutputs>

activities

readonly CategoryActivities[]

required

The activity catalog, empty where the host supplied none.

activityIconUrl

((slug: string) => string | undefined) | null

required

Where an activity's silhouette is fetched as an image, or null where the host said none.

layerThumbnail

((kind: StudioLayerKind, slug: string) => string | undefined) | null

required

The picture of a map layer, or null where the host said none.

appOrigin

string | null

required

The origin a link that leaves the tab is built from, or null for the page's own.

bus

(ToolBusDispatch<TCtx, TInputs, TOutputs> & ToolBusObserveOverrides) | null

required

The bus every dispatch runs through, or null where none is mounted.

capabilities

ReadonlySet<ToolCapability>

required

What this studio grants.

context

TCtx | null

required

The tool context each verb is handed, or null where none is mounted.

demUrl

string | undefined

required

The elevation raster the maps bake their relief from, or undefined for flat relief.

header

StudioHeaderOverride | undefined

required
languageMark

((language: MapLanguage) => ReactNode) | null

required

The mark a language picker draws beside each language, or null for none.

languages

readonly { label: string; value: MapLanguage }[]

required

The languages the studio's pickers offer, each labelled by its endonym.

navigation

NavigationSeam | null

required
resolvePeerName

StudioPeerNameSeam | null

required

How a collaborator's id becomes a name, or null where the host supplied no directory.

controlAnchors

StudioControlAnchors

required

Where a floating panel finds the toggle that opened it.

density

StudioDensity

required

How tightly the studio draws its own regions.

tokens

StudioTokens | null

required

The --mtya-* overrides the host declared, or null for none.

seams

StudioSeams

required

The capabilities the studio takes from the world around it, folded onto the defaults.

store

UiStoreApi | null

required

The studio's state, or null where no store is mounted.

strings

StudioStrings

required

The studio's own words, in the selected language with every override merged.

useStudioControlAnchors

Where a floating panel finds the toggle that opened it.

useStudioControlAnchors()

Returns StudioControlAnchors

anchorFor

(kind: StudioControlKind) => HTMLElement | null

required

The element a panel's outside-click must not treat as outside, or null.

register

(kind: StudioControlKind, element: HTMLElement | null) => void

required

Records the element a control occupies, or clears it with null on teardown.

useStudioDemUrl

useStudioDemUrl()

Returns string | undefined

useStudioDensity

useStudioDensity reads which tier the studio's own regions draw at.

useStudioDensity()

Returns StudioDensity

useStudioDispatch

useStudioDispatch()

Returns UseStudioDispatch: The UseStudioDispatch of this render.

dispatch

StudioDispatchFn

required

dispatch runs a studio tool and resolves its result. It never rejects: with no studio above it the answer is a refusal, and so is a rejection of a host's own bus.

pending

boolean

required

pending is true from the moment a dispatch starts until it settles.

useStudioDispatchUnsafe

useStudioDispatchUnsafe<TCtx>()

Returns UseStudioDispatchUnsafe: The UseStudioDispatchUnsafe of this render.

dispatch

StudioDispatchUnsafeFn

required

dispatch runs a tool and resolves its result. It never rejects: with no studio above it the answer is a refusal, said once on the console, and so is a rejection of a host's own bus.

pending

boolean

required

pending is true from the moment a dispatch starts until it settles.

useStudioEntitlement

useStudioEntitlement reports whether the viewer holds an entitlement, live.

useStudioEntitlement(entitlement)

entitlement

StudioEntitlement

required

The entitlement asked about.

Returns boolean: Whether the viewer holds it, read again when the viewer says it changed.

useStudioFailureAlert

useStudioFailureAlert()

Returns StudioFailureReporter: The StudioFailureReporter, one function for the caller's life.

useStudioFormatters

How a number, a date and a relative moment reach a screen, in this studio's locale.

useStudioFormatters()

Returns StudioFormatters

dateTimePattern

() => string

required

The pattern a date-time FIELD is written and read in, as Unicode LDML date-field symbols (DD/MM/YYYY HH:mm): the spelling dayjs, Swift's DateFormatter and Java's DateTimeFormatter all take.

formatClock

(durationMs: number) => string

required

A video's elapsed or total position, as m:ss.

formatDateTime

(value: Date, options?: Intl.DateTimeFormatOptions) => string

required

An instant, as a date and a time. A Date that holds no instant reads as the empty string.

formatNumber

(value: number, options?: Intl.NumberFormatOptions) => string

required

A plain number, grouped and rounded the way the locale writes numbers.

formatPercent

(value: number, options?: Intl.NumberFormatOptions) => string

required

A share of a whole, as a RATIO: 0.45 reads as "45%".

formatRelativeTime

(value: number, unit: StudioRelativeUnit, options?: Intl.RelativeTimeFormatOptions) => string

required

A signed offset from now (negative is in the past), as "2 days ago" or "in 6 hours". An offset that is no finite number reads as the empty string.

useStudioGeolocation

Where a device fix comes from, and whether asking would prompt.

useStudioGeolocation()

Returns GeolocationSeam

locate

(options?: GeolocationFixOptions) => Promise<GeolocationFix>

required

Asks for the device's position. Prompts the user in a browser.

permission

() => Promise<GeolocationPermission>

required

What asking would do, without asking. It prompts nobody.

useStudioHeader

useStudioHeader reads what the host put in place of the studio's own brand lockup.

useStudioHeader()

Returns StudioHeaderOverride | undefined

useStudioLanguageMark

useStudioLanguageMark reads the mark a language picker draws beside each language.

useStudioLanguageMark()

Returns ((language: MapLanguage) => ReactNode) | undefined

useStudioLanguages

useStudioLanguages reads which languages this studio's pickers offer, already labelled.

useStudioLanguages()

Returns readonly { label: string; value: MapLanguage }[]

useStudioLayerThumbnail

useStudioLayerThumbnail resolves a map layer's slug to a picture of it.

useStudioLayerThumbnail()

Returns ((kind: StudioLayerKind, slug: string) => string | undefined)

Where a link to somewhere outside the product goes, or that there is none.

useStudioLinks()

Returns StudioLinks

placeAt

(position: [number, number], name?: string) => string | null

required

A link to this coordinate on an external map, or null when there is none to offer.

useStudioMapSeams

The capabilities the studio takes from the world around it, as this tree was wired with them.

useStudioMapSeams()

Returns StudioSeams

cameraPlanner

CameraPlanner

required

Where a Camera Plan is resolved into per-frame poses, and therefore on which thread.

clock

Clock

required

Where a product-meaningful moment or delay comes from.

formatters

StudioFormatters

required

How a number, a date and a relative moment reach a screen.

geolocation

GeolocationSeam

required

Where a device fix comes from, and whether asking would prompt.

ids

StudioIds

required

Where a client-side id comes from, for a draft that has no resource to name yet.

links

StudioLinks

required

Where a link to somewhere outside the product goes, or that there is none.

saveFile

StudioSaveFile

required

Where a file the studio produced goes: a disk, a share sheet, or nowhere.

storage

StudioStorage

required

Where a preference that outlives a session is kept.

useStudioNavigationBlock

useStudioNavigationBlock holds a departure the studio is not ready to allow.

useStudioNavigationBlock(options)

options

{ readonly blockUnload: () => boolean; readonly shouldBlock: (attempt: StudioNavigationAttempt) => boolean }

required

Returns StudioNavigationHold: The hold the host's router binding answers, or one that holds nothing where no binding is mounted.

blocked

boolean

required

Whether a navigation is being held right now, waiting for an answer.

proceed

() => void

required

Let the held navigation through.

reset

() => void

required

Abandon the held navigation and stay.

useStudioNotify

useStudioNotify()

Returns StudioNotify

error

(message: string) => void

required

Reports something that failed.

success

(message: string) => void

required

Reports something that landed.

warning

(message: string) => void

required

Reports something that landed in part, or that the reader should know before going on.

useStudioObserve

useStudioObserve reports every dispatch the studio makes to observer, for as long as the calling component is mounted.

useStudioObserve(observer)

observer

ToolDispatchObserver

required

Told of each dispatch once it completes; it may be written inline.

useStudioOrganizations

useStudioOrganizations reads the roster the host supplied, or the inert one where it states none.

useStudioOrganizations()

Returns StudioOrganizations

isPersonalScope

(organizationId: string | null | undefined) => boolean

required

isPersonalScope answers whether an organization id means "the viewer's own", rather than a real organization.

writeRefusal

(resource: StudioWriteResource, organizationId: string | null | undefined) => StudioWriteRefusal | null

writeRefusal answers why the scope organizationId names refuses a write of resource, or null where it takes it: personal where the viewer's own space holds no such resource, and agreement where the organization's agreement does not include what the write needs.

readable

{ readonly isPending: boolean; readonly options: readonly OrganizationScopeOption[] }

required

The scopes whose folders the viewer may look at, viewer-role memberships included.

writable

{ readonly defaultOrganizationId: string | null; readonly options: readonly WritableOrganizationOption[]; readonly writableOrgIds: ReadonlySet<string> }

required

The organizations the viewer may create in, and the write roles that decide who edits an itinerary or a zone: writableOrgIds is the set the editor's edits and the editing verbs read (StudioScopeSeam.writable of @mountaya/studio).

useStudioPeerName

useStudioPeerName reads how a collaborator's id becomes a name, for ONE organization.

useStudioPeerName(organizationId)

organizationId

string | null

required

Returns PeerNameResolver

useStudioPlugins

useStudioPlugins reads the host's plugin engine, for installing and uninstalling at runtime.

useStudioPlugins()

Returns StudioPluginEngine<ReactNode>: The engine the host installs plugins into.

listeners

Set<() => void>

required
observers

Set<StudioPluginObserver>

required
plugins

Map<string, StudioPlugin<React.ReactNode>>

required

The installed declarations, by id, in install order.

entries

Map<string, readonly StudioPluginEntry<React.ReactNode>[]>

required

Each plugin's resolved entries, by id, in declaration order.

toolNames

Map<string, string>

required

Every tool name THIS registry owns, mapped to the plugin that brought it.

placed

Map<string, StudioTool>

required

The tools this registry put on the attached sink, by name: the ones it registered there and the ones it adopted where the sink had kept them.

unreleased

WeakMap<StudioPluginToolSink, Map<string, KeptTool>>

required

The names each sink would not release, by sink: each with the plugin that brought it and the tool that plugin declared.

declared

Set<string>

required

The ids a DECLARED list owns, which is the only thing sync may take back.

told

RefusalsTold

required

What the declared list read last was told of, which holds each refusal to one report while the list goes on stating it. See declaredListReporter.

index

SlotIndex<TView>

required
sequence

number

required
revision

number

required
snapshot

readonly StudioPlugin<TView>[] | null

required

The installed declarations as installed hands them back, or null when stale.

sink

StudioPluginToolSink | undefined

required
at

(slot: TSlot) => readonly StudioSlotEntry<TSlot, TView>[]

required

at returns the installed contributions for one slot, sorted, UNGATED.

installed

() => readonly StudioPlugin<React.ReactNode>[]

required

installed returns the declarations currently installed, in install order.

version

() => number

required

version is a counter that changes whenever any slot does.

subscribe

(listener: () => void) => (() => void)

required

subscribe registers a listener called after any change, and returns the detach.

observe

(observer: StudioPluginObserver) => () => void

required

observe registers a per-run telemetry observer and returns the detach.

attachTools

(sink: StudioPluginToolSink | null, onRefused?: StudioPluginRefusalReporter<TView>) => void

required

attachTools points the engine at a tool sink, moving every installed plugin's tools onto it.

install

(plugin: StudioPlugin<TView>) => void

required

install validates a plugin, registers its tools and indexes its contributions, or refuses the whole thing.

uninstall

(pluginId: string) => boolean

required

uninstall removes a plugin and everything it brought, reporting whether it was there.

sync

(plugins: readonly StudioPlugin<TView>[], onRefused?: StudioPluginRefusalReporter<TView>) => void

required

sync reconciles the installed set against a declared list, and notifies at most once.

reconcile

(id: string, plugin: StudioPlugin<TView>, onRefused: StudioPluginRefusalReporter<TView>) => boolean

required

reconcile brings one declaration of a declared list in under its id: installed where the id is new, replaced where its reference changed, and left where it is the one installed.

run

(entry: StudioSlotEntry<TSlot, TView>, ctx: StudioToolContext, target: StudioPluginTarget<TSlot>, onError?: (error: unknown) => void) => Promise<StudioPluginRunOutcome>

required

run invokes a contribution's verb and reports how it ended. It ALWAYS resolves.

dispose

() => void

required

dispose uninstalls everything and drops every listener and observer.

adopt

(plugin: StudioPlugin<TView>) => void

required

adopt is install without the notification: validate, register with rollback, then index.

register

(plugin: StudioPlugin<TView>, sink: StudioPluginToolSink) => readonly string[]

required

register puts one plugin's tools on a sink, unwinding its own partial work if one is refused.

take

(plugin: StudioPlugin<TView>, onRefused: StudioPluginRefusalReporter<TView> | undefined) => boolean

required

take is adopt with the refusal routed rather than thrown. Reports whether it landed.

report

(error: unknown, plugin: StudioPlugin<TView>, onRefused: StudioPluginRefusalReporter<TView> | undefined) => void

required

report hands a refusal to the reporter, or rethrows it when there is none.

drop

(pluginId: string) => boolean

required

drop is uninstall without the notification. Reports whether the plugin was there.

withdraw

(name: string, pluginId: string, sink: StudioPluginToolSink) => void

required

withdraw asks a sink for one name back, and remembers a name the sink would not give up.

rebuild

(slots: ReadonlySet<StudioPluginSlot>) => void

required

rebuild re-materialises exactly the slots named, and nothing else.

setSlot

(slot: StudioPluginSlot, entries: readonly StudioPluginEntry<TView>[]) => void

required

setSlot writes one slot of the index.

scope

(pluginId: string, replacing: boolean) => StudioPluginValidationScope

required

The collision scope a declaration of pluginId is validated against: the ids installed, and every tool name already taken.

notify

() => void

required

notify advances the version FIRST, so a listener reading at already sees the new list.

emit

(event: StudioPluginRunEvent) => void

required

emit reports one run to every observer, by the rule notify follows.

useStudioPreferences

useStudioPreferences is useStudioViewerPreferences over the viewer already in context.

useStudioPreferences()

Returns ViewerPreferences | null

language

string

A BCP 47 tag. Chooses the decimal separator and the localized unit name.

length

"metric" | "imperial"

pace

"per-time" | "per-distance"

The FORM a travel rate is stated in. The system still comes from length.

slope

"degrees" | "percentage"

temperature

"celsius" | "fahrenheit"

useStudioResourceKey

useStudioResourceKey resolves a resource to its cache key under the provider's credential.

useStudioResourceKey()

Returns ((key: ResourceRef) => QueryKey)

useStudioScopedStrings

useStudioScopedStrings<K>(sections, overrides?)

sections

readonly K[]

required

The sections the module reads, declared once as a constant tuple.

overrides

ScopedStudioStrings<K>

Returns Pick<StudioStrings, K>: The words of those sections, with every override above the caller folded on.

useStudioSignedIn

useStudioSignedIn reports that somebody is reading rather than nobody.

useStudioSignedIn()

Returns boolean

useStudioStorage

Where a preference that outlives a session is kept.

useStudioStorage()

Returns StudioStorage

remove

(key: StudioStorageKey) => void

required

Forgets a key. A key that was never written is not an error.

read

(key: StudioStorageKey) => string | null

required

The stored value, or null when there is none. Never throws.

write

(key: StudioStorageKey, value: string) => void

required

Stores a value. Does nothing where nothing can be stored. Never throws.

useStudioStore

useStudioStore subscribes to a slice of a studio store.

useStudioStore<TState, TSlice>(store, selector, fallback)

store

ReadableStore<TState> | null

required

The store to read, or null where none is mounted.

Its fields are listed under useStoreSlice.

selector

(state: TState) => TSlice

required

Reads the slice off the state.

fallback

TSlice

required

What the hook answers while store is null.

Returns TSlice: The slice, or fallback with no store.

useStudioStrings

The studio's own sentences, in the language the provider selected and with any overrides merged.

useStudioStrings()

Returns StudioStrings

useStudioTokens

useStudioTokens reads the --mtya-* overrides the host declared, as a style object.

useStudioTokens()

Returns Record<string, string>: One object per token set the provider holds.

useStudioToolContext

useStudioToolContext<TCtx>()

Returns TCtx: The tool context, typed as the caller names it.

useStudioUnits

useStudioUnits is useStudioViewerUnits over the viewer already in context.

useStudioUnits()

Returns UnitFormatOptions

language

string

required

A BCP 47 tag. Chooses the decimal separator and the localized unit name.

length

UnitLength

required
pace

UnitPace

required
slope

UnitSlope

required
temperature

UnitTemperature

required

useStudioUrl

useStudioUrl reads the studio's own slice of the address bar, or inertStudioUrlSeam where the host supplied none.

useStudioUrl()

Returns StudioUrlSeam

read

() => MirroredSearch

required

read answers the mirrored slice as the URL holds it now, by reference: the same object on every call until one of its values changes. A subscriber reads it once it is told, and a binding compares two reads by identity, so a read that built a new object per call would read as a change every time.

readOnce

() => MirroredSearch

required

readOnce answers the slice as the URL holds it at mount. Read once, and never subscribed.

subscribe

(listener: () => void) => () => void

required

subscribe registers a listener the host tells after each change of the mirrored slice, and returns its release, which is idempotent. A change to another part of the URL tells nobody.

write

(patch: MirroredSearch, options?: { hash?: string | undefined }) => void | Promise<void>

required

write merges a patch of the keys the studio owns into the URL. A key stated as undefined is removed. It may answer a promise that settles once the navigation has landed.

useStudioUserId

useStudioUserId is useStudioViewerUserId over the viewer already in context.

useStudioUserId()

Returns string | null

useStudioViewer

useStudioViewer is the viewer the mounted studio is showing this map to.

useStudioViewer()

Returns StudioViewer

getItineraryLimit

(organizationId?: string | null | undefined) => number | null

required

getItineraryLimit is how many itineraries the viewer may own in the scope organizationId names, or null when no ceiling is in force there: none applies, or the session has not said yet. A gate treats both the same.

getPreferences

() => ViewerPreferences | null

required
getUserId

() => string | null

required
hasEntitlement

(entitlement: TEntitlement) => boolean

required

hasEntitlement asks whether the host extends a named entitlement to this viewer right now, such as a product the viewer's agreement covers or a membership.

setPreferences

(partial: ViewerPreferences) => void

required
subscribe

(onChange: () => void) => () => void

required

subscribe registers a listener for any change to the answers above, and returns the unsubscribe.

useStudioViewerEntitlement

useStudioViewerEntitlement reports whether the host extends a named entitlement to the viewer, and renders again when that answer changes.

useStudioViewerEntitlement<TEntitlement>(viewer, entitlement)

viewer

ViewerSeam<TEntitlement>

required
entitlement

TEntitlement

required

The entitlement asked about.

Returns boolean: Whether the viewer holds it.

useStudioViewerItineraryLimit

useStudioViewerItineraryLimit reads how many itineraries the viewer may own in the scope organizationId names, and renders again when that answer changes.

useStudioViewerItineraryLimit(viewer, organizationId?)

viewer

Pick<StudioViewer, "getItineraryLimit" | "subscribe">

required
organizationId

string | null

The scope the itineraries are kept in: an organization, or the reader's own space in any spelling the host's scope predicate reads, an omitted id among them.

Returns number | null: The ceiling the viewer states for the scope, or null where none is in force: none applies, or none is known yet.

useStudioViewerPreferences

useStudioViewerPreferences reads the viewer's stated preferences and renders again when they change.

useStudioViewerPreferences<TEntitlement>(viewer)

viewer

ViewerSeam<TEntitlement>

required

Its fields are listed under useStudioViewerEntitlement.

Returns ViewerPreferences | null

Its fields are listed under useStudioPreferences.

useStudioViewerUnits

useStudioViewerUnits resolves the viewer's preferences into the options every formatter takes.

useStudioViewerUnits<TEntitlement>(viewer)

viewer

ViewerSeam<TEntitlement>

required

Its fields are listed under useStudioViewerEntitlement.

Returns UnitFormatOptions

Its fields are listed under useStudioUnits.

useStudioViewerUserId

useStudioViewerUserId reads who is reading, and renders again when that changes.

useStudioViewerUserId<TEntitlement>(viewer)

viewer

ViewerSeam<TEntitlement>

required

Its fields are listed under useStudioViewerEntitlement.

Returns string | null: The viewer's user id, or null for an anonymous reader.

useStudioWritableOrganizations

useStudioWritableOrganizations resolves the writable roster for one resource: the options a write of resource may target, each one the host's writeRefusal takes it in, and the default a form preselects among them.

useStudioWritableOrganizations(resource)

resource

StudioWriteResource

required

The resource the write creates.

Returns StudioWritableOrganizations: The targets, the default and whether there is any.

available

boolean

required

Whether a write of the resource has anywhere to go: an organization to target, or the viewer's own space where it takes the resource. False where every scope refuses it, which is the reader's cue to say why rather than offer a form.

defaultOrganizationId

string | null

required

The organization a create preselects, or null for the viewer's own space: the scope the reader is browsing where the resource can be created there, then the roster's own default where it takes the resource, and otherwise the first option that does.

options

readonly WritableOrganizationOption[]

required

The organizations a write of the resource may target, as a picker offers them.

useUiStore

useUiStore selects a slice of the studio's state and re-renders when that slice changes.

useUiStore<T>(selector)

selector

(state: UiStore) => T

required

Reads the slice off the studio's state.

Returns T: The slice.

useUiStoreApi

useUiStoreApi returns the store handle itself: the same instance the tool bus mutates.

useUiStoreApi()

Returns UiStoreApi

useUiStoreShallow

useUiStoreShallow selects several slots of the studio's state at once and re-renders only when one of their VALUES changes.

useUiStoreShallow<T>(selector)

selector

(state: UiStore) => T

required

Reads the slots off the studio's state; it may be written inline.

Returns T: The selector's answer, the previous object while its members match.

useWaypointList

useWaypointList is the list's own derivations: what to render, and who holds what.

useWaypointList(options)

options

UseWaypointListOptions

required

The itinerary and its saved waypoints; see UseWaypointListOptions.

Returns WaypointListModel: The WaypointListModel, whose rows is waypoints itself while no create draft is open.

agentDriving

boolean

required

True while a run drives the workspace: every entry point into a new edit stands down.

lockHolderIds

ReadonlyMap<string, string>

required

Who holds each locked waypoint, keyed by waypoint id. Absent means free.

rows

ItineraryViewSource["waypoints"]

required

The saved waypoints, plus the in-flight create draft when one is open.

draftWaypointId

string | null

required

The id of the row standing for the open create session, or null.

useWaypointRow

useWaypointRow<TElement>(options)

options

UseWaypointRowOptions

required

Returns WaypointRowModel<TElement>: The WaypointRowModel a renderer draws from.

actions

WaypointRowActions

required

The row's verbs, each bound to its itinerary and waypoint.

moveOnMap

(() => void) | undefined

required

Opens the move session, deferred so a double-click can cancel it, or undefined when this row has no persisted geometry to move.

lockHint

string | null

required

The resolved sentence holding this row, or null when it is free.

cancelMove

() => void

required

Cancels a move the single click scheduled, for a rename that arrived instead.

deferBodyClick

(action: () => void) => void

required

Runs a body action on the same delay moveOnMap takes, so a caller that replaces what a single click does inherits the rename carve-out rather than deriving it again.

mapHovered

boolean

required

True while the pointer is over THIS waypoint's marker on the map.

pluginTarget

StudioPluginTarget<"waypoint.menu">

required

What a waypoint.menu plugin contribution acts on, held stable.

rowRef

RefObject<TElement | null>

required

The ref to hang on the row element, which the map hover scrolls into view.

onMouseEnter

() => void

required

Emphasises the waypoint's marker on the map.

onMouseLeave

() => void

required

Gives the itinerary its emphasis back.

useWaypointRowActions

useWaypointRowActions is every mutation one waypoint row can dispatch, as a bundle.

useWaypointRowActions(options)

options

UseWaypointRowActionsOptions

required

Returns WaypointRowActions: The WaypointRowActions of the row.

lastFailure

WaypointRowFailure | null

required

The last refusal, naming the verb it came from, or null.

recolor

(color: string) => Promise<void>

required

Recolours the waypoint.

remove

() => Promise<void>

required

Deletes the waypoint, or cancels the create session on a draft's row.

rename

(name: string) => Promise<void>

required

Renames the waypoint. A name of spaces alone dispatches nothing: the field was abandoned.

setIcon

(icon: UserWaypointIcon) => Promise<void>

required

Changes the waypoint's icon.

@mountaya/studio-react/map

The hooks that bind a studio's state to the map it draws on.

useStudioConstraints

useStudioConstraints applies a host's camera constraints to the map: an effective zoom range and a max-bounds box, for where the camera sits.

useStudioConstraints(client, resolveConstraints?)

client

MapClient | null

required

The map to tell, or null while none is mounted.

resolveConstraints

StudioConstraintResolver

The host's rules for a camera centre, or none.

useStudioContextMenu

useStudioContextMenu opens the right-click context menu through the tool bus.

useStudioContextMenu(client)

client

MapClient | null

required

The map to listen on, or null before it is ready.

useStudioEnrichment

useStudioEnrichment draws the store's active enrichments on the map, stacked over the active overlay.

useStudioEnrichment(client)

client

MapClient | null

required

The map to draw on, or null while none is mounted.

useStudioItinerarySelection

useStudioItinerarySelection wires clicks on the rendered itinerary tile geometry to the bus. A click on a closed itinerary's line, marker or flag opens that itinerary for editing and selects nothing, as picking it in the side panel does. On the itinerary that is open, clicking a segment line selects that segment AND, when the reader may edit it, begins editing its geometry (a member whose role reads only selects and goes no further, as the segment list offers them no edit); clicking a waypoint marker selects that waypoint AND opens its details dialog.

useStudioItinerarySelection(client, options?)

client

MapClient | null

required

The map to read clicks and hovers on, or null while none is mounted.

options

UseStudioItinerarySelectionOptions

useStudioLayersScope

useStudioLayersScope reads the layers manifest of the map in context for the studio's scope: the organization whose collections the sidenav shows, or the personal space.

useStudioLayersScope()

useStudioMapBindings

useStudioMapBindings binds a map to the studio above it, with every binding MountayaStudio mounts on its own map.

useStudioMapBindings(client, options?)

client

MapClient | null

required

The map to bind, or null while none is mounted: every binding waits for it.

options

UseStudioMapBindingsOptions

default: {}

The answers only the caller has.

useStudioMapSync

useStudioMapSync reflects the studio's store on the map: the base terrain, the sprites and snap lines of the open itinerary, and the emphasis that matches the selection.

useStudioMapSync(client, demUrl?)

client

MapClient | null

required

The map to reflect the store on, or null while none is mounted.

demUrl

string

The host's elevation raster, which wins over the manifest's own (resolveDemUrl). With neither, the map renders flat.

useStudioOverlay

useStudioOverlay renders the user-selected category overlay (the store's activeOverlay slug) onto the map.

useStudioOverlay(client)

client

MapClient | null

required

The map to draw on, or null while none is mounted.

useStudioOverlayWithdrawal

useStudioOverlayWithdrawal takes the overlays off the studio's state when the viewer stops holding map-overlays: the active overlay is cleared and every enrichment but the points of interest is turned off, through the bus.

useStudioOverlayWithdrawal()

useStudioPeerDrafts

useStudioPeerDrafts paints each collaborator's in-flight edit on the local map as a read-only ghost, and clears it when the edit ends or the hook unmounts.

useStudioPeerDrafts(client, resolveName?)

client

MapClient | null

required

The map to paint on, or null while none is mounted.

resolveName

PeerNameResolver

Resolves a peer's display name, as the roster and the lock badges do. Without one, or until it answers for a peer, the ghost carries the peer's initials.

useStudioPoiLayers

useStudioPoiLayers shows and hides the render layers of the points-of-interest overlay to match the store's active groups.

useStudioPoiLayers(client)

client

MapClient | null

required

The map whose layers are toggled, or null while none is mounted.

useStudioPreviewSync

useStudioPreviewSync paints the map's preview overlay from the studio's store. It is the only writer of setItineraryPreview and of setItineraryExclusions in this package.

useStudioPreviewSync(client, glyphs)

client

MapClient | null

required

The map to paint on, or null while none is mounted.

glyphs

PreviewGlyphs

required

The marker vocabulary the previews are drawn with.

useStudioSegmentEditing

useStudioSegmentEditing owns the live interaction layer of a segment geometry edit, active only while an edit session is open.

useStudioSegmentEditing(client, collabEngine)

client

MapClient | null

required

The map the edit runs on, or null while none is mounted.

collabEngine

PeerDraftSink | null

required

The collaboration session the live segment is forwarded to, or null when the studio has none.

useStudioSegmentViaPrompt

useStudioSegmentViaPrompt opens the segment handle prompt through the tool bus.

useStudioSegmentViaPrompt(client)

client

MapClient | null

required

The map to listen on, or null before it is ready.

useStudioSplitPicking

useStudioSplitPicking turns a map click into a segment split while a split pick is armed.

useStudioSplitPicking(client, options?)

client

MapClient | null

required

The map to pick on, or null while none is mounted.

options

UseStudioSplitPickingOptions

The pin the pick wears, and the units its tooltip reads in. Omitted, the pick wears the studio's own pin and reads in the viewer's units.

useStudioSuggestionPicking

useStudioSuggestionPicking owns the live interaction layer of the suggest flow's start/end point pick, active only while the open suggest session's picking slot names an endpoint.

useStudioSuggestionPicking(client)

client

MapClient | null

required

The map to pick on, or null while none is mounted.

useStudioTimestamp

useStudioTimestamp applies the store's overlay timestamp to everything on the map that depends on the time. A null timestamp means now.

useStudioTimestamp(client)

client

MapClient | null

required

The map to apply the time to, or null while none is mounted.

useStudioUrlState

useStudioUrlState bridges the studio's URL and its map state in both directions.

useStudioUrlState(url)

url

StudioUrlSeam

required

Its fields are listed under useStudioUrl.

useStudioWaypointEditing

useStudioWaypointEditing owns the live interaction layer of a waypoint authoring session, active only while the store's waypointEditSession slot is open.

useStudioWaypointEditing(client)

client

MapClient | null

required

The map the edit runs on, or null while none is mounted.

useStudioZoneEditing

useStudioZoneEditing owns the live interaction layer of a zone geometry edit, active only while the store's zoneEditSession slot is open.

useStudioZoneEditing(client, collabEngine)

client

MapClient | null

required

The map the edit runs on, or null while none is mounted.

collabEngine

PeerDraftSink | null

required

The zone's collaboration session the drafts are forwarded to, or null for a personal zone.

Its fields are listed under useStudioSegmentEditing.

useStudioZoneOriginPicking

useStudioZoneOriginPicking owns the live interaction layer of the zone panel's reachability origin pick, active only while the store's zoneOriginPicking flag is armed.

useStudioZoneOriginPicking(client)

client

MapClient | null

required

The map to pick on, or null while none is mounted.

useStudioZoneSelection

useStudioZoneSelection wires interaction with the rendered zone tile geometry to the bus.

useStudioZoneSelection(client, options?)

client

MapClient | null

required

The map to read clicks on, or null while none is mounted.

options

UseStudioZoneSelectionOptions

@mountaya/studio-react/import

Bringing an itinerary in from somewhere else.

useImportRoutingGuide

useImportRoutingGuide returns the guide's opener. Both halves of the import flow reach it: the dropzone step, where the reader has not yet seen what matching a recording to the trail network does, and the staging list, where the per-segment toggles act on it.

useImportRoutingGuide()

Returns ImportRoutingGuideControls

open

() => void

required

@mountaya/studio-react/copilot

The studio's co-pilot, for a host that arranges its own studio.

useStudioCopilotInset

useStudioCopilotInset reports how much of the left edge the co-pilot's panel covers, in CSS pixels: the panel's width while it is open, and 0 while it is shut.

useStudioCopilotInset()

Returns number: The width the panel covers at the left edge, or 0.