@kabmo-labs/kabmo 0.0.0-stage → 0.1.0

package/src/client/components/common/context-usage-button/index.test.tsx

@@ -0,0 +1,197 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The context-usage control both headers draw.
+ *
+ * Three properties are invisible to a markup check and each was a bug first:
+ *
+ * - The ring FILLS clockwise with the share of the window in use — a ring that
+ *   renders its track and its arc in the same colour looks empty at 90%, so the
+ *   arc's own class and its `stroke-dashoffset` are both asserted.
+ * - The colour is a BAND, and the boundaries belong to the worse band (50 is
+ *   already amber, 60 already red). A table that shifts by one draws the same
+ *   shape in the neighbouring colour, which no visual review catches.
+ * - The popover reads the SESSION's telemetry, so a session with no turn says
+ *   so rather than printing a row of zeros as if they were measurements.
+ *
+ * Driven through a real realtime server (the topic IS the source) with the HTTP
+ * fallback stubbed, rendered with `h()` against happy-dom.
+ */
+
+import { afterAll, afterEach, beforeAll, describe, expect, test } from 'bun:test';
+import { Window } from 'happy-dom';
+import { h, render } from 'preact';
+import { act } from 'preact/test-utils';
+import { ContextUsageButton } from '@/client/components/common/context-usage-button';
+import { resetRealtimeClient } from '@/shared/lib/realtime/client';
+import { invalidateModelsCache } from '@/shared/lib/models/client';
+import { sessionTelemetryTopic } from '@/shared/lib/realtime/protocol';
+import { contextRingGeometry } from '@/shared/lib/chat/context/usage';
+import { startRealtimeTestServer, type RealtimeTestServer } from '@/test-support/realtime-server';
+import { installDomGlobals, pristineWebSocket, restoreDomGlobals } from '@/test-support/pristine-globals';
+import type { TopicResolver } from '@/server/lib/realtime/hub.server';
+import type { SessionContextTelemetry } from '@/shared/types/context';
+
+const SESSION = 'session-context-ring';
+const TOPIC = sessionTelemetryTopic(SESSION);
+const nativeFetch = Bun.fetch;
+
+let container: HTMLElement;
+let server: RealtimeTestServer;
+/** What the topic resolver answers; each case sets it before mounting. */
+let telemetry: SessionContextTelemetry;
+
+function telemetryAt(percent: number): SessionContextTelemetry {
+  return {
+    sessionId: SESSION,
+    sessionTitle: 'Ring',
+    modelId: 'kenari/deepseek-v4-1-flash',
+    modelName: 'deepseek-v4-1-flash',
+    timestamp: 'today',
+    contextUsed: percent * 1_000,
+    contextLimit: 100_000,
+    contextPercent: percent,
+    messagesCount: 4,
+    userCount: 1,
+    assistantCount: 3,
+    totalCost: 0.02,
+    costFormatted: '$0.02',
+    cacheHitAverage: 91.5,
+    lastMessage: { input: 10, output: 4, reasoning: 0, cacheRead: 2, cacheWrite: 0, cacheHitPercent: 16.6 },
+    distribution: { userTokens: 1, userPercent: 25, assistantTokens: 1, assistantPercent: 25, toolTokens: 1, toolPercent: 25, otherTokens: 1, otherPercent: 25 },
+    rawMessages: [],
+  };
+}
+
+beforeAll(() => {
+  installDomGlobals(new Window({ url: 'http://localhost' }));
+});
+
+afterEach(() => {
+  if (container) {
+    render(null, container);
+    container.remove();
+  }
+  resetRealtimeClient();
+  server?.stop();
+  (globalThis as unknown as Record<string, unknown>).fetch = nativeFetch;
+});
+
+afterAll(() => {
+  restoreDomGlobals();
+});
+
+/** The arc is the ring's SECOND circle: the track is drawn first. */
+function arc(): SVGElement {
+  const circles = container.querySelectorAll('svg circle');
+  return circles[1] as unknown as SVGElement;
+}
+
+function trigger(): HTMLElement {
+  return container.querySelector('button[aria-label="Context usage"]') as HTMLElement;
+}
+
+async function mount(snapshot: SessionContextTelemetry): Promise<void> {
+  telemetry = snapshot;
+  // `/api/models` is cached for 60s in MODULE state, shared by every suite in
+  // this process: a case here would otherwise read another file's empty catalog
+  // and print the raw model slug.
+  invalidateModelsCache();
+  const resolver: TopicResolver = async () => telemetry;
+  server = await startRealtimeTestServer(new Map<string, TopicResolver>([[TOPIC, resolver]]));
+  installDomGlobals(new Window({ url: `http://127.0.0.1:${server.port}` }));
+  (globalThis as unknown as Record<string, unknown>).WebSocket = pristineWebSocket;
+  // The HTTP route is only a fallback (MOCK mode, an in-memory session); it
+  // answers the same snapshot so a case never depends on which source won.
+  (globalThis as unknown as Record<string, unknown>).fetch = async (input: unknown) => {
+    const url = String(input);
+    const json = (body: unknown) => new Response(JSON.stringify(body), {
+      status: 200,
+      headers: { 'content-type': 'application/json' },
+    });
+    if (url.includes('/api/telemetry/context')) return json({ telemetry });
+    // The catalog resolves the display names the popover prints; a raw slug is
+    // the fallback, so a stub with no list would still pass a slug assertion.
+    if (url.includes('/api/models')) {
+      return json({
+        modelList: [{ id: 'deepseek-v4-1-flash', name: 'DeepSeek V4-1-Flash' }],
+        connectedProviders: [{ id: 'kenari', name: 'Kenari', disabled: false }],
+      });
+    }
+    return json({});
+  };
+
+  container = document.createElement('div');
+  document.body.appendChild(container);
+  await act(async () => {
+    render(h(ContextUsageButton, { sessionId: SESSION }), container);
+  });
+  await server.waitForTopic(TOPIC, (value) => value !== null);
+  for (let i = 0; i < 10; i += 1) await act(async () => {});
+}
+
+describe('ContextUsageButton', () => {
+  test('fills the ring with the share in use, clockwise from the top', async () => {
+    await mount(telemetryAt(42));
+
+    const { circumference, dashOffset } = contextRingGeometry(42, 18, 2);
+    expect(Number(arc().getAttribute('stroke-dasharray'))).toBeCloseTo(circumference);
+    expect(Number(arc().getAttribute('stroke-dashoffset'))).toBeCloseTo(dashOffset);
+    // The arc starts at three o'clock on an SVG circle; the rotation is what
+    // makes the fill read clockwise from twelve — around the ring's CENTRE, not
+    // the viewBox origin.
+    expect(arc().getAttribute('transform')).toBe('rotate(-90 9 9)');
+  });
+
+  test('draws the band the share falls in', async () => {
+    await mount(telemetryAt(42));
+    expect(arc().getAttribute('class')).toContain('text-success');
+    expect(trigger().getAttribute('title')).toContain('42%');
+
+    render(null, container);
+    resetRealtimeClient();
+    server.stop();
+    await mount(telemetryAt(55));
+    expect(arc().getAttribute('class')).toContain('text-warning');
+
+    render(null, container);
+    resetRealtimeClient();
+    server.stop();
+    await mount(telemetryAt(72));
+    expect(arc().getAttribute('class')).toContain('text-error');
+  });
+
+  test('the popover prints the session numbers, and Escape closes it', async () => {
+    await mount(telemetryAt(42));
+    expect(container.querySelector('[role="dialog"]')).toBeNull();
+
+    await act(async () => {
+      trigger().click();
+    });
+    const dialog = container.querySelector('[role="dialog"]');
+    expect(dialog).not.toBeNull();
+    expect(dialog?.textContent).toContain('Kenari');
+    expect(dialog?.textContent).toContain('DeepSeek V4-1-Flash');
+    expect(dialog?.textContent).toContain('42%');
+    expect(dialog?.textContent).toContain('$0.02');
+
+    await act(async () => {
+      document.dispatchEvent(new window.KeyboardEvent('keydown', { key: 'Escape' }));
+    });
+    expect(container.querySelector('[role="dialog"]')).toBeNull();
+  });
+
+  test('a session with no turn says so instead of printing zeros', async () => {
+    await mount({ ...telemetryAt(0), messagesCount: 0 });
+    expect(trigger().getAttribute('title')).toBe('Context usage — session not started');
+    await act(async () => {
+      trigger().click();
+    });
+    const dialog = container.querySelector('[role="dialog"]');
+    expect(dialog?.textContent).toContain('Session not started');
+    expect(dialog?.textContent).not.toContain('Cost:');
+  });
+});

package/src/client/components/common/context-usage-button/index.tsx

@@ -0,0 +1,159 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The context-usage control both layouts draw: a ring filled clockwise with the
+ * share of the model's window in use, and a popover with the numbers behind it.
+ *
+ * ONE component, because the two layouts used to disagree — the phone had this
+ * control and the desktop navbar did not, so the only way to see how close a run
+ * was to its window on a desktop was to open the Context panel in the right
+ * column. A second copy of the popover is also how the two would drift: the
+ * provider/model split below is the kind of detail one copy gets and the other
+ * forgets.
+ *
+ * The popover is pinned to the viewport on the phone and anchored under the
+ * trigger on the desktop; that is the only difference between the two, and it is
+ * a prop rather than two components.
+ */
+
+import { useEffect, useMemo, useRef, useState } from 'preact/hooks';
+import type { TargetedMouseEvent } from 'preact';
+import { useOnClickOutside } from '@/client/hooks/ui/on-click-outside';
+import { useSessionContextTelemetry } from '@/client/hooks/chat/context/telemetry';
+import { useModelNames } from '@/client/hooks/models/use-model-names';
+import { useProviderNames } from '@/client/hooks/models/use-provider-names';
+import { providerLabel } from '@/shared/lib/models/provider/label';
+import { formatCompactTokens } from '@/shared/lib/format/number';
+import { CONTEXT_BAND_TONES, contextUsageBand } from '@/shared/lib/chat/context/usage';
+import { ContextRing } from '@/client/components/common/context-usage-button/Ring';
+
+interface ContextUsageButtonProps {
+  sessionId: string | null;
+  /** `mobile` pins the popover to the phone's header geometry. */
+  layout?: 'desktop' | 'mobile';
+}
+
+export function ContextUsageButton({ sessionId, layout = 'desktop' }: ContextUsageButtonProps) {
+  const { telemetry, percent } = useSessionContextTelemetry(sessionId);
+  const [open, setOpen] = useState(false);
+  const containerRef = useRef<HTMLDivElement>(null);
+  useOnClickOutside(containerRef, () => setOpen(false));
+
+  // Escape closes the popover whether or not the pointer is over it; a panel
+  // that can only be dismissed by clicking elsewhere is a trap on a keyboard.
+  useEffect(() => {
+    if (!open) return;
+    const onKeyDown = (event: globalThis.KeyboardEvent) => {
+      if (event.key === 'Escape') setOpen(false);
+    };
+    document.addEventListener('keydown', onKeyDown);
+    return () => document.removeEventListener('keydown', onKeyDown);
+  }, [open]);
+
+  // The telemetry reports the model as `provider/modelId` (omp's own selector).
+  // Split once here so the popover prints the provider and the model on separate
+  // lines and resolves each to its display name — the raw slug reads as
+  // "kenari-jatis/deepseek-v4-1-flash", which names neither the vendor nor the
+  // model as the user picked them.
+  const providerNames = useProviderNames();
+  const modelNames = useModelNames();
+  const { providerName, modelName } = useMemo(() => {
+    const selector = telemetry?.modelId ?? '';
+    const slash = selector.indexOf('/');
+    if (slash <= 0) return { providerName: selector, modelName: '' };
+    return {
+      providerName: providerLabel(selector.slice(0, slash), providerNames),
+      modelName: modelNames[selector.slice(slash + 1)] ?? selector.slice(slash + 1),
+    };
+  }, [telemetry?.modelId, providerNames, modelNames]);
+
+  const started = Boolean(telemetry && telemetry.messagesCount > 0);
+  const band = contextUsageBand(percent);
+  const triggerClass = layout === 'mobile'
+    ? 'w-8 h-8 rounded-lg hover:bg-ink/5 active:bg-ink/10 flex items-center justify-center transition-colors cursor-pointer'
+    : 'p-1.5 rounded hover:bg-ink/10 transition-colors cursor-pointer';
+
+  return (
+    <div className="relative flex items-center" ref={containerRef}>
+      <button
+        type="button"
+        onClick={(event: TargetedMouseEvent<HTMLElement>) => {
+          event.stopPropagation();
+          setOpen((previous) => !previous);
+        }}
+        className={triggerClass}
+        title={started ? `Context usage — ${percent.toFixed(0)}% of the window` : 'Context usage — session not started'}
+        aria-label="Context usage"
+        aria-haspopup="dialog"
+        aria-expanded={open}
+      >
+        <ContextRing percent={percent} />
+      </button>
+
+      {open && (
+        <div
+          role="dialog"
+          aria-label="Context usage"
+          className={
+            layout === 'mobile'
+              ? 'fixed z-50 bg-paper border border-ink/20 rounded-xl shadow-xl p-3 text-xs font-mono'
+              : 'absolute right-0 top-full z-50 mt-2 w-56 bg-paper border border-ink/20 rounded-xl shadow-xl p-3 text-xs font-mono'
+          }
+          style={
+            layout === 'mobile'
+              ? {
+                  top: 'calc(3.5rem + env(safe-area-inset-top, 0px) + 0.375rem)',
+                  right: 'max(0.75rem, env(safe-area-inset-right, 0px))',
+                  width: '14rem',
+                }
+              : undefined
+          }
+        >
+          <div className="font-semibold text-ink font-sans pb-1.5 border-b border-ink/10 flex items-center justify-between">
+            <span>Context</span>
+            {started && (
+              <span className={`w-1.5 h-1.5 rounded-full ${CONTEXT_BAND_TONES[band].fill}`} />
+            )}
+          </div>
+          {!started || !telemetry ? (
+            <div className="pt-2 text-[11px] text-ink/50 italic font-sans">Session not started</div>
+          ) : (
+            <div className="pt-2 space-y-1.5 text-[11px] text-ink/80">
+              <div className="flex justify-between gap-2">
+                <span className="text-ink/50 flex-shrink-0">Provider:</span>
+                <span className="truncate text-right">{providerName || '—'}</span>
+              </div>
+              <div className="flex justify-between gap-2">
+                <span className="text-ink/50 flex-shrink-0">Model:</span>
+                <span className="truncate text-right">{modelName || '—'}</span>
+              </div>
+              <div className="flex justify-between">
+                <span className="text-ink/50">Context:</span>
+                <span>
+                  {formatCompactTokens(telemetry.contextUsed) ?? '0'} / {formatCompactTokens(telemetry.contextLimit) ?? '0'} ({percent}%)
+                </span>
+              </div>
+              <div className="flex justify-between">
+                <span className="text-ink/50">Messages:</span>
+                <span>{telemetry.messagesCount}</span>
+              </div>
+              <div className="flex justify-between">
+                <span className="text-ink/50">Cost:</span>
+                <span>{telemetry.costFormatted}</span>
+              </div>
+              {typeof telemetry.cacheHitAverage === 'number' && (
+                <div className="flex justify-between">
+                  <span className="text-ink/50">Cache hit:</span>
+                  <span>{telemetry.cacheHitAverage.toFixed(1)}%</span>
+                </div>
+              )}
+            </div>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/client/components/common/diagram-viewer/index.tsx

@@ -0,0 +1,258 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Full-screen viewer for a hydrated mermaid diagram.
+ *
+ * Opened by clicking a rendered diagram in the chat timeline (see
+ * `MarkdownRenderer`), which hands over the SVG snapshot it read from the
+ * inline block — the viewer never re-runs mermaid, so it shows exactly the
+ * pixels the message shows. Opens fitted to the viewport and never upscales
+ * past 100%: a small chart stays readable at its natural size.
+ *
+ * Interaction: wheel zooms around the cursor, drag pans, double-click toggles
+ * fit/100%, the footer bar is the pointer-free equivalent, and Esc closes.
+ */
+
+import type { ComponentChildren, CSSProperties, TargetedPointerEvent, TargetedWheelEvent } from 'preact';
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'preact/hooks';
+import { createPortal } from 'preact/compat';
+import { Maximize2, Minus, Plus, X } from 'lucide-preact';
+import type { DiagramSnapshot } from '@/client/components/common/diagram-viewer/read-block';
+
+const MIN_SCALE = 0.1;
+const MAX_SCALE = 8;
+/** Viewport pixels kept clear around a fitted diagram (chrome + breathing room). */
+const FIT_MARGIN = 112;
+/** One button press / keyboard notch. */
+const ZOOM_STEP = 1.4;
+/** Wheel `deltaY` → scale exponent, so zooming feels the same on every device. */
+const WHEEL_SENSITIVITY = 0.0015;
+
+interface View {
+  scale: number;
+  /** Translation of the canvas centre from the stage centre, in stage px. */
+  x: number;
+  y: number;
+}
+
+interface Drag {
+  pointerId: number;
+  x: number;
+  y: number;
+}
+
+const clampScale = (scale: number) => Math.min(MAX_SCALE, Math.max(MIN_SCALE, scale));
+
+/** Zoom `view` to `scale` keeping the screen point (`anchorX`,`anchorY`) under
+ *  the cursor, which is what makes wheel-zoom feel anchored rather than
+ *  centre-locked. The canvas grows from its centre, so the anchor is converted
+ *  to a centre-relative point before solving. */
+function zoomTo(view: View, scale: number, anchorX: number, anchorY: number, stage: DOMRect | undefined): View {
+  const next = clampScale(scale);
+  if (next === view.scale) return view;
+  const px = stage ? anchorX - (stage.left + stage.width / 2) : 0;
+  const py = stage ? anchorY - (stage.top + stage.height / 2) : 0;
+  const k = next / view.scale;
+  return { scale: next, x: px - (px - view.x) * k, y: py - (py - view.y) * k };
+}
+
+export interface DiagramViewerProps extends DiagramSnapshot {
+  onClose: () => void;
+}
+
+export function DiagramViewer({ svg, width, height, onClose }: DiagramViewerProps) {
+  const stageRef = useRef<HTMLDivElement>(null);
+  const dragRef = useRef<Drag | null>(null);
+  const [view, setView] = useState<View>({ scale: 1, x: 0, y: 0 });
+  const [fitScale, setFitScale] = useState(1);
+  const [dragging, setDragging] = useState(false);
+
+  /** Scale that fits the whole diagram in the stage without upscaling it. */
+  const measureFit = useCallback(() => {
+    const stage = stageRef.current?.getBoundingClientRect();
+    if (!stage) return 1;
+    return clampScale(
+      Math.min(1, (stage.width - FIT_MARGIN) / width, (stage.height - FIT_MARGIN) / height),
+    );
+  }, [width, height]);
+
+  const fitToView = useCallback(() => {
+    const scale = measureFit();
+    setFitScale(scale);
+    setView({ scale, x: 0, y: 0 });
+  }, [measureFit]);
+
+  // Fit once per diagram size: re-measuring on every render would fight an
+  // in-progress zoom, and only a size change (a re-render under a new theme
+  // that produced a differently sized SVG) invalidates the current fit.
+  useLayoutEffect(() => {
+    fitToView();
+  }, [fitToView]);
+
+  // Modal focus: the stage owns the keyboard so the shortcuts below (and Esc)
+  // never land in the composer still focused behind the overlay, and closing
+  // hands focus back to whoever had it.
+  useEffect(() => {
+    const previouslyFocused = document.activeElement as HTMLElement | null;
+    stageRef.current?.focus();
+    return () => previouslyFocused?.focus();
+  }, []);
+
+  const zoomBy = useCallback((factor: number, anchorX?: number, anchorY?: number) => {
+    setView((current) => {
+      const stage = stageRef.current?.getBoundingClientRect();
+      const x = anchorX ?? (stage ? stage.left + stage.width / 2 : 0);
+      const y = anchorY ?? (stage ? stage.top + stage.height / 2 : 0);
+      return zoomTo(current, current.scale * factor, x, y, stage);
+    });
+  }, []);
+
+  const handleWheel = useCallback(
+    (event: TargetedWheelEvent<HTMLDivElement>) => {
+      // Without this the timeline behind the overlay scrolls while zooming.
+      event.preventDefault();
+      zoomBy(Math.exp(-event.deltaY * WHEEL_SENSITIVITY), event.clientX, event.clientY);
+    },
+    [zoomBy],
+  );
+
+  const handlePointerDown = useCallback((event: TargetedPointerEvent<HTMLDivElement>) => {
+    if (event.button !== 0) return;
+    dragRef.current = { pointerId: event.pointerId, x: event.clientX, y: event.clientY };
+    event.currentTarget.setPointerCapture(event.pointerId);
+    setDragging(true);
+  }, []);
+
+  const handlePointerMove = useCallback((event: TargetedPointerEvent<HTMLDivElement>) => {
+    const drag = dragRef.current;
+    if (!drag || drag.pointerId !== event.pointerId) return;
+    const dx = event.clientX - drag.x;
+    const dy = event.clientY - drag.y;
+    drag.x = event.clientX;
+    drag.y = event.clientY;
+    setView((current) => ({ ...current, x: current.x + dx, y: current.y + dy }));
+  }, []);
+
+  const endDrag = useCallback((event: TargetedPointerEvent<HTMLDivElement>) => {
+    if (dragRef.current?.pointerId !== event.pointerId) return;
+    dragRef.current = null;
+    setDragging(false);
+  }, []);
+
+  const handleDoubleClick = useCallback(() => {
+    setView((current) => (Math.abs(current.scale - 1) < 0.01 ? { scale: fitScale, x: 0, y: 0 } : { scale: 1, x: 0, y: 0 }));
+  }, [fitScale]);
+
+  useEffect(() => {
+    const onKeyDown = (event: globalThis.KeyboardEvent) => {
+      if (event.key === 'Escape') {
+        event.preventDefault();
+        onClose();
+        return;
+      }
+      if (event.key === '+' || event.key === '=') {
+        event.preventDefault();
+        zoomBy(ZOOM_STEP);
+        return;
+      }
+      if (event.key === '-' || event.key === '_') {
+        event.preventDefault();
+        zoomBy(1 / ZOOM_STEP);
+        return;
+      }
+      if (event.key === '0') {
+        event.preventDefault();
+        fitToView();
+      }
+    };
+    window.addEventListener('keydown', onKeyDown);
+    return () => window.removeEventListener('keydown', onKeyDown);
+  }, [onClose, zoomBy, fitToView]);
+
+  // The overlay is the only scroller-free surface on screen; leaving `body`
+  // scrollable lets a wheel outside the stage scroll the timeline behind it.
+  useEffect(() => {
+    const previous = document.body.style.overflow;
+    document.body.style.overflow = 'hidden';
+    return () => {
+      document.body.style.overflow = previous;
+    };
+  }, []);
+
+  const canvasStyle: CSSProperties = {
+    width: `${width}px`,
+    height: `${height}px`,
+    transform: `translate3d(${view.x}px, ${view.y}px, 0) scale(${view.scale})`,
+  };
+
+  return createPortal(
+    <div
+      className="fixed inset-0 z-[200] bg-ink/85 backdrop-blur-sm"
+      role="dialog"
+      aria-modal="true"
+      aria-label="Diagram viewer"
+      onWheel={handleWheel}
+    >
+      <div
+        ref={stageRef}
+        tabIndex={-1}
+        className={`diagram-viewer-stage absolute inset-0 overflow-hidden outline-none ${dragging ? 'cursor-grabbing' : 'cursor-grab'}`}
+        onPointerDown={handlePointerDown}
+        onPointerMove={handlePointerMove}
+        onPointerUp={endDrag}
+        onPointerCancel={endDrag}
+        onDblClick={handleDoubleClick}
+      >
+        <div className="absolute inset-0 flex items-center justify-center">
+          <div className="diagram-viewer-canvas" style={canvasStyle} dangerouslySetInnerHTML={{ __html: svg }} />
+        </div>
+      </div>
+
+      <div className="pointer-events-none absolute inset-x-0 bottom-0 flex justify-center pb-4">
+        <div className="pointer-events-auto flex items-center gap-0.5 rounded-full border border-canvas/15 bg-paper/10 px-1.5 py-1 text-canvas backdrop-blur-sm">
+          <ViewerButton label="Zoom out (-)" onClick={() => zoomBy(1 / ZOOM_STEP)}>
+            <Minus size={14} />
+          </ViewerButton>
+          <span className="w-12 text-center font-mono text-[11px] tabular-nums text-canvas/80">
+            {Math.round(view.scale * 100)}%
+          </span>
+          <ViewerButton label="Zoom in (+)" onClick={() => zoomBy(ZOOM_STEP)}>
+            <Plus size={14} />
+          </ViewerButton>
+          <ViewerButton label="Fit to view (0)" onClick={fitToView}>
+            <Maximize2 size={14} />
+          </ViewerButton>
+          <ViewerButton label="Close (Esc)" onClick={onClose}>
+            <X size={14} />
+          </ViewerButton>
+        </div>
+      </div>
+    </div>,
+    document.body,
+  );
+}
+
+function ViewerButton({
+  label,
+  onClick,
+  children,
+}: {
+  label: string;
+  onClick: () => void;
+  children: ComponentChildren;
+}) {
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      title={label}
+      aria-label={label}
+      className="flex h-7 w-7 cursor-pointer items-center justify-center rounded-full text-canvas/80 transition-colors hover:bg-canvas/10 hover:text-canvas"
+    >
+      {children}
+    </button>
+  );
+}

package/src/client/components/common/diagram-viewer/read-block.ts

@@ -0,0 +1,53 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Read a hydrated `.mermaid-block` (see `@/shared/lib/markdown/mermaid`) back
+ * out as a self-contained snapshot: the sanitized SVG markup plus the natural
+ * pixel size mermaid gave it. Markup + size is all the viewer needs, so it
+ * renders its own copy of the diagram instead of moving the timeline node — the
+ * inline block keeps its theme, its copy button, and its place in the layout.
+ */
+
+export interface DiagramSnapshot {
+  /** Sanitized `<svg …>` markup, exactly as the inline block renders it. */
+  svg: string;
+  /** Natural diagram width in px (the transform's 100% reference). */
+  width: number;
+  /** Natural diagram height in px. */
+  height: number;
+}
+
+/** `null` while the block is pending/rendering/failed — it has no direct SVG
+ *  child until `mermaid.ts` has swapped one in. */
+export function readDiagramBlock(block: HTMLElement): DiagramSnapshot | null {
+  const svg = block.querySelector<SVGSVGElement>(':scope > svg');
+  if (!svg) return null;
+  return { svg: svg.outerHTML, ...measure(svg) };
+}
+
+/**
+ * Mermaid writes numeric px `width`/`height` attributes (the app configures
+ * `useMaxWidth: false`), but a `viewBox`-only diagram is valid SVG too, and a
+ * detached SVG reports a 0×0 border box — hence the fallback chain.
+ */
+function measure(svg: SVGSVGElement): { width: number; height: number } {
+  const box = svg.viewBox?.baseVal;
+  const rendered = svg.getBoundingClientRect();
+  return {
+    width: positive(svg.getAttribute('width'), box?.width, rendered.width),
+    height: positive(svg.getAttribute('height'), box?.height, rendered.height),
+  };
+}
+
+/** First candidate that resolves to a usable positive number; 1 otherwise, so
+ *  callers can never divide by a zero-sized diagram. */
+function positive(...candidates: (string | number | null | undefined)[]): number {
+  for (const candidate of candidates) {
+    const value = typeof candidate === 'number' ? candidate : Number.parseFloat(candidate ?? '');
+    if (Number.isFinite(value) && value > 0) return value;
+  }
+  return 1;
+}