docs: add BGP region and Earth rendering plans

docs/bgp-earth-rendering-plan.md

@@ -0,0 +1,296 @@
+# BGP Earth Rendering Plan
+
+## Goal
+
+This document defines how the BGP `region activity layer` and `incident layer` should coexist on Earth without conflicting.
+
+The main question it answers is:
+
+- how to add a regional observability background layer
+- without weakening the current incident-first event focus
+
+## Core Principle
+
+The Earth design should follow a strict semantic hierarchy:
+
+- `collector layer` = observation infrastructure
+- `region activity layer` = background situational awareness
+- `incident layer` = focal high-confidence event objects
+
+In short:
+
+- collectors prove the network is observing
+- regions show where routing behavior is active or abnormal
+- incidents show the concrete event worth clicking
+
+Region aggregation is therefore not a replacement for incident rendering.
+It is the context layer that makes sparse incident markers legible.
+
+## Rendering Hierarchy
+
+Recommended visual stack order:
+
+1. collector network / collector halos
+2. region activity glow
+3. incident markers and incident pulses
+
+This ordering should always hold.
+
+Why:
+
+- collectors should stay visible but quiet
+- regions should create ambient activity presence
+- incidents must remain the first thing users notice as a concrete event
+
+## Role Separation
+
+### Region Layer
+
+The region layer answers:
+
+- where is routing activity building up
+- where is there current noise or instability
+- which part of the world is currently worth looking at
+
+The region layer should feel:
+
+- broad
+- ambient
+- low-frequency
+- contextual
+
+### Incident Layer
+
+The incident layer answers:
+
+- which exact event should the user inspect
+- where is the highest-confidence routing event located right now
+
+The incident layer should feel:
+
+- sharp
+- compact
+- high-contrast
+- intentionally clickable
+
+## Non-Conflict Rules
+
+To avoid visual and semantic conflict, these implementation rules should be treated as hard constraints:
+
+1. region markers must not use the same symbol language as incidents
+2. region emphasis must stay weaker than incident emphasis
+3. region animation frequency must stay lower than incident animation frequency
+4. incident markers must always render above region glows
+5. region layer should support the event, not compete with it
+
+If a user notices the region layer first but misses the incident marker, the region layer is too strong.
+
+If a user only sees isolated incident points and cannot feel broader activity context, the region layer is too weak.
+
+## Region Rendering Rules
+
+The region layer should not be rendered as a second kind of incident point.
+
+Recommended representation:
+
+- diffuse glow
+- halo
+- low-detail pulse
+- soft center, not a sharp icon
+
+### Status Mapping
+
+#### `observing`
+
+- weak glow
+- cool color, such as cyan or blue
+- little to no pulse
+- purpose: keep the globe alive during calm periods
+
+#### `anomaly`
+
+- stronger glow
+- warmer color, such as amber
+- gentle breathing or low-frequency pulse
+- purpose: show that a region is experiencing abnormal routing noise
+
+#### `incident`
+
+- strongest regional background emphasis
+- still clearly weaker than the incident marker itself
+- purpose: lift the surrounding area so the focal event does not feel isolated
+
+### Region Visual Characteristics
+
+Recommended properties:
+
+- large radius
+- low opacity
+- soft edge
+- low-contrast outline or no outline
+- low pulse amplitude
+
+Avoid:
+
+- sharp symbol shapes
+- strong icon silhouettes
+- bright hard-edged centers
+- incident-like pulse language
+
+## Incident Rendering Rules
+
+The incident layer should remain visually sharper and more explicit than region activity.
+
+Recommended qualities:
+
+- clear event symbol
+- compact hot core
+- one or two outward ring pulses
+- high contrast
+- clear click target
+
+The incident layer should read as:
+
+- focal
+- deliberate
+- high-confidence
+
+while the region layer should read as:
+
+- contextual
+- ambient
+- supporting
+
+## Region And Incident In The Same Area
+
+When a region contains one or more incidents:
+
+- the region glow may intensify
+- but the incident marker must remain the dominant local feature
+
+Interpretation should be:
+
+- `region` says this area is in an event state
+- `incident marker` says this is the concrete event object
+
+So a region with `incident` status is not itself the event marker.
+It is the background state around the event.
+
+## Interaction Model
+
+Interaction should also preserve hierarchy.
+
+### Click Region
+
+Open a regional situation view, such as:
+
+- region name
+- observation count
+- anomaly count
+- incident count
+- affected prefix count
+- affected ASN count
+- recent incidents in the region
+
+### Click Incident
+
+Keep the current incident-focused detail interaction.
+
+This creates a natural two-step flow:
+
+1. region gives context
+2. incident gives detail
+
+## Layer Relationship To Existing BGP Elements
+
+### Collector Layer
+
+Collectors should remain:
+
+- quieter than regions
+- more infrastructural than semantic
+- proof of coverage, not proof of incident
+
+### Region Layer
+
+Regions should become:
+
+- the main ambient activity layer
+- the bridge between collectors and incidents
+- the answer to low-density map quietness
+
+### Incident Layer
+
+Incidents should remain:
+
+- the most legible event layer
+- sparse but dominant
+- compact and symbol-driven
+
+## Practical Visual Test
+
+Use this test when tuning the Earth implementation:
+
+### Calm Period
+
+Expected result:
+
+- collectors visible
+- some weak region glows present
+- no region feels alarm-heavy
+- globe still feels alive
+
+### Anomaly Period
+
+Expected result:
+
+- one or more regions brighten noticeably
+- user can sense the active area before clicking
+- still no confusion between region background and incident objects
+
+### Incident Period
+
+Expected result:
+
+- region provides broader context
+- incident marker is the first explicit focal object the eye lands on
+- user can immediately tell both:
+  - which region is active
+  - which specific event to inspect
+
+## Failure Modes To Avoid
+
+### Region Too Strong
+
+Symptoms:
+
+- incident markers disappear into the glow
+- users treat the region center as the main event
+- the map feels like area flooding instead of event focus
+
+### Region Too Weak
+
+Symptoms:
+
+- incident markers still feel isolated
+- low-incident periods still look visually empty
+- users cannot tell where routing activity is generally happening
+
+### Region Uses Incident Language
+
+Symptoms:
+
+- region and incident both look like event markers
+- users cannot distinguish context from event
+
+## Final Design Rule
+
+The desired reading order is:
+
+1. see the specific incident marker
+2. feel the active region around it
+3. understand that collectors and background activity keep the globe alive even during quieter periods
+
+In one sentence:
+
+`incident is the point; region is the field.`