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:
- Heuristic YAML Coordinate Guessing Polluted the Map:
LeafConfigscanned arbitrary plugin YAML files for keys matchingradiusorcenter-xand synthesized unverified circles on the World Map, producing false-positive overlays for non-spatial settings and duplicating plugin state. - Hardcoded
LeafRTP& Built-In 3D Coupling:LeafConfigembedded hardcoded assumptions aboutLeafRTPregion files and shipped an always-visible built-in 3D perspective viewport bar (#map-3d-controls-bar) insideLeafConfig's template even when no 3D/texture map engine (LeafMap) was installed. - 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 Maptab only when contributed by a registered supplier (WorldBlockFeed#registerInteractiveOverlay,ConfigExtensionProvider#mapOverlays,ConfigExtensionProvider#overlayLayers, or ingestedLeafRTP/LeafSleuthcontributions). LeafRTPandLeafSleuthregister their spatial overlays and component-level permission gates (WorldBlockFeed.OverlayPermissionGates:viewPermission,resizePermission,movePermission,actionPermission) directly withLeafMap(WorldBlockFeed), which evaluates read vs. mutation capabilities per viewer session (canView,canResize,canMove,canAct), supplies the🗺️ World Mapworkspace tab toLeafConfigvia the genericworkspaceTabsSPI (LeafMapRuntime#buildLeafConfigWorkspaceExtension->LeafConfigRuntime#ingestPeerWorkspaceExtension, matchingLeafFuzz), and pushes monotonically sequenced (overlayRevision) updates whenever overlays or map state change.- Standalone
LeafConfig(withoutLeafMapregistered) renders only its core Web IDE & Config Describer tabs (📊 Diagnostics & Radar,⚙️ Plugin Configs,📖 Docs & Guides) and does not hardcode a native🗺️ World Mapbutton 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 whichEditorPanelIoDescriptorfields 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,
LeafConfigupdates the bound provider panel fields (syncRegionHandleToProviderPanel) and submits the updated parameters back to the supplier viaConfigExtensionProvider#onPanelIoSubmitted. - When persisting region overrides to YAML files that inherit
shape: "@config",LeafConfigRuntimeexpands@configinto an explicit inlineshape: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:
ConfigExtensionProviderexposesmapViews()returningList<MapViewDescriptor>(viewId,label,icon,description,clientRendererFn,defaultActive), collected viaConfigExtensionRegistry#collectMapViews().- When
LeafMap(or anotherWorldBlockFeed/ConfigExtensionProvidermap supplier) registers withWorldBlockFeedRegistryorConfigExtensionRegistry,LeafConfigRuntimeserializes its suppliedmapViews(such asleafmap-surfacefor block-surface texture hillshading andleafmap-3dfor.lca/.dlsh3D sub-chunk rendering) alongside itsclientDrawingKernel. - In
resource/LeafConfig/docs/editor/index.html,#map-supplier-views-barremains hidden whenmapViewsis empty and dynamically renders view-switcher buttons only when a map supplier contributes views, delegating canvas rendering for non-2D modes to the supplier'sclientRendererFn.
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 & Hotspotsthird forLeafSleuthhotspot attribution and 1-click config remediation.Staged Config Changes(#staging-diff) at the bottom.ingestSessionPayloadpreserves the initial live server disk snapshot as the diff baseline (defaultConfigs) while keepingjarDefaultsseparate for comment restoration and schema reset, ensuring a new session opensCLEAN(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 registeredConfigExtensionProviderorWorldBlockFeedsuppliers. - GOAL-LEAFCFG-003-2 (Live-Disk Staging Baseline):
ingestSessionPayloadinitializesdefaultConfigsfrom the live server disk snapshot while keepingjarDefaultsseparate inshippedConfigs, so freshly opened workspaces report0 MODIFIEDuntil edited. - PROHIBIT-LEAFCFG-003-1 (No Built-In 3D Viewport in LeafConfig):
LeafConfigshall not embed a hardcoded 3D viewport bar (map-3d-controls-bar) in its core template; non-2D views are rendered only when supplied viaConfigExtensionProvider#mapViews(). [forbid-pattern: map-3d-controls-bar in resource/LeafConfig/docs/editor/**] - PROHIBIT-LEAFCFG-003-2 (No Heuristic YAML Radius Guessing on World Map):
LeafConfigshall 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
radiusacross 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 toLeafMap(WorldBlockFeed), whereasLeafConfig'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-priorityLeafRTPregion scaling controls, and a clean 2D biome +LeafSleuthheatmap canvas that seamlessly upgrades withLeafMapview modes whenLeafMapis present. - Negative: Third-party plugins that want interactive region handles or custom map view modes on the World Map must register a
ConfigExtensionProvider(orWorldBlockFeed) rather than relying onLeafConfigto guess from YAML key names.