Skip to content

Latest commit

 

History

History
572 lines (499 loc) · 38.2 KB

ARCHITECTURE.md

File metadata and controls

572 lines (499 loc) · 38.2 KB

Architecture

GlobeCraft is a Cargo workspace with one desktop application and four libraries.

flowchart TD
    App[apps/globecraft] --> Core[globecraft-core]
    App --> Data[globecraft-data]
    App --> Render[globecraft-render]
    App --> Assistant[globecraft-assistant]
    Assistant --> Core
    Render --> Core
    Render --> Data
    Data --> Core
Loading

Libraries never depend on the application. The workspace manifest owns versions, package metadata and build profiles; Cargo.lock pins resolved dependencies. apps/globecraft is the default member, so cargo run --release starts the app.

Package Responsibility Entry points
globecraft Native startup, input, UI state, font layout, styled shapes and texture upload main.rs, app/mod.rs, app/ui, app/rendering.rs, app/overlays
globecraft-core Command catalog and map-layer identities, double-precision math, camera/picking/flight, Unicode name normalization, language, Fluent catalogs and placemarks camera, flight, math, language, localization, placemark
globecraft-data Async HTTP, tiles, boundaries, local search, KML, settings, persistence and the network policy table runtime, http, network, tiles, boundaries, search, kml, files, settings
globecraft-render CPU rasterization, terrain relief, frame scheduling, geographic overlay preparation and tile priorities worker, overlays, terrain
globecraft-assistant The AI assistant as a sans-I/O agent: provider wire formats, tool calls over the command catalog, approvals, retries and compaction agent, provider, tools

Rendering and UI

The desktop uses eframe/egui/emath 0.36 with eframe's default wgpu UI backend and upstream graphics backend fallbacks. The saved Uncap FPS preference selects automatic non-vsync presentation at startup; other presentation defaults remain unchanged. Background completion polling runs in App::logic, including while hidden; panels and widgets run in App::ui using the root UI, which also provides context access through dereferencing. The optional compute renderer uses wgpu 30 independently of the UI backend, with shader tests using its matching wgpu::naga re-export. The workspace requires Rust 1.95 and uses Edition 2024 with Cargo resolver 3. Fixed-size geographic segments use array windows without changing arithmetic order. Render benchmarks and device-loss fixtures inject private cache roots; normal startup retains the existing platform cache path and limits. App-owned frame timing gives repeated layout passes a zero movement delta, preventing held navigation controls from advancing twice in a presented frame.

The app captures immutable camera/style/layer inputs. A render-owned coordinator holds one active job, one replaceable pending request and one completed frame. Provider, release, size and style changes reject incompatible results; compatible completed camera snapshots remain presentable during motion. Picking, borders, labels and scale use the displayed camera, keeping input and overlays aligned.

CPU rasterization uses the shared Rayon pool, eight-row tile batches and wide four-lane f64 rays. Geographic conversion and LOD stay in f64; glam handles camera matrices/quaternions and SIMD colors. Batch-local tile handles avoid repeated cache reads and are released after the batch. Safe bytemuck casts describe byte pixels; workspace code forbids unsafe Rust. Native macOS menus stay in the desktop adapter; their callbacks queue actions and wake egui. Windows and Linux use an in-window menu with the same command catalog, alongside sidebar controls. The macOS menu registers Window/Help with the system, while About and shortcut help use app-owned egui windows. Captions, enablement and checkmarks update from the current language and app state. See desktop menus. The sidebar can be collapsed from the persistent toolbar button; its settings and sections remain available when reopened. The toolbar ruler shortcut toggles the sidebar's existing ruler state and, when enabling it, requests that its section expand and scroll into view, retaining measurements and history. The camera shortcut uses the same screenshot job as the sidebar and native menu. The file worker reserves screenshot names with create_new and adds numeric suffixes on collisions before encoding the unchanged PNG pixels. The pin shortcut shares the sidebar's At center placemark action, including selected-folder insertion and localized default names. A pending reveal reopens Placemarks and focuses/scrolls its existing name editor into view. The top/bottom panel layout lives in app/ui/chrome.rs; the search input and submission widgets live in app/ui/search_bar.rs. Query state, suggestion merging/debouncing and search dispatch stay in app/search.rs, while app/ui/suggestions.rs draws the results popup. The toolbar status readout lives in app/ui/status.rs, with text at 90% of the Body font size. It fits text using that same font, retains filename endings and shows the full message on hover only when text or a file path is shortened.

The coordinator prepares CPU image data and matching overlay geometry before publication. Egui uploads textures and builds styled shapes on its own thread. RGBA buffers are reused when uniquely owned; screenshots retain immutable Arc snapshots, so an export never reads a recycled frame. PNG encoding runs on the bounded file worker.

Application state

App (apps/globecraft/src/app/mod.rs) holds what every feature reads and one state per feature (roadmap 10.2). Shared, as fields of App itself: ctx, runtime, lang, settings, cam, status and time. Everything else belongs to a feature state, a plain struct in the feature's module:

Field State Holds
chrome chrome::ChromeState Header and ribbon: style scale, ribbon tools and peek, native menu (macOS)
windows, panes windows::WindowsState, panes::PanesState Open windows and dialogs; what the Settings pages, Layers pane and colour keys show
locale, saved, keys locale::LocaleState, saved::SavedSettings, keys::KeysState Language choice and system region; the settings on disk and their writer; service keys as typed
motion, nav motion::MotionState, navigation::NavState A flight, the idle rotation, the followed ground; the navigator's drags
tiles cache::TilesState The imagery cache, its Settings controls, tiles loaded ahead
frame frame::FrameState Renderer, displayed frame and fade, render wake-up, screenshot in progress, diagnostics
borders borders::BordersState Boundary data and loader, close-up place names, overlay geometry cache
live live::LiveState Aircraft, vessels, satellites, aurora, airports, time zones, sea names, weather maps, traffic, and their drawn shapes
map_data map_data::MapDataState Roads, transport and places of interest: tiles and shapes
picked, pointer picked::PickedState, pointer::PointerState The picked flight and satellite; the pointer on the globe and the "What's here?" card
files, updates files::FilesState, update_restart::UpdatesState File jobs and their status; the update service and restart
search, places, measure, wayback, timeline, assistant, explorer, flat_earth, user_layers in the modules of the same name The features split out first

Rules for new state:

  • A new field goes into the state of its feature; a new feature gets its own state struct in its own module. App gains a field only for a new state or for a value that most features read.
  • A state's fields are pub(super): the app's modules read them directly, as self.frame.texture. Borrows of different states (and of different fields of one state) stay disjoint that way, so a draw function can hold &mut self.live.geometry and &self.tiles.cache together; an accessor method on App would borrow all of it.
  • Logic that needs one state and a few plain inputs is a method of that state, taking the inputs as a query struct (LiveState::update_feeds(runtime, ctx, LiveQuery), MapDataState::update). Logic that reads several states stays an impl App method in the feature's module.
  • States are declared in the order their parts were before the split, which is the order they are dropped in at exit.

Commands and the interface

globecraft_core::commands lists every action as a command: id, Fluent label/help keys, icon, ribbon tab, JSON-Schema parameters and reach (view, files, destructive, interface). App::run(id, params) (apps/globecraft/src/app/commands.rs) reads the command once with commands::Command::parse: the id becomes a typed Command, grouped by feature (Command::Camera(CameraCommand::FlyTo(FlyTo { lat, lon, .. }))), and the JSON parameters become the command's own struct (commands/params.rs, read leniently: numbers also as text, text trimmed). One handler per feature matches its group (commands/camera.rs, places.rs, ruler.rs, files.rs, layers.rs, interface.rs, settings.rs, info.rs; run_time, run_flight, run_satellite, run_user_data and run_legend beside their states); a match must name every command of its group, so a command without a handler does not compile. The table in commands/command.rs is the only place that pairs an id with its variant; core tests check that it holds every catalogue command once and that each parameter struct has exactly the parameters of its JSON Schema (which stays hand-written: it is what the assistant reads). commands/state.rs reports enabled/checked state (App::command_state) and commands/shortcuts.rs owns the keyboard shortcuts. The ribbon, File menu, macOS native menu, shortcuts, context menu, controllers, Command Search and the assistant all dispatch through App::run. globecraft_core::layers::MapLayer names every toggleable layer; data's Settings stores their visibility (layers, plus the earlier sky and grid_numbers fields).

The window is laid out like RustGIS (Apache-2.0, see CREDITS.md): header, ribbon, left/right panes, status bar and the globe in the central panel (app/ui/chrome.rs, ribbon.rs, panes.rs, widgets.rs, theme.rs, icons.rs). The header also serves as the title bar (app/ui/window_chrome.rs): macOS uses a full-size content view with hidden title text and its native traffic lights; Windows and Linux keep the native title bar, buttons and resize borders, so the header is an ordinary row there. The window title stays GlobeCraft; the executable keeps its globecraft name. Theme tokens are applied to both egui themes once per UI scale; egui switches themes itself. The render pipeline below is unchanged by the interface. See interface.

AI assistant

globecraft-assistant builds provider requests and reads replies as plain data (Anthropic, OpenAI Chat Completions and compatible servers, Gemini), and runs tool calls through a Host trait. The desktop's app/assistant.rs sends requests with data's model_http on the service runtime (streamed, bounded, waking egui per piece), applies results on egui's thread and implements Host with App::run. Commands that touch files wait for approval; interface-only commands are refused. See AI assistant.

Tile sources

Every raster source (imagery, maps, elevation, night lights) is described as data in crates/globecraft-data/src/tiles/sources.json: a stable id (part of every tile key and of the disk cache, never reused), a code, its kind, whether it is a basemap, how tiles are addressed (an XYZ/WMTS-REST template, or Esri Wayback), the zoom range, tile size, cache folder, attribution and prefetch policy. tiles::Provider is a source id with the built-in sources as named constants; everything else asks Provider::source(). A new template source is a new entry in the file. Each source's first failed download goes to the run log.

Network policy

globecraft_data::network is the one readable table of built-in services: hosts, request cadence, user agent and the Settings group each belongs to. Tile rows are derived from sources.json, so adding a source adds its host automatically. The desktop's Settings → Network page renders the table plus the dynamic hosts from user-added layers and the assistant provider. HTTP clients take their user agents from this module; the table is descriptive, not an interceptor. See network policy for the current hosts, the provider-policy caveats and the redirect/third-party limits.

Terrain

globecraft-render::terrain marches each view ray through the Mapterhorn Terrarium elevation (at most z15) until it meets the ground, so relief hides what lies behind it and reaches the horizon. Elevation tiles decode into heights plus a pyramid of block maxima (globecraft_data::tiles::Elevation); while a ray is above a block's maximum it jumps to the block's edge, and only the last texels before the ground are walked one by one. The elevation level follows the distance (about two pixels per texel), Mercator positions move linearly between exact measurements, and a hit is refined by secant steps and shaded by the local slope. Missing tiles are requested with screen priority and drawn at sea level until they arrive.

The camera looks at the terrain height under the view centre (Cam::basis_over_ground, eased in App::follow_ground), a tilted camera is kept 150 m above the ground beneath it, and borders, names and live vector layers (roads, railways, ferries, airports, rivers, parks and place/peak markers) are raised onto the relief from the loaded tiles (overlays::GroundHeights). Terrain is drawn below 150 km and only on the CPU path (the GPU renderer falls back).

The CPU renderer has no depth buffer, so overlays are also tested against that relief: overlays::TerrainVisibility samples the straight eye-to-point line at 16 points and reports the target hidden when the line passes below the ground. Borders split into their visible runs, and roads, railways, ferries, airport markers, rivers, parks, place/peak markers, vessels, placemarks, satellite subpoints and their labels are dropped where a ridge or island hides them. Ships stay on the water surface but can still be hidden by land. The test runs only when relief is drawn and the view is tilted at least 1°; the exact top-down default view performs no elevation lookups. It reads the frame's loaded elevation tiles and never requests new ones, and a missing tile reads as sea level. A tilted view with relief therefore pays up to 16 elevation lookups per overlay point.

Live layers and the hidden illustration

Roads, AIS vessels, predicted satellite subpoints and traffic rasters use a render-owned preparer and coalesced worker: one active request, one replaceable pending request and one completed result. Inputs hold immutable Arc snapshots. Moving raster frames carry geometry prepared for their camera; stationary data refreshes use the same preparer off the UI thread. The app rejects geometry with an incompatible camera, rectangle, DPI, scale, data identity or orbital time tick. Roads/vessels/traffic reuse their prepared components when only satellite time changes. Screen projection uses the selected Earth's surface; road hover tests all visible fragments after a cheap prepared-bounds rejection.

Egui owns final styled mesh/label caches and texture upload. Traffic image projection and tile decode/stitching stay off egui; the data-owned feature and tile workers also perform OSM geometry conversion, AIS conversion and OMM conversion. Snapshots are allocated before publication, so applying a result swaps shared ownership instead of cloning fleets or road arrays. Service URLs, refresh intervals, retries, source fallback and draw order remain unchanged. Traffic completions from a replaced or cleared API key are discarded. Border tile loading status is separate from the bundled border/name datasets.

globecraft-core::orbit owns the existing approximate two-body propagation; data owns CelesTrak format/epoch decoding. This preserves the existing educational model, not SGP4 precision, and rejects invalid/non-finite orbital elements. Normal live-layer labels use Fluent; errors retain structured causes until status formatting. Roads' zoom limit uses the selected distance units (180 km / 112 mi).

The flat-Earth illustration remains a separate hidden scene with its existing shortcuts, pan/rotate/zoom/reset/exit controls. It never changes EarthModel. Its embedded image loads on the file worker. The app shares a static disk layout (3,201 vertices / 6,144 triangles), caches tessellated stars/rim/surface meshes per viewport/rotation/zoom/texture/DPI, and rebuilds only when that view changes. Image completion after exit cannot reopen it. See the isolated construction comparison in PERFORMANCE_BASELINE.md.

Overlays and spatial indexes

Render owns geographic visibility, border projection and ordered label candidates. A packed geo-index R-tree indexes immutable boundary-line bounds, with conservative 3D horizon/frustum tests and dateline/pole handling. Dataset changes rebuild the index; camera changes query it. Source order and visible line interiors are preserved.

The app caches one displayed set of egui shapes/galleys. Camera, viewport, DPI, altitude, dataset, layers, language and text scale invalidate it. Tile arrivals and unrelated UI updates reuse unchanged projections. Stationary changes use a coalesced overlay worker; moving frames carry their matching geometry. Both workers also tessellate the border segments into one white mesh per border kind, in an app-provided step (render stays egui-free); the UI thread tints those vertices with the current altitude and arrival fades. Font measurement, final label occupancy and label shapes remain on egui. Label galleys live in the overlay cache across rebuilds (egui keeps a galley only one frame), and a rebuild lays out at most 120 new names, so a layer arriving with a thousand names fills in over a few frames instead of one long one. Mutable rstar indexes accepted screen rectangles in priority order, including touching-edge rejection, padding and the 500-label limit. Placemarks and ruler edits remain immediate. Optional graticule label candidates are prepared by the same background worker using the displayed raster grid step. Render aligns candidates on shared column/row guides inside the visible globe, swapping axes with view orientation. The desktop measures monospaced labels, anchors them consistently and rejects collisions with place names and other grid labels. Core owns disconnected ruler paths, bounded undo/redo history (100 edits), path-aware distance totals, true-north heading formatting and initial great-circle bearings; the desktop draws the status heading and compass. Pointer drags use core move transactions so one drag is one history step. Native Edit menu commands and keyboard shortcuts route to ruler history unless a text edit has focus. The ruler coordinate editor accepts separate latitude/longitude decimal-degree fields, uses core’s shared coordinates module to validate finite values within ±90°/±180°. Search coordinate queries use the same parser after splitting comma, semicolon or whitespace separators. Core also validates decoded numeric coordinates for geocoding, suggestions, GeoJSON boundaries/labels and KML I/O. Data owns JSON/XML decoding and longitude-first format adaptation. Invalid service coordinates are skipped; invalid KML coordinates return a typed error before an import completes or an export touches its destination. The editor adds/edits points through the same history. Input and editing preserve the stored f64 values without display rounding. Realistic — WGS 84 (G2296) is the default; the 6,371.0088 km sphere remains an optional model. The persisted selection routes camera, picking, rendering, geographic overlays and geodesics through core's Earth-model boundary; model changes invalidate compatible frame/overlay caches. See Earth models for supported calculations, reference-frame limits and extension points. Precise entry alone does not establish survey-grade accuracy.

Async services and files

The app owns one Tokio ServiceRuntime and injects handles/repaint callbacks. Pooled reqwest clients enforce response limits, timeouts and retry policies. Boundary JSON and PMTiles range reads also share a 120 s whole-request timeout, so a body that trickles cannot outlive the connect/read limits, and all archive range reads share six permits because they come from the same release host. Network I/O runs asynchronously; bounded feature, tile-decoding and file workers separate CPU-heavy parsing from interactive imagery. A panic in one of those jobs is returned as that job's error, so the pool and the application keep running. Six async tile workers use 48-job admission, current-view priority and delayed retries; stale queued detail is retired while active work and coarse overview jobs remain.

Borders and place names come from OpenStreetMap vector tiles (OpenMapTiles schema, served by OpenFreeMap) in boundaries::osm_tiles, streamed like imagery: a tile level for the altitude (at most zoom 12), the tiles around the view, and ahead of a zoom out the view's ancestors, a view-wide block at the next three levels up and the world to zoom 3. A missing tile is drawn from its nearest loaded ancestor. Only land borders (raw admin_level, disputed, claim and country-edge flags) and names are kept, in a compact format, in memory (bounded by vertices, tiles to zoom 6 pinned) and in a size-limited SQLite cache on disk (osm_borders.sqlite, least recently used dropped first). Lines cut at tile edges are joined again, and the visible set is composed off the UI thread and published as one replacing OsmBorders patch. OpenStreetMap stores each border once, so no border is matched, cut or deduplicated between sources. admin_level 2 draws as country, 3–4 as state, 5–8 as municipal (from zoom 11); disputed and claimed lines draw dashed, every side's. Small names appear with the municipal lines, below municipal_detail_max_km.

The other map data sets (transport, roads, places, points of interest) stream through vector_tiles::TileStream. Each keeps its vector tiles, gzip-compressed as downloaded, in its own size-limited SQLite file on disk (map_data_<set>.sqlite, the same store code and limit as the border cache, least recently used dropped first): a tile on disk shows at once, one of an older build of the set shows and is downloaded again, and the set's archive addresses are kept for offline starts.

The bundled Natural Earth 1:110m countries and places are the fallback: they draw a cold or offline start before the first tile arrives, and the country polygons' outer rings answer which country is under the camera (holes are drawn but excluded from point-in-polygon lookup). Once tiles are loaded only tile lines are drawn. Details: docs/BORDER_PIPELINE.md.

Loaded-name prefix search uses background-built Unicode-normalized FST indexes, with scanning during rebuilds. Ranking and remote-result merging remain explicit.

Boundary attribution (OpenStreetMap ODbL, OpenMapTiles, OpenFreeMap; Natural Earth public domain) is shown under the layer controls and on the globe while border tiles are in use.

GeoRust kml owns XML reading/writing. A bounded quick-xml preparation pass skips empty Points, balances incomplete containers and wraps bare-coordinate fragments. Core's placemark module owns a tree of Documents, Folders and point markers, session-stable node IDs, inherited visibility and cycle-safe moves. Import/export retains container order, names, descriptions, empty folders and visibility; repeated saves do not introduce additional Document wrappers. The existing first-coordinate policy for line/polygon Placemarks remains; this is not a lossless editor for unsupported KML geometry, styles or network links. The desktop draws disclosure arrows, full-width selectable rows and visibility checkboxes, with a details editor for the selection. Compact rows use eight-point indentation and vector folder/pin icons, independent of font glyph coverage. The tree uses the height supplied by the sidebar layout; descriptions use a separate three-line scrolling editor so long imported text cannot expand the sidebar. Double-click flies to a marker; drag onto a folder or My Places to move it. Creating a place/folder uses the selected folder, otherwise the root. Hidden ancestors suppress map markers without changing children's own visibility. File jobs capture the whole tree at submission; decoding, encoding and filesystem work stay off the UI thread. KML/KMZ I/O and screenshot encoding use an ordered bounded file service. KMZ imports select the first KML entry in archive order without extracting resources to disk. The entry is inflated with a 128 MiB limit on the bytes actually decompressed (entry headers are untrusted), then takes the same XML preparation pass and GeoRust KmlReader path as a plain KML file, so folder visibility and malformed-document handling match. Archive and reader errors are reported directly. Export writes the supported places tree as compressed doc.kml. Embedded resources, styles and network links retain the existing importer limitations. Native dialogs and result application belong to the app. Settings/language writes coalesce on a filesystem worker and flush at shutdown; startup reads the small preference files. Open KML source paths are stored separately in open-kml.json by that worker. Startup reopens them in order on the file service, silently drops missing files and rewrites the retained list; other failures remain visible and retry next launch. Only paths are remembered, so unsaved tree edits require an explicit KML save. A whole-tree save replaces the remembered sources with its destination to avoid loading both the combined snapshot and its former inputs. Clear All empties the tree and remembered list and discards pending KML results, without deleting sources.

Explorer image decoding (including the embedded Moon image) and planet document I/O use that same file service. Texture upload remains on egui's thread. Planet loads retain shared original encoded images, and saves snapshot their references, selected paths and name at submission. Re-saving an imported planet does not require its former image paths or re-encode its JPEG/PNG assets. Pending Explorer file controls are disabled, and selecting another body prevents a late load from changing the active body. The version-1 sidecar and version-2 embedded document formats remain supported.

Live aircraft use a data-owned asynchronous controller with one coalesced camera query and one latest immutable snapshot. It keeps at most one OpenSky and one ADSB.lol request active. JSON decoding and source merging/sorting use the bounded feature pool; the UI swaps shared snapshots, including shared immutable identifier strings. Coordinates use core validation and movement refresh uses core's mean-radius distance calculation. Provider URLs, response budgets, 17-minute/90-second refresh, three-minute failure retry and 30-second movement throttle remain unchanged. New requests pause when the layer or Earth body is hidden. Completed requests still publish and wake the UI. Cached global samples expire after 20 minutes; local samples retain the existing three-minute provider and 120-second position limits, with expiry publication coalesced to the one-second marker cadence. Re-enabling the layer with expired cached sources waits for background revalidation before displaying those positions again.

Render prepares aircraft projection and ordered label candidates in a bounded worker for stationary views, and alongside raster frames during motion. Both use the same preparer and the displayed camera. Geometry is reused for unchanged view/data/scale/DPI within a one-second time bucket; mismatched results never draw. One previous tick may remain visible while refreshing, up to two seconds old; expired geometry and older completions cannot replace a current result. Moving frames timestamp aircraft preparation at completion rather than raster submission. The 25-second extrapolation cap, icon geometry and label priority/spacing/count limits remain unchanged. Core owns the spherical destination calculation. The app owns Fluent statuses, English diagnostics, hover and font layout. It caches icon meshes and text galleys for the current geometry, preserving paint order; glyph UVs are not baked into cached meshes. No aircraft decoding, deduplication, sorting or geographic projection runs in a widget callback.

Application updates

Data's updater service uses the async GitHub backend from self_update 1.3 on the injected service runtime. It retains the selected stable version, exact tag and asset identity, requires GitHub's SHA-256 digest, coalesces progress through one watch snapshot and wakes the UI after publication. Downloads/installations are click-triggered and single-flight. Library verification/extraction/replacement runs off the UI thread; macOS replaces and verifies the whole app bundle. Debug builds and executables in Cargo output skip update checks independently of their version. Managed installations use the official release-page fallback.

The desktop owns the centered bottom-bar notice and restart/save orchestration. It reuses native save dialogs and the bounded file service, waits for file completions without blocking egui, and closes normally. Startup relaunches only after run_native returns, so preference flushing and app teardown precede restart. A failed restart reopens the desktop with an inline error and the saved documents. On macOS a normal quit flushes the settings writer and profiling log in on_exit and then ends the process directly: AccessKit restores the content view's class during window teardown while AppKit still observes it, so returning to eframe's teardown crashes in _NSTouchBarFinderObservation. A pending update restart execs the replacement from on_exit for the same reason; a failed restart reports to stderr and exits instead of returning to the crashing teardown. See releases for artifact names, install policy and integrity limits.

Cache ownership

Storage Policy
Decoded tiles Moka sync, weighted LRU, 256 MiB best-effort target; temporary overshoot and frame references are separate
Decoded vector tiles Per set, LRU bounded by both tile count and a 64 MiB estimated decoded-heap budget; one tile is always kept, and the estimate excludes allocator overhead
Encoded imagery MBTiles 1.3 through one tokio-rusqlite worker; 1 GiB managed-file target by default (Settings → Cache; 128 MiB before 2026-10-25), including SQLite overhead

MBTiles separates providers, stable Wayback releases and encoded formats, converts XYZ rows to TMS, and lazily imports legacy tile files. Eviction favors coarse imagery and reclaims pages. Tiles publish before optional persistence. Clearing removes only owned imagery files, rejects old-epoch writeback, preserves decoded memory/settings/boundaries, and refreshes actual usage. SQLite R-tree/FTS5 support is available for auxiliary catalogs; it is not duplicated in the tile hot path.

Satellite overview warming covers zooms 0–4 globally: 341 tiles, 85.25 MiB decoded. It runs while idle at 14,000 km or farther away, after visible work, with bounded admission. Other providers stay on demand. The cache folder (paths::cache_dir) is XDG_CACHE_HOME/globecraft when that is set, else Caches on macOS, LOCALAPPDATA on Windows and ~/.cache/globecraft elsewhere; migrate_cache renames the globecraft_tiles folder of earlier versions into place once. Preferences (settings.json, lang.txt, open-kml.json) and the key files live in the configuration folder instead (paths::config_dir: Application Support on macOS, APPDATA on Windows, XDG_CONFIG_HOME elsewhere), where cache cleaners leave them; migrate_config moves them out of the cache folder once.

Units, localization and diagnostics

Settings exposes a System/explicit language preference separate from the resolved session Lang. Core resolves supported system locales with English fallback; the desktop uses its existing OS locale detector. Data persists system, en or pt-BR in lang.txt, preserving old explicit choices. Missing preferences use System Locale; selecting it never writes the resolved locale as an override.

Coordinates use degrees, internal altitude/distances use kilometers, and raster footprints use meters. Core owns display conversions; the desktop detects the system locale once and data persists the System/Metric/Imperial preference. GlobeCraft defaults to miles/feet for the US, UK, Liberia, Myanmar, Belize, Bahamas, US Virgin Islands, Guam, Puerto Rico, Cayman Islands, Guernsey, Jersey and Isle of Man. This application policy extends CLDR's US/GB length defaults to include mixed/traditional mile usage; it does not claim uniform statutory units in those regions. Other locales and unknown regions use kilometers/meters. Clicking the camera altitude opens an exact-value editor in its displayed unit. Core validates/converts entries within the existing camera limits; the desktop owns the editor and applies accepted values, cancelling active flight. Camera altitude and scale bar share the selection; the ruler's Automatic option also follows it. Its separate saved selector supports centimeters, meters, kilometers, inches, feet, yards, miles, nautical miles, smoots, degrees and arcseconds. Angular units represent accumulated central angle on the mean-radius sphere. Football fields (100 yards, excluding end zones) are available everywhere. The selector uses “Football fields” for US system locales and “American football fields” elsewhere, with localized names. Optional selector-name overrides are separate from short measurement labels; totals and segments retain “football fields”. KML/GeoJSON arrays are longitude-first; domain pairs are latitude-first. UI strings live in embedded locales/{en,pt-BR}.ftl, with matching semantic keys and named whole-message arguments. Errors/logs are English; normal UI messages follow the selected language. See localization.

Opt-in profiling records pipeline and queue timings through a bounded background recorder. Normal builds compile it out. Component results and native measurements are documented separately; neither raster timing nor app-side texture submission is an application FPS guarantee. See contributing, CPU baseline.

GPU Earth rasterization

The Earth overview raster can be computed by the globecraft-render backend module with wgpu compute shaders (gpu/), then read back for the existing egui view. GPU globe rendering is a beta, on by default wherever the gpu feature is built in (Settings → Graphics turns it off); each adapter checks itself against the CPU renderer before its first frame. The CPU path is always the fallback. Set GLOBECRAFT_RENDERER=auto, gpu or cpu to override the default. The Explorer, live meteorological/aircraft layers, moon and custom planet remain integrated in apps/globecraft. See GPU_RENDERER.md for hardware limits, performance and CPU-only build instructions.

Frontend boundaries for GlobeCraft web

Core owns body selection, spherical destination calculations and camera orbit/zoom mapping. Render owns body meshes (positions/UVs/indices), weather compositing, aircraft/ruler projection, scale-bar selection, raster sizing and frame keys. These APIs use domain values, image buffers and emath, with no egui widgets, texture handles or window objects. The desktop adapter uploads textures, measures fonts, handles input and draws the returned geometry.

Data owns cloud/radar fetching, refresh/retry state, palette decoding, geographic resource URLs and .globeplanet documents. Byte-oriented planet encode/decode APIs support a frontend-provided legacy sidecar resolver; native path I/O is separate. OS URL opening, speech commands and file dialogs remain desktop responsibilities. This extraction prepares reusable logic; it does not make Tokio, SQLite, native file services or GPU readback compile for WebAssembly. A web frontend still needs browser transport/storage/execution adapters. Weather projection and body mesh construction retain their current frontend scheduling; this PR does not add jobs.

Panes

app/ui/panes.rs draws the left pane (Layers, Places, Globe; Places can be pinned below the others) and the right pane (AI Assistant, Measure). Data owns tolerant SidebarLayout (left) and WorkspaceLayout (ribbon tab, collapse, right panes) persistence in the existing settings file; name/description editing and tree mutations remain in app/ui/places.rs and core.

Coordinate presentation

Core owns CoordinateDisplay, CoordinateFormat and recognized coordinate queries. The mgrs-convert adapter handles UTM/UPS/MGRS; presentation changes never rewrite geographic values. Data persists tolerant format/precision fields and the desktop owns labels/copy controls. Recognized invalid input fails locally in English; ordinary addresses retain remote search. See coordinate display.

Preferences and fonts

Data owns tolerant appearance/navigation/cache preferences and applies configured imagery budgets at cache construction. The app owns searchable category widgets, OS font discovery and a bounded font-loading worker. Installed UI/map faces have independent bundled fallbacks; font application invalidates cached overlay text. Camera math remains in core. See settings.

Controllers

Core owns normalized Explore bindings, response/deadzone policy, button edges and camera steps. Data persists bounded per-model profiles. The app's gilrs adapter polls hotplug/input, arbitrates focus and dispatches tool actions through menus; its settings module owns remapping and the live monitor. See controllers for device/platform limits.

Celestial background

Core's celestial frame adapter uses sofars to transform Earth-fixed rays into ICRF/J2000 directions. Data owns the pinned bundled image and bounded asynchronous decode. Render owns equatorial bilinear sampling, daylight visibility and shared CPU/GPU sky repair. App owns toggles, diagnostic/credit widgets and frame-matched screenshot attribution. See celestial background and the independent dataset manifest in assets/sky.