feat(loom): A3.1 — explode (peel-apart floors) + dependency lines (#267)

The "exploded" in BIM exploded view: a slider separates the stacked
floors vertically, and the model's dependency edges are drawn as 3D lines
between component boxes that re-route as the floors move.

- axon.ts: each layer is now a THREE.Group (floor) movable on y. New
  `setExplode(0..1)` maps to the floor gap (MIN_FLOOR_GAP..MAX_FLOOR_GAP).
- One THREE.Line per `/api/architecture` edge (source→target box); on each
  explode change the lines are re-routed to the boxes' new world positions
  (getWorldPosition after updateMatrixWorld).
- `#axon-explode` slider (bottom-right, shown only in 3D), wired to
  setExplode; localized label (en/es/zh-CN).

Verified on Sentinel: cranking the slider separates the 7 floors and the
dependency lines stretch across the gaps. 719 Rust tests unaffected; tsc +
vite build clean. No tag — loom-0.6.0 rides A3.3.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: montfort

experimento/specs/002-architecture-plan/tasks.md

@@ -347,8 +347,13 @@
   `/api/architecture` (auto-laid-out per floor — the 3D view doesn't need the human DrawIO
   geometry). Verified on Sentinel (7 floors stacked) + the demo (all 5 state colors). `tsc` +
   `vite build` clean.
-- [ ] **A3.1 — Explode.** A slider that separates the floors vertically (the BIM peel-apart) +
-  cross-layer dependency connectors (the `links` as 3D lines between boxes).
+- [x] **A3.1 — Explode.** `axon.ts` refactored so each layer is a `THREE.Group` (a "floor")
+  movable on `y`; an **Explode slider** (`#axon-explode`, bottom-right, localized) drives
+  `setExplode(0..1)` → floor gap `MIN_FLOOR_GAP..MAX_FLOOR_GAP` (the BIM peel-apart). Each model
+  edge (`/api/architecture` `edges`) is a `THREE.Line` between the source/target boxes; on every
+  explode change the lines are re-routed to the boxes' new world positions
+  (`getWorldPosition` after `updateMatrixWorld`). Verified on Sentinel (7 floors separate, the
+  dependency lines stretch across the gaps). `tsc` + `vite build` clean.
 - [ ] **A3.2 — Interaction & labels.** Floor labels (layer names) + component labels (sprites),
   click a box → the A2.4 component detail panel, hover highlight. Reuse the where/legend panels.
 - [ ] **A3.3 — Acceptance + release.** Dogfood; `experimento/CHANGELOG.md` + bump

experimento/web/index.html

@@ -105,6 +105,9 @@
       #plan-mode button { color:var(--muted); background:none; border:1px solid var(--border); border-radius:5px; padding:3px 9px; font-size:11px; font-weight:600; }
       #plan-mode button:hover { color:var(--text); }
       #plan-mode button.active { color:#14161c; background:var(--accent); border-color:var(--accent); }
+      #axon-explode { position:absolute; right:14px; bottom:14px; z-index:110; display:none; align-items:center; gap:9px; background:var(--panel); border:1px solid var(--border); border-radius:10px; padding:8px 13px; color:var(--muted); font-size:11px; }
+      body.view-plan.plan-3d #axon-explode { display:flex; }
+      #axon-explode input { width:130px; accent-color:var(--accent); cursor:pointer; }
       body.view-plan #plan-legend { display:block; }
       body.view-plan #graph, body.view-plan .kg-only, body.view-plan #stats, body.view-plan #legend, body.view-plan #selection, body.view-plan #zoom-controls { display:none !important; }
       #plan-legend { position:absolute; left:14px; bottom:14px; z-index:100; display:none; background:var(--panel); border:1px solid var(--border); border-radius:10px; padding:9px 11px; font-size:11px; color:var(--muted); }
@@ -200,6 +203,10 @@ <h1><span class="brand">Loom</span> · <span id="subtitle">knowledge graph</span
       <button type="button" id="plan-zoom-out" title="Zoom out"><svg viewBox="0 0 16 16" aria-hidden="true"><path d="M3 8h10" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round"/></svg></button>
       <button type="button" id="plan-zoom-fit" title="Fit to view"><svg viewBox="0 0 16 16" aria-hidden="true"><path d="M3 6V3h3M13 6V3h-3M3 10v3h3M13 10v3h-3" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"/></svg></button>
     </div>
+    <div id="axon-explode">
+      <span id="axon-explode-label">Explode</span>
+      <input type="range" id="axon-explode-range" min="0" max="100" value="25" aria-label="Explode floors" />
+    </div>
     <script type="module" src="/src/main.ts"></script>
   </body>
 </html>

experimento/web/src/axon.ts

@@ -1,13 +1,13 @@
 //! Axonometric / BIM exploded view (Loom A3, Spec 002 §12 north star): the
-//! architecture model rendered in 3D — each layer is a stacked "floor", each
-//! component a box on it, colored by the §4 "you are here" status. A real WebGL
-//! scene (Three.js) with an **orthographic** camera (true axonometric — parallel
-//! projection, no perspective) and orbit controls. Explode (separating the
-//! floors) and labels land in A3.1/A3.2.
+//! architecture model in 3D — each layer is a stacked "floor", each component a
+//! box on it, colored by the §4 "you are here" status. A real WebGL scene
+//! (Three.js) with an **orthographic** camera (true axonometric — parallel
+//! projection) and orbit controls.
 //!
-//! Same model as the 2D plan (`/api/architecture`); this is just a second view
-//! of it (the BIM "one model, many views"). Auto-laid-out per floor — the 3D
-//! view doesn't need the human `plan.drawio` geometry.
+//! A3.1 adds the **explode** (a slider that separates the floors vertically —
+//! the BIM "peel apart") and the **dependency lines** (the model's `links` as
+//! 3D connectors between boxes, redrawn as floors move). Labels + click-detail
+//! land in A3.2.
 
 import * as THREE from 'three';
 import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
@@ -25,10 +25,15 @@ interface ArchLayer {
   label: string;
   order: number;
 }
+interface ArchEdge {
+  source: string;
+  target: string;
+}
 interface ArchResponse {
   model_present: boolean;
   layers: ArchLayer[];
   components: ArchComponent[];
+  edges: ArchEdge[];
 }
 
 const PRIORITY = ['active', 'in-progress', 'implemented', 'has-debt', 'wiring-gap', 'uncharted'];
@@ -38,8 +43,19 @@ const BOX_W = 4;
 const BOX_H = 1.4;
 const BOX_D = 3;
 const GAP_X = 2.4;
-const FLOOR_GAP = 6; // vertical spacing between floors (A3.1 makes this a slider)
 const SLAB_PAD = 2;
+const MIN_FLOOR_GAP = 3.2; // compact
+const MAX_FLOOR_GAP = 17; // fully exploded
+
+interface Floor {
+  group: THREE.Group;
+  index: number; // 0..n-1 bottom→top
+}
+interface Conn {
+  line: THREE.Line;
+  a: THREE.Object3D;
+  b: THREE.Object3D;
+}
 
 interface Scene3D {
   renderer: THREE.WebGLRenderer;
@@ -48,12 +64,15 @@ interface Scene3D {
   controls: OrbitControls;
   frame: number;
   onResize: () => void;
+  floors: Floor[];
+  conns: Conn[];
+  layerCount: number;
 }
 
 let current: Scene3D | null = null;
 
 /** (Re)render the axonometric view into `container`. Idempotent. */
-export async function renderAxon(container: HTMLElement): Promise<void> {
+export async function renderAxon(container: HTMLElement, explode = 0.25): Promise<void> {
   let arch: ArchResponse;
   try {
     arch = await fetch('/api/architecture').then((r) => r.json() as Promise<ArchResponse>);
@@ -75,7 +94,6 @@ export async function renderAxon(container: HTMLElement): Promise<void> {
   const scene = new THREE.Scene();
   scene.background = new THREE.Color('#14161c');
 
-  // Orthographic camera = true axonometric (parallel) projection.
   const frustum = 26;
   const aspect = width / height;
   const camera = new THREE.OrthographicCamera(
@@ -104,7 +122,8 @@ export async function renderAxon(container: HTMLElement): Promise<void> {
   controls.dampingFactor = 0.1;
   controls.target.set(0, 0, 0);
 
-  buildFloors(scene, arch);
+  const { floors, boxByComp } = buildFloors(scene, arch);
+  const conns = buildConnections(scene, arch, boxByComp);
 
   const onResize = () => {
     const w = container.clientWidth || width;
@@ -119,32 +138,46 @@ export async function renderAxon(container: HTMLElement): Promise<void> {
   };
   window.addEventListener('resize', onResize);
 
-  const s: Scene3D = { renderer, scene, camera, controls, frame: 0, onResize };
+  const s: Scene3D = {
+    renderer,
+    scene,
+    camera,
+    controls,
+    frame: 0,
+    onResize,
+    floors,
+    conns,
+    layerCount: floors.length,
+  };
+  current = s;
+  applyExplode(s, explode);
+
   const tick = () => {
     controls.update();
     renderer.render(scene, camera);
     s.frame = requestAnimationFrame(tick);
   };
   tick();
-  current = s;
 }
 
-/** Build a stacked floor per layer with a box per component (centered). */
-function buildFloors(scene: THREE.Scene, arch: ArchResponse): void {
-  const layers = [...arch.layers].sort((a, b) => a.order - b.order);
-  // Center the whole stack vertically.
-  const yOffset = ((layers.length - 1) * FLOOR_GAP) / 2;
+/** Build a floor group per layer with a box per component; index the boxes. */
+function buildFloors(
+  scene: THREE.Scene,
+  arch: ArchResponse,
+): { floors: Floor[]; boxByComp: Map<string, THREE.Object3D> } {
+  const layers = [...arch.layers]
+    .sort((a, b) => a.order - b.order)
+    .filter((l) => arch.components.some((c) => c.layer === l.id));
+  const boxByComp = new Map<string, THREE.Object3D>();
+  const floors: Floor[] = [];
 
   layers.forEach((layer, i) => {
     const comps = arch.components.filter((c) => c.layer === layer.id);
-    if (comps.length === 0) return;
-    const y = i * FLOOR_GAP - yOffset;
+    const group = new THREE.Group();
 
-    // Row of boxes, centered on x.
     const rowWidth = comps.length * BOX_W + (comps.length - 1) * GAP_X;
     let x = -rowWidth / 2 + BOX_W / 2;
 
-    // Translucent slab = the "floor".
     const slab = new THREE.Mesh(
       new THREE.BoxGeometry(rowWidth + SLAB_PAD * 2, 0.25, BOX_D + SLAB_PAD * 2),
       new THREE.MeshStandardMaterial({
@@ -154,8 +187,8 @@ function buildFloors(scene: THREE.Scene, arch: ArchResponse): void {
         roughness: 0.9,
       }),
     );
-    slab.position.set(0, y - BOX_H / 2 - 0.4, 0);
-    scene.add(slab);
+    slab.position.set(0, -BOX_H / 2 - 0.4, 0);
+    group.add(slab);
 
     for (const comp of comps) {
       const state = pickState(comp.states);
@@ -170,18 +203,67 @@ function buildFloors(scene: THREE.Scene, arch: ArchResponse): void {
           metalness: 0.1,
         }),
       );
-      box.position.set(x, y, 0);
+      box.position.set(x, 0, 0);
       box.userData = { componentId: comp.id, label: comp.label };
-      // Crisp edge outline in the component's stroke color.
-      const edges = new THREE.LineSegments(
-        new THREE.EdgesGeometry(box.geometry),
-        new THREE.LineBasicMaterial({ color: new THREE.Color(palette.stroke) }),
+      box.add(
+        new THREE.LineSegments(
+          new THREE.EdgesGeometry(box.geometry),
+          new THREE.LineBasicMaterial({ color: new THREE.Color(palette.stroke) }),
+        ),
       );
-      box.add(edges);
-      scene.add(box);
+      group.add(box);
+      boxByComp.set(comp.id, box);
       x += BOX_W + GAP_X;
     }
+
+    scene.add(group);
+    floors.push({ group, index: i });
   });
+
+  return { floors, boxByComp };
+}
+
+/** One line per model edge (source → target component box). */
+function buildConnections(
+  scene: THREE.Scene,
+  arch: ArchResponse,
+  boxByComp: Map<string, THREE.Object3D>,
+): Conn[] {
+  const conns: Conn[] = [];
+  const material = new THREE.LineBasicMaterial({ color: 0x6b7280, transparent: true, opacity: 0.75 });
+  for (const edge of arch.edges) {
+    const a = boxByComp.get(edge.source);
+    const b = boxByComp.get(edge.target);
+    if (!a || !b) continue;
+    const geom = new THREE.BufferGeometry().setFromPoints([new THREE.Vector3(), new THREE.Vector3()]);
+    const line = new THREE.Line(geom, material);
+    scene.add(line);
+    conns.push({ line, a, b });
+  }
+  return conns;
+}
+
+/** Position the floors at the given explode amount (0 compact … 1 exploded)
+ * and re-route the dependency lines to the boxes' new world positions. */
+function applyExplode(s: Scene3D, amount: number): void {
+  const gap = MIN_FLOOR_GAP + amount * (MAX_FLOOR_GAP - MIN_FLOOR_GAP);
+  const yOffset = ((s.layerCount - 1) * gap) / 2;
+  for (const f of s.floors) {
+    f.group.position.y = f.index * gap - yOffset;
+  }
+  s.scene.updateMatrixWorld(true);
+  const pa = new THREE.Vector3();
+  const pb = new THREE.Vector3();
+  for (const c of s.conns) {
+    c.a.getWorldPosition(pa);
+    c.b.getWorldPosition(pb);
+    c.line.geometry.setFromPoints([pa.clone(), pb.clone()]);
+  }
+}
+
+/** Set the explode amount on the live scene (called by the slider). */
+export function setExplode(amount: number): void {
+  if (current) applyExplode(current, Math.max(0, Math.min(1, amount)));
 }
 
 function pickState(states: string[]): string {
@@ -198,7 +280,7 @@ export function dispose(): void {
   window.removeEventListener('resize', current.onResize);
   current.controls.dispose();
   current.scene.traverse((obj) => {
-    if (obj instanceof THREE.Mesh || obj instanceof THREE.LineSegments) {
+    if (obj instanceof THREE.Mesh || obj instanceof THREE.LineSegments || obj instanceof THREE.Line) {
       obj.geometry.dispose();
       const m = obj.material;
       if (Array.isArray(m)) m.forEach((mm) => mm.dispose());

experimento/web/src/i18n.ts

@@ -15,6 +15,7 @@ const STRINGS: Record<Locale, Dict> = {
     'tab.kg': 'Knowledge Graph',
     'tab.plan': 'Architecture',
     'plan.subtitle': 'architecture plan',
+    'axon.explode': 'Explode',
     'plan.legend': 'Status',
     'plan.empty': 'No architecture model yet — run `straymark architecture generate` to draft one.',
     'plan.error': 'Could not load the architecture plan.',
@@ -93,6 +94,7 @@ const STRINGS: Record<Locale, Dict> = {
     'tab.kg': 'Grafo de conocimiento',
     'tab.plan': 'Arquitectura',
     'plan.subtitle': 'plano de arquitectura',
+    'axon.explode': 'Separar capas',
     'plan.legend': 'Estado',
     'plan.empty': 'Aún no hay modelo de arquitectura — ejecuta `straymark architecture generate` para crear uno.',
     'plan.error': 'No se pudo cargar el plano de arquitectura.',
@@ -171,6 +173,7 @@ const STRINGS: Record<Locale, Dict> = {
     'tab.kg': '知识图谱',
     'tab.plan': '架构',
     'plan.subtitle': '架构平面图',
+    'axon.explode': '分离层',
     'plan.legend': '状态',
     'plan.empty': '尚无架构模型 — 运行 `straymark architecture generate` 生成草稿。',
     'plan.error': '无法加载架构平面图。',

experimento/web/src/main.ts

@@ -11,7 +11,7 @@ import Sigma from 'sigma';
 
 import { setLocale, t } from './i18n';
 import { renderPlan, stateColor, LEGEND_STATES, setPlanHooks } from './plan';
-import { renderAxon, dispose as disposeAxon } from './axon';
+import { renderAxon, dispose as disposeAxon, setExplode } from './axon';
 
 interface ApiNode {
   id: string;
@@ -705,6 +705,7 @@ function applyStaticI18n(): void {
   document.getElementById('badge')!.textContent = t('app.experimental');
   document.getElementById('tab-kg')!.textContent = t('tab.kg');
   document.getElementById('tab-plan')!.textContent = t('tab.plan');
+  document.getElementById('axon-explode-label')!.textContent = t('axon.explode');
   buildPlanLegend();
   searchEl.placeholder = t('search.placeholder');
   document.getElementById('sizing-label')!.textContent = t('size.label');
@@ -874,6 +875,9 @@ for (const b of planModeBtns) {
   b.addEventListener('click', () => setPlanMode((b.dataset.mode as PlanMode) ?? '2d'));
 }
 
+const axonExplode = document.getElementById('axon-explode-range') as HTMLInputElement | null;
+axonExplode?.addEventListener('input', () => setExplode(Number(axonExplode.value) / 100));
+
 /** The color legend for the plan's status overlay (localized). */
 function buildPlanLegend(): void {
   planLegendEl.innerHTML =