ryOS ryOS / Docs
GitHub Launch

Maps

Maps is the ryOS Apple MapKit JS app for place search, pins, saved locations (Home / Work / Favorites), a Taiwan YouBike station overlay, in-map YouBike directions, and optional hand-off to Apple Maps for turn-by-turn driving.

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). YouBike is the in-map exception: in Taiwan, a place card can plan walk → bike → walk legs, draw polylines on the MapKit map, and show station availability. General driving/transit overlays are still a hand-off to Apple Maps.

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
  • YouBike overlay: live YouBike 2.0 stations in the current Taiwan viewport (View → YouBike); small full-opacity gradient dots with no labels. Light mode uses a white outer outline; dark mode uses brighter fills and a dark outline. Tap hides that dot and shows a MapKit POI labeled bikes/total (e.g. 4/60); other docks stay. During directions, only start and end docks stay full size and opacity. Hidden at city-scale zoom (Taipei default and wider)
  • YouBike directions: in-map walk / bike / walk legs; bike geometry prefers MapKit Cycling, then OSRM bike; camera fits the route; route card replaces the place card and keeps turn-by-turn street steps hidden until Steps is tapped. The step list fades when it scrolls, and tapping a step moves the map to that turn. With Locate Me on, passed steps dim and the step you are on stays highlighted.
  • 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. The default camera is your approximate GeoIP city (city scale), or Taipei if that lookup fails, unless a selected place, granted location, or saved Home already frames the map. 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 and YouBike stay on the card. The round More button follows those buttons and opens Favorite, Set as Home, and Set as Work.
  • Directions: From the place card, use Directions to open Apple Maps driving directions in a new tab (ryOS stays open in the original tab). In Taiwan, YouBike plans an in-map trip instead: walk to a station with bikes, bike on roads (MapKit Cycling, then OSRM bike) to a station with docks, walk to the destination. The route card replaces the place card and shows time and distance only. Steps opens turn-by-turn directions with street names. The list fades at the edges once it scrolls, and tapping a step moves the map to that turn. With Locate Me on, passed steps dim and the step you are on stays highlighted.
  • YouBike overlay: Leave View → YouBike on (default). Stations appear only when the Taiwan viewport is zoomed in past city scale (plus a small pan margin). Browse-mode pins are small, fully opaque gradient dots. Light mode uses a white outer outline; dark mode uses brighter fills and a dark outline. Tap one to hide that dot, open the place card, and drop a MapKit POI whose label is bikes/total docks (e.g. 4/60). The other docks stay on the map. During YouBike directions, docks that are not the start or end shrink and dim; start and end stay full size and opacity. They stay hidden outside Taiwan and at city-wide cameras.
  • 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

Chats UI

Related Apps

  • Chats — Hosts the mapsSearchPlaces tool and inline place cards
  • Control Panels — System settings (themes, sync); MapKit keys are environment-level