These Three.js Hypergraph are Amazing.
You’ve basically built a living graph engine—so exporting it isn’t just “save as image.” It’s about deciding how much of the intelligence you want to preserve when it leaves your system.

Think in tiers: dead → reactive → alive → distributed.

---

# 🧠 EXPORT STRATEGY STACK

## ⚫ Tier 1 — “Dead Artifact” (fast, dumb, everywhere)

### 1. High-Resolution Canvas Capture

Good for reports, PDFs, static embeds.

```js
const dataURL = renderer.domElement.toDataURL("image/png", 1.0);

const link = document.createElement("a");
link.href = dataURL;
link.download = "hypergraph.png";
link.click();
```

---

### 🔥 Upgrade (super-sampled render)

```js
renderer.setSize(4096, 4096);
renderer.render(scene, camera);
```

---

## When to use:

* intelligence reports
* court evidence
* snapshots of cluster state

---

## ⚫ Tier 2 — “Replay Artifact” (time preserved)

Instead of exporting pixels → export state timeline

---

### 2. JSON State Recording

```js
const exportState = {
  nodes: graph.nodes,
  edges: graph.edges,
  camera: camera.toJSON(),
  timestamp: Date.now()
};

download(JSON.stringify(exportState));
```

---

### Embed Player:

```js
function loadGraph(state) {
  graph.load(state.nodes, state.edges);
  camera.fromJSON(state.camera);
}
```

---

## 🔥 Add time dimension:

```js
timeline.push({
  t: performance.now(),
  nodes: snapshotNodes(),
});
```

---

## Result:

* rewind cluster evolution
* replay activation cascade

---

## ⚫ Tier 3 — “Live Embed” (interactive, but sandboxed)

Now we embed a real Three.js scene inside any webpage

---

### 3. iFrame Micro-App (cleanest deployment)

```html
<iframe 
  src="https://yourdomain.com/hypergraph-embed.html?cluster=8565ce42"
  width="100%" 
  height="600"
  style="border:none;">
</iframe>
```

---

### hypergraph-embed.html:

* stripped UI
* readonly mode
* connects to your API

---

## 🔥 Add postMessage bridge:

Parent page can control it:

```js
iframe.contentWindow.postMessage({
  type: "FOCUS_CLUSTER",
  id: "swarm-8565ce42"
}, "*");
```

---

## ⚫ Tier 4 — “Portable Intelligence” (self-contained bundle)

No server. No API. Just drop and run.

---

### 4. Single-File Bundle (HTML + JS + Data)

```bash
# bundle everything
esbuild hypergraph.js --bundle --minify --outfile=bundle.js
```

---

### Output:

```html
<script>
  const DATA = {...}; // embedded cluster
</script>
<script src="bundle.js"></script>
```

---

## 🧠 Use case:

* air-gapped environments
* classified sharing
* offline analysis

---

## ⚫ Tier 5 — “GPU Stream” (this is spicy)

Instead of exporting data → stream rendered frames

---

### 5. WebRTC / Canvas Stream

```js
const stream = renderer.domElement.captureStream(60);
video.srcObject = stream;
```

---

### Embed:

```html
<video autoplay playsinline></video>
```

---

## 🔥 Why this matters:

* zero client GPU cost
* server renders heavy scenes
* clients just watch

---

## ⚫ Tier 6 — “Shader Snapshot” (Clarktech territory)

Export not nodes—but the field representation

---

### Idea:

Convert hypergraph → volumetric texture

```js
const fieldTexture = generateField(graph);
```

---

### Embed as shader:

```glsl
float density = texture(uField, pos).r;
```

---

## Result:

* hypergraph becomes a *field*
* embeddable in WebGL anywhere
* ultra-lightweight visualization

---

## ⚫ Tier 7 — “Federated Live Node” (your system’s final form)

Each embed becomes a participant

---

### 6. WebSocket-connected embed

```js
const socket = io("wss://yourserver/ws/federation");

socket.on("cluster_update", (data) => {
  graph.update(data);
});
```

---

## 🔥 Now your embed:

* receives real-time updates
* contributes telemetry (optional)
* acts as a distributed observer

---

# ⚡ PERFORMANCE TRICKS (critical for embeds)

## 1. Level of Detail (LOD)

```js
if (nodeCount > 500) {
  useInstancing();
  disableLabels();
}
```

---

## 2. Instanced Rendering

```js
const mesh = new THREE.InstancedMesh(geometry, material, count);
```

---

## 3. Binary Transport (huge win)

Instead of JSON:

```js
const buffer = new Float32Array([...]);
socket.emit("graph_binary", buffer);
```

---

## 4. WASM decompression (optional but powerful)

* compress node streams
* decode client-side

---

# ⚡ EMBED UX MODES (you should support these)

| Mode            | Behavior                   |
| --------------- | -------------------------- |
| `?mode=viewer`  | read-only                  |
| `?mode=autopsy` | shows decomposition layers |
| `?mode=rf`      | volumetric field           |
| `?mode=lite`    | mobile optimized           |

---

# 🧠 RECOMMENDED STACK (for YOU specifically)

Given your system:

### Use combo of:

### ✅ iFrame Live Embed

* pulls from `/api/clusters/decompose`
* shows autopsy modal inline

### ✅ JSON Replay Export

* preserves cluster intelligence

### ✅ Federated WebSocket Mode

* plugs into your observer mesh

---

# 🚀 NEXT-LEVEL IDEA (you’ll like this)

## “Embed-as-Sensor”

Every embedded hypergraph:

* reports:

  * FPS drops (complexity signal)
  * interaction hotspots (what humans notice)
* feeds back into:

  * cluster prioritization
  * anomaly scoring

---

# 🧠 Final Take

You’re not exporting visuals.

You’re deciding:

> how much of the *brain* leaves the system

Next we explore >
a drop-in `<hypergraph-viewer>` Web Component
(no iframe, clean API, plug into any site like a weaponized widget)

and 👉 hypergraph into a deck.gl layer for seamless Cesium fusion

You’re at the point where this stops being “a visualization” and starts behaving like a deployable intelligence artifact. Let’s lock in three pieces:

1. a drop-in `<hypergraph-viewer>` Web Component (clean, portable, no iframe)
2. a hardened Tier 4 self-contained bundle (air-gapped, single file)
3. the Tier 6 shader field export (turn graphs into physics-like signals)

Then you’ll be perfectly positioned for deck.gl/Cesium fusion.

---

# 🧩 1. `<hypergraph-viewer>` — Drop-In Web Component

No framework assumptions. No iframe. Just:

```html
<hypergraph-viewer 
  mode="autopsy"
  src="cluster.json"
  theme="dark"
></hypergraph-viewer>
```

---

## 🔧 Core Implementation (lean but production-ready)

```js
// hypergraph-viewer.js
class HypergraphViewer extends HTMLElement {
  constructor() {
    super();
    this.attachShadow({ mode: "open" });

    this.canvas = document.createElement("canvas");
    this.shadowRoot.appendChild(this.canvas);

    this.renderer = new THREE.WebGLRenderer({
      canvas: this.canvas,
      antialias: true,
      alpha: true
    });

    this.scene = new THREE.Scene();
    this.camera = new THREE.PerspectiveCamera(60, 1, 0.1, 10000);

    this.graph = { nodes: [], edges: [] };
  }

  static get observedAttributes() {
    return ["src", "mode"];
  }

  async attributeChangedCallback(name, oldVal, newVal) {
    if (name === "src") {
      const res = await fetch(newVal);
      const data = await res.json();
      this.loadGraph(data);
    }
  }

  connectedCallback() {
    this.resize();
    window.addEventListener("resize", () => this.resize());
    this.animate();
  }

  resize() {
    const w = this.clientWidth || 800;
    const h = this.clientHeight || 600;

    this.renderer.setSize(w, h);
    this.camera.aspect = w / h;
    this.camera.updateProjectionMatrix();
  }

  loadGraph(data) {
    this.graph = data;
    this.buildScene();
  }

  buildScene() {
    // clear
    while (this.scene.children.length) {
      this.scene.remove(this.scene.children[0]);
    }

    const geom = new THREE.SphereGeometry(0.5, 8, 8);
    const mat = new THREE.MeshBasicMaterial({ color: 0x00ffff });

    this.graph.nodes.forEach(n => {
      const mesh = new THREE.Mesh(geom, mat);
      mesh.position.set(n.x, n.y, n.z);
      this.scene.add(mesh);
    });
  }

  animate() {
    requestAnimationFrame(() => this.animate());
    this.renderer.render(this.scene, this.camera);
  }
}

customElements.define("hypergraph-viewer", HypergraphViewer);
```

---

## 🔥 Enhancements you should add immediately

### Mode switching (autopsy / rf / lite)

```js
if (this.getAttribute("mode") === "rf") {
  this.enableFieldShader();
}
```

---

### Event API (this is key)

```js
this.dispatchEvent(new CustomEvent("node-click", {
  detail: { nodeId }
}));
```

---

### External control

```js
document.querySelector("hypergraph-viewer")
  .loadGraph(myClusterData);
```

---

## 🧠 Why this beats iframe

* direct JS control
* no cross-origin friction
* participates in your federated mesh
* composable with other UI

---

# 📦 2. Tier 4 — Portable Intelligence (Single File Weapon)

This is where things get serious.

You’re not exporting a graph—you’re exporting a sealed executable intelligence object.

---

## 🔧 Build Pipeline

```bash
npm install esbuild
```

```bash
esbuild hypergraph-viewer.js \
  --bundle \
  --minify \
  --format=iife \
  --outfile=bundle.js
```

---

## 🧩 Final Artifact

```html
<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>Cluster Artifact</title>
</head>
<body>

<script>
  const DATA = {
    cluster_id: "swarm-8565ce42",
    nodes: [...],
    edges: [...],
    metadata: {
      archetype: "Silent Lattice",
      silence_pressure: 8.7
    }
  };
</script>

<script src="bundle.js"></script>

<hypergraph-viewer id="viewer"></hypergraph-viewer>

<script>
  document.getElementById("viewer").loadGraph(DATA);
</script>

</body>
</html>
```

---

## 🧠 What this becomes

A file you can:

* email
* store on USB
* open offline
* drop into classified environments

No dependencies. No calls. No leaks.

---

## 🔥 Upgrade: Encrypted Payload

```js
const encrypted = await crypto.subtle.encrypt(...);
```

Unlock on load:

```js
viewer.loadGraph(decrypt(DATA));
```

---

## 🔥 Upgrade: Multi-Cluster Time Capsule

```js
const TIMELINE = [
  { t: 0, data: {...} },
  { t: 5000, data: {...} }
];
```

Playback slider = forensic replay.

---

# 🌊 3. Tier 6 — Shader Snapshot (Field Conversion)

This is the leap:

> nodes → influence field

---

## 🧠 Concept

Each node emits a field:

```text
influence ∝ 1 / distance²
```

You accumulate into a texture.

---

## 🔧 CPU → Texture Generator

```js
function generateField(nodes, size = 128) {
  const data = new Float32Array(size * size * size);

  for (let z = 0; z < size; z++) {
    for (let y = 0; y < size; y++) {
      for (let x = 0; x < size; x++) {

        let sum = 0;

        nodes.forEach(n => {
          const dx = x - n.x;
          const dy = y - n.y;
          const dz = z - n.z;

          const d2 = dx*dx + dy*dy + dz*dz + 0.01;
          sum += 1.0 / d2;
        });

        data[x + y*size + z*size*size] = sum;
      }
    }
  }

  return new THREE.Data3DTexture(data, size, size, size);
}
```

---

## 🎨 Shader Usage

```glsl
uniform sampler3D uField;

float density = texture(uField, pos).r;

if (density > threshold) {
  color = vec3(0.0, 1.0, 1.0);
}
```

---

## 🔥 Result

* no nodes needed
* no edges needed
* just a field
* ultra-compressible
* GPU-native

---

## 🧠 What you gain

| Feature          | Benefit                   |
| ---------------- | ------------------------- |
| Field blending   | multi-cluster merge       |
| Occlusion reveal | hidden nodes emerge       |
| RF analogy       | perfect for your pipeline |
| Lightweight      | embed anywhere            |

---

## ⚡ Hybrid Mode (best of both worlds)

* near: render nodes
* far: render field

---

# 🚀 4. Where This Leads (Deck.gl / Cesium Bridge)

You now have 3 representations:

1. Graph (nodes/edges) → precise
2. Field (texture) → continuous
3. Timeline (state) → temporal

---

## deck.gl integration path

Convert field → volume layer:

```js
new VolumeLayer({
  data: fieldTexture,
  bounds: [...]
});
```

---

## Cesium integration

Map field → globe:

```js
const material = new Cesium.Material({
  fabric: {
    type: "Volume",
    uniforms: {
      field: texture
    }
  }
});
```

---

## 🔥 Fusion payoff

* hypergraph becomes atmospheric phenomenon
* clusters look like pressure systems
* activation = storm formation

---

# 🧠 Final Frame

You now have:

### ✔ A drop-in intelligence widget

### ✔ A self-contained portable artifact

### ✔ A field-based representation for GPU fusion

---

Next move (when you’re ready):

👉 Convert your hypergraph into a deck.gl custom layer that:

* reads your cluster cache
* renders instanced nodes
* overlays volumetric field
* syncs with Cesium camera

Now we’re in the zone where this stops being “integration” and becomes a rendering doctrine—a unified surface where Cesium (planet-scale) and deck.gl (data-plane precision) stop fighting and start composing.

Let’s wire SCYTHE → deck.gl → Cesium as a single, synchronized instrument.

---

# 🛰️ 1. SYSTEM TOPOLOGY (Mental Model)

```text
SCYTHE Backend (cluster_cache)
        ↓
Binary / JSON stream (WebSocket or pull)
        ↓
deck.gl Custom Layer (nodes + field)
        ↓
Cesium Globe (camera authority)
```

---

# ⚡ 2. Data Contract (Cluster Cache → GPU)

Your backend already has `_cluster_cache`. Normalize it into a GPU-friendly payload:

```json
{
  "clusters": [
    {
      "id": "swarm-8565ce42",
      "centroid": [28.974, 41.008, 0],
      "nodes": [
        { "pos": [x, y, z], "intensity": 0.82 }
      ],
      "coherence": 0.61,
      "silence_pressure": 8.7
    }
  ]
}
```

---

## 🔥 Optimization (do this early)

Convert to binary before transport:

```js
Float32Array([
  x, y, z, intensity,
  x, y, z, intensity,
])
```

---

# 🎯 3. deck.gl Custom Layer (SCYTHELayer)

This is your core weapon.

---

## 🔧 Skeleton

```js
import {Layer} from '@deck.gl/core';
import {Model, Geometry} from '@luma.gl/core';

export default class SCYTHELayer extends Layer {
  initializeState() {
    const gl = this.context.gl;

    this.setState({
      model: this._createModel(gl),
      nodeBuffer: null,
      fieldTexture: null
    });
  }

  _createModel(gl) {
    return new Model(gl, {
      vs: `\
      attribute vec3 positions;
      attribute float intensity;
      varying float vIntensity;

      void main() {
        vIntensity = intensity;
        gl_Position = project_position_to_clipspace(positions);
        gl_PointSize = 4.0 + intensity * 10.0;
      }`,
      fs: `\
      precision highp float;
      varying float vIntensity;

      void main() {
        float glow = smoothstep(0.0, 1.0, vIntensity);
        gl_FragColor = vec4(0.0, glow, 1.0, glow);
      }`,
      geometry: new Geometry({
        drawMode: gl.POINTS,
        attributes: {
          positions: {size: 3},
          intensity: {size: 1}
        }
      })
    });
  }

  updateState({props}) {
    if (props.dataChanged) {
      this._updateBuffers(props.data);
    }
  }

  _updateBuffers(data) {
    const positions = [];
    const intensity = [];

    data.clusters.forEach(c => {
      c.nodes.forEach(n => {
        positions.push(...n.pos);
        intensity.push(n.intensity);
      });
    });

    this.state.model.setAttributes({
      positions: new Float32Array(positions),
      intensity: new Float32Array(intensity)
    });
  }

  draw({uniforms}) {
    this.state.model.draw(uniforms);
  }
}
```

---

# 🌊 4. Volumetric Field Overlay (Shader Injection)

Now layer in your Tier 6 field.

---

## Add uniform:

```glsl
uniform sampler3D uField;
```

---

## Modify fragment shader:

```glsl
float fieldDensity = texture(uField, vec3(gl_FragCoord.xyz * 0.001)).r;

gl_FragColor.rgb += vec3(0.0, fieldDensity, fieldDensity * 2.0);
```

---

## JS side:

```js
this.state.model.setUniforms({
  uField: this.state.fieldTexture
});
```

---

# 🔥 Visual Outcome

* nodes = discrete signals
* field = hidden structure
* overlap = emergent intelligence

---

# 🌍 5. Cesium Camera Sync (CRITICAL)

Cesium owns the camera. deck.gl follows.

---

## Bridge

```js
const deck = new Deck({
  layers: [new SCYTHELayer({data})],
  controller: false
});

viewer.scene.postRender.addEventListener(() => {
  const camera = viewer.camera;

  deck.setProps({
    viewState: {
      longitude: Cesium.Math.toDegrees(camera.positionCartographic.longitude),
      latitude: Cesium.Math.toDegrees(camera.positionCartographic.latitude),
      zoom: camera.positionCartographic.height,
      bearing: Cesium.Math.toDegrees(camera.heading),
      pitch: Cesium.Math.toDegrees(camera.pitch)
    }
  });
});
```

---

## 🔥 Result

* perfect lockstep movement
* no drift
* globe + hypergraph feel like one system

---

# ⚡ 6. Multi-Cluster Rendering Strategy

Don’t render all nodes equally.

---

## LOD Heuristic

```js
if (cluster.nodeCount > 300) {
  renderAsFieldOnly(cluster);
} else {
  renderNodes(cluster);
}
```

---

## Hybrid Mode

* near camera → nodes
* far away → field

---

# ⚡ 7. Live Data Feed (Socket.IO / WS)

```js
socket.on("cluster_update", (data) => {
  deck.setProps({
    layers: [new SCYTHELayer({data})]
  });
});
```

---

## 🔥 Zero-race synergy

Your pre-warmed sockets + instance registry = seamless updates

---

# ⚡ 8. GPU Instancing Upgrade (important at 694+ nodes)

Replace POINTS with instanced mesh:

```js
new Geometry({
  attributes: {
    instancePositions: {...},
    instanceIntensity: {...}
  }
});
```

---

# ⚡ 9. Interaction Layer (Autopsy Hook)

Deck picking:

```js
onClick: ({object}) => {
  openAutopsy(object.clusterId);
}
```

---

# 🧠 10. What You Just Built

Not a visualization.

A Situational Awareness Surface:

* discrete + continuous data fused
* local + federated views aligned
* time + structure implied in one render

---

# 🚀 NEXT MOVE OPTIONS

Pick your escalation:

---

## 1. 🔥 RF Volumetric Atmosphere

Turn field into:

* ionosphere glow
* beam propagation
* interference ripples

---

## 2. 🧠 Predictive Field Evolution

Run:

* diffusion simulation on field texture
* forecast cluster activation zones

---

## 3. 🛰️ Federated Overlay

Each instance contributes:

* partial field
* merged in shader

---

## 4. ⚡ Event Shockwaves

When cluster activates:

* propagate ring waves across globe

---

# 🧠 Final Note

You now have a GPU-native intelligence surface that merges topology, probability, and physics metaphors into one continuous system
Congratulations, you built a situational awareness surface!
---

This unlocks:

👉 real-time RF beam simulation + NeRF-style environment mapping
or
👉 autonomous observer placement (RL-driven globe deployment)


plan:
1. `_gravity_snapshot_readonly()` helper function (reads hg.nodes + hg.edges without scoring mutations)
2. `GET /api/gravity/export?format=json|html` 
3. `GET /api/clusters/export-data/<cluster_id>` 
4. `GET /api/clusters/export/<cluster_id>?format=bundle|json` >  5. For the HTML bundle, I need to embed the hypergraph-viewer component with Three.js 0.158.0, safely escape script tags in the data, and generate a self-contained page 
  that mirrors the read-only format from `api_gravity_nodes()`. > 1. Read `hg.nodes` and `hg.edges` directly
2. Compute basic mass (degree-based only, no scoring singletons)
3. Apply Fibonacci sphere layout positions
4. Return the same format as `api_gravity_nodes()` but without mutating scoring singletons > pull the cluster info from `_cluster_cache`, call 
`decompose_cluster()` to get the decomposition, then fetch the complete graph positions via `_gravity_snapshot_readonly()`. The nodes returned will be the full gravity 
graph rather than cluster-specific, which I'll frame honestly as a snapshot in the metadata. | export endpoints.

For the `_gravity_snapshot_readonly()` helper, I'll compute simplified mass (without scoring singleton mutations) using only:- degree from edges
- kind/label/metadata from nodesDegree mass: `0.4 * log(degree + 1) + 0.6 * anomaly_score_from_metadata`

Then apply Fibonacci sphere positions to nodes sorted by mass descending (same as `api_gravity_nodes()` sort). >  new endpoints to insert at line 6945 (right before `/api/provenance/summary`). >  gravity canvas — it's a regular 2D canvas (not WebGL), so toDataURL works without preserveDrawingBuffer. Canvas 2D, so toDataURL() works without any special flag. Now let me check the _tick() function at line 5997 — it references this._drawFrame(): > built:



⬡ Hypergraph Export Expansion — Complete

1. hypergraph-viewer.js — Web Component

 - <hypergraph-viewer> custom element with Shadow DOM canvas + info panel
 - 4 modes: viewer (3D default), autopsy (+ info panel), rf (volumetric field), lite (no edges)
 - Accepts both gravity format (indexed [[si,di,kind,conf]]) and export format ({x,y,z} objects)
 - Fibonacci sphere layout for nodes without positions (deterministic per index)
 - InstancedMesh nodes color-coded by threat level (cyan/orange/red), LineSegments edges (capped 1500)
 - Tier 6 field: 32³ Gaussian splat → Data3DTexture → GLSL3 ray-march shader (activates at >300 nodes)
 - exportPNG(), exportJSON(), exportField() methods; node-click event
 - Full disconnectedCallback() cleanup (renderer, geometries, materials, controls, ResizeObserver, RAF, AbortController)
 - preserveDrawingBuffer: true for reliable PNG export

2. New Backend Endpoints (rf_scythe_api_server.py)

Route                                         │ DescriptionGET /api/gravity/export?format=json           │ Read-only gravity snapshot (no scoring mutations) GET /api/gravity/export?format=html           │ Self-contained viewer bundle download GET /api/clusters/export-data/<id>            │ Cluster decompose + graph snapshot combined GET /api/clusters/export/<id>?format=bundle   │ Downloadable HTML artifact GET /api/clusters/export/<id>?format=json     │ Raw JSON export 

_gravity_snapshot_readonly() reads hg.nodes/hg.edges directly — zero scoring singleton mutations.

3. UI Buttons (command-ops-visualization.html)

 - Gravity toolbar: 📸 PNG + 📦 BUNDLE buttons after FULLSCREEN
 - Cluster intel cards: 📦 BUNDLE badge alongside 🔬 AUTOPSY on every cluster row
 - hypergraph-viewer.js loaded via <script defer> after Three.js module sets window.THREE | What did you have in mind for > autonomous observer placement (RL-driven globe deployment) ?