Maps

Maps is the ryOS Apple MapKit JS app for place search, pins, saved locations (Home / Work / Favorites), and optional hand-off to Apple Maps for turn-by-turn directions.

Overview

Maps embeds Apple’s MapKit web stack inside a desktop window: search and geocoding run through MapKit, results and saved places appear as annotations, and the place card surfaces actions for each pin. The Directions control does not navigate away from ryOS in the current window — it opens a new browser tab with an Apple Maps driving-directions URL (destination coordinates; start defaults to the device location when the Maps client allows it). In-map routing overlays (polyline, steps, ETAs) inside MapKit are not implemented yet.

When Ryo uses the mapsSearchPlaces chat tool, the inline result list opens the chosen place in ryOS Maps (same window) so you can explore without leaving Chats; a separate control still opens Apple Maps in a new tab when you want the native client.

Features

• Place search via MapKit (city, business, address)

• Drop pins from search results; recenter and zoom
• Locate Me to recenter on the current position (browser geolocation)
• Saved places: Home, Work, and Favorites with branded or category markers
• Map types (View menu): Standard, Hybrid, Satellite, Muted Standard
• Directions hand-off: Apple Maps driving directions in a new tab (no in-window navigation away from ryOS)
• Chats integration: mapsSearchPlaces rows open places in-app; external link opens in Apple Maps

User Guide

Getting Started

Open Maps from the desktop or launcher. Type a query in the search bar, pick a result to drop a pin, and use the place card for details.

Key Actions

• Search: Enter a place name or address; choose a result to focus the map and show the place card.

• Directions: From the place card, use Directions to open Apple Maps driving directions in a new tab (ryOS stays open in the original tab).
• Locate Me: Use the toolbar control to recenter on your location (grant permission if the browser prompts).
• Saved places: Set Home and Work from the places drawer; star favorites to keep them on the map.
• Map style: Use the View menu to switch map type.

Tips

• Directions always use a new tab so your ryOS session is unchanged; they require network access and an Apple Maps–capable environment.

• From Chats, tapping a mapsSearchPlaces result launches Maps with that place selected — use the small external-link control if you prefer Apple Maps in a separate tab.

Technical Details

Requirements

MapKit JS needs a MapKit origin and credentials configured server-side (see project env docs for MAPKIT_* variables). Search and tiles depend on that setup.

Component Architecture

• src/apps/maps/components/MapsAppComponent.tsx — Map instance, search, annotations, place card

• src/apps/maps/components/MapsMenuBar.tsx — Menus and map type switching
• src/apps/maps/components/MapsPlaceCard.tsx — Place details and Directions action
• src/apps/maps/components/MapsPlacesDrawer.tsx — Home / Work / Favorites UI
• src/apps/maps/utils/appleMapsLinks.ts — Apple Maps unified URL for driving directions (maps.apple.com)

Chats UI

• src/components/shared/MapsSearchPlacesCard.tsx — Inline tool results; row opens Maps in-app; external icon opens appleMapsUrl

Related Apps

• Chats — Hosts the mapsSearchPlaces tool and inline place cards

• Control Panels — System settings (themes, sync); MapKit keys are environment-level