release: bump version to 0.68.0

docs/technical/en/README.md

@@ -21,6 +21,7 @@ This is the current Intelligent Planet documentation entry point. Docs are organ
 - [Earth Satellite Footprint Policy](/home/ray/dev/linkong/planet/docs/technical/en/earth-satellite-footprint-policy.md): satellite footprint display boundaries and strategy
 - [BGP Context](/home/ray/dev/linkong/planet/docs/technical/en/earth-bgp-context.md): BGP rendering, aggregation, and collector implementation in Earth
 - [Earth Interactable Usage](/home/ray/dev/linkong/planet/docs/technical/en/earth-interactable-usage.md): `Interactable` API, lifecycle, and integration examples
+- [Earth Interactable Clustering](/home/ray/dev/linkong/planet/docs/technical/en/earth-interactable-clustering.md): pluggable cluster strategies, stable spherical clustering, and dynamic screen clustering boundaries
 - [Earth Toolbar and Overlay Coordination](/home/ray/dev/linkong/planet/docs/technical/en/earth-toolbar-overlay-coordination.md): close matrix for toolbar buttons, search, settings, news, and layer overlays
 
 ## Frontend Implementation

docs/technical/en/backend-collectors.md

@@ -75,6 +75,8 @@ async def run(self, db):
 
 Manual trigger, data clearing, and cache clearing now enter the PostgreSQL data job queue. `collection_tasks` remains the task ledger. Collectors only own `fetch -> transform -> save`; the `data_jobs.py` worker claims `collect` / `clear_data` / `clear_cache` / `earth_refresh` jobs and writes progress back. Earth layer refresh relationships live in `earth_layer_adapters.py`; do not hand-code cache invalidation or WebSocket broadcasts inside individual collectors or buttons.
 
+Data deletion runs in batches so AIS-scale tables are not locked by one huge statement. A `clear_data` job clears `collected_data`, then source-specific AIS derived tables, and broadcasts `records_processed` as it goes; the console queue renders only user-facing text such as `Deleting data` and `Delete complete`, while internal table names remain in logs and raw task details. After AIS cleanup, the backend runs `ANALYZE ais_raw_observations` so datasource-list estimates converge quickly. The datasource directory uses PostgreSQL statistics for AIS record counts by default to avoid a cold-start `count(*)`; opening a single datasource detail row requests the exact count for that source.
+
 ## III. Collector List
 
 | Collector | Data type | Content | Frequency |

docs/technical/en/earth-frontend-context.md

@@ -317,6 +317,8 @@ If future cable, satellite, or news cruise is added, do not copy a new set of `m
 
 [controls.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/controls.js) owns the Earth zoom state, and every zoom entry point must ultimately call `setZoomLevel()` to write the camera distance. Do not write `camera.position.z` from other modules, or the zoom percentage, drag sensitivity, and Interactable clustering thresholds will diverge again.
 
+Interactable clustering is selected per layer through `cluster.strategy`. `stable-spherical` uses discrete zoom bands and local 3D bucket clustering, so BGP, compute centers, and Earth interactables do not regroup while the globe rotates inside the same band. `dynamic-screen` keeps the projection-based behavior for high-frequency realtime layers such as vessels, and `none` disables clustering. Stable cluster dots stay rigidly aligned to their 3D centroid projection and do not participate in 2D avoidance. See [Earth Interactable Clustering](/home/ray/dev/linkong/planet/docs/technical/en/earth-interactable-clustering.md) for strategy configuration and tuning.
+
 Wheel input has two paths. Traditional mouse wheels keep the 10% step and short animation, using `wheelZoomTarget` as the logical base for continuous wheel input. Trackpads and high-precision wheels use the pixel delta for continuous zoom and call `setZoomLevel()` directly instead of passing through the 10% stepped animation. The trackpad path also filters a short-window, old-direction residual delta after a real direction change so inertia tails do not pull a just-reversed zoom back in the previous direction.
 
 The gesture capsule updates at most once every 90ms and fades after 760ms. It is view feedback, not data loading progress, and should not be written into layer loading state.

docs/technical/en/earth-interactable-clustering.md

@@ -0,0 +1,84 @@
+# Intelligent Planet Interactable Clustering
+
+Earth interactable icons are managed by `createInteractableLayer`. Rendering still uses Three.js `Points`, and picking, hover, locked state, tooltips, and cruise focus still depend on marker `userData`; the clustering strategy only decides which markers are represented by a cluster dot.
+
+## Strategies
+
+`cluster.strategy` supports three modes:
+
+- `stable-spherical`: stable spherical clustering. It clusters by local 3D positions on the globe and caches topology by zoom band. Rotation and small zoom changes within the same band only update projection and size. Use it for semi-static layers such as BGP, compute centers, and Earth interactables.
+- `dynamic-screen`: dynamic screen-space clustering. This keeps the previous projection-based behavior and evaluates visible relationships per frame. Use it for high-frequency realtime layers such as vessels, or as a fallback.
+- `none`: no clustering. Every marker is shown independently. Use it for low-count layers or precision-first views.
+
+`cluster: false` is equivalent to `strategy: "none"`. If a layer enables clustering without declaring a strategy, it keeps the compatible `dynamic-screen` behavior.
+
+## Stable Spherical
+
+`stable-spherical` moves cluster identity from screen distance to globe distance:
+
+- Each marker uses `icon_base_position` as its geographic anchor.
+- By default, zoom levels above `2.5` force clustering off and show every marker as its original icon.
+- The current zoom maps to a discrete band; rotation and small zoom changes inside the same band do not recompute topology.
+- Clusters are recomputed only when the band, data revision, visibility, or filter state changes.
+- A cluster centroid is computed from member 3D positions and normalized back to the globe shell, so the cluster dot stays rigidly aligned to its geographic center.
+- Cluster dots do not participate in 2D avoidance, so screen-space repulsion cannot push them away from their real geographic projection.
+- Band changes use a small hysteresis margin so zooming at a boundary does not repeatedly bounce between two bands.
+- Newly created marker and cluster dots run a short scale + opacity ease. This is only a rendering transition; it does not change marker coordinates, picking objects, or locked state.
+
+The stable strategy uses spherical bucket/hash neighbor lookup and must not use an all-pairs loop. Most frames only pay projection and material-size cost; topology cost is paid only on band or data changes.
+
+## Configuration
+
+```js
+const computeCenterIconLayer = createInteractableLayer({
+  id: "computeCenters",
+  // ...
+  avoidance: SURFACE_AVOIDANCE_PROFILES.city,
+  cluster: {
+    strategy: "stable-spherical",
+    minCount: 2,
+    maxMarkersPerDot: 14,
+    transitionMs: 220,
+    bandHysteresis: 0.08,
+    disableAboveZoom: 2.5,
+    bands: [
+      { key: "far", maxZoom: 1.7, distance: 15 },
+      { key: "mid", maxZoom: 2.6, distance: 8 },
+      { key: "near", maxZoom: 3.5, distance: 4 },
+      { key: "detail", maxZoom: Infinity, distance: 0 },
+    ],
+  },
+});
+```
+
+Realtime layers can stay dynamic:
+
+```js
+const vesselIconLayer = createInteractableLayer({
+  id: "vessels",
+  // ...
+  cluster: {
+    strategy: "dynamic-screen",
+    enabled: true,
+    maxMarkersPerDot: 10,
+  },
+});
+```
+
+## Tuning
+
+- `distance` is the 3D globe-distance threshold and uses the same unit as `CONFIG.earthRadius`. Larger values cluster more aggressively.
+- The farthest band usually uses a larger `distance`; the nearest detail band usually uses `0` to split clusters into original icons.
+- `bandHysteresis` controls band-boundary stickiness. Too little can flicker near thresholds; too much can make band changes feel late.
+- `transitionMs` controls cluster split/merge easing. Keep it around 160-260ms; longer durations can make realtime layers feel sluggish.
+- `disableAboveZoom` controls the precision-view threshold. It defaults to `2.5`; above that zoom, no cluster dots are generated. Set it to `false` to disable the hard threshold.
+- High-frequency realtime layers should prefer `dynamic-screen` so frequent data changes do not trigger stable topology recomputation.
+- If a layer behaves poorly, switch it back to `dynamic-screen` or use `cluster: false`.
+
+## Acceptance Checks
+
+- Rotating the globe inside one zoom band should not cause clusters to flicker or regroup.
+- Cluster dots should stay aligned with the globe-surface centroid and should not be pushed by avoidance.
+- Zooming into the detail band should restore the layer's original icon textures and click behavior.
+- Zoom levels above 250% should not show cluster dots.
+- Realtime layers such as vessels should reflect incoming updates immediately.

docs/technical/en/ops-runbook.md

@@ -286,6 +286,8 @@ bun run build
 
 Do not use `npm run ...`. In the WSL / Windows mixed environment Bun avoids Node/npm path inconsistencies.
 
+`./planet.sh start` / `init` now runs `bun install` before startup instead of only checking whether the Vite entry file exists. This keeps new devices, cleaned `node_modules`, and lockfile changes synchronized before the console loads, avoiding dynamic-import 500s caused by missing frontend dependencies.
+
 Validate the frontend build:
 
 ```bash