Skip to content

leafconfig-ADR-003 - Provider-Driven World Map Overlays, Interactive Region Scaling, and Map View Supplier SPI

  • Status: Accepted
  • Date: 2026-11-02
  • Applies to: resource/LeafConfig/ (leafconfig-common, leafconfig-paper, leafconfig-plugin, docs/editor/index.html)

Context

LeafConfig provides a unified browser workspace (leafconfig-workspace.html) whose first tab (World Map) visualizes server geography alongside spatial plugin controls and diagnostic telemetry. Early iterations suffered from three architectural coupling defects:

  1. Heuristic YAML Coordinate Guessing Polluted the Map: LeafConfig scanned arbitrary plugin YAML files for keys matching radius or center-x and synthesized unverified circles on the World Map, producing false-positive overlays for non-spatial settings and duplicating plugin state.
  2. Hardcoded LeafRTP & Built-In 3D Coupling: LeafConfig embedded hardcoded assumptions about LeafRTP region files and shipped an always-visible built-in 3D perspective viewport bar (#map-3d-controls-bar) inside LeafConfig's template even when no 3D/texture map engine (LeafMap) was installed.
  3. Unprioritized Sidebar Layout & False-Dirty Staging Baseline: The World Map sidebar stacked explanatory prose, false-positive overlays, and auto-generated non-spatial plugin panels (Paper, ViaVersion, LeafConfig) above the active region parameters, and diffed live disk configs against raw JAR defaults so freshly opened workspaces reported modified files before any user edit.

Decision

1. Strict Supplier Ownership on the World Map (ConfigExtensionProvider)

LeafConfig shall not guess or synthesize spatial map overlays from unverified YAML key names on the World Map, and shall not generate World Map parameter tabs for plugins that do not supply map overlays or spatial panels:

  • Spatial zones, boundaries, and heatmaps appear on the World Map tab only when contributed by a registered supplier (WorldBlockFeed#registerInteractiveOverlay, ConfigExtensionProvider#mapOverlays, ConfigExtensionProvider#overlayLayers, or ingested LeafRTP / LeafSleuth contributions).
  • LeafRTP and LeafSleuth register their spatial overlays and component-level permission gates (WorldBlockFeed.OverlayPermissionGates: viewPermission, resizePermission, movePermission, actionPermission) directly with LeafMap (WorldBlockFeed), which evaluates read vs. mutation capabilities per viewer session (canView, canResize, canMove, canAct), supplies the 🗺️ World Map workspace tab to LeafConfig via the generic workspaceTabs SPI (LeafMapRuntime#buildLeafConfigWorkspaceExtension -> LeafConfigRuntime#ingestPeerWorkspaceExtension, matching LeafFuzz), and pushes monotonically sequenced (overlayRevision) updates whenever overlays or map state change.
  • Standalone LeafConfig (without LeafMap registered) renders only its core Web IDE & Config Describer tabs (📊 Diagnostics & Radar, ⚙️ Plugin Configs, 📖 Docs & Guides) and does not hardcode a native 🗺️ World Map button in <nav class="nav-tabs">.

2. Interactive Region Scaling Contract (RegionScaleSpec)

ConfigExtensionProvider.MapOverlayDescriptor includes a declarative RegionScaleSpec (scalable, movable, innerRadiusScalable, snapStepBlocks, supportedShapes, and field ID bindings radiusFieldId, innerRadiusFieldId, centerXFieldId, centerZFieldId, shapeFieldId, worldFieldId):

  • Supplying plugins (such as LeafRTP) declare whether their regions can be scaled or moved on the canvas and which EditorPanelIoDescriptor fields receive updates.
  • When an operator drags the N/S/E/W outer radius handles, inner donut radius handles, or center grip on the 2D canvas, LeafConfig updates the bound provider panel fields (syncRegionHandleToProviderPanel) and submits the updated parameters back to the supplier via ConfigExtensionProvider#onPanelIoSubmitted.
  • When persisting region overrides to YAML files that inherit shape: "@config", LeafConfigRuntime expands @config into an explicit inline shape: block so per-region geometry edits persist cleanly without mutating global defaults unless requested.

3. Map View Supplier SPI (MapViewDescriptor & WorldBlockFeed)

LeafConfig ships only the network-safe 2D biome base canvas (BiomeBinCodec Hilbert RLE bins, coarse-first 1-run overview embedding, BiomeColorSource paletteRgb, and viewport-budgeted <= 28 KB "land" WebSocket LOD streaming) and removes the built-in 3D viewport mode from its core UI:

  • ConfigExtensionProvider exposes mapViews() returning List<MapViewDescriptor> (viewId, label, icon, description, clientRendererFn, defaultActive), collected via ConfigExtensionRegistry#collectMapViews().
  • When LeafMap (or another WorldBlockFeed / ConfigExtensionProvider map supplier) registers with WorldBlockFeedRegistry or ConfigExtensionRegistry, LeafConfigRuntime serializes its supplied mapViews (such as leafmap-surface for block-surface texture hillshading and leafmap-3d for .lca / .dlsh 3D sub-chunk rendering) alongside its clientDrawingKernel.
  • In resource/LeafConfig/docs/editor/index.html, #map-supplier-views-bar remains hidden when mapViews is empty and dynamically renders view-switcher buttons only when a map supplier contributes views, delegating canvas rendering for non-2D modes to the supplier's clientRendererFn.

4. Prioritized World Map Sidebar & Live-Disk Staging Baseline

  • The World Map sidebar (#region-sidebar) orders cards by operator task priority:
  • Region & Overlay Controls (#map-panel-io-box) at the top for immediate region selection and radius/shape/center editing.
  • Biomes in Region (#grp-biomes) second for live biome distribution feedback while scaling a region.
  • Clicked Map Element & Active Overlays & Hotspots third for LeafSleuth hotspot attribution and 1-click config remediation.
  • Staged Config Changes (#staging-diff) at the bottom.
  • ingestSessionPayload preserves the initial live server disk snapshot as the diff baseline (defaultConfigs) while keeping jarDefaults separate for comment restoration and schema reset, ensuring a new session opens CLEAN (0 MODIFIED) until the operator edits a setting or scales a region.

Invariants & Prohibitions

  • GOAL-LEAFCFG-003-1 (Strict Supplier Ownership): World Map overlays, interactive region handles (RegionScaleSpec / syncRegionHandleToProviderPanel), and non-2D view modes (ConfigExtensionProvider#mapViews / ConfigExtensionRegistry#collectMapViews) originate strictly from registered ConfigExtensionProvider or WorldBlockFeed suppliers.
  • GOAL-LEAFCFG-003-2 (Live-Disk Staging Baseline): ingestSessionPayload initializes defaultConfigs from the live server disk snapshot while keeping jarDefaults separate in shippedConfigs, so freshly opened workspaces report 0 MODIFIED until edited.
  • PROHIBIT-LEAFCFG-003-1 (No Built-In 3D Viewport in LeafConfig): LeafConfig shall not embed a hardcoded 3D viewport bar (map-3d-controls-bar) in its core template; non-2D views are rendered only when supplied via ConfigExtensionProvider#mapViews(). [forbid-pattern: map-3d-controls-bar in resource/LeafConfig/docs/editor/**]
  • PROHIBIT-LEAFCFG-003-2 (No Heuristic YAML Radius Guessing on World Map): LeafConfig shall not synthesize World Map overlay circles by heuristically scanning arbitrary plugin YAML keys (synthesizeHeuristicRadiusCircles). [forbid-symbol: synthesizeHeuristicRadiusCircles in resource/LeafConfig/**]

Alternatives Considered

  • Keep heuristic YAML regex scanning for map circles: Rejected. Regex-matching keys named radius across arbitrary plugin configs created false-positive circles at (0, 0) and confused operators.
  • Keep a built-in 3D renderer inside LeafConfig: Rejected. 3D voxel/column rendering and surface texture sampling belong to LeafMap (WorldBlockFeed), whereas LeafConfig's built-in map only needs a fast, network-safe 2D biome + region + heatmap canvas unless a map supplier registers additional views.

Consequences

  • Positive: LeafConfig's World Map opens with zero false-positive overlays, zero modified files on load, top-priority LeafRTP region scaling controls, and a clean 2D biome + LeafSleuth heatmap canvas that seamlessly upgrades with LeafMap view modes when LeafMap is present.
  • Negative: Third-party plugins that want interactive region handles or custom map view modes on the World Map must register a ConfigExtensionProvider (or WorldBlockFeed) rather than relying on LeafConfig to guess from YAML key names.

References