@hybridlabor-api/bdb-synapse 1.0.0

package/web/src/ui/Dock.tsx

@@ -0,0 +1,104 @@
+import type { LucideIcon } from "lucide-react";
+import { useEffect, useRef, type ReactNode } from "react";
+
+export type PanelPresentation = "sheet" | "pop";
+export type PanelSection = "scene" | "session";
+export type PanelBadge = "running" | "done" | "stale" | "failed";
+
+/**
+ * One dock panel, declared as data. Extending the dock — a layers toggle, a
+ * compare view, a metrics board — means registering one descriptor here;
+ * the strip, grouping, badges, and open/close behavior come for free.
+ */
+export interface PanelDescriptor {
+  id: string;
+  icon: LucideIcon;
+  hint: string;
+  /** scene = how the stage renders; session = depth content about the trace */
+  section: PanelSection;
+  /** sheet = full-height paper, one at a time; pop = compact card anchored
+   * to the strip, coexists with an open sheet */
+  presentation: PanelPresentation;
+  badge?: PanelBadge | null;
+  render: () => ReactNode;
+}
+
+interface DockProps {
+  panels: PanelDescriptor[];
+  openSheet: string | null;
+  openPop: string | null;
+  onToggle: (panel: PanelDescriptor) => void;
+  onClosePop: () => void;
+}
+
+export function Dock({ panels, openSheet, openPop, onToggle, onClosePop }: DockProps) {
+  const popRef = useRef<HTMLDivElement | null>(null);
+  const stripRef = useRef<HTMLDivElement | null>(null);
+  const sheet = panels.find((panel) => panel.id === openSheet && panel.presentation === "sheet");
+  const pop = panels.find((panel) => panel.id === openPop && panel.presentation === "pop");
+  const sections: PanelSection[] = ["scene", "session"];
+  const grouped = sections
+    .map((section) => ({ section, items: panels.filter((panel) => panel.section === section) }))
+    .filter((group) => group.items.length > 0);
+
+  // pops are transient: click-away or Escape dismisses, like any menu; the
+  // strip is exempt so the toggle button doesn't dismiss-then-reopen
+  useEffect(() => {
+    if (!pop) return;
+    const onPointerDown = (event: PointerEvent) => {
+      const target = event.target as Node;
+      if (popRef.current?.contains(target) || stripRef.current?.contains(target)) return;
+      onClosePop();
+    };
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key === "Escape") onClosePop();
+    };
+    document.addEventListener("pointerdown", onPointerDown);
+    document.addEventListener("keydown", onKeyDown);
+    return () => {
+      document.removeEventListener("pointerdown", onPointerDown);
+      document.removeEventListener("keydown", onKeyDown);
+    };
+  }, [pop, onClosePop]);
+
+  return (
+    <div className="dock">
+      {/* anchored left of the whole dock: beside the sheet when one is open,
+          beside the strip otherwise — never covering either */}
+      {pop ? (
+        <div className="dock-pop" ref={popRef}>
+          {pop.render()}
+        </div>
+      ) : null}
+      {sheet ? <aside className="dock-panel">{sheet.render()}</aside> : null}
+      <div className="dock-side" ref={stripRef}>
+        {/* toggle buttons, not tabs: panels open as pops or sheets with no
+            tabpanel relationship, so aria-pressed is the honest semantic */}
+        <div className="dock-strip" role="group" aria-label="Stage panels">
+          {grouped.map((group, index) => (
+            <div key={group.section} className="dock-strip-group">
+              {index > 0 ? <div className="dock-strip-divider" aria-hidden /> : null}
+              {group.items.map((panel) => {
+                const active = panel.id === openSheet || panel.id === openPop;
+                const Icon = panel.icon;
+                return (
+                  <button
+                    key={panel.id}
+                    aria-pressed={active}
+                    className={active ? "active" : ""}
+                    onClick={() => onToggle(panel)}
+                    data-hint={panel.hint}
+                    aria-label={panel.hint}
+                  >
+                    <Icon size={15} />
+                    {panel.badge ? <span className={`dock-dot dock-dot-${panel.badge}`} /> : null}
+                  </button>
+                );
+              })}
+            </div>
+          ))}
+        </div>
+      </div>
+    </div>
+  );
+}

package/web/src/ui/Hud.tsx

@@ -0,0 +1,335 @@
+import { memo, useEffect, useRef, useState } from "react";
+import type { ActionCounts, CityMap, MetricObservability, Trace } from "../types";
+
+export interface ChurnEntry {
+  path: string;
+  edits: number;
+}
+
+interface HudProps {
+  trace?: Trace;
+  city?: CityMap;
+  agentLabel?: string;
+  // live counts at the playhead, passed as primitives so memo stays effective
+  editedNow: number;
+  readNow: number;
+  seenNow: number;
+  churn: ChurnEntry[];
+  onSelectFile: (path: string) => void;
+  onOpenAgents?: () => void;
+  locked?: boolean;
+}
+
+const CHURN_PANEL_ROWS = 8;
+
+// memo: the app re-renders every playback tick; the HUD only changes when the
+// session, the view toggle, or the touch counts under the playhead change
+export const Hud = memo(function Hud({
+  trace,
+  city,
+  agentLabel,
+  editedNow,
+  readNow,
+  seenNow,
+  churn,
+  onSelectFile,
+  onOpenAgents,
+  locked = false
+}: HudProps) {
+  const stats = trace?.stats;
+  const readFinal = stats ? stats.fovea - stats.edited : 0;
+  const unvisitedNow = stats ? Math.max(0, stats.filesInRepo - editedNow - readNow - seenNow) : 0;
+  const unvisitedFinal = stats ? Math.max(0, stats.filesInRepo - stats.fovea - stats.parafovea) : 0;
+  const ghostCount = city ? city.files.reduce((n, file) => n + (file.ghost ? 1 : 0), 0) : 0;
+  const errorCount = stats ? countActions(stats.errors) : 0;
+  const showReview = stats ? errorCount > 0 || stats.churnFiles > 0 || stats.actions.edit > 0 : false;
+
+  const [churnOpen, setChurnOpen] = useState(false);
+  const churnPanelRef = useRef<HTMLDivElement | null>(null);
+  const churnToggleRef = useRef<HTMLButtonElement | null>(null);
+
+  // a new session invalidates the open list; close instead of showing stale rows
+  useEffect(() => setChurnOpen(false), [trace]);
+
+  useEffect(() => {
+    if (!churnOpen) return;
+    const onPointerDown = (event: PointerEvent) => {
+      const target = event.target as Node;
+      if (churnPanelRef.current?.contains(target) || churnToggleRef.current?.contains(target)) return;
+      setChurnOpen(false);
+    };
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key === "Escape") setChurnOpen(false);
+    };
+    document.addEventListener("pointerdown", onPointerDown);
+    document.addEventListener("keydown", onKeyDown);
+    return () => {
+      document.removeEventListener("pointerdown", onPointerDown);
+      document.removeEventListener("keydown", onKeyDown);
+    };
+  }, [churnOpen]);
+
+  return (
+    <div className="hud" aria-hidden={!city}>
+      <div className="hud-left">
+        <div className="hud-title-line">
+          <div className="hud-repo">{city ? basename(city.repo.root) : ""}</div>
+          {trace && agentLabel ? (
+            <button
+              className="hud-lens"
+              onClick={onOpenAgents}
+              disabled={!onOpenAgents || locked}
+              aria-label={`Open Agent lenses, current ${agentLabel}`}
+            >
+              <span>Lens</span>
+              {agentLabel}
+            </button>
+          ) : null}
+        </div>
+        {city ? (
+          <div className="hud-commit">
+            <span>{city.repo.commit || "worktree"}</span>
+            {city.repo.dirty ? <span className="dirty">● dirty</span> : null}
+            {trace?.session.model ? <span>{trace.session.model}</span> : null}
+            {stats ? (
+              <span data-hint="Files in the repository map — the denominator of the coverage spectrum below">
+                {stats.filesInRepo} files
+              </span>
+            ) : null}
+            {city.repo.truncated ? (
+              <span data-hint="The tree holds more files than the map shows — scanning stopped at the budget">
+                partial map
+              </span>
+            ) : null}
+          </div>
+        ) : null}
+        {stats ? (
+          <>
+            {/* the spectrum doubles as scene legend and live tally: each entry is
+                a touch state, counted at the playhead → across the whole walk */}
+            <div className="spectrum">
+              <SpectrumStat
+                kind="edit"
+                label="edited"
+                now={editedNow}
+                final={stats.edited}
+                hint="Files the agent changed"
+              />
+              <SpectrumStat
+                kind="read"
+                label="read"
+                now={readNow}
+                final={readFinal}
+                hint="Files the agent opened and read, but never changed"
+              />
+              <SpectrumStat
+                kind="hit"
+                label="seen"
+                now={seenNow}
+                final={stats.parafovea}
+                hint="Files that only appeared in search results, never opened"
+              />
+              <SpectrumStat
+                kind="unvisited"
+                label="unvisited"
+                now={unvisitedNow}
+                final={unvisitedFinal}
+                hint="Files in the map the agent never touched"
+              />
+              {ghostCount > 0 ? (
+                <SpectrumStat
+                  kind="ghost"
+                  label="ghost"
+                  now={ghostCount}
+                  final={ghostCount}
+                  hint="Files the session touched that are gone from the repository — drawn hollow in the scene"
+                />
+              ) : null}
+            </div>
+            {/* session scale: quiet background numbers, final totals only —
+                unlike the playhead-live spectrum above */}
+            <div className="hud-quiet">
+              <span data-hint={`Tool calls — ${mixHint(stats.actions)}`}>
+                {countActions(stats.actions)} calls
+              </span>
+              <span data-hint="User messages — each one starts a turn of agent work">
+                {stats.userTurns} turns
+              </span>
+              {stats.subagents > 0 ? (
+                <button
+                  className="hud-agent-link"
+                  data-hint="Subagent launches (Task/Agent) — open Agent lenses"
+                  onClick={onOpenAgents}
+                  disabled={!onOpenAgents || locked}
+                  aria-label={`Open ${stats.subagents} subagent${stats.subagents === 1 ? "" : "s"} in Agent lenses`}
+                >
+                  {stats.subagents} subagent{stats.subagents === 1 ? "" : "s"}
+                </button>
+              ) : null}
+              {stats.compactions > 0 ? (
+                <span data-hint="Context compactions — the conversation was summarized to free memory">
+                  {stats.compactions} compaction{stats.compactions === 1 ? "" : "s"}
+                </span>
+              ) : null}
+              <span data-hint="Tool output the agent consumed over the session">
+                {fmtBytes(stats.resultBytes)} output
+              </span>
+              <span data-hint={rereadHint(stats.observability.reads)}>
+                {stats.observability.reads === "unavailable"
+                  ? "re-reads n/a"
+                  : `re-reads ${approx(stats.observability.reads)}${pct(stats.regressionRate)}`}
+              </span>
+            </div>
+            {/* review: only signals worth a second look — absent when clean */}
+            {showReview ? (
+              <div className="hud-review">
+                <span className="review-label">review</span>
+                {errorCount > 0 ? (
+                  <span
+                    className="warn"
+                    data-hint={`${mixHint(stats.errors)} — press X to jump to the next one${errorCaveat(stats.observability.errors)}`}
+                  >
+                    {approx(stats.observability.errors)}
+                    {errorCount} error{errorCount === 1 ? "" : "s"}
+                  </span>
+                ) : null}
+                {stats.churnFiles > 0 ? (
+                  <button
+                    ref={churnToggleRef}
+                    className={churnOpen ? "warn churn-toggle open" : "warn churn-toggle"}
+                    aria-expanded={churnOpen}
+                    onClick={() => setChurnOpen((open) => !open)}
+                    data-hint={`Files edited in three or more separate events — the most-edited file changed ${stats.maxEditsPerFile} times. Click to list them.`}
+                  >
+                    {stats.churnFiles} file{stats.churnFiles === 1 ? "" : "s"} edited 3+ times
+                  </button>
+                ) : null}
+                {stats.actions.edit > 0 ? (
+                  stats.actions.verify === 0 ? (
+                    <span
+                      className="warn"
+                      data-hint="The session edited files but no build or test commands were recognized (go test, make test, npm run build, …)"
+                    >
+                      never verified
+                    </span>
+                  ) : stats.editsAfterLastVerify > 0 ? (
+                    <span
+                      className="warn"
+                      data-hint={`Edit events after the session's last build or test run — ${verifyRuns(stats.actions.verify)} total; pass/fail is not tracked`}
+                    >
+                      {stats.editsAfterLastVerify} edit{stats.editsAfterLastVerify === 1 ? "" : "s"} after
+                      last verify
+                    </span>
+                  ) : (
+                    <span
+                      className="ok"
+                      data-hint={`The last edit was followed by a build or test run — ${verifyRuns(stats.actions.verify)} total; pass/fail is not tracked`}
+                    >
+                      verified after final edit
+                    </span>
+                  )
+                ) : null}
+              </div>
+            ) : null}
+            {churnOpen ? (
+              <div className="churn-panel" ref={churnPanelRef}>
+                {churn.slice(0, CHURN_PANEL_ROWS).map((entry) => (
+                  <button
+                    key={entry.path}
+                    className="churn-row"
+                    onClick={() => {
+                      onSelectFile(entry.path);
+                      setChurnOpen(false);
+                    }}
+                  >
+                    <span className="churn-path">{entry.path}</span>
+                    <span className="churn-count">
+                      {entry.edits} edit{entry.edits === 1 ? "" : "s"}
+                    </span>
+                  </button>
+                ))}
+                {churn.length > CHURN_PANEL_ROWS ? (
+                  <p className="churn-more">…and {churn.length - CHURN_PANEL_ROWS} more</p>
+                ) : null}
+              </div>
+            ) : null}
+          </>
+        ) : null}
+      </div>
+    </div>
+  );
+});
+
+function SpectrumStat({
+  kind,
+  label,
+  now,
+  final,
+  hint
+}: {
+  kind: "edit" | "read" | "hit" | "unvisited" | "ghost";
+  label: string;
+  now: number;
+  final: number;
+  hint: string;
+}) {
+  return (
+    <div className="spectrum-stat" data-hint={hint}>
+      <span className={`legend-dot ${kind}`} />
+      <span className="spectrum-label">{label}</span>
+      <strong>{now === final ? final : `${now} → ${final}`}</strong>
+    </div>
+  );
+}
+
+function pct(rate: number): string {
+  return `${Math.round(rate * 100)}%`;
+}
+
+function approx(observability: MetricObservability): string {
+  return observability === "estimated" ? "~" : "";
+}
+
+function verifyRuns(count: number): string {
+  return `${count} verify run${count === 1 ? "" : "s"}`;
+}
+
+function rereadHint(observability: MetricObservability): string {
+  switch (observability) {
+    case "unavailable":
+      return "No file reads observed — this session reads files through commands Synapse could not recognize";
+    case "estimated":
+      return "Reads that re-read a file unchanged since its last read — inferred from shell commands, so the rate is approximate";
+    default:
+      return "Reads that re-read a file unchanged since its last read";
+  }
+}
+
+function errorCaveat(observability: MetricObservability): string {
+  return observability === "estimated"
+    ? " — inferred from command output; failures inside scripted calls may be missed"
+    : "";
+}
+
+const ACTION_ORDER = ["search", "read", "edit", "exec", "verify", "other"] as const;
+
+function countActions(counts: ActionCounts): number {
+  return ACTION_ORDER.reduce((sum, key) => sum + counts[key], 0);
+}
+
+function mixHint(counts: ActionCounts): string {
+  const parts = ACTION_ORDER.filter((key) => counts[key] > 0).map((key) => `${counts[key]} ${key}`);
+  return parts.length ? parts.join(" · ") : "none";
+}
+
+function fmtBytes(bytes: number): string {
+  const kb = bytes / 1024;
+  if (kb < 1) return `${bytes} B`;
+  if (kb < 1000) return `${Math.round(kb)} KB`;
+  return `${(kb / 1024).toFixed(1)} MB`;
+}
+
+function basename(path: string): string {
+  const clean = path.replace(/\/+$/, "");
+  return clean.slice(clean.lastIndexOf("/") + 1);
+}

package/web/src/ui/Inspector.tsx

@@ -0,0 +1,107 @@
+import { AlertTriangle, X } from "lucide-react";
+import { touchWord, type CityFile, type Touch, type TraceEvent } from "../types";
+
+interface InspectorProps {
+  /** absent when nothing is selected yet — renders the teaching empty state */
+  file?: CityFile;
+  touch?: Touch;
+  history: TraceEvent[];
+  onClose: () => void;
+  onJumpTo: (seq: number) => void;
+  locked?: boolean;
+}
+
+// dock panel content: the selected file's identity, touch state, and visit
+// history. The Dock owns positioning; this owns only its own markup.
+export function Inspector({
+  file,
+  touch,
+  history,
+  onClose,
+  onJumpTo,
+  locked = false
+}: InspectorProps) {
+  if (!file) {
+    return (
+      <div className="dock-body" aria-label="File inspector">
+        <div className="inspector-head">
+          <div className="inspector-path">Inspect</div>
+          <button className="icon-btn" onClick={onClose} title="Close" aria-label="Close inspector">
+            <X size={15} />
+          </button>
+        </div>
+        <p className="dock-note">Click a building in the scene to inspect a file — its touch state, size, and every visit the agent paid it.</p>
+      </div>
+    );
+  }
+  const slash = file.path.lastIndexOf("/");
+  const dir = slash >= 0 ? file.path.slice(0, slash + 1) : "";
+  const name = slash >= 0 ? file.path.slice(slash + 1) : file.path;
+
+  return (
+    <div className="dock-body" aria-label={`File ${file.path}`}>
+      <div className="inspector-head">
+        <div>
+          <div className="inspector-path">
+            <span className="dir">{dir}</span>
+            {name}
+          </div>
+          {file.ghost ? <span className="ghost-badge">ghost — not in this tree</span> : null}
+        </div>
+        <button className="icon-btn" onClick={onClose} title="Close" aria-label="Close inspector">
+          <X size={15} />
+        </button>
+      </div>
+      <dl className="inspector-facts">
+        <div>
+          <dt>Touch</dt>
+          <dd className={touch ? `touch-${touch}` : undefined}>{touchWord(touch)}</dd>
+        </div>
+        <div>
+          <dt>Lang</dt>
+          <dd>{file.lang || "text"}</dd>
+        </div>
+        <div>
+          <dt>Lines</dt>
+          <dd>{file.lines.toLocaleString()}</dd>
+        </div>
+        <div>
+          <dt>Bytes</dt>
+          <dd>{file.bytes.toLocaleString()}</dd>
+        </div>
+      </dl>
+      <section className="inspector-history">
+        <p className="eyebrow">Visits · {history.length}</p>
+        <div className="history-list">
+          {history
+            .slice(-14)
+            .reverse()
+            .map((event) => (
+              <button
+                key={event.seq}
+                className="history-row"
+                onClick={() => onJumpTo(event.seq)}
+                disabled={locked}
+                title={`Jump to step ${event.seq + 1} — ${event.summary}`}
+              >
+                <span className={`action-dot ${event.action}`} />
+                <strong>#{event.seq + 1}</strong>
+                <span>{event.tool}</span>
+                <span className="history-time">{event.ts ? clock(event.ts) : ""}</span>
+                {event.isError ? <AlertTriangle className="history-err" size={13} /> : <span />}
+              </button>
+            ))}
+          {history.length === 0 ? (
+            <p className="muted">Not visited yet at this point of the walk. Scrub the timeline forward.</p>
+          ) : null}
+        </div>
+      </section>
+    </div>
+  );
+}
+
+function clock(iso: string): string {
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return "";
+  return [d.getHours(), d.getMinutes(), d.getSeconds()].map((n) => String(n).padStart(2, "0")).join(":");
+}

package/web/src/ui/LogoMark.tsx

@@ -0,0 +1,38 @@
+// The mark tells the product's story in one tile: a repository waiting in the
+// dark, and an agent's walk lighting it up — footsteps of warm firefly light,
+// touched nodes glowing by state (search moss, read moon, edit amber).
+// Colors are literal so the mark stays identical to the favicon and README asset.
+export function LogoMark({ size = 22 }: { size?: number }) {
+  return (
+    <svg viewBox="0 0 64 64" width={size} height={size} aria-hidden focusable="false">
+      <defs>
+        <radialGradient id="logo-halo">
+          <stop offset="0%" stopColor="#f1aa57" stopOpacity="0.55" />
+          <stop offset="100%" stopColor="#f1aa57" stopOpacity="0" />
+        </radialGradient>
+      </defs>
+      <rect width="64" height="64" rx="14" fill="#0f141b" />
+      <circle cx="20" cy="15" r="1.6" fill="#3b4047" />
+      <circle cx="11" cy="27" r="1.4" fill="#3b4047" />
+      <circle cx="51" cy="40" r="1.6" fill="#3b4047" />
+      <circle cx="34" cy="53" r="1.4" fill="#3b4047" />
+      <g fill="#f1aa57">
+        <circle cx="18.6" cy="47.9" r="1.15" opacity="0.35" />
+        <circle cx="22.7" cy="45.2" r="1.25" opacity="0.42" />
+        <circle cx="25.9" cy="42" r="1.35" opacity="0.49" />
+        <circle cx="28.2" cy="38.1" r="1.45" opacity="0.56" />
+        <circle cx="30.9" cy="29.3" r="1.55" opacity="0.64" />
+        <circle cx="33" cy="25.4" r="1.65" opacity="0.72" />
+        <circle cx="36" cy="22.1" r="1.75" opacity="0.8" />
+        <circle cx="38" cy="20.4" r="1.85" opacity="0.88" />
+      </g>
+      <circle cx="13" cy="50" r="4.5" fill="#9fc67b" opacity="0.16" />
+      <circle cx="13" cy="50" r="2.4" fill="#9fc67b" />
+      <circle cx="29.5" cy="34" r="5" fill="#b6daf1" opacity="0.16" />
+      <circle cx="29.5" cy="34" r="2.7" fill="#b6daf1" />
+      <circle cx="44" cy="17.5" r="9.5" fill="url(#logo-halo)" />
+      <circle cx="44" cy="17.5" r="3.4" fill="#f1aa57" />
+      <circle cx="44" cy="17.5" r="1.7" fill="#ffe0b0" />
+    </svg>
+  );
+}