Hooks
Each hook is listed under the narrowest entry point that exports it.
React bindings for the Mountaya API client.
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?)
queryKeyQueryKey
The entry the read caches under.
queryFn(options: RequestOptions) => Promise<TQueryFnData>
The read, handed TanStack's AbortSignal to pass on to each call.
optionsMountayaQueryOptions<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 returns mountayaKeys with the provider's credential already bound.
useMountayaKeys()
Returns MountayaKeys
all() => QueryKey
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
One operation under this credential, optionally narrowed by its arguments and, on the Data API, by its field selection.
scope() => QueryKey
This credential's reads, for a sign-out or a rotated share token.
surface(surface: Surface) => QueryKey
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>
The write, called with the variables mutate is handed.
optionsOmit<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<S, Op, Sel, TData>(surface, operationId, args?, options?)
surfaceS
operationIdOp
argsOperationArgsOf<S, Op>
The operation's arguments, or its input on the Data API. Omitted for an operation that takes none.
optionsMountayaQueryOptions<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 is collectionQueryOptions bound to the provider's client.
useCollection<TData>(collectionId, options?)
collectionIdstring | undefined
The collection to read. The read stays idle while it is undefined or empty.
optionsMountayaResourceQueryOptions<RestSchema.Collection, TData>
TanStack's options: enabled joins the id's gate, and select is handed the record.
Returns UseQueryResult<TData, MountayaError>
useCollectionSpecification is collectionSpecificationQueryOptions bound to the provider's client.
useCollectionSpecification<TData>(collectionId, options?)
collectionIdstring | undefined
The collection whose specification to read. The read stays idle while it is undefined or empty.
optionsMountayaResourceQueryOptions<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 is collectionsInfiniteQueryOptions bound to the provider's client.
useCollections<TData>(query?, options?)
queryParameters<typeof collectionsInfiniteQueryOptions>[1]
The listing's filters, its sort and its page size. Omitted, every collection the credential reaches, most recently changed first.
optionsMountayaListingQueryOptions<RestSchema.Collection[], TData>
TanStack's options: enabled gates the read, and select is handed the rows.
Returns UseInfiniteQueryResult<TData, MountayaError>
useItineraries is itinerariesInfiniteQueryOptions bound to the provider's client.
useItineraries<TData>(query?, options?)
queryParameters<typeof itinerariesInfiniteQueryOptions>[1]
The listing's filters, its sort and its page size. Omitted, every itinerary the credential reaches, most recently changed first.
optionsMountayaListingQueryOptions<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 is itineraryQueryOptions bound to the provider's client.
useItinerary<TData>(itineraryId, options?)
itineraryIdstring | undefined
The itinerary to read. The read stays idle while it is undefined or empty.
optionsMountayaResourceQueryOptions<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 is itinerarySpecificationQueryOptions bound to the provider's client.
useItinerarySpecification<TData>(itineraryId, options?)
itineraryIdstring | undefined
The itinerary whose specification to read. The read stays idle while it is undefined or empty.
optionsMountayaResourceQueryOptions<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 is zoneQueryOptions bound to the provider's client.
useZone<TData>(zoneId, options?)
zoneIdstring | undefined
The zone to read. The read stays idle while it is undefined or empty.
optionsMountayaResourceQueryOptions<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 is zonesInfiniteQueryOptions bound to the provider's client.
useZones<TData>(query?, options?)
queryParameters<typeof zonesInfiniteQueryOptions>[1]
The listing's filters, its sort and its page size. Omitted, every zone the credential reaches, most recently changed first.
optionsMountayaListingQueryOptions<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 reads the activity catalog: every outdoor activity type grouped by category, with the routing capabilities and tile sources each one carries.
useActivities<TData>(options?)
optionsMountayaResourceQueryOptions<RestSchema.CategoryActivities[], TData>
Its fields are listed under useCollection.
Returns UseQueryResult<TData, MountayaError>
useLayers<TData>(organizationId?, options?)
organizationIdstring
The organization whose studio scope the manifest is read for. Omitted or empty, the read names none.
optionsMountayaResourceQueryOptions<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 keeps a session token fresh, and hands the client a session that waits for the first one.
useSessionToken(options)
optionsUseSessionTokenOptions
The mint, and whether to mint at all.
Returns UseSessionTokenResult
errorunknown
The last mint failure: whatever your mint rejected with, which is why it is unknown. Minting is retried on schedule regardless.
expiresAtDate | undefined
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
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.
isLoadingboolean
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
Mint now, replacing any pending refresh, or join the mint already out, so repeated calls during one mint cost one call to your endpoint.
sessionSessionTokenSource
The session, for the client's credential: new Mountaya({ credential: { publishableKey, sessionToken: session } }).
tokenstring | undefined
The current token, or undefined before the first mint completes.
useMountaya returns the client from the nearest provider.
useMountaya()
Returns Mountaya: The client the nearest MountayaProvider hands down.
adminReturnType<typeof bindRest>["admin"]
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.
agentReturnType<typeof bindRest>["agent"]
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.
dataReturnType<typeof bindData>
The GraphQL Data API: directions, search, terrain, isochrones, matrices. Each method resolves to the operation's own field, with no envelope.
studioReturnType<typeof bindRest>["studio"]
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.
tilesReturnType<typeof bindTiles>
The Tile API's style specifications. Each method resolves to the response envelope.
transportMountayaTransport
The transport every method calls through: for a call this client binds no method for, and for the openers of @mountaya/client/events.
useMountayaOrNull returns the client from the nearest provider, or null when there is none.
useMountayaOrNull()
Returns Mountaya | null
Its fields are listed under useMountaya.
Just the bearing.
useBearing()
Returns number: The bearing in degrees, and 0 with no map and in a server render.
The whole camera, refreshed when the map settles after a move.
useCamera()
Returns Camera
center[number, number]
zoomnumber
bearingnumber
pitchnumber
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.
Whether the zoom has reached a threshold: true at the threshold and above it.
useZoomAtLeast(threshold)
thresholdnumber
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 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
Selects the terrain with this slug and switches the map's base to it.
setOverlay(slug: string | null) => void
Passing the slug already selected clears it, which is what a second press means.
toggleEnrichment(slug: string) => void
Turns the enrichment with this slug on when it is off, and off when it is on.
manifestRestSchema.Layers | null
The manifest, or null until it has been read from the current map.
terrainsreadonly RestSchema.Terrain[]
The manifest's terrains, in its order; empty until it has been read.
classicCategoriesreadonly RestSchema.CategoryOverlays[]
The categories whose overlays replace one another, in the manifest's order.
enrichmentCategoriesreadonly RestSchema.CategoryOverlays[]
The categories whose overlays stack, in the manifest's order.
terrainstring | null
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.
overlaystring | null
The selected classic overlay's slug, or null while none is selected.
enrichmentsreadonly string[]
The selected enrichments' slugs, in the order they were turned on.
errorError | null
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 reads the layers catalogue the map already holds.
useMountayaLayersManifest()
Returns UseMountayaLayersManifestResult
manifestLayers | null
The catalogue of the provider's map, or null until it has been read from that map.
errorError | null
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 reads the sections one element renders, with that element's own overrides folded on.
useMountayaScopedStrings<K>(sections, overrides?)
sectionsreadonly K[]
The sections the element renders, and the only ones an override may name.
overridesScopedElementStrings<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 binds SearchEngine to a component: props in, a snapshot out, React's own subscription in between.
useSearch(input)
inputUseSearchOptions
Returns UseSearchResult
retry() => void
Re-runs the current query from the top: what a failed section's retry is wired to.
snapshotSearchSnapshot
useSearchKeyboard owns ↑/↓/Enter/Escape over the rows a search is showing.
useSearchKeyboard(options)
optionsUseSearchKeyboardOptions
Returns UseSearchKeyboardResult
onKeyDown(event: KeyboardEvent<HTMLInputElement>) => void
rowCountnumber
How many rows the cursor can reach, for a caller rendering the highlight.
React over a map a host drives through a MapClient.
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)
clientMapClient | null
The client <EditorMapView> or <ViewerMapView> handed out, or null before it has.
languagestring | undefined
A BCP 47 tag, or undefined for English.
useTilesAccessRequired reports whether the Tile API is refusing the map's tile fetches for want of access.
useTilesAccessRequired(client)
clientMapClient | null
Returns boolean: true while a refusal of access stands for this client, and false while none does and while client is null.
The elements that need no map.
useElevationSeries reads an itinerary's profile out of its GeoJSON, once per itinerary.
useElevationSeries(input)
inputProfileInput | null | undefined
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.
seriesElevationSeries
domainReturnType<typeof profileDomain>
useItineraryResource resolves an itinerary by id, through the client on the provider.
useItineraryResource(options)
optionsUseItineraryResourceOptions
Returns ItineraryResource
geojsonProfileInput | null
The itinerary's geometry, ready to profile, or null until it has resolved.
characteristicsItineraryCharacteristics | null
The server's own figures, folded from the chain, or null until it has resolved.
segmentsreadonly ItinerarySegmentInput[] | null
The authored chain with its groups collapsed: a table's rows and a chart's chips.
waypointsreadonly Waypoint[] | null
The itinerary's own waypoints: the pins on the curve and the names under the axis.
resolvingboolean
Whether the itinerary is being read.
errorError | null
Why the itinerary could not be read, or null while nothing has failed.
useItinerarySegmentRows derives a table's rows, and the one curve every row lights part of.
useItinerarySegmentRows(options)
optionsUseItinerarySegmentRowsOptions
Returns UseItinerarySegmentRowsResult
rowsreadonly ItinerarySegmentRow[]
polylinestring
The whole itinerary's curve, built ONCE and shared by every row's sparkline.
areastring
useMapFeatureHover reports what the pointer is over on the map, if there is a map.
useMapFeatureHover(enabled?)
enabledboolean
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
segmentIdstring | null
The leg under the cursor, or null when the pointer is not on the route.
waypointIdstring | null
The place under the cursor, or null.
useProfileMarker shows the hovered point of a profile on the map, if there is a map.
useProfileMarker(point, options?)
pointElevationPoint | null
The hovered point, or null to take the pin down.
optionsUseProfileMarkerOptions
default: {}
How the pin is drawn and the id it is held under.
useProfileRange holds the stretch of itinerary a chart is drawn over.
useProfileRange(options)
optionsUseProfileRangeOptions
Returns UseProfileRangeResult
rangeProfileRange
setRange(next: ProfileRange) => void
useSegmentEmphasis lights the leg a reader is pointing at, if there is a map.
useSegmentEmphasis(geometry, options?)
geometryGeoJSON.Geometry | null
The leg to light, or null to take the lit stretch down.
optionsUseSegmentEmphasisOptions
default: {}
How the lit stretch is drawn.
useWaypointCard derives everything a card about one place states, and renders nothing.
useWaypointCard(options)
optionsUseWaypointCardOptions
Returns UseWaypointCardResult
amenitiesreadonly WaypointCardAmenity[]
contactreadonly WaypointContactRow[]
emptyboolean
True when the place states no FACTS at all.
headlinestring | null
The author's description, or a sentence assembled from what the place records.
linksreadonly WaypointCardLink[]
Every media link the place records, in the author's order: what waypointMediaLinks of @mountaya/elements/profile answers for the place.
photosreadonly WaypointPhotoDetail[]
The photos a renderer may load, in the author's order: what waypointMediaPhotos of @mountaya/elements/profile answers for the place.
propertiesreadonly WaypointCardProperty[]
timingreadonly WaypointCardRow[]
useProfilePlot reads the plot a component is being drawn into.
useProfilePlot()
Returns ProfilePlot
totalDistancenumber
The itinerary's total length in meters.
rangeProfileRange
The stretch of itinerary the plot is drawn over, in meters from its start.
x(distance: number) => number
Where a distance sits horizontally, as a percentage of the plot.
y(elevation: number) => number
Where an elevation sits vertically, as a percentage of the plot.
curveAt(distance: number) => PlotPosition | null
Where a distance lands on the curve, or null where the curve has no sample.
scrubTo(distance: number | null) => void
Moves the profile's cursor to a distance, or clears it with null.
The context these elements read, and the lifecycle primitives they are built on, with no renderer attached.
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)
valueT
Returns RefObject<T>
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)
languageMapLanguage
The language following was resolved for.
overridesTOverrides | undefined
The overrides as the render wrote them.
followingTResolved
The bundle resolved for this render.
sourceunknown
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 resolves a copy bundle, and keeps the SAME object while the overrides say the same thing.
useStableBundle<TOverrides, TResolved>(language, overrides, resolve)
languageMapLanguage
The language the bundle is resolved for. A different one resolves again, whatever the overrides say.
overridesTOverrides | undefined
The overrides as the render wrote them, compared through sameOverrides.
resolve(language: MapLanguage, overrides: TOverrides | undefined) => TResolved
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.
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 }> } }
The glyph set the map controls draw with: the provider's controlIcons.
useMountayaControlIcons()
Returns IconProvider
namestring
Identifies the set in diagnostics and in the sprite image ids.
paintGlyphPaint
Whether the caller paints these glyphs by filling their shapes or by stroking their outlines. Getting this wrong renders nothing, silently.
strokeWidthnumber
Stroke width in viewBox units. Meaningful only when paint is "stroke".
viewBoxnumber
The square viewBox the markup is authored against.
has(glyph: string) => boolean
Whether this set can draw the named glyph.
markup(glyph: string) => string | undefined
The inner SVG markup for a glyph, or undefined when the set has no such glyph.
names() => readonly string[]
Every glyph name this set can draw, sorted.
useMountayaLanguage()
Returns MapLanguage
The locale the provider selected, for everything that WRITES a number rather than a word.
useMountayaLocale()
Returns string
The map the controls drive, or null before it is ready and when there is no map.
useMountayaMap()
Returns MountayaMap | null
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.
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.
layerRanksReadonly<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.
The copy the elements render. English unless the provider was given overrides.
useMountayaStrings()
Returns ElementsStrings
amenitiesAmenityStrings
controlsControlStrings
layersLayersStrings
poisPoiStrings
preferencesPreferencesStrings
profileProfileStrings
searchSearchStrings
streetViewStreetViewStrings
tableTableStrings
tooltipsTooltipStrings
videoOverlayVideoOverlayStrings
waypointCardCardStrings
waypointsWaypointStrings
The token overrides the provider was given, as the style record an element root merges.
useMountayaTokens()
Returns Record<string, string>
useMountayaUiIcons()
Returns IconProvider
Its fields are listed under useMountayaControlIcons.
Mountaya's map studio, as components.
useAgentThreads()
Returns AgentThreadsValue: The value the nearest AgentThreadsProvider hands down.
answerQuestion(entryId: string, label: string) => void
Settles a question card with the answer picked, and sends its label as the next turn.
chooseSuggestion(entryId: string, seed: number, label: string) => void
Applies one suggested route of a suggestions card, and sends the pick as the next turn.
previewCandidate(seed: number) => void
Paints one staged route on the map, by its seed.
closeAiTab(tabId: string) => void
Closes a conversation's tab, through the tool bus.
newAiTab() => void
Opens a new conversation in a tab of its own, through the tool bus.
resolveConfirmation(approved: boolean) => void
Settles the in-chat approval card with the reader's decision.
stopActive() => void
Aborts the active conversation's run. The one control left live while the agent drives.
storeAgentThreadsStoreApi
The per-mount threads store, read with narrow selectors.
submit(message: string) => void
Opens the active conversation's run with a message, or continues it.
switchTab(tabId: string) => void
Makes a tab the active one, through the tool bus.
usePeerLockLabels()
Returns ((lockHolderId: string) => string)
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?)
organizationIdstring | null
The scope a create targets, as useAgreementLimits takes it.
Returns ItineraryUsage
atLimitboolean
countnumber
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.
limitnumber | null
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?)
languagestring
The UI language the labels resolve in.
organizationIdstring
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.
isEmptyboolean
Whether a manifest arrived holding no layer. False until one has arrived.
isLoadingboolean
Whether the manifest is still loading.
overlayGroupsCatalogOptionGroup[]
The overlays, grouped under their category.
terrainOptionsCatalogOption[]
The terrains, as slug/label options.
useStudioHostRegistry reads the map-lifecycle registry the studio host owns.
useStudioHostRegistry()
Returns StudioHostRegistry
busToolBus<StudioToolContext, StudioToolInputs, StudioToolOutputs>
The studio's bus, whole.
clientMapClient | null
The studio's live map, or null before one mounts and after it tears down.
onClientDestroy() => void
Clears the studio's map.
onClientReady(client: MapClient) => void
Publishes the studio's map.
registerCollab(seam: CollabSeam) => void
Publishes the live collaboration session, so lock-aware verbs can consult it.
registerTabs(surface: TabSurface) => void
registerVideoMap(client: MapClient) => void
Publishes the video wizard's recording map, distinct from the studio's own.
unregisterCollab() => void
Clears the collaboration session; lock-aware verbs fall back to the single-editor path.
unregisterTabs() => void
unregisterVideoMap() => void
Clears the video wizard's map; a video verb then answers a structured failure.
useItinerarySubject derives a header subject from an itinerary record the caller ALREADY HOLDS.
useItinerarySubject(itinerary, loading?)
itineraryItineraryWithDetails | null | undefined
loadingboolean
default: false
Returns ItinerarySubject | null
ascentstring
distancestring
namestring
slugActivitySlug | null
useStudioItinerary reads one itinerary with every segment's analysis arrays normalized.
useStudioItinerary(itineraryId, surface?)
itineraryIdstring | undefined
surface"draft" | "published"
Returns UseQueryResult<ItineraryWithDetails, MountayaError>
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)
organizationIdstring | null | undefined
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 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)
itineraryIdstring | undefined
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.
failedboolean
The published read was attempted and refused.
itineraryItineraryWithDetails | null
loadingboolean
organizationIdstring | null | undefined
The DRAFT's owning organization: null for a personal itinerary, which belongs to none, and undefined until the draft read has answered.
publicationPublicationState
The studio's state, lifecycle and actions, with no markup of any kind.
useActiveCollabResources()
Returns readonly CollabResource[]
useActiveItineraryResource()
Returns CollabResource | null: The open itinerary's handle, or null when no itinerary is open.
idstring
kind"itineraries" | "zones"
useActiveZoneResource()
Returns CollabResource | null: The open zone's handle, or null when no zone is open.
Its fields are listed under useActiveItineraryResource.
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(activitySlug?)
activitySlugstring
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()
Returns BeginWaypointEdit: The BeginWaypointEdit callback, one function for the caller's life.
useCapability(capability)
capabilityToolCapability
The class of action asked about.
Returns boolean: Whether the studio above grants it; false outside a provider.
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 reports whether the co-pilot may run for a resource's organization.
useCopilotAvailability(organizationId)
organizationIdstring | undefined
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.
canConfigureboolean
Whether the viewer may configure a provider themselves: an owner or an admin.
configuredboolean
A provider is configured for this organization.
loadingboolean
Neither answer has arrived; every flag above defaults false while this is true.
notConfiguredboolean
A provider is definitively NOT configured, which is not the same as not yet knowing.
writableboolean
The viewer may write to this organization.
useCopilotModelLine names the provider and model a configured co-pilot runs on.
useCopilotModelLine(organizationId)
organizationIdstring | undefined
Returns string | null
useCopilotSetupAction reads the control that opens the host's provider configuration.
useCopilotSetupAction(organizationId)
organizationIdstring | undefined
Returns ReactNode
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)
organizationIdstring | undefined
Returns ReactNode
useDeferredClick defers a single-click action so a double-click can cancel it.
useDeferredClick()
Returns DeferredClick
cancel() => void
Drops the action a single click scheduled, if it has not run.
schedule(action: () => void, delayMs?: number) => void
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 drives the Save for a segment geometry edit or a waypoint authoring session.
useEditActions(options?)
optionsUseEditActionsOptions
default: {}
The scope of the save and the source of a segment's draft; see UseEditActionsOptions.
Returns EditActionsModel: The EditActionsModel of the open session.
canSaveboolean
Whether the open session may be committed: enough handles, or a placed coordinate.
family"segment" | "waypoint" | null
Which authoring session is open, or null when none is.
save() => Promise<ToolResultOf<StudioToolOutputs, "studio.itinerary.segment.editCommit" | "studio.itinerary.waypoint.editCommit"> | null>
Commits the open session, and resolves to the answer of its family's commit verb, typed by that verb.
useEscapeKey runs handler whenever the Escape key is pressed, for as long as enabled is true.
useEscapeKey(handler, enabled?)
handler(event: KeyboardEvent) => void
Runs with the keydown event, so it can preventDefault.
enabledboolean
default: true
Whether the listener is attached.
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)
optionsUseInlineRenameOptions
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
Closes the field and puts the current name back.
commit() => void
Commits the typed name, by the rules UseInlineRenameOptions states.
editingboolean
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 }
The handlers and the value to spread onto a DOM <input>.
setValue(value: string) => void
Replaces what the field holds, for an input that is not a DOM <input>.
start() => void
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.
valuestring
What the field holds: the text as typed while it is open.
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)
segmentsItineraryViewSource["segments"]
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 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)
kindItinerarySelection["kind"]
Whether the row stands for a segment or a waypoint.
idstring
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.
hoveredboolean
Whether the pointer is over this row's feature on the map.
rowRefRefObject<TElement | null>
The ref to hang on the row element, which is scrolled into view as its feature lights.
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)
resourceCollabResource | null
Its fields are listed under useActiveItineraryResource.
kindCollabLockKind
idstring | null
Returns string | null
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)
optionsUsePlatformViewerOptions
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.
errorMountayaError | null
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"
Where the memberships read stands:
viewerStudioViewer
The viewer to hand MountayaStudioHost as data.viewer.
usePluginSlot reads what is installed in one slot, gated and ordered, ready to render.
usePluginSlot<TSlot>(slot, target)
slotTSlot
The slot to read, as a plugin names it.
targetStudioPluginTarget<TSlot> | null
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 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)
optionsUseSegmentListOptions
The itinerary, its committed chain and the list's callbacks; see UseSegmentListOptions.
Returns SegmentListModel: The SegmentListModel a list renders from.
actionsSegmentListActions
The verbs the list dispatches that a row does not.
agentDrivingboolean
True while a run drives the workspace: every entry point into a new edit stands down.
chainEndsSegmentChainEnds
The ends of the committed chain, which decide what a row at either end offers.
groupRunsReadonlyMap<string, SegmentGroupRun>
The grouping fold, keyed by segment id.
isEditingboolean
True while ANY authoring engine owns the map: segment, waypoint or zone.
liveSegmentsItineraryViewSource["segments"]
The committed chain with the in-flight edit overlaid: what the list RENDERS.
lockHolderIdsReadonlyMap<string, string>
Who holds each locked segment, keyed by segment id. Absent means free.
mergesSegmentChainMerges
The merges the committed chain allows, read by the gutters and the row menus alike.
seamsreadonly SegmentSeamModel[]
One model per rendered row, positional over liveSegments.
seamsEnabledboolean
True when a gutter may offer its accelerators at all.
useSegmentRow<TElement>(options)
optionsUseSegmentRowOptions
Returns SegmentRow<TElement>: The SegmentRow a renderer draws from.
activeboolean
True while the pointer or the keyboard is on the row, or its menu is open.
actionsSegmentRowActions
The row's verbs, each bound to its itinerary and segment.
editGeometry() => void
Opens the geometry editor, deferred so a double-click can cancel it.
mapHoveredboolean
True while the pointer is over THIS segment's line on the map.
menuOpenboolean
Whether the row's menu is open, which pins its trigger visible.
pluginTargetStudioPluginTarget<"segment.menu">
What a segment.menu plugin contribution acts on, held stable.
postureSegmentRowPostureState
What the row is allowed to be, as one closed choice.
renameInlineRename
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> }
Spread onto the row element: hover, focus and the ref the map hover scrolls.
setMenuOpen(open: boolean) => void
Opens or closes the row's menu.
startRename() => void
Opens the inline rename, cancelling the geometry edit the first click scheduled.
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)
optionsUseSegmentRowActionsOptions
Returns SegmentRowActions
exportSegment() => void
Opens the export dialog scoped to this segment.
merge(segmentId: string) => Promise<void>
Folds segmentId into its successor: this row's id merges with the next segment.
lastFailureSegmentRowFailure | null
The last refusal, naming the verb it came from, or null.
recolor(color: string) => Promise<void>
Recolours the segment.
remove() => Promise<void>
Deletes the segment, once the reader confirms.
rename(name: string) => Promise<void>
Renames the segment.
setMode(mode: SegmentEditMode) => Promise<void>
Changes the engine the segment is drawn with.
setSpeed(speed: number | null) => Promise<void>
Sets the segment's speed in km/h, or null for the activity's default.
splitPick() => Promise<void>
Arms the pick on the map where the segment is split.
toggleImportMode() => void
Toggles a proposed segment between its routed and its freehand candidate.
useShallowSelector wraps a selector so its result is compared by members rather than by identity.
useShallowSelector<TState, TSlice>(selector)
selector(state: TState) => TSlice
The selector to wrap, which may be written inline.
Returns ((state: TState) => TSlice): The wrapped selector, to hand to useUiStore, useStoreSlice or useStudioStore.
useStoreSlice subscribes to a slice of a store.
useStoreSlice<TState, TSlice>(store, selector)
storeReadableStore<TState>
selector(state: TState) => TSlice
Returns TSlice: The slice the selector reads, read again at each notification of the store.
useStreetViewCorridor(bounded)
boundedboolean
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>.
boundsStreetViewBounds | undefined
The itinerary a drop is bounded to, or undefined where nothing bounds it.
onDragEnd() => void
Takes the coverage raster and the corridor band down, on every path that ends a drag.
onDragStart() => void
Shows the coverage raster, and the corridor band where a drop is bounded.
onOpen(lngLat: [number, number]) => void
Opens the panorama at an accepted drop, longitude first.
useStudioActivities reads the activity catalog the host resolved.
useStudioActivities()
Returns readonly CategoryActivities[]
useStudioActivityIconUrl resolves an activity's silhouette to an image URL.
useStudioActivityIconUrl()
Returns ((slug: string) => string | undefined)
useStudioApi()
Returns StudioApi | undefined
cacheStudioCache
clientMountaya
persistenceStudioPersistence
persistence is where a committed write GOES, as distinct from what a read comes back through.
useStudioAppOrigin answers the origin a link that leaves this tab is built from.
useStudioAppOrigin()
Returns string
useStudioBillingGate(organizationId)
organizationIdstring | null
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.
limitPromptReactNode
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.
publicationPromptReactNode
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
handleRefusal takes a finished dispatch the host may be able to recover.
useStudioCache is createStudioCache with the provider's credential already bound.
useStudioCache(queryClient)
queryClientQueryClient
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
The value currently cached for a resource, or undefined when nothing has read it yet.
invalidate(...keys: readonly ResourceRef[]) => Promise<void>
Mark these resources stale, so the next read fetches the persisted truth.
set<Kind extends keyof StudioCacheValues>(key: StudioCacheRef<Kind>, value: StudioCacheValues[Kind]) => void
Seed a resource with a value the handler already has.
Where a product-meaningful moment or delay comes from.
useStudioClock()
Returns Clock
after(delayMs: number, run: () => void) => () => void
Schedules run after delayMs, and returns the cancel. Calling it twice is safe.
now() => number
The current instant, in epoch milliseconds.
useStudioContext<TCtx, TInputs, TOutputs>()
Returns StudioContextValue<TCtx, TInputs, TOutputs>
activitiesreadonly CategoryActivities[]
The activity catalog, empty where the host supplied none.
activityIconUrl((slug: string) => string | undefined) | null
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
The picture of a map layer, or null where the host said none.
appOriginstring | null
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
The bus every dispatch runs through, or null where none is mounted.
capabilitiesReadonlySet<ToolCapability>
What this studio grants.
contextTCtx | null
The tool context each verb is handed, or null where none is mounted.
demUrlstring | undefined
The elevation raster the maps bake their relief from, or undefined for flat relief.
headerStudioHeaderOverride | undefined
languageMark((language: MapLanguage) => ReactNode) | null
The mark a language picker draws beside each language, or null for none.
languagesreadonly { label: string; value: MapLanguage }[]
The languages the studio's pickers offer, each labelled by its endonym.
navigationNavigationSeam | null
resolvePeerNameStudioPeerNameSeam | null
How a collaborator's id becomes a name, or null where the host supplied no directory.
controlAnchorsStudioControlAnchors
Where a floating panel finds the toggle that opened it.
densityStudioDensity
How tightly the studio draws its own regions.
tokensStudioTokens | null
The --mtya-* overrides the host declared, or null for none.
seamsStudioSeams
The capabilities the studio takes from the world around it, folded onto the defaults.
storeUiStoreApi | null
The studio's state, or null where no store is mounted.
stringsStudioStrings
The studio's own words, in the selected language with every override merged.
Where a floating panel finds the toggle that opened it.
useStudioControlAnchors()
Returns StudioControlAnchors
anchorFor(kind: StudioControlKind) => HTMLElement | null
The element a panel's outside-click must not treat as outside, or null.
register(kind: StudioControlKind, element: HTMLElement | null) => void
Records the element a control occupies, or clears it with null on teardown.
useStudioDemUrl()
Returns string | undefined
useStudioDensity reads which tier the studio's own regions draw at.
useStudioDensity()
Returns StudioDensity
useStudioDispatch()
Returns UseStudioDispatch: The UseStudioDispatch of this render.
dispatchStudioDispatchFn
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.
pendingboolean
pending is true from the moment a dispatch starts until it settles.
useStudioDispatchUnsafe<TCtx>()
Returns UseStudioDispatchUnsafe: The UseStudioDispatchUnsafe of this render.
dispatchStudioDispatchUnsafeFn
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.
pendingboolean
pending is true from the moment a dispatch starts until it settles.
useStudioEntitlement reports whether the viewer holds an entitlement, live.
useStudioEntitlement(entitlement)
entitlementStudioEntitlement
The entitlement asked about.
Returns boolean: Whether the viewer holds it, read again when the viewer says it changed.
useStudioFailureAlert()
Returns StudioFailureReporter: The StudioFailureReporter, one function for the caller's life.
How a number, a date and a relative moment reach a screen, in this studio's locale.
useStudioFormatters()
Returns StudioFormatters
dateTimePattern() => string
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
A video's elapsed or total position, as m:ss.
formatDateTime(value: Date, options?: Intl.DateTimeFormatOptions) => string
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
A plain number, grouped and rounded the way the locale writes numbers.
formatPercent(value: number, options?: Intl.NumberFormatOptions) => string
A share of a whole, as a RATIO: 0.45 reads as "45%".
formatRelativeTime(value: number, unit: StudioRelativeUnit, options?: Intl.RelativeTimeFormatOptions) => string
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.
Where a device fix comes from, and whether asking would prompt.
useStudioGeolocation()
Returns GeolocationSeam
locate(options?: GeolocationFixOptions) => Promise<GeolocationFix>
Asks for the device's position. Prompts the user in a browser.
permission() => Promise<GeolocationPermission>
What asking would do, without asking. It prompts nobody.
useStudioHeader reads what the host put in place of the studio's own brand lockup.
useStudioHeader()
Returns StudioHeaderOverride | undefined
useStudioLanguageMark reads the mark a language picker draws beside each language.
useStudioLanguageMark()
Returns ((language: MapLanguage) => ReactNode) | undefined
useStudioLanguages reads which languages this studio's pickers offer, already labelled.
useStudioLanguages()
Returns readonly { label: string; value: MapLanguage }[]
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
A link to this coordinate on an external map, or null when there is none to offer.
The capabilities the studio takes from the world around it, as this tree was wired with them.
useStudioMapSeams()
Returns StudioSeams
cameraPlannerCameraPlanner
Where a Camera Plan is resolved into per-frame poses, and therefore on which thread.
clockClock
Where a product-meaningful moment or delay comes from.
formattersStudioFormatters
How a number, a date and a relative moment reach a screen.
geolocationGeolocationSeam
Where a device fix comes from, and whether asking would prompt.
idsStudioIds
Where a client-side id comes from, for a draft that has no resource to name yet.
linksStudioLinks
Where a link to somewhere outside the product goes, or that there is none.
saveFileStudioSaveFile
Where a file the studio produced goes: a disk, a share sheet, or nowhere.
storageStudioStorage
Where a preference that outlives a session is kept.
useStudioNavigationBlock holds a departure the studio is not ready to allow.
useStudioNavigationBlock(options)
options{ readonly blockUnload: () => boolean; readonly shouldBlock: (attempt: StudioNavigationAttempt) => boolean }
Returns StudioNavigationHold: The hold the host's router binding answers, or one that holds nothing where no binding is mounted.
blockedboolean
Whether a navigation is being held right now, waiting for an answer.
proceed() => void
Let the held navigation through.
reset() => void
Abandon the held navigation and stay.
useStudioNotify()
Returns StudioNotify
error(message: string) => void
Reports something that failed.
success(message: string) => void
Reports something that landed.
warning(message: string) => void
Reports something that landed in part, or that the reader should know before going on.
useStudioObserve reports every dispatch the studio makes to observer, for as long as the calling component is mounted.
useStudioObserve(observer)
observerToolDispatchObserver
Told of each dispatch once it completes; it may be written inline.
useStudioOrganizations reads the roster the host supplied, or the inert one where it states none.
useStudioOrganizations()
Returns StudioOrganizations
isPersonalScope(organizationId: string | null | undefined) => boolean
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[] }
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> }
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 reads how a collaborator's id becomes a name, for ONE organization.
useStudioPeerName(organizationId)
organizationIdstring | null
Returns PeerNameResolver
useStudioPlugins reads the host's plugin engine, for installing and uninstalling at runtime.
useStudioPlugins()
Returns StudioPluginEngine<ReactNode>: The engine the host installs plugins into.
listenersSet<() => void>
observersSet<StudioPluginObserver>
pluginsMap<string, StudioPlugin<React.ReactNode>>
The installed declarations, by id, in install order.
entriesMap<string, readonly StudioPluginEntry<React.ReactNode>[]>
Each plugin's resolved entries, by id, in declaration order.
toolNamesMap<string, string>
Every tool name THIS registry owns, mapped to the plugin that brought it.
placedMap<string, StudioTool>
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.
unreleasedWeakMap<StudioPluginToolSink, Map<string, KeptTool>>
The names each sink would not release, by sink: each with the plugin that brought it and the tool that plugin declared.
declaredSet<string>
The ids a DECLARED list owns, which is the only thing sync may take back.
toldRefusalsTold
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.
indexSlotIndex<TView>
sequencenumber
revisionnumber
snapshotreadonly StudioPlugin<TView>[] | null
The installed declarations as installed hands them back, or null when stale.
sinkStudioPluginToolSink | undefined
at(slot: TSlot) => readonly StudioSlotEntry<TSlot, TView>[]
at returns the installed contributions for one slot, sorted, UNGATED.
installed() => readonly StudioPlugin<React.ReactNode>[]
installed returns the declarations currently installed, in install order.
version() => number
version is a counter that changes whenever any slot does.
subscribe(listener: () => void) => (() => void)
subscribe registers a listener called after any change, and returns the detach.
observe(observer: StudioPluginObserver) => () => void
observe registers a per-run telemetry observer and returns the detach.
attachTools(sink: StudioPluginToolSink | null, onRefused?: StudioPluginRefusalReporter<TView>) => void
attachTools points the engine at a tool sink, moving every installed plugin's tools onto it.
install(plugin: StudioPlugin<TView>) => void
install validates a plugin, registers its tools and indexes its contributions, or refuses the whole thing.
uninstall(pluginId: string) => boolean
uninstall removes a plugin and everything it brought, reporting whether it was there.
sync(plugins: readonly StudioPlugin<TView>[], onRefused?: StudioPluginRefusalReporter<TView>) => void
sync reconciles the installed set against a declared list, and notifies at most once.
reconcile(id: string, plugin: StudioPlugin<TView>, onRefused: StudioPluginRefusalReporter<TView>) => boolean
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>
run invokes a contribution's verb and reports how it ended. It ALWAYS resolves.
dispose() => void
dispose uninstalls everything and drops every listener and observer.
adopt(plugin: StudioPlugin<TView>) => void
adopt is install without the notification: validate, register with rollback, then index.
register(plugin: StudioPlugin<TView>, sink: StudioPluginToolSink) => readonly string[]
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
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
report hands a refusal to the reporter, or rethrows it when there is none.
drop(pluginId: string) => boolean
drop is uninstall without the notification. Reports whether the plugin was there.
withdraw(name: string, pluginId: string, sink: StudioPluginToolSink) => void
withdraw asks a sink for one name back, and remembers a name the sink would not give up.
rebuild(slots: ReadonlySet<StudioPluginSlot>) => void
rebuild re-materialises exactly the slots named, and nothing else.
setSlot(slot: StudioPluginSlot, entries: readonly StudioPluginEntry<TView>[]) => void
setSlot writes one slot of the index.
scope(pluginId: string, replacing: boolean) => StudioPluginValidationScope
The collision scope a declaration of pluginId is validated against: the ids installed, and every tool name already taken.
notify() => void
notify advances the version FIRST, so a listener reading at already sees the new list.
emit(event: StudioPluginRunEvent) => void
emit reports one run to every observer, by the rule notify follows.
useStudioPreferences is useStudioViewerPreferences over the viewer already in context.
useStudioPreferences()
Returns ViewerPreferences | null
languagestring
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 resolves a resource to its cache key under the provider's credential.
useStudioResourceKey()
Returns ((key: ResourceRef) => QueryKey)
useStudioScopedStrings<K>(sections, overrides?)
sectionsreadonly K[]
The sections the module reads, declared once as a constant tuple.
overridesScopedStudioStrings<K>
Returns Pick<StudioStrings, K>: The words of those sections, with every override above the caller folded on.
useStudioSignedIn reports that somebody is reading rather than nobody.
useStudioSignedIn()
Returns boolean
Where a preference that outlives a session is kept.
useStudioStorage()
Returns StudioStorage
remove(key: StudioStorageKey) => void
Forgets a key. A key that was never written is not an error.
read(key: StudioStorageKey) => string | null
The stored value, or null when there is none. Never throws.
write(key: StudioStorageKey, value: string) => void
Stores a value. Does nothing where nothing can be stored. Never throws.
useStudioStore subscribes to a slice of a studio store.
useStudioStore<TState, TSlice>(store, selector, fallback)
storeReadableStore<TState> | null
The store to read, or null where none is mounted.
Its fields are listed under useStoreSlice.
selector(state: TState) => TSlice
Reads the slice off the state.
fallbackTSlice
What the hook answers while store is null.
Returns TSlice: The slice, or fallback with no store.
The studio's own sentences, in the language the provider selected and with any overrides merged.
useStudioStrings()
Returns StudioStrings
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<TCtx>()
Returns TCtx: The tool context, typed as the caller names it.
useStudioUnits is useStudioViewerUnits over the viewer already in context.
useStudioUnits()
Returns UnitFormatOptions
languagestring
A BCP 47 tag. Chooses the decimal separator and the localized unit name.
lengthUnitLength
paceUnitPace
slopeUnitSlope
temperatureUnitTemperature
useStudioUrl reads the studio's own slice of the address bar, or inertStudioUrlSeam where the host supplied none.
useStudioUrl()
Returns StudioUrlSeam
read() => MirroredSearch
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
readOnce answers the slice as the URL holds it at mount. Read once, and never subscribed.
subscribe(listener: () => void) => () => void
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>
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 is useStudioViewerUserId over the viewer already in context.
useStudioUserId()
Returns string | null
useStudioViewer is the viewer the mounted studio is showing this map to.
useStudioViewer()
Returns StudioViewer
getItineraryLimit(organizationId?: string | null | undefined) => number | null
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
getUserId() => string | null
hasEntitlement(entitlement: TEntitlement) => boolean
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
subscribe(onChange: () => void) => () => void
subscribe registers a listener for any change to the answers above, and returns the unsubscribe.
useStudioViewerEntitlement reports whether the host extends a named entitlement to the viewer, and renders again when that answer changes.
useStudioViewerEntitlement<TEntitlement>(viewer, entitlement)
viewerViewerSeam<TEntitlement>
entitlementTEntitlement
The entitlement asked about.
Returns boolean: Whether the viewer holds it.
useStudioViewerItineraryLimit reads how many itineraries the viewer may own in the scope organizationId names, and renders again when that answer changes.
useStudioViewerItineraryLimit(viewer, organizationId?)
viewerPick<StudioViewer, "getItineraryLimit" | "subscribe">
organizationIdstring | 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 reads the viewer's stated preferences and renders again when they change.
useStudioViewerPreferences<TEntitlement>(viewer)
viewerViewerSeam<TEntitlement>
Its fields are listed under useStudioViewerEntitlement.
Returns ViewerPreferences | null
Its fields are listed under useStudioPreferences.
useStudioViewerUnits resolves the viewer's preferences into the options every formatter takes.
useStudioViewerUnits<TEntitlement>(viewer)
viewerViewerSeam<TEntitlement>
Its fields are listed under useStudioViewerEntitlement.
Returns UnitFormatOptions
Its fields are listed under useStudioUnits.
useStudioViewerUserId reads who is reading, and renders again when that changes.
useStudioViewerUserId<TEntitlement>(viewer)
viewerViewerSeam<TEntitlement>
Its fields are listed under useStudioViewerEntitlement.
Returns string | null: The viewer's user id, or null for an anonymous reader.
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)
resourceStudioWriteResource
The resource the write creates.
Returns StudioWritableOrganizations: The targets, the default and whether there is any.
availableboolean
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.
defaultOrganizationIdstring | null
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.
optionsreadonly WritableOrganizationOption[]
The organizations a write of the resource may target, as a picker offers them.
useUiStore selects a slice of the studio's state and re-renders when that slice changes.
useUiStore<T>(selector)
selector(state: UiStore) => T
Reads the slice off the studio's state.
Returns T: The slice.
useUiStoreApi returns the store handle itself: the same instance the tool bus mutates.
useUiStoreApi()
Returns UiStoreApi
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
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 is the list's own derivations: what to render, and who holds what.
useWaypointList(options)
optionsUseWaypointListOptions
The itinerary and its saved waypoints; see UseWaypointListOptions.
Returns WaypointListModel: The WaypointListModel, whose rows is waypoints itself while no create draft is open.
agentDrivingboolean
True while a run drives the workspace: every entry point into a new edit stands down.
lockHolderIdsReadonlyMap<string, string>
Who holds each locked waypoint, keyed by waypoint id. Absent means free.
rowsItineraryViewSource["waypoints"]
The saved waypoints, plus the in-flight create draft when one is open.
draftWaypointIdstring | null
The id of the row standing for the open create session, or null.
useWaypointRow<TElement>(options)
optionsUseWaypointRowOptions
Returns WaypointRowModel<TElement>: The WaypointRowModel a renderer draws from.
actionsWaypointRowActions
The row's verbs, each bound to its itinerary and waypoint.
moveOnMap(() => void) | undefined
Opens the move session, deferred so a double-click can cancel it, or undefined when this row has no persisted geometry to move.
lockHintstring | null
The resolved sentence holding this row, or null when it is free.
cancelMove() => void
Cancels a move the single click scheduled, for a rename that arrived instead.
deferBodyClick(action: () => void) => void
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.
mapHoveredboolean
True while the pointer is over THIS waypoint's marker on the map.
pluginTargetStudioPluginTarget<"waypoint.menu">
What a waypoint.menu plugin contribution acts on, held stable.
rowRefRefObject<TElement | null>
The ref to hang on the row element, which the map hover scrolls into view.
onMouseEnter() => void
Emphasises the waypoint's marker on the map.
onMouseLeave() => void
Gives the itinerary its emphasis back.
useWaypointRowActions is every mutation one waypoint row can dispatch, as a bundle.
useWaypointRowActions(options)
optionsUseWaypointRowActionsOptions
Returns WaypointRowActions: The WaypointRowActions of the row.
lastFailureWaypointRowFailure | null
The last refusal, naming the verb it came from, or null.
recolor(color: string) => Promise<void>
Recolours the waypoint.
remove() => Promise<void>
Deletes the waypoint, or cancels the create session on a draft's row.
rename(name: string) => Promise<void>
Renames the waypoint. A name of spaces alone dispatches nothing: the field was abandoned.
setIcon(icon: UserWaypointIcon) => Promise<void>
Changes the waypoint's icon.
The hooks that bind a studio's state to the map it draws on.
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?)
clientMapClient | null
The map to tell, or null while none is mounted.
resolveConstraintsStudioConstraintResolver
The host's rules for a camera centre, or none.
useStudioContextMenu opens the right-click context menu through the tool bus.
useStudioContextMenu(client)
clientMapClient | null
The map to listen on, or null before it is ready.
useStudioEnrichment draws the store's active enrichments on the map, stacked over the active overlay.
useStudioEnrichment(client)
clientMapClient | null
The map to draw on, or null while none is mounted.
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?)
clientMapClient | null
The map to read clicks and hovers on, or null while none is mounted.
optionsUseStudioItinerarySelectionOptions
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 binds a map to the studio above it, with every binding MountayaStudio mounts on its own map.
useStudioMapBindings(client, options?)
clientMapClient | null
The map to bind, or null while none is mounted: every binding waits for it.
optionsUseStudioMapBindingsOptions
default: {}
The answers only the caller has.
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?)
clientMapClient | null
The map to reflect the store on, or null while none is mounted.
demUrlstring
The host's elevation raster, which wins over the manifest's own (resolveDemUrl). With neither, the map renders flat.
useStudioOverlay renders the user-selected category overlay (the store's activeOverlay slug) onto the map.
useStudioOverlay(client)
clientMapClient | null
The map to draw on, or null while none is mounted.
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 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?)
clientMapClient | null
The map to paint on, or null while none is mounted.
resolveNamePeerNameResolver
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 shows and hides the render layers of the points-of-interest overlay to match the store's active groups.
useStudioPoiLayers(client)
clientMapClient | null
The map whose layers are toggled, or null while none is mounted.
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)
clientMapClient | null
The map to paint on, or null while none is mounted.
glyphsPreviewGlyphs
The marker vocabulary the previews are drawn with.
useStudioSegmentEditing owns the live interaction layer of a segment geometry edit, active only while an edit session is open.
useStudioSegmentEditing(client, collabEngine)
clientMapClient | null
The map the edit runs on, or null while none is mounted.
collabEnginePeerDraftSink | null
The collaboration session the live segment is forwarded to, or null when the studio has none.
useStudioSegmentViaPrompt opens the segment handle prompt through the tool bus.
useStudioSegmentViaPrompt(client)
clientMapClient | null
The map to listen on, or null before it is ready.
useStudioSplitPicking turns a map click into a segment split while a split pick is armed.
useStudioSplitPicking(client, options?)
clientMapClient | null
The map to pick on, or null while none is mounted.
optionsUseStudioSplitPickingOptions
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 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)
clientMapClient | null
The map to pick on, or null while none is mounted.
useStudioTimestamp applies the store's overlay timestamp to everything on the map that depends on the time. A null timestamp means now.
useStudioTimestamp(client)
clientMapClient | null
The map to apply the time to, or null while none is mounted.
useStudioUrlState bridges the studio's URL and its map state in both directions.
useStudioUrlState(url)
urlStudioUrlSeam
Its fields are listed under useStudioUrl.
useStudioWaypointEditing owns the live interaction layer of a waypoint authoring session, active only while the store's waypointEditSession slot is open.
useStudioWaypointEditing(client)
clientMapClient | null
The map the edit runs on, or null while none is mounted.
useStudioZoneEditing owns the live interaction layer of a zone geometry edit, active only while the store's zoneEditSession slot is open.
useStudioZoneEditing(client, collabEngine)
clientMapClient | null
The map the edit runs on, or null while none is mounted.
collabEnginePeerDraftSink | null
The zone's collaboration session the drafts are forwarded to, or null for a personal zone.
Its fields are listed under useStudioSegmentEditing.
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)
clientMapClient | null
The map to pick on, or null while none is mounted.
useStudioZoneSelection wires interaction with the rendered zone tile geometry to the bus.
useStudioZoneSelection(client, options?)
clientMapClient | null
The map to read clicks on, or null while none is mounted.
optionsUseStudioZoneSelectionOptions
Bringing an itinerary in from somewhere else.
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
The studio's co-pilot, for a host that arranges its own studio.
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.