@hybridlabor-api/bdb-synapse 1.0.0

package/web/src/scene/dirLabels.ts

@@ -0,0 +1,145 @@
+import * as THREE from "three";
+import { labelTexture } from "./textures";
+
+// Map-style LOD for directory names, shared by both scenes: a label shows
+// while its subtree spans enough screen pixels — zoom out and only the big
+// forks stay named, push in and deeper directories surface where you're
+// looking. Two colliding labels drop whichever names fewer files.
+
+export interface DirLabelEntry {
+  name: string;
+  x: number;
+  z: number;
+  /** world-space reach of the directory's subtree, drives the LOD cutoff */
+  radius: number;
+  fileCount: number;
+  depth: number;
+}
+
+interface DirLabel {
+  sprite: THREE.Sprite;
+  entry: DirLabelEntry;
+  aspect: number;
+  target: number;
+}
+
+const LABEL_MIN_SUBTREE_PX = 60;
+const LABEL_BUDGET = 120;
+
+export class DirLabelSet {
+  private readonly labels: DirLabel[] = [];
+  private readonly y: number;
+  private dirty = true;
+  private readonly lastCamPos = new THREE.Vector3(Infinity, Infinity, Infinity);
+  private readonly lastCamQuat = new THREE.Quaternion(0, 0, 0, 0);
+  private lastViewW = 0;
+  private lastViewH = 0;
+  private readonly point = new THREE.Vector3();
+
+  // sprites start invisible and fade in once the first projection pass runs;
+  // alwaysOnTop labels (terrain) skip the depth test so mountains never bury
+  // the district names
+  constructor(entries: DirLabelEntry[], group: THREE.Group, y: number, alwaysOnTop = false) {
+    this.y = y;
+    const budget = [...entries].sort((a, b) => b.fileCount - a.fileCount).slice(0, LABEL_BUDGET);
+    for (const entry of budget) {
+      const { texture, aspect } = labelTexture(entry.name);
+      const sprite = new THREE.Sprite(
+        new THREE.SpriteMaterial({
+          map: texture,
+          transparent: true,
+          opacity: 0,
+          depthWrite: false,
+          depthTest: !alwaysOnTop,
+          toneMapped: false,
+          fog: false
+        })
+      );
+      if (alwaysOnTop) sprite.renderOrder = 20;
+      sprite.visible = false;
+      sprite.position.set(entry.x, y, entry.z);
+      sprite.raycast = () => undefined;
+      group.add(sprite);
+      this.labels.push({ sprite, entry, aspect, target: 0 });
+    }
+  }
+
+  markDirty() {
+    this.dirty = true;
+  }
+
+  // reprojects subtrees whenever the camera or viewport moves, picks the
+  // labels whose subtree is prominent on screen, drops collision losers
+  updateTargets(camera: THREE.PerspectiveCamera, viewW: number, viewH: number) {
+    if (this.labels.length === 0 || viewW === 0 || viewH === 0) return;
+    const moved =
+      this.dirty ||
+      !camera.position.equals(this.lastCamPos) ||
+      !camera.quaternion.equals(this.lastCamQuat) ||
+      viewW !== this.lastViewW ||
+      viewH !== this.lastViewH;
+    if (!moved) return;
+    this.dirty = false;
+    this.lastCamPos.copy(camera.position);
+    this.lastCamQuat.copy(camera.quaternion);
+    this.lastViewW = viewW;
+    this.lastViewH = viewH;
+
+    const tanV = Math.tan(THREE.MathUtils.degToRad(camera.fov) / 2);
+    const maxDim = Math.max(viewW, viewH);
+    interface Candidate {
+      label: DirLabel;
+      sx: number;
+      sy: number;
+      pw: number;
+      ph: number;
+    }
+    const candidates: Candidate[] = [];
+    for (const label of this.labels) {
+      this.point.set(label.entry.x, this.y, label.entry.z);
+      const dist = this.point.distanceTo(camera.position);
+      const pxPerWorld = viewH / (2 * dist * tanV);
+      const subtreePx = label.entry.radius * pxPerWorld;
+      this.point.project(camera);
+      const sx = ((this.point.x + 1) / 2) * viewW;
+      const sy = ((1 - this.point.y) / 2) * viewH;
+      const onScreen = this.point.z < 1 && sx > -60 && sx < viewW + 60 && sy > -40 && sy < viewH + 40;
+      // too small to matter, or so large we're inside it — either way the
+      // name would float over unrelated geometry
+      if (!onScreen || subtreePx < LABEL_MIN_SUBTREE_PX || subtreePx > maxDim * 1.6) {
+        label.target = 0;
+        continue;
+      }
+      // constant screen-size type, like map labels
+      const ph = label.entry.depth <= 1 ? 15 : 13;
+      const worldH = ph / pxPerWorld;
+      label.sprite.scale.set(worldH * label.aspect, worldH, 1);
+      candidates.push({ label, sx, sy, pw: ph * label.aspect, ph });
+    }
+    candidates.sort((a, b) => b.label.entry.fileCount - a.label.entry.fileCount);
+    const kept: Candidate[] = [];
+    for (const candidate of candidates) {
+      const clash = kept.some(
+        (other) =>
+          Math.abs(other.sx - candidate.sx) < (other.pw + candidate.pw) / 2 + 14 &&
+          Math.abs(other.sy - candidate.sy) < (other.ph + candidate.ph) / 2 + 10
+      );
+      candidate.label.target = clash ? 0 : 1;
+      if (!clash) kept.push(candidate);
+    }
+  }
+
+  // labels ease toward their LOD targets each frame
+  ease(reduced: boolean) {
+    for (const label of this.labels) {
+      const material = label.sprite.material as THREE.SpriteMaterial;
+      const diff = label.target - material.opacity;
+      if (Math.abs(diff) > 0.02) {
+        material.opacity = reduced ? label.target : material.opacity + diff * 0.16;
+      } else if (material.opacity !== label.target) {
+        material.opacity = label.target;
+      }
+      label.sprite.visible = material.opacity > 0.02;
+    }
+  }
+}

package/web/src/scene/sceneUtils.ts

@@ -0,0 +1,144 @@
+import * as THREE from "three";
+import type { Touch } from "../types";
+
+// Shared scene vocabulary. The touch colors are the meaning the HUD legend
+// promises; both scenes must draw them identically. Ambient colors (ground,
+// unvisited, ghost) stay per-scene tuning.
+export const SKY = new THREE.Color("#12151c");
+export const EMBER = new THREE.Color("#ff9e5e");
+
+export const touchColors: Record<Touch | "selected", THREE.Color> = {
+  hit: new THREE.Color("#8fb45f"),
+  // chromatic enough to read as blue on lit terrain columns — a paler tint
+  // washed out to white and stopped matching the HUD legend
+  read: new THREE.Color("#a5c8f1"),
+  edit: new THREE.Color("#f0ad5a"),
+  selected: new THREE.Color("#f6ead2")
+};
+
+// Distance along `dir` that fits every point inside the camera frustum.
+// Returns null while the viewport has no usable aspect (hidden pane, tab in
+// the background, mid-layout) — fitting then would park the camera at NaN
+// forever; callers must retry once a real resize lands.
+export function fitDistance(
+  camera: THREE.PerspectiveCamera,
+  dir: THREE.Vector3,
+  points: Iterable<THREE.Vector3>
+): number | null {
+  if (!Number.isFinite(camera.aspect) || camera.aspect <= 0) return null;
+  const forward = dir.clone().negate();
+  const right = new THREE.Vector3().crossVectors(forward, new THREE.Vector3(0, 1, 0)).normalize();
+  const up = new THREE.Vector3().crossVectors(right, forward);
+  const tanV = Math.tan(THREE.MathUtils.degToRad(camera.fov) / 2);
+  const tanH = tanV * camera.aspect;
+  let distance = 0;
+  for (const point of points) {
+    const depth = point.dot(forward);
+    distance = Math.max(
+      distance,
+      Math.abs(point.dot(right)) / tanH - depth,
+      Math.abs(point.dot(up)) / tanV - depth
+    );
+  }
+  return distance;
+}
+
+// Pan the camera (position + orbit target together, so the view direction
+// holds) until `world` projects inside the viewport's safe area. The right
+// margin reserves room for the inspector panel, which would otherwise sit
+// exactly on top of the leaf the user just selected.
+export function ensureVisible(
+  camera: THREE.PerspectiveCamera,
+  controls: { target: THREE.Vector3; update: () => void },
+  world: THREE.Vector3,
+  viewW: number,
+  viewH: number,
+  reservedRight: number
+) {
+  if (viewW === 0 || viewH === 0) return;
+  const forward = camera.getWorldDirection(new THREE.Vector3());
+  const depth = world.clone().sub(camera.position).dot(forward);
+  if (depth <= 0) return; // behind the camera: panning math breaks down
+  const projected = world.clone().project(camera);
+  const sx = ((projected.x + 1) / 2) * viewW;
+  const sy = ((1 - projected.y) / 2) * viewH;
+  const safeL = 48;
+  const safeR = Math.max(safeL + 60, viewW - reservedRight - 48);
+  const safeT = 120;
+  const safeB = viewH - 100;
+  const targetX = Math.min(Math.max(sx, safeL), safeR);
+  const targetY = Math.min(Math.max(sy, safeT), safeB);
+  if (targetX === sx && targetY === sy) return;
+  const tanV = Math.tan(THREE.MathUtils.degToRad(camera.fov) / 2);
+  const tanH = tanV * camera.aspect;
+  const right = new THREE.Vector3().crossVectors(forward, new THREE.Vector3(0, 1, 0)).normalize();
+  const up = new THREE.Vector3().crossVectors(right, forward);
+  // moving the camera right shifts the point left on screen, and vice versa
+  const pan = right
+    .multiplyScalar(((sx - targetX) * 2 * depth * tanH) / viewW)
+    .addScaledVector(up, ((targetY - sy) * 2 * depth * tanV) / viewH);
+  camera.position.add(pan);
+  controls.target.add(pan);
+  controls.update();
+}
+
+// One-line hover readout, driven imperatively from the scenes' pointermove
+// handlers so hovering never re-renders the React tree.
+export class SceneTip {
+  private readonly el: HTMLDivElement;
+  private readonly pathEl: HTMLSpanElement;
+  private readonly metaEl: HTMLSpanElement;
+
+  constructor(private readonly host: HTMLElement) {
+    this.el = document.createElement("div");
+    this.el.className = "scene-tip";
+    this.pathEl = document.createElement("span");
+    this.metaEl = document.createElement("span");
+    this.metaEl.className = "dim";
+    this.el.append(this.pathEl, this.metaEl);
+    host.appendChild(this.el);
+  }
+
+  show(path: string, meta: string, clientX: number, clientY: number) {
+    this.pathEl.textContent = path;
+    this.metaEl.textContent = ` · ${meta}`;
+    this.el.style.display = "block";
+    const bounds = this.host.getBoundingClientRect();
+    const x = clientX - bounds.left;
+    const y = clientY - bounds.top;
+    const left = Math.min(x + 14, Math.max(0, bounds.width - this.el.offsetWidth - 8));
+    const top = Math.min(y + 16, Math.max(0, bounds.height - this.el.offsetHeight - 8));
+    this.el.style.left = `${left}px`;
+    this.el.style.top = `${top}px`;
+  }
+
+  hide() {
+    this.el.style.display = "none";
+  }
+
+  dispose() {
+    this.el.remove();
+  }
+}
+
+export const prefersReducedMotion = () =>
+  typeof window !== "undefined" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+
+export function disposeGroup(group: THREE.Group) {
+  group.traverse((obj) => {
+    if (obj instanceof THREE.Mesh || obj instanceof THREE.Line || obj instanceof THREE.Sprite) {
+      obj.geometry?.dispose();
+      const mat = obj.material as THREE.Material | THREE.Material[];
+      if (Array.isArray(mat)) mat.forEach(disposeMaterial);
+      else if (mat) disposeMaterial(mat);
+    }
+  });
+}
+
+function disposeMaterial(mat: THREE.Material) {
+  // Material.dispose() does not free assigned textures; module-cached
+  // textures (fireflyTexture/haloTexture) are marked shared and must survive.
+  const map = (mat as THREE.Material & { map?: THREE.Texture | null }).map;
+  if (map && !map.userData.shared) map.dispose();
+  mat.dispose();
+}

package/web/src/scene/textures.ts

@@ -0,0 +1,60 @@
+import * as THREE from "three";
+
+let fireflyMap: THREE.Texture | null = null;
+export function fireflyTexture(): THREE.Texture {
+  if (fireflyMap) return fireflyMap;
+  const size = 64;
+  const canvas = document.createElement("canvas");
+  canvas.width = size;
+  canvas.height = size;
+  const ctx = canvas.getContext("2d")!;
+  const g = ctx.createRadialGradient(size / 2, size / 2, 0, size / 2, size / 2, size / 2);
+  g.addColorStop(0, "rgba(255,255,255,1)");
+  g.addColorStop(0.25, "rgba(255,210,160,0.55)");
+  g.addColorStop(1, "rgba(255,158,94,0)");
+  ctx.fillStyle = g;
+  ctx.fillRect(0, 0, size, size);
+  fireflyMap = new THREE.CanvasTexture(canvas);
+  fireflyMap.userData.shared = true; // module cache: disposeGroup must not free it
+  return fireflyMap;
+}
+
+let haloMap: THREE.Texture | null = null;
+export function haloTexture(): THREE.Texture {
+  if (haloMap) return haloMap;
+  const size = 128;
+  const canvas = document.createElement("canvas");
+  canvas.width = size;
+  canvas.height = size;
+  const ctx = canvas.getContext("2d")!;
+  const g = ctx.createRadialGradient(size / 2, size / 2, 0, size / 2, size / 2, size / 2);
+  g.addColorStop(0, "rgba(255,255,255,0.9)");
+  g.addColorStop(0.4, "rgba(255,255,255,0.28)");
+  g.addColorStop(1, "rgba(255,255,255,0)");
+  ctx.fillStyle = g;
+  ctx.fillRect(0, 0, size, size);
+  haloMap = new THREE.CanvasTexture(canvas);
+  haloMap.userData.shared = true; // module cache: disposeGroup must not free it
+  return haloMap;
+}
+
+export function labelTexture(text: string): { texture: THREE.Texture; aspect: number } {
+  const font = '500 30px "Schibsted Grotesk Variable", "PingFang SC", sans-serif';
+  const measure = document.createElement("canvas").getContext("2d")!;
+  measure.font = font;
+  const width = Math.ceil(measure.measureText(text).width) + 24;
+  const height = 44;
+  const canvas = document.createElement("canvas");
+  canvas.width = width * 2;
+  canvas.height = height * 2;
+  const ctx = canvas.getContext("2d")!;
+  ctx.scale(2, 2);
+  ctx.font = font;
+  ctx.textBaseline = "middle";
+  ctx.textAlign = "center";
+  ctx.fillStyle = "rgba(197, 205, 222, 0.95)";
+  ctx.fillText(text, width / 2, height / 2 + 1);
+  const texture = new THREE.CanvasTexture(canvas);
+  texture.anisotropy = 4;
+  return { texture, aspect: width / height };
+}

package/web/src/scene/trail.ts

@@ -0,0 +1,79 @@
+import * as THREE from "three";
+import { EMBER } from "./sceneUtils";
+
+const SAMPLES = 14;
+const MAX_ARCS = 11; // playback keeps 12 recent targets → at most 11 arcs
+
+// Fixed-capacity trail: the arc soup changes every playback tick, so the
+// geometry and material are allocated once and only the attribute contents
+// (plus the draw range) are rewritten in place.
+export class TrailRenderer {
+  readonly object: THREE.LineSegments;
+  private readonly positions: THREE.BufferAttribute;
+  private readonly colors: THREE.BufferAttribute;
+  private readonly lift: number;
+  private readonly arcPoints = Array.from({ length: SAMPLES + 1 }, () => new THREE.Vector3());
+  private readonly mid = new THREE.Vector3();
+  private readonly curve = new THREE.QuadraticBezierCurve3();
+  private readonly color = new THREE.Color();
+
+  constructor(lift: number) {
+    this.lift = lift;
+    const vertexCount = MAX_ARCS * SAMPLES * 2;
+    const geometry = new THREE.BufferGeometry();
+    this.positions = new THREE.BufferAttribute(new Float32Array(vertexCount * 3), 3);
+    this.positions.setUsage(THREE.DynamicDrawUsage);
+    this.colors = new THREE.BufferAttribute(new Float32Array(vertexCount * 3), 3);
+    this.colors.setUsage(THREE.DynamicDrawUsage);
+    geometry.setAttribute("position", this.positions);
+    geometry.setAttribute("color", this.colors);
+    geometry.setDrawRange(0, 0);
+    const material = new THREE.LineBasicMaterial({
+      vertexColors: true,
+      transparent: true,
+      blending: THREE.AdditiveBlending,
+      depthWrite: false,
+      fog: false
+    });
+    this.object = new THREE.LineSegments(geometry, material);
+    this.object.frustumCulled = false;
+  }
+
+  // points are the recent fixations, oldest first, y already at arc height
+  update(points: THREE.Vector3[]) {
+    const arcs = Math.min(Math.max(points.length - 1, 0), MAX_ARCS);
+    if (arcs === 0) {
+      this.object.geometry.setDrawRange(0, 0);
+      return;
+    }
+    const start = points.length - 1 - arcs;
+    let v = 0;
+    for (let i = 1; i <= arcs; i++) {
+      const a = points[start + i - 1];
+      const b = points[start + i];
+      this.mid.copy(a).lerp(b, 0.5);
+      this.mid.y = Math.max(a.y, b.y) + a.distanceTo(b) * 0.22 + this.lift;
+      this.curve.v0.copy(a);
+      this.curve.v1.copy(this.mid);
+      this.curve.v2.copy(b);
+      for (let s = 0; s <= SAMPLES; s++) {
+        this.curve.getPoint(s / SAMPLES, this.arcPoints[s]);
+      }
+      const recency = i / arcs;
+      this.color.copy(EMBER).multiplyScalar(0.05 + 0.95 * recency * recency);
+      for (let s = 0; s < SAMPLES; s++) {
+        const pa = this.arcPoints[s];
+        const pb = this.arcPoints[s + 1];
+        this.positions.setXYZ(v, pa.x, pa.y, pa.z);
+        this.colors.setXYZ(v, this.color.r, this.color.g, this.color.b);
+        v++;
+        this.positions.setXYZ(v, pb.x, pb.y, pb.z);
+        this.colors.setXYZ(v, this.color.r, this.color.g, this.color.b);
+        v++;
+      }
+    }
+    this.object.geometry.setDrawRange(0, v);
+    this.positions.needsUpdate = true;
+    this.colors.needsUpdate = true;
+  }
+}

package/web/src/scene/treeLayout.ts

@@ -0,0 +1,169 @@
+import type { CityFile } from "../types";
+
+// Deterministic radial tree: root at the origin, directories as branch
+// forks, files as leaf slots. Every leaf gets an equal angular share in
+// path-sorted order, so the same commit always grows the same tree.
+
+export interface TreeDir {
+  path: string;
+  name: string;
+  x: number;
+  z: number;
+  depth: number;
+  fileCount: number;
+  // how far the subtree's leaves reach from the fork, in layout units —
+  // the scene projects this to screen pixels to decide when the directory
+  // is prominent enough to deserve its label
+  radius: number;
+}
+
+export interface TreeEdge {
+  childPath?: string;
+  childFileId?: number;
+  points: { x: number; z: number }[];
+}
+
+export interface TreeLayout {
+  radius: number;
+  leaf: Map<number, { x: number; z: number }>;
+  dirs: TreeDir[];
+  edges: TreeEdge[];
+}
+
+interface Node {
+  name: string;
+  path: string;
+  depth: number;
+  children: Map<string, Node>;
+  files: CityFile[];
+  leafCount: number;
+  angle: number;
+}
+
+export function computeTreeLayout(files: CityFile[]): TreeLayout {
+  const root: Node = { name: "", path: "", depth: 0, children: new Map(), files: [], leafCount: 0, angle: 0 };
+  const sorted = [...files].sort((a, b) => (a.path < b.path ? -1 : 1));
+  for (const file of sorted) {
+    const parts = file.path.split("/").filter(Boolean);
+    let node = root;
+    for (const part of parts.slice(0, -1)) {
+      let next = node.children.get(part);
+      if (!next) {
+        next = {
+          name: part,
+          path: node.path ? `${node.path}/${part}` : part,
+          depth: node.depth + 1,
+          children: new Map(),
+          files: [],
+          leafCount: 0,
+          angle: 0
+        };
+        node.children.set(part, next);
+      }
+      node = next;
+    }
+    node.files.push(file);
+  }
+
+  let maxDepth = 1;
+  const countLeaves = (node: Node): number => {
+    node.leafCount = node.files.length;
+    if (node.files.length > 0) maxDepth = Math.max(maxDepth, node.depth + 1);
+    for (const child of node.children.values()) {
+      node.leafCount += countLeaves(child);
+    }
+    return node.leafCount;
+  };
+  countLeaves(root);
+
+  const total = Math.max(root.leafCount, 1);
+  const radius = Math.max(55, Math.sqrt(total) * 4);
+  const step = radius / Math.max(maxDepth, 1);
+  const slotAngle = (Math.PI * 2) / total;
+
+  const layout: TreeLayout = { radius, leaf: new Map(), dirs: [], edges: [] };
+  const polar = (r: number, angle: number) => ({ x: r * Math.cos(angle), z: r * Math.sin(angle) });
+
+  const sampleEdge = (r1: number, a1: number, r2: number, a2: number): { x: number; z: number }[] => {
+    // straight spokes out of the root, eased sweeps between rings
+    const from = r1 < 1e-6 ? a2 : a1;
+    let delta = a2 - from;
+    while (delta > Math.PI) delta -= Math.PI * 2;
+    while (delta < -Math.PI) delta += Math.PI * 2;
+    const points: { x: number; z: number }[] = [];
+    const SEGMENTS = 8;
+    for (let s = 0; s <= SEGMENTS; s++) {
+      const t = s / SEGMENTS;
+      const ease = t * t * (3 - 2 * t);
+      points.push(polar(r1 + (r2 - r1) * t, from + delta * ease));
+    }
+    return points;
+  };
+
+  let cursor = 0;
+  const place = (node: Node) => {
+    node.angle = (cursor + node.leafCount / 2) * slotAngle;
+    const dirs = [...node.children.values()].sort((a, b) => (a.name < b.name ? -1 : 1));
+    const files = [...node.files].sort((a, b) => (a.path < b.path ? -1 : 1));
+    for (const child of dirs) {
+      place(child);
+    }
+    for (const file of files) {
+      const angle = (cursor + 0.5) * slotAngle;
+      cursor += 1;
+      const pos = polar((node.depth + 1) * step, angle);
+      layout.leaf.set(file.id, pos);
+      layout.edges.push({
+        childFileId: file.id,
+        points: sampleEdge(node.depth * step, node.angle, (node.depth + 1) * step, angle)
+      });
+    }
+    if (node.path !== "") {
+      const pos = polar(node.depth * step, node.angle);
+      layout.dirs.push({
+        path: node.path,
+        name: node.name,
+        x: pos.x,
+        z: pos.z,
+        depth: node.depth,
+        fileCount: node.leafCount,
+        radius: 0
+      });
+    }
+  };
+  place(root);
+
+  // parent→dir edges need final angles, so wire them after placement
+  const nodeByPath = new Map<string, Node>();
+  const collect = (node: Node) => {
+    nodeByPath.set(node.path, node);
+    for (const child of node.children.values()) collect(child);
+  };
+  collect(root);
+  for (const dir of layout.dirs) {
+    const node = nodeByPath.get(dir.path)!;
+    const parentPath = dir.path.includes("/") ? dir.path.slice(0, dir.path.lastIndexOf("/")) : "";
+    const parent = nodeByPath.get(parentPath)!;
+    layout.edges.push({
+      childPath: dir.path,
+      points: sampleEdge(parent.depth * step, parent.angle, node.depth * step, node.angle)
+    });
+  }
+
+  // subtree reach: every leaf stretches the radius of each ancestor dir
+  const dirByPath = new Map(layout.dirs.map((dir) => [dir.path, dir]));
+  for (const file of files) {
+    const pos = layout.leaf.get(file.id);
+    if (!pos) continue;
+    const parts = file.path.split("/").filter(Boolean);
+    let path = "";
+    for (let i = 0; i < parts.length - 1; i++) {
+      path = path ? `${path}/${parts[i]}` : parts[i];
+      const dir = dirByPath.get(path);
+      if (!dir) continue;
+      dir.radius = Math.max(dir.radius, Math.hypot(pos.x - dir.x, pos.z - dir.z));
+    }
+  }
+
+  return layout;
+}

package/web/src/state/filters.ts

@@ -0,0 +1,40 @@
+import type { SessionMeta } from "../types";
+
+export interface SessionFilters {
+  hideEmpty: boolean;
+  harness?: string;
+}
+
+const STORAGE_KEY = "mindwalk.sessionFilters";
+
+// activeKey keeps an explicitly opened session visible even when it has no
+// calls; the harness filter is deliberate user intent, so it still applies
+export function sessionVisible(session: SessionMeta, filters: SessionFilters, activeKey?: string): boolean {
+  if (filters.harness && session.harness !== filters.harness) return false;
+  if (filters.hideEmpty && session.eventCount === 0 && session.key !== activeKey) return false;
+  return true;
+}
+
+export function loadFilters(): SessionFilters {
+  try {
+    const raw = localStorage.getItem(STORAGE_KEY);
+    if (raw) {
+      const parsed = JSON.parse(raw) as Partial<SessionFilters>;
+      return {
+        hideEmpty: parsed.hideEmpty !== false,
+        harness: typeof parsed.harness === "string" ? parsed.harness : undefined
+      };
+    }
+  } catch {
+    // corrupted storage: fall through to defaults
+  }
+  return { hideEmpty: true };
+}
+
+export function saveFilters(filters: SessionFilters): void {
+  try {
+    localStorage.setItem(STORAGE_KEY, JSON.stringify(filters));
+  } catch {
+    // storage unavailable: filters reset on next load
+  }
+}