@visualli/react 0.1.7 → 0.2.0

package/src/design/runtime.ts

@@ -0,0 +1,154 @@
+// ─── Design-system runtime ───────────────────────────────────────────────────
+//
+// Injects the design system's CSS (tokens + spec components) once per page,
+// loads its fonts, and tracks devicePixelRatio for the canvas.
+//
+// Dependencies: ../generated/specCss.ts (generated from design-system/).
+
+import { useSyncExternalStore } from 'react';
+import { TOKENS, TYPE_STYLES } from '@visualli/core';
+import {
+  SPEC_BUNDLED_FONTS,
+  SPEC_COMPONENT_CSS,
+  SPEC_DESIGN_SYSTEM_VERSION,
+  SPEC_FONTS_URL,
+  SPEC_TOKENS_CSS,
+} from '../generated/specCss';
+
+const STYLE_ID = 'visualli-design-system';
+
+/**
+ * Responsive rules the SDK adds on top of the spec CSS. The design system defines the
+ * touch variant (`.is-touch`, bottom sheet); phone / tablet / desktop widths are
+ * handled with the container-width classes the canvas sets (`is-compact` < 560px,
+ * `is-medium` < 900px). Only design-system custom properties are used.
+ */
+const LAYOUT_CSS = `
+.vi-map__ctrls { transition: bottom var(--duration-quick) var(--ease-standard); } /* controlsPosition 'bottom-right': rising above the sheet */
+.vi-map.is-compact .vi-trail li:not(:first-child):not(.is-current):not(:nth-last-child(2)) { display: none; }
+.vi-map.is-compact .vi-trail button span { max-width: 40vw; max-width: 40cqw; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.vi-map.is-compact .vi-fact:not(.vi-fact--sheet) { width: min(300px, calc(100cqw - 2 * var(--space-4))); }
+.vi-map.is-touch .vi-trail button { min-height: 32px; }
+`;
+const FONTS_ID = 'visualli-design-system-fonts';
+const CAVEAT_ID = 'visualli-design-system-caveat';
+// Injected by tsup (`define`) from package.json so it can never drift from the published version.
+declare const __SDK_VERSION__: string;
+const SDK_VERSION = typeof __SDK_VERSION__ === 'string' ? __SDK_VERSION__ : 'latest';
+
+export interface DesignSystemAssets {
+  /**
+   * Where the bundled Caveat font file is served from (URL of the directory that
+   * contains `Caveat-Variable.ttf`). Defaults to the copy shipped inside the npm
+   * package, via jsDelivr.
+   */
+  fontBaseUrl?: string;
+  /** Set false to skip the Google Fonts stylesheet (Kalam + Atkinson Hyperlegible), e.g. when self-hosting them. */
+  loadWebFonts?: boolean;
+}
+
+let webFontsSheet: Promise<void> = Promise.resolve();
+
+/**
+ * Inject the spec CSS and font declarations once. Safe to call repeatedly and on the server (no-op).
+ * The returned promise settles when the web-font stylesheet has loaded (its @font-face rules must exist
+ * before document.fonts.load() can fetch anything).
+ */
+export function ensureDesignSystemStyles(assets: DesignSystemAssets = {}): Promise<void> {
+  if (typeof document === 'undefined') return Promise.resolve();
+
+  if (!document.getElementById(STYLE_ID)) {
+    const style = document.createElement('style');
+    style.id = STYLE_ID;
+    style.setAttribute('data-design-system', SPEC_DESIGN_SYSTEM_VERSION);
+    // Component CSS goes first so token rules (same specificity) win ties, exactly like index.css load order.
+    style.textContent = `${SPEC_TOKENS_CSS}\n${SPEC_COMPONENT_CSS}\n${LAYOUT_CSS}`;
+    document.head.appendChild(style);
+  }
+
+  if (assets.loadWebFonts !== false && SPEC_FONTS_URL && !document.getElementById(FONTS_ID)) {
+    const link = document.createElement('link');
+    link.id = FONTS_ID;
+    link.rel = 'stylesheet';
+    link.href = SPEC_FONTS_URL;
+    webFontsSheet = new Promise<void>((resolve) => {
+      link.addEventListener('load', () => resolve(), { once: true });
+      link.addEventListener('error', () => resolve(), { once: true });
+    });
+    document.head.appendChild(link);
+  }
+
+  if (!document.getElementById(CAVEAT_ID)) {
+    const base = (assets.fontBaseUrl ?? `https://cdn.jsdelivr.net/npm/@visualli/react@${SDK_VERSION}/fonts`).replace(/\/$/, '');
+    const style = document.createElement('style');
+    style.id = CAVEAT_ID;
+    style.textContent = SPEC_BUNDLED_FONTS
+      .map((f) => `@font-face { font-family: "${f.family}"; src: url("${base}/${f.file}"); font-weight: ${f.weight}; font-display: swap; }`)
+      .join('\n');
+    document.head.appendChild(style);
+  }
+  return webFontsSheet;
+}
+
+// ── Fonts ─────────────────────────────────────────────────────────────────────
+
+/** First family of a font stack token, e.g. `font-hand` -> its handwriting face. */
+const firstFamily = (stack: string): string => stack.split(',')[0]!.trim();
+
+/**
+ * Faces the canvas draws with, derived from the design-system tokens and type styles.
+ * Loading them up front means the first frame already uses the right fonts.
+ */
+const CANVAS_FONT_FACES = (['node-label', 'edge-label', 'body'] as const).map((style) => {
+  const t = TYPE_STYLES[style];
+  return `${t.weight} ${t.size}px ${firstFamily(TOKENS.light[t.family]!)}`;
+});
+
+let fontsEpochValue = 0;
+const fontListeners = new Set<() => void>();
+
+/** Bumps whenever web fonts finish loading; text measurement caches are keyed on it. */
+export const fontsEpoch = (): number => fontsEpochValue;
+
+/** React hook: re-renders when fonts finish loading (so canvases redraw with the real faces). */
+export function useFontsEpoch(): number {
+  return useSyncExternalStore(onFontsChange, fontsEpoch, () => 0);
+}
+export const onFontsChange = (cb: () => void): (() => void) => { fontListeners.add(cb); return () => fontListeners.delete(cb); };
+
+/**
+ * Resolves once the canvas fonts are usable (or after `timeoutMs`, so an
+ * offline reader still gets a map in the fallback faces).
+ */
+export function loadCanvasFonts(sheet: Promise<void> = Promise.resolve(), timeoutMs = 3000): Promise<void> {
+  if (typeof document === 'undefined' || !('fonts' in document)) return Promise.resolve();
+  const fonts = document.fonts;
+  const loads = sheet.then(() => Promise.all(CANVAS_FONT_FACES.map((f) => fonts.load(f).catch(() => [])))).then(() => fonts.ready).then(() => undefined);
+  const timeout = new Promise<void>((r) => setTimeout(r, timeoutMs));
+  return Promise.race([loads, timeout]).then(() => { fontsEpochValue++; fontListeners.forEach((cb) => cb()); });
+}
+
+if (typeof document !== 'undefined' && 'fonts' in document) {
+  // Late-arriving faces (slow network) invalidate cached text layouts and trigger a redraw.
+  document.fonts.addEventListener?.('loadingdone', () => { fontsEpochValue++; fontListeners.forEach((cb) => cb()); });
+}
+
+// ── Pixel ratio ───────────────────────────────────────────────────────────────
+
+/** Device pixel ratio the canvas renders at (capped: >3 only costs memory). */
+export const currentPixelRatio = (): number =>
+  typeof window === 'undefined' ? 1 : Math.min(Math.max(window.devicePixelRatio || 1, 1), 3);
+
+/** Calls `cb` whenever devicePixelRatio changes (browser zoom, moving the window between displays). */
+export function watchPixelRatio(cb: (ratio: number) => void): () => void {
+  if (typeof window === 'undefined' || !window.matchMedia) return () => {};
+  let mql: MediaQueryList;
+  let stopped = false;
+  const arm = () => {
+    mql = window.matchMedia(`(resolution: ${window.devicePixelRatio}dppx)`);
+    mql.addEventListener('change', onChange, { once: true });
+  };
+  const onChange = () => { if (stopped) return; cb(currentPixelRatio()); arm(); };
+  arm();
+  return () => { stopped = true; mql.removeEventListener('change', onChange); };
+}

package/src/design/useDesign.ts

@@ -0,0 +1,38 @@
+// ─── useDesign ───────────────────────────────────────────────────────────────
+//
+// Resolves theme + comfort props against the reader's environment (colour
+// scheme, forced colours, reduced motion) and keeps them live.
+
+import { useMemo, useSyncExternalStore } from 'react';
+import { resolveDesign, type Design, type DesignProps } from './design';
+
+function useMedia(query: string): boolean {
+  const subscribe = (cb: () => void) => {
+    if (typeof window === 'undefined' || !window.matchMedia) return () => {};
+    const mq = window.matchMedia(query);
+    mq.addEventListener('change', cb);
+    return () => mq.removeEventListener('change', cb);
+  };
+  const get = () => (typeof window !== 'undefined' && !!window.matchMedia && window.matchMedia(query).matches);
+  return useSyncExternalStore(subscribe, get, () => false);
+}
+
+/** The reader's current preferences. */
+export function useReaderEnv() {
+  return {
+    prefersDark: useMedia('(prefers-color-scheme: dark)'),
+    forcedColors: useMedia('(forced-colors: active)'),
+    prefersReducedMotion: useMedia('(prefers-reduced-motion: reduce)'),
+  };
+}
+
+export function useDesign(props: DesignProps): Design {
+  const env = useReaderEnv();
+  const { theme, isDark, respectForcedColors } = props;
+  const { readableType, largerText, reducedMotion } = props.comfort ?? {};
+  return useMemo(
+    () => resolveDesign({ theme, isDark, respectForcedColors, comfort: { readableType, largerText, reducedMotion } }, env),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [theme, isDark, respectForcedColors, readableType, largerText, reducedMotion, env.prefersDark, env.forcedColors, env.prefersReducedMotion],
+  );
+}

package/src/generated/specCss.ts

@@ -0,0 +1,15 @@
+// GENERATED by scripts/gen-design-system.mjs from design-system/ (tokens/tokens.css, css/spec.css). Do not edit.
+// Change the design system instead; the next `npm run build` regenerates this file.
+
+export const SPEC_TOKENS_CSS = "/* Spec tokens for all 8 themes — generated from the Visualli design system (v0.2.0). Do not edit here: changes come in through PRs from the private design system. MIT license, see ../LICENSE. */\n:root, [data-theme=\"light\"] {\n  --font-display: \"Atkinson Hyperlegible Next\", system-ui, sans-serif;\n  --font-ui: \"Atkinson Hyperlegible Next\", system-ui, -apple-system, \"Segoe UI\", sans-serif;\n  --font-hand: Kalam, \"Atkinson Hyperlegible Next\", cursive;\n  --font-note: Caveat, Kalam, cursive;\n  --font-mono: \"Atkinson Hyperlegible Mono\", ui-monospace, \"SF Mono\", Menlo, monospace;\n  --canvas: #f6f3ee;\n  --surface: #ffffff;\n  --surface-sunken: #f0ece5;\n  --surface-overlay: #ffffff;\n  --line: #e4dfd6;\n  --line-strong: #7a7f94;\n  --ink: #182140;\n  --ink-muted: #4f5671;\n  --ink-subtle: #5f647c;\n  --action: #182140;\n  --on-action: #ffffff;\n  --focus: #325e8c;\n  --link: #2f5a87;\n  --selection: rgba(18, 199, 211, 0.28);\n  --node-ink: #182140;\n  --edge: #2a3048;\n  --edge-label: #4f5671;\n  --topic-teal: #87f2f8;\n  --topic-teal-ring: #00cdd5;\n  --topic-harbor: #bcdbff;\n  --topic-harbor-ring: #76b2f5;\n  --topic-iris: #e0c8fe;\n  --topic-iris-ring: #bd96ea;\n  --topic-berry: #ffbdc4;\n  --topic-berry-ring: #f47e8f;\n  --topic-coral: #ffc7b2;\n  --topic-coral-ring: #f38e65;\n  --topic-amber: #ffcf9d;\n  --topic-amber-ring: #eb9c38;\n  --topic-sun: #ffea94;\n  --topic-sun-ring: #dfbd04;\n  --topic-stone: #e0dacf;\n  --topic-stone-ring: #bab09f;\n  --space-1: 4px;\n  --space-2: 8px;\n  --space-3: 12px;\n  --space-4: 16px;\n  --space-7: 48px;\n  --radius-sm: 10px;\n  --radius-md: 16px;\n  --radius-lg: 24px;\n  --radius-pill: 999px;\n  --shadow-float: 0 1px 2px rgba(24, 33, 64, 0.06), 0 8px 24px rgba(24, 33, 64, 0.08);\n  --shadow-pop: 0 2px 4px rgba(24, 33, 64, 0.08), 0 16px 40px rgba(24, 33, 64, 0.14);\n  --node-width: 200px;\n  --node-height: 148px;\n  --node-stroke: 3px;\n  --edge-width: 2.5px;\n  --edge-gap: 15px;\n  --edge-arc-max: 45px;\n  --immersion-alpha: 0.15;\n  --zoom-min: 0.3;\n  --zoom-max: 5;\n  --duration-instant: 100ms;\n  --duration-quick: 160ms;\n  --duration-base: 240ms;\n  --duration-zoom: 500ms;\n  --duration-reveal: 420ms;\n  --stagger-reveal: 70ms;\n  --ease-zoom: cubic-bezier(0.2, 0.8, 0.2, 1);\n  --ease-standard: cubic-bezier(0.4, 0, 0.2, 1);\n  --ease-bloom: cubic-bezier(0.34, 1.4, 0.64, 1);\n  --z-chrome: 10;\n  --z-card: 20;\n  --z-menu: 40;\n  }\n[data-theme=\"dark\"] {\n  --canvas: #0f1220;\n  --surface: #171b2b;\n  --surface-sunken: #0f1220;\n  --surface-overlay: #212639;\n  --line: #2b3148;\n  --line-strong: #6c7392;\n  --ink: #eef0f7;\n  --ink-muted: #b3b8cc;\n  --ink-subtle: #8f95ae;\n  --action: #f6f3ee;\n  --on-action: #182140;\n  --focus: #12c7d3;\n  --link: #5fd8e1;\n  --selection: rgba(18, 199, 211, 0.32);\n  --edge: #c9cddc;\n  --edge-label: #b3b8cc;\n  --topic-teal-ring: #0fc5cd;\n  --topic-harbor-ring: #73aceb;\n  --topic-iris-ring: #b691e1;\n  --topic-berry-ring: #eb798a;\n  --topic-coral-ring: #ea8962;\n  --topic-amber-ring: #e29737;\n  --topic-sun-ring: #d8b70a;\n  --topic-stone-ring: #b4a999;\n  --shadow-float: 0 1px 2px rgba(0, 0, 0, 0.40), 0 8px 24px rgba(0, 0, 0, 0.35);\n  --shadow-pop: 0 2px 4px rgba(0, 0, 0, 0.50), 0 16px 40px rgba(0, 0, 0, 0.50);\n  }\n[data-theme=\"focus-light\"] {\n  --canvas: #f4f2ee;\n  --edge: #5a6079;\n  --edge-label: #5a6079;\n  --topic-teal: #bce8ea;\n  --topic-teal-ring: #67c6cb;\n  --topic-harbor: #c9d9ec;\n  --topic-harbor-ring: #8bb2de;\n  --topic-iris: #d9cfe8;\n  --topic-iris-ring: #b79ed4;\n  --topic-berry: #edc6c9;\n  --topic-berry-ring: #da9099;\n  --topic-coral: #eecec1;\n  --topic-coral-ring: #db9b82;\n  --topic-amber: #eed4ba;\n  --topic-amber-ring: #d6a570;\n  --topic-sun: #f4eac1;\n  --topic-sun-ring: #d2bf73;\n  --topic-stone: #dddad5;\n  }\n[data-theme=\"focus-dark\"] {\n  --canvas: #12141c;\n  --surface: #171b2b;\n  --surface-sunken: #0f1220;\n  --surface-overlay: #212639;\n  --line: #2b3148;\n  --line-strong: #6c7392;\n  --ink: #eef0f7;\n  --ink-muted: #b3b8cc;\n  --ink-subtle: #8f95ae;\n  --action: #f6f3ee;\n  --on-action: #182140;\n  --focus: #12c7d3;\n  --link: #5fd8e1;\n  --selection: rgba(18, 199, 211, 0.32);\n  --edge: #a9aec0;\n  --edge-label: #b3b8cc;\n  --topic-teal: #bce8ea;\n  --topic-teal-ring: #71bdc1;\n  --topic-harbor: #c9d9ec;\n  --topic-harbor-ring: #8cabce;\n  --topic-iris: #d9cfe8;\n  --topic-iris-ring: #ae9bc6;\n  --topic-berry: #edc6c9;\n  --topic-berry-ring: #cc8e95;\n  --topic-coral: #eecec1;\n  --topic-coral-ring: #cd9884;\n  --topic-amber: #eed4ba;\n  --topic-amber-ring: #c9a176;\n  --topic-sun: #f4eac1;\n  --topic-sun-ring: #c9b97a;\n  --topic-stone: #dddad5;\n  --topic-stone-ring: #b4a999;\n  }\n[data-theme=\"colorsafe-light\"] {\n  --topic-teal: #b0ecbc;\n  --topic-teal-ring: #6cc982;\n  --topic-harbor: #abdbfe;\n  --topic-harbor-ring: #60b4ec;\n  --topic-iris: #f6bde2;\n  --topic-iris-ring: #dc87c0;\n  --topic-berry: #feb79e;\n  --topic-berry-ring: #ec7f58;\n  --topic-coral: #fece96;\n  --topic-coral-ring: #e49d41;\n  --topic-amber: #b2e8fa;\n  --topic-amber-ring: #5cc4e2;\n  --topic-sun: #f6f097;\n  --topic-sun-ring: #d0c637;\n  --topic-stone: #dbdbdb;\n  --topic-stone-ring: #b7afb1;\n  }\n[data-theme=\"colorsafe-dark\"] {\n  --canvas: #0f1220;\n  --surface: #171b2b;\n  --surface-sunken: #0f1220;\n  --surface-overlay: #212639;\n  --line: #2b3148;\n  --line-strong: #6c7392;\n  --ink: #eef0f7;\n  --ink-muted: #b3b8cc;\n  --ink-subtle: #8f95ae;\n  --action: #f6f3ee;\n  --on-action: #182140;\n  --focus: #12c7d3;\n  --link: #5fd8e1;\n  --selection: rgba(18, 199, 211, 0.32);\n  --edge: #c9cddc;\n  --edge-label: #b3b8cc;\n  --topic-teal: #b0ecbc;\n  --topic-teal-ring: #69c27e;\n  --topic-harbor: #abdbfe;\n  --topic-harbor-ring: #5eade2;\n  --topic-iris: #f6bde2;\n  --topic-iris-ring: #d383b9;\n  --topic-berry: #feb79e;\n  --topic-berry-ring: #e37a55;\n  --topic-coral: #fece96;\n  --topic-coral-ring: #db9840;\n  --topic-amber: #b2e8fa;\n  --topic-amber-ring: #5bbdda;\n  --topic-sun: #f6f097;\n  --topic-sun-ring: #c9bf37;\n  --topic-stone: #dbdbdb;\n  --topic-stone-ring: #b1a8aa;\n  }\n[data-theme=\"contrast-light\"] {\n  --canvas: #ffffff;\n  --surface-sunken: #f2f2f2;\n  --line: #5c6178;\n  --line-strong: #000000;\n  --ink: #000000;\n  --ink-muted: #1f2433;\n  --ink-subtle: #3a3f52;\n  --action: #000000;\n  --focus: #0b4a8f;\n  --link: #0b4a8f;\n  --node-ink: #000000;\n  --edge: #000000;\n  --edge-label: #1f2433;\n  --topic-teal-ring: #006b70;\n  --topic-harbor-ring: #0e599d;\n  --topic-iris-ring: #683b92;\n  --topic-berry-ring: #96173a;\n  --topic-coral-ring: #923400;\n  --topic-amber-ring: #7e4d00;\n  --topic-sun-ring: #7a6600;\n  --topic-stone-ring: #63594b;\n  --shadow-float: none;\n  --shadow-pop: none;\n  }\n[data-theme=\"contrast-dark\"] {\n  --canvas: #000000;\n  --surface: #000000;\n  --surface-sunken: #0d0d0d;\n  --surface-overlay: #0d0d0d;\n  --line: #9aa0b8;\n  --line-strong: #ffffff;\n  --ink: #ffffff;\n  --ink-muted: #e6e8f0;\n  --ink-subtle: #c8ccda;\n  --action: #ffffff;\n  --on-action: #000000;\n  --focus: #5fe8f0;\n  --link: #7ff0f5;\n  --selection: rgba(18, 199, 211, 0.32);\n  --node-ink: #000000;\n  --edge: #ffffff;\n  --edge-label: #e6e8f0;\n  --topic-teal-ring: #64eff7;\n  --topic-harbor-ring: #b0d5fe;\n  --topic-iris-ring: #dcbfff;\n  --topic-berry-ring: #feb3bb;\n  --topic-coral-ring: #ffbea5;\n  --topic-amber-ring: #ffc78a;\n  --topic-sun-ring: #ffe26d;\n  --topic-stone-ring: #ddd3c2;\n  --shadow-float: none;\n  --shadow-pop: none;\n  }\n[data-motion=\"reduced\"] {\n  --duration-instant: 120ms;\n  --duration-quick: 0ms;\n  --duration-base: 0ms;\n  --duration-zoom: 0ms;\n  --duration-reveal: 0ms;\n  --stagger-reveal: 0ms;\n  }\n@media (prefers-reduced-motion: reduce) {\n  :root:not([data-motion=\"full\"]) {\n  --duration-instant: 120ms;\n  --duration-quick: 0ms;\n  --duration-base: 0ms;\n  --duration-zoom: 0ms;\n  --duration-reveal: 0ms;\n  --stagger-reveal: 0ms;\n  }\n}\n\n/* Type styles */\n.heading { font-family: var(--font-ui); font-size: 17px; line-height: 24px; font-weight: 700; }\n.body { font-family: var(--font-ui); font-size: 15px; line-height: 22px; font-weight: 400; }\n.body-sm { font-family: var(--font-ui); font-size: 13px; line-height: 18px; font-weight: 400; }\n.label { font-family: var(--font-ui); font-size: 13px; line-height: 16px; font-weight: 600; letter-spacing: 0.01em; }\n.caption { font-family: var(--font-ui); font-size: 12px; line-height: 16px; font-weight: 400; }\n.node-root { font-family: var(--font-hand); font-size: 30px; line-height: 34px; font-weight: 700; }\n.node-label { font-family: var(--font-hand); font-size: 22px; line-height: 26px; font-weight: 700; }\n.edge-label { font-family: var(--font-note); font-size: 18px; line-height: 20px; font-weight: 500; }\n.annotation { font-family: var(--font-note); font-size: 24px; line-height: 26px; font-weight: 600; }\n";
+export const SPEC_COMPONENT_CSS = "/* Styles for the spec components (map, nodes, connectors, peek, terms, depth trail, controls) — generated from the Visualli design system (v0.2.0). Do not edit here: changes come in through PRs from the private design system. MIT license, see ../LICENSE. */\n:root { --vi-fs-body: 15px; --vi-fs-sm: 13px; --vi-fs-cap: 12px; --vi-lh-body: 22px; --vi-label-scale: 1; color-scheme: light; }\n[data-theme$=\"dark\"] { color-scheme: dark; }\n[data-scale=\"lg\"] { --vi-fs-body: 17px; --vi-fs-sm: 15px; --vi-fs-cap: 14px; --vi-lh-body: 26px; --vi-label-scale: 1.15; }\n[data-type=\"readable\"] { --font-hand: \"Atkinson Hyperlegible Next\", system-ui, sans-serif; --font-note: \"Atkinson Hyperlegible Next\", system-ui, sans-serif; --font-display: \"Atkinson Hyperlegible Next\", system-ui, sans-serif; letter-spacing: 0.01em; }\n[data-type=\"readable\"] .vi-node__label, [data-type=\"readable\"] .vi-edge__label, [data-type=\"readable\"] .vi-map__group-label { font-family: var(--font-ui) !important; font-weight: 700; letter-spacing: 0.02em; font-style: normal; }\n\n.vi-sr { position: absolute; width: 1px; height: 1px; overflow: hidden; clip: rect(0 0 0 0); white-space: nowrap; }\n.vi-icon { flex: none; display: block; }\n.vi-map :where(button, a, input, textarea, [tabindex]):focus-visible { outline: 2px solid var(--focus); outline-offset: 2px; }\n.vi-iconbtn { display: inline-grid; place-items: center; border-radius: var(--radius-sm); border: 1.5px solid transparent; background: transparent; color: var(--ink); cursor: pointer; transition: background var(--duration-instant); flex: none; }\n.vi-iconbtn--sm { width: 32px; height: 32px; }\n.vi-iconbtn--md { width: 40px; height: 40px; }\n.vi-iconbtn--lg { width: 48px; height: 48px; border-radius: var(--radius-md); }\n.vi-iconbtn:hover { background: var(--surface-sunken); }\n.vi-iconbtn--surface { background: var(--surface); border-color: var(--line); }\n.vi-iconbtn--surface:hover { border-color: var(--line-strong); }\n.vi-iconbtn--primary { background: var(--action); color: var(--on-action); border-radius: var(--radius-pill); }\n.vi-iconbtn.is-active { background: var(--action); color: var(--on-action); }\n[data-theme^=\"contrast\"] .vi-ctrls { border: 2px solid var(--line-strong); }\n.vi-node { position: relative; display: inline-grid; place-items: center; border: 0; padding: 0; background: none; color: var(--node-ink); cursor: default; transition: transform var(--duration-base) var(--ease-bloom), opacity var(--duration-base); -webkit-tap-highlight-color: transparent; }\nbutton.vi-node { cursor: pointer; }\n.vi-node__svg { position: absolute; inset: 0; overflow: visible; }\n.vi-node__body { filter: drop-shadow(var(--vi-node-shadow, 0 6px 14px rgba(24, 33, 64, .10))); }\n[data-theme$=\"dark\"] .vi-node__body { --vi-node-shadow: 0 0 22px rgba(255, 255, 255, .10); }\n[data-theme^=\"contrast\"] .vi-node__body { filter: none; }\n.vi-node__rings { transform-origin: center; transition: transform var(--duration-base) var(--ease-standard); }\n@media (hover: hover) {\n  button.vi-node:hover .vi-node__rings { transform: rotate(var(--vi-ring-turn, -2deg)) scale(var(--vi-ring-grow, 1.015)); }\n  button.vi-node:hover { transform: translateY(calc(var(--vi-lift, 2px) * -1)); }\n}\n.vi-node { -webkit-user-select: none; user-select: none; -webkit-touch-callout: none; touch-action: manipulation; }\n.vi-node.is-selected { transform: translateY(-2px); }\n.vi-node.is-selected .vi-node__rings { transform: rotate(var(--vi-ring-turn, -2deg)) scale(var(--vi-ring-grow, 1.015)); }\n.vi-node.is-selected .vi-node__body { stroke-width: 4; }\n.vi-node:focus-visible { outline: none; }\n.vi-node:focus-visible .vi-node__body { stroke: var(--focus); stroke-width: 4; }\n.vi-node.is-selected .vi-node__body { stroke: var(--ink); }\n.vi-node__label { position: relative; text-align: center; color: var(--node-ink); display: -webkit-box; -webkit-line-clamp: 3; -webkit-box-orient: vertical; overflow: hidden; font-size: calc(var(--vi-nfs, 22px) * var(--vi-label-scale) * var(--vi-ninv, 1)); line-height: 1.15; padding-top: 2px; }\n.vi-node__label.node-root { --vi-nfs: 30px; }\n.vi-node--mini .vi-node__label { --vi-nfs: 15px; }\n.vi-node.is-dimmed { opacity: 1; }\n[data-theme^=\"focus\"] .vi-node.is-dimmed { opacity: .4; }\n.vi-map.is-touch .vi-node.is-dimmed { opacity: .6; }\n[data-theme^=\"focus\"] .vi-map.is-touch .vi-node.is-dimmed { opacity: .4; }\n.vi-edge__line { fill: none; stroke: var(--edge); stroke-width: 2.5; stroke-linecap: round; }\n.vi-edge.is-dashed .vi-edge__line { stroke-dasharray: 7 7; }\n.vi-edge__arrow { fill: none; stroke: var(--edge); stroke-width: 2.5; stroke-linecap: round; stroke-linejoin: round; }\n.vi-edge__label { font: 500 calc(18px * var(--vi-inv, 1)) / 1 var(--font-note); fill: var(--edge-label); paint-order: stroke; stroke: var(--canvas); stroke-width: 5px; stroke-linejoin: round; letter-spacing: .01em; }\n[data-type=\"readable\"] .vi-edge__label { font-size: calc(14px * var(--vi-inv, 1)); font-weight: 600; }\n.vi-fact { position: relative; width: 300px; box-sizing: border-box; padding: var(--space-4) var(--space-4) var(--space-3); background: var(--surface-overlay); color: var(--ink); border: 2px solid var(--vi-fact-ring); border-radius: 14px 18px 12px 16px / 16px 12px 18px 14px; font: 400 var(--vi-fs-sm)/20px var(--font-ui); z-index: var(--z-card); animation: vi-pop var(--duration-quick) var(--ease-standard); }\n.vi-fact { box-shadow: 5px 6px 0 0 var(--vi-fact-fill), 5px 6px 0 2px var(--vi-fact-ring); }\n[data-theme^=\"contrast\"] .vi-fact { border-color: var(--ink); }\n[data-theme^=\"contrast\"] .vi-fact { box-shadow: none; }\n.vi-fact__title { font: 700 22px/26px var(--font-hand); margin-bottom: var(--space-1); }\n.vi-fact__body { color: var(--ink); }\n.vi-fact__foot { display: flex; align-items: center; justify-content: space-between; gap: var(--space-2); margin-top: var(--space-3); padding-top: var(--space-2); border-top: 1px dashed var(--line); }\n.vi-fact__acts { display: inline-flex; gap: var(--space-3); align-items: center; flex: none; }\n.vi-fact__link { color: var(--link); font: 600 var(--vi-fs-cap)/16px var(--font-ui); }\n.vi-fact__step { display: inline-flex; align-items: center; gap: 2px; border: 0; background: var(--action); color: var(--on-action); font: 600 var(--vi-fs-cap)/16px var(--font-ui); padding: 5px 8px 5px 10px; border-radius: var(--radius-pill); cursor: pointer; }\n.vi-trail ol { list-style: none; margin: 0; padding: 0; display: grid; gap: 2px; position: relative; }\n.vi-trail li { position: relative; }\n.vi-trail li + li::before { content: \"\"; position: absolute; left: 13px; top: -8px; height: 10px; border-left: 1.5px dashed var(--line-strong); }\n.vi-trail button { display: inline-flex; align-items: center; gap: 6px; border: 0; background: none; padding: 4px 8px 4px 5px; border-radius: var(--radius-sm); color: var(--ink-muted); font: 400 var(--vi-fs-cap)/16px var(--font-ui); cursor: pointer; }\n.vi-trail button span { display: inline-flex; align-items: center; gap: 4px; }\n.vi-trail button:hover:not(:disabled) { background: var(--surface-sunken); color: var(--ink); }\n.vi-trail li.is-current button { color: var(--ink); font-weight: 700; font-size: var(--vi-fs-sm); cursor: default; background: var(--surface); box-shadow: var(--shadow-float); }\n.vi-trail li.is-current button:disabled { opacity: 1; }\n.vi-ctrls { display: inline-flex; align-items: center; gap: 2px; padding: 4px; background: var(--surface); border: 1px solid var(--line); border-radius: var(--radius-md); box-shadow: var(--shadow-float); }\n.vi-ctrls__pct { min-width: 44px; text-align: center; font: 600 var(--vi-fs-cap)/16px var(--font-ui); color: var(--ink-muted); font-variant-numeric: tabular-nums; }\n.vi-ctrls__div { width: 1px; height: 20px; background: var(--line); margin: 0 4px; }\n.vi-map { position: relative; overflow: hidden; background: var(--canvas); border-radius: inherit; isolation: isolate; }\n.vi-map__immersion { position: absolute; inset: 0; opacity: var(--immersion-alpha); transition: background var(--duration-base); z-index: -1; }\n.vi-map__world { position: absolute; left: 0; top: 0; transform-origin: 0 0; }\n.vi-map__edges { position: absolute; overflow: visible; pointer-events: none; }\n.vi-map__group rect { fill: none; stroke: var(--line-strong); stroke-width: 1.5; stroke-dasharray: 10 6; }\n.vi-map__group-label { position: absolute; transform: translate(-50%, -50%); z-index: 2; max-width: 420px; box-sizing: border-box; padding: 6px 22px 8px; background: var(--topic-stone); border: 1.5px solid var(--topic-stone-ring); border-radius: var(--radius-pill); font: 700 22px/1.1 var(--font-note); color: var(--node-ink); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; pointer-events: none; font-size: calc(26px * var(--vi-label-scale) * var(--vi-ninv, 1)); }\n[data-theme^=\"contrast\"] .vi-map__group-label { border: 2px solid var(--line-strong); }\n.vi-map__slot { position: absolute; transform: translate(-50%, -50%); }\n.vi-map.is-reveal .vi-map__slot { animation: vi-bloom var(--duration-reveal) var(--ease-bloom) backwards; }\n.vi-map.is-reveal .vi-edge { animation: vi-fade var(--duration-base) var(--ease-standard) backwards; }\n.vi-map.is-reveal .vi-edge__line { stroke-dasharray: 1; stroke-dashoffset: 1; animation: vi-line var(--vi-line-draw, .5s) var(--ease-standard) forwards; animation-delay: inherit; }\n.vi-map.is-reveal .vi-edge.is-dashed .vi-edge__line { stroke-dasharray: 7 7; stroke-dashoffset: 0; animation: vi-fade var(--vi-line-draw, .5s) var(--ease-standard) backwards; animation-delay: inherit; }\n.vi-map:not(.is-reveal) .vi-edge__line { stroke-dasharray: none; }\n.vi-map:not(.is-reveal) .vi-edge.is-dashed .vi-edge__line { stroke-dasharray: 7 7; }\n.vi-map__lens { position: absolute; inset: 0; transform-origin: var(--vi-ox) var(--vi-oy); }\n.vi-map.is-diving .vi-map__lens { transform: scale(var(--vi-dive-scale, 3.2)); opacity: 0; transition: transform var(--duration-zoom) var(--ease-zoom), opacity var(--vi-dive-fade, 160ms) var(--vi-dive-fade-delay, 150ms); }\n.vi-map.is-surfacing .vi-map__lens { transform: scale(var(--vi-surface-scale, .6)); opacity: 0; transform-origin: 50% 50%; transition: transform var(--vi-surface-dur, 220ms) var(--ease-zoom), opacity var(--vi-surface-fade, 200ms); }\n.vi-map.is-reveal .vi-map__lens { animation: vi-settle var(--vi-settle-dur, 260ms) var(--ease-standard); }\n[data-motion=\"reduced\"] .vi-map__lens { animation: none !important; transform: none !important; }\n.vi-map__fact { position: absolute; }\n.vi-map.is-idle .vi-map__world { transition: transform var(--duration-base) var(--ease-standard); }\n.vi-map__hint { position: absolute; left: var(--space-4); right: var(--space-4); margin: 0; text-align: center; color: var(--ink-muted); pointer-events: none; z-index: var(--z-chrome); animation: vi-fade var(--duration-base) var(--ease-standard); }\n.vi-fact__head { display: flex; align-items: flex-start; justify-content: space-between; gap: var(--space-2); }\n.vi-fact__back { display: inline-flex; align-items: center; gap: 2px; border: 0; background: none; padding: 2px 0; margin-bottom: var(--space-1); color: var(--link); font: 600 var(--vi-fs-cap)/16px var(--font-ui); cursor: pointer; }\n.vi-term { border: 0; background: none; padding: 0; font: inherit; color: var(--link); text-decoration: underline; text-decoration-style: dotted; text-decoration-thickness: 1.5px; text-underline-offset: 3px; cursor: pointer; }\n.vi-fact--sheet { position: absolute; left: 0; right: 0; bottom: 0; width: auto; max-width: 560px; margin: 0 auto; max-height: var(--vi-sheet-h, 300px); overflow-y: auto; overscroll-behavior: contain; padding: 0 var(--space-4) calc(var(--space-4) + env(safe-area-inset-bottom, 0px)); border: 0; border-top: 2px solid var(--vi-fact-ring); border-radius: var(--radius-lg) var(--radius-lg) 0 0; box-shadow: 0 -6px 0 0 var(--vi-fact-fill), var(--shadow-pop); font-size: var(--vi-fs-body); line-height: var(--vi-lh-body); animation: vi-sheet-in var(--duration-base) var(--ease-standard); transition: transform var(--duration-quick) var(--ease-standard), max-height var(--duration-base) var(--ease-standard); }\n.vi-fact--sheet.is-expanded { max-height: calc(100% - var(--space-7)); }\n.vi-fact__grip { position: sticky; top: 0; display: flex; justify-content: center; margin: 0 calc(var(--space-4) * -1); background: var(--surface-overlay); touch-action: none; cursor: grab; z-index: 1; }\n.vi-fact__handle { position: relative; width: 64px; height: 24px; border: 0; padding: 0; background: none; cursor: pointer; }\n.vi-fact__handle::after { content: \"\"; position: absolute; left: 12px; right: 12px; top: 10px; height: 5px; border-radius: var(--radius-pill); background: var(--line-strong); }\n.vi-fact--sheet .vi-fact__title { font-size: calc(24px * var(--vi-label-scale)); line-height: 1.15; padding-top: var(--space-1); }\n.vi-fact--sheet .vi-fact__close { margin: 0 calc(var(--space-2) * -1) 0 0; }\n.vi-fact--sheet .vi-fact__step { min-height: 44px; padding: 0 var(--space-3) 0 var(--space-4); font-size: var(--vi-fs-sm); }\n.vi-fact--sheet .vi-fact__link { font-size: var(--vi-fs-sm); min-height: 44px; display: inline-flex; align-items: center; }\n[data-motion=\"reduced\"] .vi-fact--sheet { animation: vi-fade 120ms; }\n@media (prefers-reduced-motion: reduce) {\n  .vi-fact--sheet { animation: vi-fade 120ms; }\n  .vi-map.is-idle .vi-map__world { transition: none; }\n}\n.vi-map__trail { position: absolute; top: var(--space-4); left: var(--space-4); z-index: var(--z-chrome); }\n.vi-map__ctrls { position: absolute; top: var(--space-4); right: var(--space-4); z-index: var(--z-chrome); }\n[data-reveal=\"instant\"] .vi-map.is-reveal .vi-map__slot, [data-motion=\"reduced\"] .vi-map.is-reveal .vi-map__slot { animation: vi-fade var(--vi-reduced-fade, 120ms) backwards; animation-delay: 0ms !important; }\n[data-reveal=\"instant\"] .vi-map.is-reveal .vi-edge, [data-reveal=\"instant\"] .vi-map.is-reveal .vi-edge__line, [data-motion=\"reduced\"] .vi-map.is-reveal .vi-edge, [data-motion=\"reduced\"] .vi-map.is-reveal .vi-edge__line { animation: none; stroke-dashoffset: 0; }\n@media (prefers-reduced-motion: reduce) {\n  .vi-map.is-reveal .vi-map__slot { animation: vi-fade var(--vi-reduced-fade, 120ms) backwards; animation-delay: 0ms !important; }\n  .vi-map.is-reveal .vi-edge, .vi-map.is-reveal .vi-edge__line { animation: none; stroke-dashoffset: 0; }\n}\n[data-motion=\"reduced\"] *, [data-motion=\"reduced\"] *::before, [data-motion=\"reduced\"] *::after { transition-duration: 1ms !important; }\n.vi-fact__acts { flex-wrap: wrap; justify-content: flex-end; }\n.vi-fact__link { display: inline-flex; align-items: center; gap: 2px; }\n.vi-anchor { position: relative; display: inline; }\n.vi-anchor.is-open .vi-term { background: var(--selection); border-radius: 3px; }\n.vi-anchor__pop { position: absolute; left: -12px; top: calc(100% + 6px); z-index: var(--z-menu); display: block; width: max-content; }\n.vi-anchor-card { position: relative; display: block; width: min(300px, calc(100vw - 32px)); box-sizing: border-box; padding: var(--space-3) var(--space-4) var(--space-3); background: var(--surface-overlay); color: var(--ink); text-align: left; white-space: normal; font: 400 var(--vi-fs-sm)/20px var(--font-ui); border: 2px solid var(--vi-fact-ring); border-radius: 12px 16px 10px 14px / 14px 10px 16px 12px; box-shadow: 4px 5px 0 0 var(--vi-fact-fill), 4px 5px 0 2px var(--vi-fact-ring), var(--shadow-pop); animation: vi-pop var(--duration-quick) var(--ease-standard); }\n.vi-anchor-card.is-in-sheet { width: auto; border: 0; box-shadow: none; padding: 0; animation: none; background: transparent; }\n[data-theme^=\"contrast\"] .vi-anchor-card { border-color: var(--ink); box-shadow: none; }\n.vi-anchor-card__eyebrow { font: 400 11px/14px var(--font-display); letter-spacing: .14em; text-transform: uppercase; color: var(--ink-muted); }\n.vi-anchor-card__word { font: 700 20px/24px var(--font-hand); color: var(--ink); margin: 2px 0 var(--space-1); }\n.vi-fact--sheet .vi-anchor-card__word { font-size: calc(24px * var(--vi-label-scale)); line-height: 1.15; }\n.vi-anchor-card__desc { margin: 0; color: var(--ink); }\n.vi-anchor-card__acts { display: flex; align-items: center; justify-content: flex-end; flex-wrap: wrap; gap: var(--space-3); margin-top: var(--space-3); padding-top: var(--space-2); border-top: 1px dashed var(--line); }\n.vi-fact--sheet .vi-anchor-card__acts .vi-fact__link { min-height: 44px; }\n[data-type=\"readable\"] .vi-anchor-card__word { font-family: var(--font-ui); }\n[data-motion=\"reduced\"] .vi-anchor-card { animation: vi-fade 120ms; }\n@media (prefers-reduced-motion: reduce) {\n  .vi-anchor-card { animation: vi-fade 120ms; }\n}\n.vi-peek .vi-fact__foot { flex-wrap: wrap; row-gap: var(--space-2); }\n.vi-peek .vi-fact__acts { margin-left: auto; }\n.vi-map.has-highlight .vi-node.is-dimmed { opacity: .35; transition: opacity var(--duration-quick) var(--ease-standard); }\n.vi-map.has-highlight .vi-node.is-selected .vi-node__body { stroke: var(--ink); }\n.vi-map { container-type: inline-size; }\n.vi-edge__hit { fill: none; stroke: transparent; stroke-width: 18; pointer-events: stroke; cursor: pointer; }\n.vi-edge__hit:hover + .vi-edge__line { stroke-width: 3.5; }\n.vi-edge.is-selected .vi-edge__line, .vi-edge.is-selected .vi-edge__arrow { stroke: var(--focus); stroke-width: 3.5; }\n.vi-map__group-hit { fill: none; stroke: transparent; stroke-width: 16; pointer-events: stroke; cursor: pointer; }\n.vi-map__group.is-selected rect:not(.vi-map__group-hit) { stroke: var(--focus); stroke-width: 2.5; stroke-dasharray: none; }\n.vi-map__group-label.is-selected { border-color: var(--focus); color: var(--focus); box-shadow: 0 0 0 1px var(--focus); }\n.vi-map { touch-action: pan-x pan-y; }\n.vi-map.is-app { touch-action: none; }\n.vi-map.is-pinching .vi-map__world { transition: none; }\n.vi-map.is-instant.is-reveal .vi-map__slot { animation: vi-fade var(--vi-reduced-fade, 120ms) backwards; animation-delay: 0ms !important; }\n.vi-map.is-instant.is-reveal .vi-edge, .vi-map.is-instant.is-reveal .vi-edge__line { animation: none; stroke-dashoffset: 0; }\n.vi-map.is-instant .vi-node, .vi-map.is-instant .vi-node__rings { transition: none; }\n.vi-map.is-detail-body .vi-node:not(.is-selected):not(:focus-visible):not(:hover) :is(.vi-node__rings, .vi-node__label), .vi-map.is-detail-speck .vi-node:not(.is-selected):not(:focus-visible):not(:hover) :is(.vi-node__rings, .vi-node__label) { display: none; }\n.vi-map.is-detail-body .vi-node:not(.is-selected):not(:focus-visible):not(:hover) .vi-node__body, .vi-map.is-detail-speck .vi-node:not(.is-selected):not(:focus-visible):not(:hover) .vi-node__body, .vi-map.no-shadows .vi-node__body { filter: none; }\n@keyframes vi-pop { from { opacity: 0; transform: translateY(-4px) scale(.98); } }\n@keyframes vi-fade { from { opacity: 0; } }\n@keyframes vi-bloom { from { opacity: 0; transform: translate(calc(-50% + var(--vi-dx)), calc(-50% + var(--vi-dy))) scale(var(--vi-bloom-from, .55)); } }\n@keyframes vi-line { to { stroke-dashoffset: 0; } }\n@keyframes vi-settle { from { transform: scale(var(--vi-settle-from, .94)); } }\n@keyframes vi-sheet-in { from { transform: translateY(100%); } }\n";
+export const SPEC_FONTS_URL = "https://fonts.googleapis.com/css2?family=Atkinson+Hyperlegible+Next:ital,wght@0,200..800;1,200..800&family=Atkinson+Hyperlegible+Mono:wght@400;600&family=Kalam:wght@400;700&display=swap";
+export const SPEC_DESIGN_SYSTEM_VERSION = "0.2.0";
+/** Font files shipped with the package (fonts/ directory), from design-system/fonts/fonts.css. */
+export const SPEC_BUNDLED_FONTS = [
+  {
+    "family": "Caveat",
+    "file": "Caveat-Variable.ttf",
+    "weight": "400 700"
+  }
+] as const;

package/src/hooks/index.ts

@@ -1,7 +1,5 @@
 export { useKonvaRenderer } from './useKonvaRenderer';
 export type { UseKonvaRendererOptions } from './useKonvaRenderer';
 
-export { useKonvaLayerTransition } from './useKonvaLayerTransition';
-export type { LayerTransitionHandlers } from './useKonvaLayerTransition';
 
 export { useViewportNodes } from './useViewportNodes';

package/src/hooks/useKonvaRenderer.ts

@@ -12,7 +12,6 @@
 
 import { useEffect, useCallback, useRef, useState } from 'react';
 import type Konva from 'konva';
-import { ZOOM_MIN, ZOOM_MAX } from '@visualli/core';
 import { useViewportStore } from '../stores/useViewportStore';
 import { useRenderConfigStore } from '../stores/stores';
 
@@ -27,19 +26,18 @@ export interface UseKonvaRendererReturn {
   handleMouseDown:(e: Konva.KonvaEventObject<MouseEvent>) => void;
   handleMouseMove:(e: Konva.KonvaEventObject<MouseEvent>) => void;
   handleMouseUp:  (e: Konva.KonvaEventObject<MouseEvent>) => void;
+  /** End a one-finger / mouse pan now (e.g. a second finger turns it into a pinch), keeping how far it moved. */
+  cancelPan:      () => void;
   canvasWidth:    number;
   canvasHeight:   number;
 }
 
 export function useKonvaRenderer({
   containerRef,
-  stageRef,
   enabled = true,
 }: UseKonvaRendererOptions): UseKonvaRendererReturn {
   const pan              = useViewportStore(s => s.pan);
   const zoom             = useViewportStore(s => s.zoom);
-  const setZoom          = useViewportStore(s => s.setZoom);
-  const setCenter        = useViewportStore(s => s.setCenter);
   const updateCanvasSize = useViewportStore(s => s.updateCanvasSize);
   const autoAdjust       = useRenderConfigStore(s => s.autoAdjustQuality);
 
@@ -114,7 +112,7 @@ export function useKonvaRenderer({
     }
 
     return () => {
-      ro ? ro.disconnect() : window.removeEventListener('resize', updateSize);
+      if (ro) ro.disconnect(); else window.removeEventListener('resize', updateSize);
       if (rafId) cancelAnimationFrame(rafId);
     };
   }, [enabled, containerRef, updateCanvasSize]);
@@ -138,19 +136,11 @@ export function useKonvaRenderer({
       isPanningRef.current = true;
       lastPanPointRef.current = { x: e.evt.clientX, y: e.evt.clientY };
       panAccumRef.current = { x: 0, y: 0 };
-      const stage = e.target.getStage();
-      if (stage) stage.container().style.cursor = 'grabbing';
     }
   }, []);
 
   const handleMouseMove = useCallback((e: Konva.KonvaEventObject<MouseEvent>): void => {
-    if (!isPanningRef.current) {
-      // Update cursor on empty canvas
-      const isOverEmpty = e.target === e.target.getStage();
-      const stage = e.target.getStage();
-      if (stage) stage.container().style.cursor = isOverEmpty ? 'grab' : 'default';
-      return;
-    }
+    if (!isPanningRef.current) return;
     e.evt.preventDefault();
     const deltaX = e.evt.clientX - lastPanPointRef.current.x;
     const deltaY = e.evt.clientY - lastPanPointRef.current.y;
@@ -168,7 +158,7 @@ export function useKonvaRenderer({
     lastPanPointRef.current = { x: e.evt.clientX, y: e.evt.clientY };
   }, []); // No Zustand dep — pan flushed on mouseUp
 
-  const handleMouseUp = useCallback((e: Konva.KonvaEventObject<MouseEvent>): void => {
+  const handleMouseUp = useCallback((): void => {
     if (isPanningRef.current) {
       isPanningRef.current = false;
       const { x, y } = panAccumRef.current;
@@ -176,10 +166,15 @@ export function useKonvaRenderer({
         pan(x, y);
         panAccumRef.current = { x: 0, y: 0 };
       }
-      const stage = e.target.getStage();
-      if (stage) stage.container().style.cursor = 'grab';
     }
   }, [pan]);
 
-  return { handleWheel, handleMouseDown, handleMouseMove, handleMouseUp, canvasWidth, canvasHeight };
+  const cancelPan = useCallback((): void => {
+    if (!isPanningRef.current) return;
+    isPanningRef.current = false;
+    const { x, y } = panAccumRef.current;
+    if (x !== 0 || y !== 0) { pan(x, y); panAccumRef.current = { x: 0, y: 0 }; }
+  }, [pan]);
+
+  return { handleWheel, handleMouseDown, handleMouseMove, handleMouseUp, cancelPan, canvasWidth, canvasHeight };
 }

package/src/hooks/useLayerChoreography.ts

@@ -0,0 +1,159 @@
+// ─── useLayerChoreography ─────────────────────────────────────────────────────
+//
+// Step inside / back out, as the design system's motion.ts describes them:
+//
+//   step inside  the current layer zooms toward the idea (scale 3.2, ease-zoom, 500ms)
+//                and fades (160ms after 150ms); the layers swap at 320ms.
+//   back out     the current layer shrinks toward the centre (scale .6, 220ms) and
+//                fades (200ms); the layers swap at 220ms.
+//   arrive       the new layer's ideas bloom in and its connectors draw (RevealClock),
+//                while the layer as a whole settles from scale .94 (260ms).
+//   reduced      motion reduced (or instant reveal): no zoom, the layers swap at once and
+//                the new one fades in (120ms).
+//
+// The zoom/fade/settle run on the canvas wrapper as compositor animations (Web
+// Animations API), so the Konva canvas is not redrawn while they play.
+// All numbers and easings come from core's MOTION (design-system/geometry/motion.ts).
+
+import { useCallback, useEffect, useRef } from 'react';
+import type Konva from 'konva';
+import { MOTION, cssEase, swapDelay, type FlatNode } from '@visualli/core';
+import { useViewportStore } from '../stores/useViewportStore';
+/** A viewport to return to: centre and zoom. */
+export interface AnimatorViewport { centerX: number; centerY: number; zoomLevel: number }
+import { calculateFitView } from '../utils/layerNavigation';
+
+export interface LayerChoreographyOptions {
+  stageRef: React.RefObject<Konva.Stage | null>;
+  /** The element around the Konva stage; the zoom, fade and settle play on it. */
+  canvasWrapperRef: React.RefObject<HTMLDivElement | null>;
+  reducedMotion: boolean;
+  /** Switch the displayed layer to a child layer (the layers swap here). */
+  onSwapLayer: (childLayerId: string) => void;
+  /** Switch back to the parent layer (the layers swap here). */
+  onSwapBack: () => void;
+  /** Called once the new layer has settled. */
+  onComplete: () => void;
+  /** 'start' before anything moves, 'end' after the new layer has settled (pause hit-testing, GPU hints). */
+  onLifecycle?: (phase: 'start' | 'end') => void;
+}
+
+export interface LayerChoreography {
+  /** Step inside `targetNode` into the child layer. */
+  stepInside: (targetNode: FlatNode, childLayerId: string, childNodes: ReadonlyArray<FlatNode>) => void;
+  /** Back out to a layer whose fit viewport is `parent`. */
+  backOut: (parent: AnimatorViewport) => void;
+  /** The new layer is committed and drawing at its first frame: lift the veil and settle. Call after the swap's React commit. */
+  arrive: () => void;
+  isTransitioning: () => boolean;
+}
+
+export function useLayerChoreography(o: LayerChoreographyOptions): LayerChoreography {
+  const { stageRef, canvasWrapperRef } = o;
+  const opts = useRef(o);
+  opts.current = o;
+
+  const busy = useRef(false);
+  const waiting = useRef(false); // swapped, waiting for the new layer's commit
+  const anims = useRef<Animation[]>([]);
+  const timers = useRef<ReturnType<typeof setTimeout>[]>([]);
+  const after = useRef<number[]>([]);
+
+  const clear = useCallback(() => {
+    timers.current.forEach(clearTimeout); timers.current = [];
+    after.current.forEach(cancelAnimationFrame); after.current = [];
+    anims.current.forEach((a) => a.cancel()); anims.current = [];
+  }, []);
+
+  const applyViewport = useCallback((vp: AnimatorViewport) => {
+    const stage = stageRef.current;
+    if (stage) {
+      stage.x(stage.width() / 2 - vp.centerX * vp.zoomLevel);
+      stage.y(stage.height() / 2 - vp.centerY * vp.zoomLevel);
+      stage.scaleX(vp.zoomLevel); stage.scaleY(vp.zoomLevel);
+      stage.getLayers().forEach((l) => l.drawScene());
+    }
+    const s = useViewportStore.getState();
+    s.setCenter(vp.centerX, vp.centerY);
+    s.setZoom(vp.zoomLevel);
+  }, [stageRef]);
+
+  const lifecycle = useCallback((phase: 'start' | 'end') => {
+    const stage = stageRef.current;
+    stage?.getLayers().forEach((l) => { l.listening(phase === 'end'); });
+    if (phase === 'end') stage?.batchDraw();
+    opts.current.onLifecycle?.(phase);
+  }, [stageRef]);
+
+  const leave = useCallback((wrap: HTMLElement | null, dir: 'in' | 'out', origin: string, vp: AnimatorViewport, swap: () => void) => {
+    busy.current = true;
+    waiting.current = false;
+    lifecycle('start');
+    const reduced = opts.current.reducedMotion;
+    if (wrap && !reduced && typeof wrap.animate === 'function') {
+      const m = MOTION;
+      wrap.style.transformOrigin = origin;
+      wrap.style.willChange = 'transform, opacity';
+      if (dir === 'in') {
+        anims.current.push(
+          wrap.animate([{ transform: 'scale(1)' }, { transform: `scale(${m.dive.scale})` }], { duration: m.dive.duration, easing: cssEase(m.dive.ease), fill: 'forwards' }),
+          wrap.animate([{ opacity: 1 }, { opacity: 0 }], { delay: m.dive.fadeDelay, duration: m.dive.fade, easing: 'ease', fill: 'both' }),
+        );
+      } else {
+        anims.current.push(
+          wrap.animate([{ transform: 'scale(1)' }, { transform: `scale(${m.surface.scale})` }], { duration: m.surface.duration, easing: cssEase(m.surface.ease), fill: 'forwards' }),
+          wrap.animate([{ opacity: 1 }, { opacity: 0 }], { duration: m.surface.fade, easing: 'ease', fill: 'both' }),
+        );
+      }
+    }
+    timers.current.push(setTimeout(() => {
+      waiting.current = true;
+      swap();
+      applyViewport(vp);
+      // Safety net: if the host never reports the commit, arrive anyway.
+      timers.current.push(setTimeout(() => arriveRef.current(), 500));
+    }, swapDelay(dir, reduced)));
+  }, [applyViewport, lifecycle]);
+
+  const arriveRef = useRef<() => void>(() => {});
+  const arrive = useCallback(() => {
+    if (!waiting.current) return;
+    waiting.current = false;
+    const wrap = canvasWrapperRef.current;
+    const reduced = opts.current.reducedMotion;
+    // Drop the zoomed-and-faded veil (the new layer is drawing its first frame, ideas not yet bloomed) and settle.
+    anims.current.forEach((a) => a.cancel()); anims.current = [];
+    let settle = reduced ? MOTION.reduced.fade : MOTION.settle.duration;
+    if (wrap && !reduced && typeof wrap.animate === 'function') {
+      const a = wrap.animate([{ transform: `scale(${MOTION.settle.fromScale})` }, { transform: 'none' }], { duration: MOTION.settle.duration, easing: cssEase(MOTION.settle.ease) });
+      anims.current.push(a);
+      settle = MOTION.settle.duration;
+    }
+    timers.current.push(setTimeout(() => {
+      anims.current.forEach((a) => a.cancel()); anims.current = [];
+      if (wrap) { wrap.style.willChange = 'auto'; wrap.style.transformOrigin = ''; }
+      busy.current = false;
+      opts.current.onComplete();
+      lifecycle('end');
+    }, settle));
+  }, [canvasWrapperRef, lifecycle]);
+  arriveRef.current = arrive;
+
+  const stepInside = useCallback((targetNode: FlatNode, childLayerId: string, childNodes: ReadonlyArray<FlatNode>) => {
+    if (busy.current) return;
+    const stage = stageRef.current;
+    const zoom = stage?.scaleX() ?? 1;
+    const origin = stage ? `${targetNode.x * zoom + stage.x()}px ${targetNode.y * zoom + stage.y()}px` : '50% 50%';
+    const fit = calculateFitView(childNodes as FlatNode[], stage?.width() ?? 800, stage?.height() ?? 600);
+    leave(canvasWrapperRef.current, 'in', origin, { centerX: fit.centerX, centerY: fit.centerY, zoomLevel: fit.zoomLevel }, () => opts.current.onSwapLayer(childLayerId));
+  }, [stageRef, canvasWrapperRef, leave]);
+
+  const backOut = useCallback((parent: AnimatorViewport) => {
+    if (busy.current) return;
+    leave(canvasWrapperRef.current, 'out', '50% 50%', parent, () => opts.current.onSwapBack());
+  }, [canvasWrapperRef, leave]);
+
+  const isTransitioning = useCallback(() => busy.current, []);
+  useEffect(() => () => { clear(); busy.current = false; }, [clear]);
+  return { stepInside, backOut, arrive, isTransitioning };
+}

package/src/hooks/useViewportNodes.ts

@@ -54,6 +54,5 @@ export function useViewportNodes(
       spatialIndex: indexRef.current,
       spatialIndexThreshold: SPATIAL_INDEX_THRESHOLD,
     });
-  // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [nodes, levelFilter, skipCulling, isDragging, centerX, centerY, zoomLevel, canvasWidth, canvasHeight]);
 }

package/src/index.ts

@@ -24,32 +24,26 @@ export type { IViewportStore }    from './stores/useViewportStore';
 
 // Hooks
 export { useKonvaRenderer }         from './hooks/useKonvaRenderer';
-export { useKonvaLayerTransition }  from './hooks/useKonvaLayerTransition';
+export { useLayerChoreography }     from './hooks/useLayerChoreography';
+export type { LayerChoreography, LayerChoreographyOptions } from './hooks/useLayerChoreography';
 export { useViewportNodes }         from './hooks/useViewportNodes';
 export type { UseKonvaRendererOptions, UseKonvaRendererReturn } from './hooks/useKonvaRenderer';
-export type { LayerTransitionHandlers } from './hooks/useKonvaLayerTransition';
 
-// Animations
-export { KonvaLayerTransitionAnimator, konvaLayerTransitionAnimator } from './animations/konvaLayerTransition';
-export type { AnimatorViewport, TransitionCallbacks } from './animations/konvaLayerTransition';
+export type { AnimatorViewport } from './hooks/useLayerChoreography';
 
-// Config helpers
+// Design system: themes, comfort, tokens, geometry (generated from design-system/ in @visualli/core)
 export {
-  ALL_BLOB_SHAPES,
-  ACTIVE_BLOB_TYPES,
-  BLOB_LAYER_CONFIG,
-  NODE_LAYER_CONFIG,
-  getBlobTypeForLayer,
-  BLOB_TEXT_OFFSETS,
-  drawBlobPath,
-  buildBlobPathData,
-  NODE_TEXT_BASE_FONT_PX,
-  DESCRIPTION_TEXT_BASE_FONT_PX,
-  computeNodeTextWorldScale,
-  computeNodeTextScreenScale,
-  computeOverlayScale,
-  computeEdgeLabelScale,
-} from './config';
+  THEME_NAMES, TOPICS, DESIGN_SYSTEM_VERSION, TOKENS, METRICS,
+  resolveTheme, resolveComfort, ideaColor, ideaStyle, topicStyle, getTokens,
+  BLOB_SHAPES, RINGS, blobPath, blobRadius, edgePath, arrowPath, shapeForLevel,
+  IDEA, LABEL_GROWTH, ideaSize, labelGrowth,
+} from '@visualli/core';
+export type { ThemeName, ThemeInput, TopicName, Comfort } from '@visualli/core';
+export { useDesign, useReaderEnv } from './design/useDesign';
+export { makeDesign, resolveDesign, DEFAULT_DESIGN } from './design/design';
+export type { Design, DesignProps } from './design/design';
+export { ensureDesignSystemStyles, loadCanvasFonts } from './design/runtime';
+export type { DesignSystemAssets } from './design/runtime';
 
 // Utils
 export {
@@ -70,12 +64,18 @@ export { default as KonvaNodeLayer }      from './components/KonvaNodeLayer';
 export { default as KonvaEdgeLayer }      from './components/KonvaEdgeLayer';
 export { default as KonvaContainer }      from './components/KonvaContainer';
 export { default as KonvaContainerLayer } from './components/KonvaContainerLayer';
+export { default as KonvaContainerLabelLayer } from './components/KonvaContainerLabelLayer';
 export { default as NavigationStack }     from './components/NavigationStack';
 export { default as ZoomControls }        from './components/ZoomControls';
-export { default as SketchyBoxKonva }     from './components/SketchyBoxKonva';
+export { PeekCard, TermCard, DepthTrail, splitTerms, paintVars } from './components/Overlays';
+export { A11yLayer } from './components/A11yLayer';
 export type { NavStackEntry }             from './components/NavigationStack';
+export type { PeekCardProps, TrailEntry, DepthTrailProps, IdeaPaint } from './components/Overlays';
+export { ideaMeasure } from './design/measure';
 export type { KonvaNodeProps }            from './components/KonvaNode';
 export type { KonvaEdgeProps }            from './components/KonvaEdge';
 export type { KonvaStageProps }           from './components/KonvaStage';
 export type { ContainerGroup }            from './components/KonvaContainerLayer';
+export { layoutContainers, measurePill, drawHull, drawPill } from './design/containers';
+export type { PlacedContainer, PlacedPill } from './design/containers';
 

package/src/stores/stores.ts

@@ -4,14 +4,14 @@ import { create } from 'zustand';
 import { selectionStore, renderConfigStore } from '@visualli/core';
 import type { ISelectionStore, IRenderConfigStore } from '@visualli/core';
 
-export const useSelectionStore = create<ISelectionStore>((set, get, store) => {
+export const useSelectionStore = create<ISelectionStore>((set) => {
   selectionStore.subscribe((state) => set(state));
   return selectionStore.getState();
 });
 
 // ─── Render Config Store ──────────────────────────────────────────────────────
 
-export const useRenderConfigStore = create<IRenderConfigStore>((set, get, store) => {
+export const useRenderConfigStore = create<IRenderConfigStore>((set) => {
   renderConfigStore.subscribe((state) => set(state));
   return renderConfigStore.getState();
 });