@visualli/react 0.1.7 → 0.2.1

package/src/components/Overlays.tsx

@@ -0,0 +1,327 @@
+// ─── Overlay chrome (DOM) ─────────────────────────────────────────────────────
+//
+// Peek, term cards, depth trail and canvas controls are plain DOM styled by the
+// design system's own CSS (.vi-fact, .vi-anchor-card, .vi-trail, .vi-ctrls,
+// .vi-iconbtn …). No colours or fonts are set here: topic colours reach the CSS
+// as the --topic-* custom properties of the active theme; a custom colour is used
+// as given (the design system's colour rule).
+
+import React, { memo, useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
+import { SHEET, TERM, TRAIL, VIEW, blobPath, hoverOpensTerm, shapeOfLevel, type FlatNode, type SemanticAnchor } from '@visualli/core';
+import { useViewportStore } from '../stores/useViewportStore';
+
+// ── Icons (stroke = currentColor) ─────────────────────────────────────────────
+
+const Icon = ({ children, size = 20 }: { children: React.ReactNode; size?: number }) => (
+  <svg className="vi-icon" width={size} height={size} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+    {children}
+  </svg>
+);
+const MinusIcon = () => <Icon><line x1="5" y1="12" x2="19" y2="12" /></Icon>;
+const PlusIcon = () => <Icon><line x1="12" y1="5" x2="12" y2="19" /><line x1="5" y1="12" x2="19" y2="12" /></Icon>;
+const FitIcon = () => <Icon><path d="M8 3H5a2 2 0 0 0-2 2v3" /><path d="M21 8V5a2 2 0 0 0-2-2h-3" /><path d="M3 16v3a2 2 0 0 0 2 2h3" /><path d="M16 21h3a2 2 0 0 0 2-2v-3" /></Icon>;
+const ChevronLeftIcon = () => <Icon size={14}><polyline points="15 6 9 12 15 18" /></Icon>;
+const ChevronIcon = () => <Icon size={14}><polyline points="9 6 15 12 9 18" /></Icon>;
+const ExternalIcon = () => <Icon size={14}><path d="M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6" /><polyline points="15 3 21 3 21 9" /><line x1="10" y1="14" x2="21" y2="3" /></Icon>;
+const HomeIcon = () => <Icon size={TRAIL.homeIconSize}><path d="m3 9 9-7 9 7v11a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z" /><polyline points="9 22 9 12 15 12 15 22" /></Icon>;
+const CloseIcon = () => <Icon size={18}><line x1="6" y1="6" x2="18" y2="18" /><line x1="18" y1="6" x2="6" y2="18" /></Icon>;
+
+// ── Canvas controls ───────────────────────────────────────────────────────────
+
+export interface ZoomControlsProps {
+  /** Re-fit the current layer into view. */
+  onFit?: () => void;
+  /** Touch layout: larger targets (the design system's `md` icon buttons). */
+  touch?: boolean;
+  /** @deprecated theme comes from the surrounding data-theme; kept so existing callers compile. */
+  isDark?: boolean;
+}
+
+export const ZoomControls = memo(function ZoomControls({ onFit, touch = false }: ZoomControlsProps) {
+  const size = touch ? 'vi-iconbtn--md' : 'vi-iconbtn--sm';
+  const zoom = useViewportStore((s) => s.zoomLevel);
+  const setZoom = useViewportStore((s) => s.setZoom);
+  // As the design system's canvas controls: zoom is shown relative to the layer's fit (fit = 100%), the store keeps
+  // it within VIEW's limits, and Fit is disabled while the whole layer is already in view.
+  const fitted = useViewportStore((s) => Math.abs(s.zoomLevel - s.fitScale) < 1e-6 && Math.abs(s.centerX - s.fitCenterX) < 0.5 && Math.abs(s.centerY - s.fitCenterY) < 0.5);
+  const fit = useViewportStore((s) => s.fitScale);
+  const zoomIn = useCallback(() => setZoom(zoom * VIEW.zoomStep), [zoom, setZoom]);
+  const zoomOut = useCallback(() => setZoom(zoom / VIEW.zoomStep), [zoom, setZoom]);
+  return (
+    <div className="vi-ctrls" role="toolbar" aria-label="Canvas" data-help="zoom-controls">
+      <button type="button" className={`vi-iconbtn ${size}`} aria-label="Zoom out" onClick={zoomOut}><MinusIcon /></button>
+      <span className="vi-ctrls__pct" aria-live="polite">{Math.round((zoom / fit) * 100)}%</span>
+      <button type="button" className={`vi-iconbtn ${size}`} aria-label="Zoom in" onClick={zoomIn}><PlusIcon /></button>
+      {onFit && (<>
+        <span className="vi-ctrls__div" aria-hidden="true" />
+        <button type="button" className={`vi-iconbtn ${size}`} aria-label="Fit map to view" disabled={fitted} onClick={onFit}><FitIcon /></button>
+      </>)}
+    </div>
+  );
+});
+
+// ── Depth trail ───────────────────────────────────────────────────────────────
+
+/** An idea's colour: its topic, or a custom colour drawn as given (FlatNode.topic / FlatNode.custom). */
+export type IdeaPaint = Pick<FlatNode, 'topic' | 'custom'>;
+
+/** CSS fill + ring for an idea's colour, as the design system's topicColors: the active theme's topic properties, or
+ *  the custom colour with its darker ring (the `edge` token when it has none). */
+export function paintVars(p: IdeaPaint): { fill: string; ring: string } {
+  if (p.custom) return { fill: p.custom.fill, ring: p.custom.ring ?? 'var(--edge)' };
+  const t = p.topic ?? TRAIL.rootTopic;
+  return { fill: `var(--topic-${t})`, ring: `var(--topic-${t}-ring)` };
+}
+
+/** A depth trail entry: the idea stepped into (its title and colour); the first is the map (home glyph, its title as the accessible name). */
+export interface TrailEntry { layerId: string; label: string; level: number; paint: IdeaPaint }
+
+/** The trail dot: the level's blob shape in the idea's colour (the design system's TRAIL). */
+const TrailDot = ({ level, paint, current }: { level: number; paint: IdeaPaint; current: boolean }) => {
+  const { fill, ring } = paintVars(paint);
+  return (
+    <svg width={TRAIL.dotBox} height={TRAIL.dotBox} viewBox={`${-TRAIL.dotBox / 2} ${-TRAIL.dotBox / 2} ${TRAIL.dotBox} ${TRAIL.dotBox}`} aria-hidden="true">
+      <path d={blobPath(shapeOfLevel(level), TRAIL.dotRadius, TRAIL.dotRadius)} fill={fill} stroke={ring} strokeWidth={current ? TRAIL.currentStroke : TRAIL.stroke} />
+    </svg>
+  );
+};
+
+export interface DepthTrailProps { stack: TrailEntry[]; onNavigateBack: (index: number) => void }
+
+export const DepthTrail = memo(function DepthTrail({ stack, onNavigateBack }: DepthTrailProps) {
+  if (stack.length === 0) return null;
+  const current = stack.length - 1;
+  // The map's own entry: the home glyph only, its title as the accessible name and tooltip (the design system's TRAIL.rootLabel).
+  const iconOnly = TRAIL.rootLabel === 'icon';
+  return (
+    <nav className="vi-trail" aria-label="Depth trail" data-help="navigation-stack">
+      <ol>
+        {stack.map((e, i) => (
+          <li key={`${e.layerId}-${i}`} className={i === current ? 'is-current' : undefined}>
+            <button type="button" disabled={i === current} aria-current={i === current ? 'location' : undefined} onClick={() => onNavigateBack(i)}
+              {...(i === 0 && iconOnly ? { 'aria-label': e.label, title: e.label } : {})}>
+              <TrailDot level={e.level} paint={e.paint} current={i === current} />
+              <span>{i === 0 ? (iconOnly ? <HomeIcon /> : <><HomeIcon /> {e.label}</>) : e.label}</span>
+            </button>
+          </li>
+        ))}
+      </ol>
+    </nav>
+  );
+});
+
+// ── Terms (semantic anchors) ──────────────────────────────────────────────────
+
+const escapeRe = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/** Split `text` into plain runs and runs that match an anchor word (longest word wins, whole words only). */
+export function splitTerms(text: string, anchors: ReadonlyArray<SemanticAnchor>): Array<string | SemanticAnchor> {
+  const words = anchors.filter((a) => a.word).sort((a, b) => b.word.length - a.word.length);
+  if (!words.length) return [text];
+  const re = new RegExp(`(${words.map((a) => escapeRe(a.word)).join('|')})`, 'giu');
+  const byWord = new Map(words.map((a) => [a.word.toLowerCase(), a]));
+  const isWordChar = (ch: string | undefined) => !!ch && /[\p{L}\p{N}]/u.test(ch);
+  const out: Array<string | SemanticAnchor> = [];
+  let last = 0;
+  for (const m of text.matchAll(re)) {
+    const start = m.index!, end = start + m[0].length;
+    // Whole words only (no lookbehind: it is not available in older Safari).
+    if (isWordChar(text[start - 1]) || isWordChar(text[end])) continue;
+    if (start > last) out.push(text.slice(last, start));
+    out.push({ ...byWord.get(m[0].toLowerCase())!, word: m[0] });
+    last = end;
+  }
+  if (last < text.length) out.push(text.slice(last));
+  return out;
+}
+
+export const TermCard = ({ anchor, inSheet = false }: { anchor: SemanticAnchor; inSheet?: boolean }) => (
+  <span className={`vi-anchor-card${inSheet ? ' is-in-sheet' : ''}`} role="note">
+    <span className="vi-anchor-card__eyebrow">Term</span>
+    <span className="vi-anchor-card__word" style={{ display: 'block' }}>{anchor.word}</span>
+    <p className="vi-anchor-card__desc">{anchor.description}</p>
+    {anchor.knowMoreUrl && (
+      <span className="vi-anchor-card__acts">
+        <a className="vi-fact__link" href={anchor.knowMoreUrl} target="_blank" rel="noopener noreferrer">{TERM.learnMoreLabel} <ExternalIcon /></a>
+      </span>
+    )}
+  </span>
+);
+
+// ── Term (semantic anchor) in a peek ─────────────────────────────────────────
+
+/**
+ * An underlined term and its definition card, behaving as the design system's
+ * `SemanticAnchor` (rules from geometry/interaction.ts → TERM): a mouse opens
+ * it after TERM.hoverOpen and it closes TERM.hoverClose after the pointer leaves
+ * the term and its card; a click, Enter or Space pins it (pressing again closes);
+ * Escape closes it (without stepping out of the layer) and returns focus to the
+ * term; a press outside closes it; opening by click / keyboard moves focus into
+ * the card; the card stays TERM.viewportMargin inside the viewport.
+ */
+export function TermAnchor({ anchor }: { anchor: SemanticAnchor }) {
+  const [open, setOpen] = useState(false);
+  const [shift, setShift] = useState(0);
+  const pinned = useRef(false);
+  const timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+  const wrap = useRef<HTMLSpanElement>(null), btn = useRef<HTMLButtonElement>(null), card = useRef<HTMLSpanElement>(null);
+  const show = (pin: boolean) => { clearTimeout(timer.current); if (pin) pinned.current = true; setOpen(true); };
+  const hide = () => { clearTimeout(timer.current); pinned.current = false; setOpen(false); };
+  useEffect(() => () => clearTimeout(timer.current), []);
+  useLayoutEffect(() => { // keep the card inside the viewport
+    if (!open || !card.current) { setShift(0); return; }
+    const r = card.current.getBoundingClientRect(), vw = document.documentElement.clientWidth, m = TERM.viewportMargin;
+    setShift(r.right > vw - m ? vw - m - r.right : r.left < m ? m - r.left : 0);
+  }, [open]);
+  useEffect(() => {
+    if (!open) return;
+    const onKey = (e: KeyboardEvent) => { if (e.key === 'Escape') { e.stopPropagation(); hide(); btn.current?.focus(); } };
+    const onPress = (e: PointerEvent) => { if (!wrap.current?.contains(e.target as Node)) hide(); };
+    document.addEventListener('keydown', onKey, true);
+    document.addEventListener('pointerdown', onPress, true);
+    return () => { document.removeEventListener('keydown', onKey, true); document.removeEventListener('pointerdown', onPress, true); };
+  }, [open]);
+  return (
+    <span
+      ref={wrap}
+      className={`vi-anchor${open ? ' is-open' : ''}`}
+      data-semantic-tooltip="true"
+      onPointerEnter={(e) => { if (!hoverOpensTerm(e.pointerType)) return; clearTimeout(timer.current); timer.current = setTimeout(() => setOpen(true), TERM.hoverOpen); }}
+      onPointerLeave={(e) => { if (!hoverOpensTerm(e.pointerType) || pinned.current) return; clearTimeout(timer.current); timer.current = setTimeout(() => setOpen(false), TERM.hoverClose); }}
+      onBlur={(e) => { if (!wrap.current?.contains(e.relatedTarget as Node | null)) hide(); }}
+    >
+      <button
+        ref={btn}
+        type="button"
+        className="vi-term"
+        aria-expanded={open}
+        onClick={() => {
+          if (open && pinned.current) { hide(); return; }
+          show(true);
+          setTimeout(() => card.current?.querySelector<HTMLElement>('a, button')?.focus(), 0);
+        }}
+      >
+        {anchor.word}
+      </button>
+      {open && <span ref={card} className="vi-anchor__pop" style={shift ? { transform: `translateX(${shift}px)` } : undefined}><TermCard anchor={anchor} /></span>}
+    </span>
+  );
+}
+
+// ── Peek ─────────────────────────────────────────────────────────────────────
+
+export interface PeekCardProps {
+  node: FlatNode;
+  anchors: ReadonlyArray<SemanticAnchor>;
+  /** Present when the idea has a layer inside it. */
+  onStepInside?: () => void;
+  onClose?: () => void;
+  /** Replaces the plain summary text (extension point kept from earlier versions). */
+  renderContent?: (summary: string) => React.ReactNode;
+}
+
+export const PeekCard = memo(function PeekCard({ node, anchors, onStepInside, onClose, renderContent }: PeekCardProps) {
+  const parts = useMemo(() => splitTerms(node.description ?? '', anchors), [node.description, anchors]);
+  const { fill, ring } = paintVars(node);
+  const style = { ['--vi-fact-fill' as string]: fill, ['--vi-fact-ring' as string]: ring } as React.CSSProperties;
+  return (
+    <div className="vi-fact vi-peek" style={style} role="dialog" aria-label={node.title} data-node-tooltip="true">
+      <div className="vi-fact__head">
+        <div className="vi-fact__title">{node.title}</div>
+        {onClose && <button type="button" className="vi-iconbtn vi-iconbtn--sm vi-fact__close" aria-label="Close" onClick={onClose}><CloseIcon /></button>}
+      </div>
+      <div className="vi-fact__body">
+        {renderContent ? renderContent(node.description ?? '') : parts.map((p, i) =>
+          typeof p === 'string' ? <React.Fragment key={i}>{p}</React.Fragment> : (
+            <TermAnchor key={i} anchor={p} />
+          ))}
+      </div>
+      {onStepInside && (
+        <div className="vi-fact__foot">
+          <span />
+          <div className="vi-fact__acts">
+            <button type="button" className="vi-fact__step" onClick={onStepInside}>Step inside <ChevronIcon /></button>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+});
+
+// ── Peek as a bottom sheet (touch) ────────────────────────────────────────────
+
+export interface PeekSheetProps extends Omit<PeekCardProps, 'onClose'> {
+  onClose: () => void;
+  expanded: boolean;
+  onToggleExpanded: () => void;
+  /** Collapsed height in px (`--vi-sheet-h`). */
+  height: number;
+}
+
+// Swipe thresholds on the sheet's grip: the design system's SHEET (geometry/interaction.ts).
+
+/**
+ * The peek on touch devices: the design system's bottom sheet (`.vi-fact--sheet`).
+ * Stays open until dismissed (close button, swipe down, tap on empty canvas, Esc).
+ * A tapped term opens its definition inside the sheet, with a Back button.
+ */
+export const PeekSheet = memo(function PeekSheet({ node, anchors, onStepInside, onClose, renderContent, expanded, onToggleExpanded, height }: PeekSheetProps) {
+  const [term, setTerm] = useState<SemanticAnchor | null>(null);
+  const parts = useMemo(() => splitTerms(node.description ?? '', anchors), [node.description, anchors]);
+  const startY = useRef<number | null>(null);
+  const swiped = useRef(false);
+  const { fill, ring } = paintVars(node);
+  const style = {
+    ['--vi-fact-fill' as string]: fill,
+    ['--vi-fact-ring' as string]: ring,
+    ['--vi-sheet-h' as string]: `${height}px`,
+    zIndex: 'var(--z-card)',
+  } as React.CSSProperties;
+
+  return (
+    <div className={`vi-fact vi-fact--sheet vi-peek${expanded ? ' is-expanded' : ''}`} style={style} role="dialog" aria-label={node.title} data-node-tooltip="true">
+      <div
+        className="vi-fact__grip"
+        onPointerDown={(e) => { startY.current = e.clientY; swiped.current = false; }}
+        onPointerUp={(e) => {
+          if (startY.current === null) return;
+          const dy = e.clientY - startY.current;
+          startY.current = null;
+          if (dy < -SHEET.expandDrag) { swiped.current = true; if (!expanded) onToggleExpanded(); }
+          else if (dy > SHEET.dismissDrag) { swiped.current = true; if (expanded) onToggleExpanded(); else onClose(); }
+        }}
+      >
+        <button type="button" className="vi-fact__handle" aria-label={expanded ? 'Collapse' : 'Expand'} aria-expanded={expanded} onClick={() => { if (!swiped.current) onToggleExpanded(); swiped.current = false; }} />
+      </div>
+      {term ? (
+        <>
+          <button type="button" className="vi-fact__back" onClick={() => setTerm(null)}><ChevronLeftIcon /> Back</button>
+          <TermCard anchor={term} inSheet />
+        </>
+      ) : (
+        <>
+          <div className="vi-fact__head">
+            <div className="vi-fact__title">{node.title}</div>
+            <button type="button" className="vi-iconbtn vi-iconbtn--md vi-fact__close" aria-label="Close" onClick={onClose}><CloseIcon /></button>
+          </div>
+          <div className="vi-fact__body">
+            {renderContent ? renderContent(node.description ?? '') : parts.map((p, i) =>
+              typeof p === 'string' ? <React.Fragment key={i}>{p}</React.Fragment> : (
+                <span key={i} className="vi-anchor" data-semantic-tooltip="true">
+                  <button type="button" className="vi-term" onClick={() => setTerm(p)}>{p.word}</button>
+                </span>
+              ))}
+          </div>
+          {onStepInside && (
+            <div className="vi-fact__foot">
+              <span />
+              <div className="vi-fact__acts">
+                <button type="button" className="vi-fact__step" onClick={onStepInside}>Step inside <ChevronIcon /></button>
+              </div>
+            </div>
+          )}
+        </>
+      )}
+    </div>
+  );
+});

package/src/components/ZoomControls.tsx

@@ -1,110 +1,6 @@
 // ─── ZoomControls ─────────────────────────────────────────────────────────────
 //
-// Floating zoom control matching the visualli.ai design:
-//   • Side-by-side ZoomIn / ZoomOut buttons (65×32px)
-//   • SVG icons (no external dependency)
-//   • Inline styles (no Tailwind required in SDK)
+// Zoom out / percentage / zoom in / fit, in the design system's controls style.
+// The implementation lives with the other overlay chrome (Overlays.tsx).
 
-import React, { useCallback, memo } from 'react';
-import { ZOOM_MIN, ZOOM_MAX } from '@visualli/core';
-import { useViewportStore } from '../stores/useViewportStore';
-
-export interface ZoomControlsProps {
-  isDark?: boolean;
-}
-
-// ── ZoomIn SVG (Lucide-compatible path) ───────────────────────────────────────
-const ZoomInIcon = () => (
-  <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
-    <circle cx="11" cy="11" r="8" />
-    <line x1="21" y1="21" x2="16.65" y2="16.65" />
-    <line x1="11" y1="8" x2="11" y2="14" />
-    <line x1="8" y1="11" x2="14" y2="11" />
-  </svg>
-);
-
-// ── ZoomOut SVG ───────────────────────────────────────────────────────────────
-const ZoomOutIcon = () => (
-  <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
-    <circle cx="11" cy="11" r="8" />
-    <line x1="21" y1="21" x2="16.65" y2="16.65" />
-    <line x1="8" y1="11" x2="14" y2="11" />
-  </svg>
-);
-
-const ZOOM_STEP = 0.2;
-
-const ZoomControls = memo(function ZoomControls({ isDark = false }: ZoomControlsProps) {
-  const zoomLevel = useViewportStore(s => s.zoomLevel);
-  const setZoom   = useViewportStore(s => s.setZoom);
-
-  const handleZoomIn  = useCallback(() => setZoom(Math.min(ZOOM_MAX, zoomLevel * 1.2)), [zoomLevel, setZoom]);
-  const handleZoomOut = useCallback(() => setZoom(Math.max(ZOOM_MIN, zoomLevel / 1.2)), [zoomLevel, setZoom]);
-
-  const surfaceBg = isDark ? 'var(--bg-surface, #1C1C1A)'   : 'var(--bg-surface, #FAF8F4)';
-  const border    = isDark ? 'var(--border-color, #333330)'  : 'var(--border-color, #DDD9D0)';
-  const primary   = isDark ? 'var(--text-primary, #F0EDE6)'  : 'var(--text-primary, #1A1A18)';
-  const muted     = isDark ? 'var(--text-muted, #8E8C88)'    : 'var(--text-muted, #747270)';
-
-  return (
-    <div
-      style={{
-        position: 'relative',
-        background: surfaceBg,
-        border: `0.5px solid ${border}`,
-        borderRadius: '8px',
-        overflow: 'hidden',
-        width: '65px',
-        height: '32px',
-        flexShrink: 0,
-      }}
-      role="group"
-      aria-label="Zoom controls"
-    >
-      {/* Zoom In — left half */}
-      <button
-        onClick={handleZoomIn}
-        disabled={zoomLevel >= ZOOM_MAX}
-        style={{
-          position: 'absolute',
-          top: 0, left: 0,
-          width: '32px', height: '100%',
-          display: 'flex', alignItems: 'center', justifyContent: 'center',
-          border: 'none', background: 'transparent', cursor: zoomLevel >= ZOOM_MAX ? 'not-allowed' : 'pointer',
-          color: zoomLevel >= ZOOM_MAX ? muted : primary,
-          transition: 'background 0.15s',
-        }}
-        onMouseEnter={e => { if (zoomLevel < ZOOM_MAX) (e.currentTarget as HTMLButtonElement).style.background = isDark ? 'rgba(255,255,255,0.06)' : 'rgba(0,0,0,0.05)'; }}
-        onMouseLeave={e => { (e.currentTarget as HTMLButtonElement).style.background = 'transparent'; }}
-        aria-label="Zoom in"
-      >
-        <ZoomInIcon />
-      </button>
-
-      {/* Divider */}
-      <div style={{ position: 'absolute', top: 0, bottom: 0, left: '32px', width: '0.5px', background: border }} />
-
-      {/* Zoom Out — right half */}
-      <button
-        onClick={handleZoomOut}
-        disabled={zoomLevel <= ZOOM_MIN}
-        style={{
-          position: 'absolute',
-          top: 0, right: 0,
-          width: '33px', height: '100%',
-          display: 'flex', alignItems: 'center', justifyContent: 'center',
-          border: 'none', background: 'transparent', cursor: zoomLevel <= ZOOM_MIN ? 'not-allowed' : 'pointer',
-          color: zoomLevel <= ZOOM_MIN ? muted : primary,
-          transition: 'background 0.15s',
-        }}
-        onMouseEnter={e => { if (zoomLevel > ZOOM_MIN) (e.currentTarget as HTMLButtonElement).style.background = isDark ? 'rgba(255,255,255,0.06)' : 'rgba(0,0,0,0.05)'; }}
-        onMouseLeave={e => { (e.currentTarget as HTMLButtonElement).style.background = 'transparent'; }}
-        aria-label="Zoom out"
-      >
-        <ZoomOutIcon />
-      </button>
-    </div>
-  );
-});
-
-export default ZoomControls;
+export { ZoomControls as default, type ZoomControlsProps } from './Overlays';

package/src/components/useFrames.ts

@@ -0,0 +1,30 @@
+// ─── useFrames ───────────────────────────────────────────────────────────────
+//
+// Redraws a Konva layer every animation frame for as long as `busy()` says an
+// animation is running. Nothing runs while the map is at rest. `run()` draws at
+// once (sharing the frame with any draw already queued, so a state change plus an
+// animation start still paints once) and keeps drawing each frame while busy.
+
+import { useEffect, useMemo, useRef, type RefObject } from 'react';
+import type Konva from 'konva';
+
+export function useFrames(layerRef: RefObject<Konva.Layer | null>, busy: () => boolean): { run: () => void } {
+  const raf = useRef<number | null>(null);
+  const busyRef = useRef(busy);
+  busyRef.current = busy;
+  useEffect(() => () => { if (raf.current !== null) cancelAnimationFrame(raf.current); raf.current = null; }, []);
+  return useMemo(() => {
+    const tick = () => {
+      raf.current = null;
+      if (!busyRef.current()) return;
+      layerRef.current?.batchDraw();
+      raf.current = requestAnimationFrame(tick);
+    };
+    return {
+      run: () => {
+        layerRef.current?.batchDraw();
+        if (raf.current === null) raf.current = requestAnimationFrame(tick);
+      },
+    };
+  }, [layerRef]);
+}

package/src/context/VisualliContext.tsx

@@ -4,9 +4,9 @@
 
 import React, { createContext, useContext } from 'react';
 
-export interface VisualliContextValue {
-  // Reserved for future use
-}
+// Reserved for future use (public type, kept as an open interface).
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface VisualliContextValue {}
 
 const VisualliContext = createContext<VisualliContextValue | null>(null);
 

package/src/design/choreography.ts

@@ -0,0 +1,157 @@
+// ─── Choreography ────────────────────────────────────────────────────────────
+//
+// Runs the design system's motion timeline (core's MOTION / revealDelay /
+// connectorDelay / bloomOffset / easeBezier, copied verbatim from
+// design-system/geometry/motion.ts) on the canvas: the same arrival, hover and
+// reduced-motion behaviour VisualMap gets from its CSS animations.
+//
+// No React and no Konva in here; the layers ask "what does idea / connector i
+// look like right now?" while they paint, and redraw each frame while a
+// timeline is running.
+
+import { MOTION, easeBezier, bloomOffset, layerReveal, type FlatNode } from '@visualli/core';
+
+const clamp01 = (v: number) => (v < 0 ? 0 : v > 1 ? 1 : v);
+
+/** How an idea looks mid-arrival (multiplies its resting look). */
+export interface Arrival { alpha: number; scale: number; dx: number; dy: number }
+/** How a connector looks mid-arrival: `draw` is the fraction of the line drawn, `alpha` its group's fade. */
+export interface EdgeArrival { alpha: number; draw: number }
+
+/** The timeline of one layer's arrival. Shared by the idea layer and the connector layer. */
+export class RevealClock {
+  private t0 = -Infinity;
+  private end = 0;
+  private plan = layerReveal(0, 0);
+  private reduced = false;
+  private center = { x: 0, y: 0 };
+  private order = new Map<string, number>();
+  private listeners = new Set<(running: boolean) => void>();
+  private timer: ReturnType<typeof setTimeout> | null = null;
+
+  /** Begin a layer's arrival. `reduced` (reduced motion or instant reveal): everything fades in together. */
+  start(nodes: ReadonlyArray<FlatNode>, edgeCount: number, reduced: boolean, now = performance.now()): void {
+    this.order.clear();
+    nodes.forEach((n, i) => this.order.set(n.id, i));
+    // The design system's arrival, large layers included (geometry/motion.ts → layerReveal): shared stagger slots
+    // above largeLayer.staggerSlots, a fade-in together above largeLayer.bloomMax.
+    this.plan = layerReveal(nodes.length, edgeCount);
+    this.reduced = reduced || this.plan.instant;
+    reduced = this.reduced;
+    let minX = Infinity, maxX = -Infinity, minY = Infinity, maxY = -Infinity;
+    for (const n of nodes) { minX = Math.min(minX, n.x); maxX = Math.max(maxX, n.x); minY = Math.min(minY, n.y); maxY = Math.max(maxY, n.y); }
+    this.center = nodes.length ? { x: (minX + maxX) / 2, y: (minY + maxY) / 2 } : { x: 0, y: 0 };
+    this.t0 = now;
+    this.end = reduced ? MOTION.reduced.fade : this.plan.total;
+    this.emit(true);
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = setTimeout(() => { this.timer = null; this.emit(false); }, this.end + 50);
+  }
+
+  /** Jump to the finished state (e.g. on unmount). */
+  stop(): void {
+    this.t0 = -Infinity;
+    if (this.timer) { clearTimeout(this.timer); this.timer = null; }
+    this.emit(false);
+  }
+
+  /** True while the layer is still arriving. */
+  active(now = performance.now()): boolean { return now - this.t0 < this.end; }
+
+  /** Called with true when an arrival starts and false when it has finished. Returns the unsubscribe function. */
+  subscribe(fn: (running: boolean) => void): () => void {
+    this.listeners.add(fn);
+    return () => { this.listeners.delete(fn); };
+  }
+
+  private emit(running: boolean) { this.listeners.forEach((fn) => fn(running)); }
+
+  /** Fills `out` with idea `id`'s arrival look. Returns false when it has arrived (nothing to apply). */
+  node(id: string, x: number, y: number, now: number, out: Arrival): boolean {
+    const el = now - this.t0;
+    if (el >= this.end) return false;
+    const i = this.order.get(id);
+    if (i === undefined) return false;
+    if (this.reduced) {
+      out.alpha = clamp01(el / MOTION.reduced.fade); out.scale = 1; out.dx = 0; out.dy = 0;
+      return true;
+    }
+    const r = MOTION.reveal;
+    const t = el - this.plan.ideaDelay(i);
+    if (t >= r.duration) return false;
+    const e = t <= 0 ? 0 : easeBezier(r.ease, t / r.duration); // `backwards` fill: waiting ideas sit at the first keyframe
+    const from = bloomOffset({ x, y }, this.center);
+    out.alpha = clamp01(e);
+    out.scale = r.fromScale + (1 - r.fromScale) * e;
+    out.dx = from.x * (1 - e);
+    out.dy = from.y * (1 - e);
+    return true;
+  }
+
+  /** Fills `out` with connector `i`'s arrival look. Returns false when it has arrived. */
+  edge(i: number, dashed: boolean, now: number, out: EdgeArrival): boolean {
+    const el = now - this.t0;
+    if (el >= this.end) return false;
+    if (this.reduced) { out.alpha = clamp01(el / MOTION.reduced.fade); out.draw = 1; return true; }
+    const c = MOTION.connector;
+    const t = el - this.plan.connectorDelay(i);
+    if (t >= c.draw && t >= c.fade) return false;
+    const group = t <= 0 ? 0 : easeBezier(c.ease, clamp01(t / c.fade));
+    const line = t <= 0 ? 0 : easeBezier(c.ease, clamp01(t / c.draw));
+    // A solid connector draws from source to target; a dashed one fades in instead.
+    out.alpha = dashed ? group * line : group;
+    out.draw = dashed ? 1 : line;
+    return true;
+  }
+}
+
+// ── Hover ─────────────────────────────────────────────────────────────────────
+
+interface HoverTween { fromLift: number; fromRing: number; to: number; t0: number }
+
+/**
+ * Hover / select / press: an idea lifts (ease-bloom, so it settles with a little
+ * overshoot) while its rings turn and grow (ease-standard), both over
+ * `MOTION.hover.duration`. Tracks each raised idea's progress so reversing
+ * mid-way continues from where it was.
+ */
+export class HoverTweens {
+  private tweens = new Map<string, HoverTween>();
+  private raised = new Set<string>();
+
+  /** Set which ideas are raised now. Returns true when anything started moving. */
+  set(next: ReadonlySet<string>, reduced: boolean, now = performance.now()): boolean {
+    let changed = false;
+    const ids = new Set<string>([...this.raised, ...next]);
+    for (const id of ids) {
+      const was = this.raised.has(id), is = next.has(id);
+      if (was === is) continue;
+      const cur = this.progress(id, now);
+      this.tweens.set(id, { fromLift: cur.lift, fromRing: cur.ring, to: is ? 1 : 0, t0: reduced ? -Infinity : now });
+      changed = true;
+    }
+    this.raised = new Set(next);
+    return changed;
+  }
+
+  private cache = { lift: 0, ring: 0 };
+  /** Lift (bloom ease) and ring (standard ease) progress of an idea, 0 at rest and 1 fully raised. */
+  progress(id: string, now: number): { lift: number; ring: number } {
+    const tw = this.tweens.get(id);
+    const out = this.cache;
+    if (!tw) { out.lift = out.ring = this.raised.has(id) ? 1 : 0; return out; }
+    const u = clamp01((now - tw.t0) / MOTION.hover.duration);
+    out.lift = tw.fromLift + (tw.to - tw.fromLift) * easeBezier(MOTION.hover.liftEase, u);
+    out.ring = tw.fromRing + (tw.to - tw.fromRing) * easeBezier(MOTION.hover.ringEase, u);
+    if (u >= 1) { this.tweens.delete(id); out.lift = out.ring = tw.to; }
+    return out;
+  }
+
+  /** True while any idea is still moving. */
+  active(now = performance.now()): boolean {
+    for (const tw of this.tweens.values()) if (now - tw.t0 < MOTION.hover.duration) return true;
+    return false;
+  }
+
+  has(id: string): boolean { return this.tweens.has(id) || this.raised.has(id); }
+}