@visualli/react 0.1.6 → 0.2.0

package/dist/index.d.ts

@@ -1,11 +1,38 @@
 import React$1 from 'react';
-import { VisualliDocument, FlatNode, VisualliLayer, NodeMap, ViewportState, IRenderConfigStore, ISelectionStore, MindMapConnection } from '@visualli/core';
-export { ACTIVE_BLOB_TYPES, ALL_BLOB_SHAPES, BLOB_LAYER_CONFIG, BLOB_TEXT_OFFSETS, DESCRIPTION_TEXT_BASE_FONT_PX, FitResult, NODE_LAYER_CONFIG, NODE_TEXT_BASE_FONT_PX, calculateFitCenter, calculateFitView, calculateFitZoom, computeEdgeLabelScale, computeNodeTextScreenScale, computeNodeTextWorldScale, computeOverlayScale, drawBlobPath, getBlobTypeForLayer, getChildLayerForNode, getConnectionsForLayer, getLayerForNavigation } from '@visualli/core';
+import { ThemeInput, Comfort, VisualliDocument, FlatNode, VisualliLayer, NodeMap, ViewportState, IRenderConfigStore, ISelectionStore, ThemeName, ResolvedComfort, Metrics, MindMapConnection, Hull, LabelSide, SemanticAnchor, IdeaMeasure } from '@visualli/core';
+export { BLOB_SHAPES, Comfort, DESIGN_SYSTEM_VERSION, FitResult, IDEA, LABEL_GROWTH, METRICS, RINGS, THEME_NAMES, TOKENS, TOPICS, ThemeInput, ThemeName, TopicName, arrowPath, blobPath, blobRadius, calculateFitCenter, calculateFitView, calculateFitZoom, edgePath, getChildLayerForNode, getConnectionsForLayer, getLayerForNavigation, getTokens, ideaColor, ideaSize, ideaStyle, labelGrowth, resolveComfort, resolveTheme, shapeForLevel, topicStyle } from '@visualli/core';
 import * as zustand from 'zustand';
 import Konva from 'konva';
 import * as konva_lib_Stage from 'konva/lib/Stage';
 
-type VisualliTheme = 'dark' | 'light' | 'auto';
+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;
+}
+/**
+ * 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).
+ */
+declare function ensureDesignSystemStyles(assets?: DesignSystemAssets): Promise<void>;
+/**
+ * Resolves once the canvas fonts are usable (or after `timeoutMs`, so an
+ * offline reader still gets a map in the fallback faces).
+ */
+declare function loadCanvasFonts(sheet?: Promise<void>, timeoutMs?: number): Promise<void>;
+
+/**
+ * Any of the 8 design-system themes ('light', 'dark', 'focus-light', 'focus-dark', 'colorsafe-light',
+ * 'colorsafe-dark', 'contrast-light', 'contrast-dark'), a family ('focus' | 'colorsafe' | 'contrast'),
+ * or 'auto' (follow the reader's colour scheme). 'light' | 'dark' | 'auto' are the pre-0.2 values and keep working.
+ */
+type VisualliTheme = ThemeInput;
 interface VisualliRendererProps {
     /**
      * Raw JSONL string — the content of a .visualli file.
@@ -29,18 +56,35 @@ interface VisualliRendererProps {
      */
     useWorker?: boolean;
     /**
-     * Colour theme.
-     *  - 'dark'  → always dark background
-     *  - 'light' → always light background
-     *  - 'auto'  → follows the OS/browser prefers-color-scheme
+     * Colour theme (see VisualliTheme).
+     *  - 'auto' follows prefers-color-scheme (and switches to high contrast under forced-colors)
      * @default 'light'
      */
     theme?: VisualliTheme;
+    /** Comfort settings: readable type, larger text, reduced motion ('system' follows the OS). */
+    comfort?: Comfort;
+    /** Switch to the high-contrast theme under forced-colors. @default true */
+    respectForcedColors?: boolean;
+    /**
+     * Interaction layout: 'auto' follows the reader's input (touch -> bottom-sheet peek and larger
+     * controls, pointer -> floating peek on hover); force one with 'touch' or 'pointer'.
+     * @default 'auto'
+     */
+    layout?: 'auto' | 'touch' | 'pointer';
+    /** Where the zoom / fit controls sit: the design system's 'bottom-right' (default) or the pre-0.2 'top-right'. */
+    /**
+     * The map is the page (an app such as Visualli's web app): it takes every touch gesture, so the browser never
+     * zooms or scrolls the page — the design system's `.vi-map.is-app` (`touch-action: none`). Leave it off when the
+     * map is embedded in a scrolling page: one finger then still scrolls the page, two fingers pinch the map.
+     */
+    app?: boolean;
+    /** Where the zoom / fit controls sit: 'top-right' (default, the design system's placement) or 'bottom-right'. */
+    controlsPosition?: 'top-right' | 'bottom-right';
     /**
      * Enable chromatic immersion background effect.
      * When true:
-     *  - Root layer (level 0) shows base background color
-     *  - Child layers show parent node's color as semi-transparent background
+     *  - Root layer (level 0) shows the plain canvas
+     *  - Child layers are tinted with the parent idea's topic colour
      * @default false
      */
     chromaticImmersion?: boolean;
@@ -56,12 +100,16 @@ interface VisualliRendererProps {
      * @default '100%'
      */
     height?: string | number;
+    /** Directory URL the bundled Caveat font is served from (defaults to the copy in the npm package, via jsDelivr). */
+    fontBaseUrl?: DesignSystemAssets['fontBaseUrl'];
+    /** Set false when you load Kalam and Atkinson Hyperlegible yourself. */
+    loadWebFonts?: DesignSystemAssets['loadWebFonts'];
     /** Additional CSS class on the root element. */
     className?: string;
     /** Additional inline styles merged onto the root element. */
     style?: React$1.CSSProperties;
 }
-declare function VisualliRenderer({ visualliString, visualliFile, theme, width, height, useWorker, chromaticImmersion, className, style, }: VisualliRendererProps): React$1.JSX.Element;
+declare function VisualliRenderer({ visualliString, visualliFile, theme, comfort, respectForcedColors, layout, controlsPosition, app, width, height, useWorker, chromaticImmersion, fontBaseUrl, loadWebFonts, className, style, }: VisualliRendererProps): React$1.JSX.Element;
 
 interface VisualliCanvasProps {
     preParsedVisualli?: VisualliDocument;
@@ -77,12 +125,51 @@ interface VisualliCanvasProps {
      * Component handles all fetching and parsing automatically.
      */
     visualliFile?: File | string;
+    /**
+     * Theme: one of the 8 design-system themes ('light', 'dark', 'focus-light', …), a family
+     * ('focus' | 'colorsafe' | 'contrast') or 'auto' (follow the reader). Default 'light'.
+     */
+    theme?: ThemeInput;
+    /** @deprecated use `theme`. true -> 'dark', false -> 'light'. Kept for one release. */
     isDark?: boolean;
+    /** Comfort settings: readable type, larger text, reduced motion. */
+    comfort?: Comfort;
+    /**
+     * How a layer arrives. 'gradual' (default): ideas bloom in one by one, then connectors draw
+     * (design-system motion). 'instant': everything fades in together, as with reduced motion.
+     */
+    reveal?: 'gradual' | 'instant';
+    /** Switch to the high-contrast theme under forced-colors. Default true. */
+    respectForcedColors?: boolean;
+    /**
+     * Interaction layout. 'auto' (default) follows the reader's input: touch devices get the design
+     * system's bottom-sheet peek and larger controls, pointer devices the floating peek on hover.
+     * Force one with 'touch' or 'pointer'.
+     */
+    layout?: 'auto' | 'touch' | 'pointer';
+    /**
+     * The map is the page (an app such as Visualli's web app): it takes every touch gesture, so the browser never
+     * zooms or scrolls the page — the design system's `.vi-map.is-app` (`touch-action: none`). Leave it off when the
+     * map is embedded in a scrolling page: one finger then still scrolls the page, two fingers pinch the map.
+     */
+    app?: boolean;
+    /**
+     * Where the zoom / fit controls sit. Default 'top-right', the design system's placement (`.vi-map__ctrls`,
+     * opposite the depth trail). 'bottom-right' moves them to the bottom corner for hosts that need the top edge;
+     * there they rise above the touch peek sheet while it's open.
+     */
+    controlsPosition?: 'top-right' | 'bottom-right';
+    /** Where the bundled Caveat font is served from (directory URL). Defaults to the copy in the npm package, via jsDelivr. */
+    fontBaseUrl?: DesignSystemAssets['fontBaseUrl'];
+    /** Set false when you load Kalam and Atkinson Hyperlegible yourself. */
+    loadWebFonts?: DesignSystemAssets['loadWebFonts'];
     chromaticImmersion?: boolean;
     onNodeClick?: (node: FlatNode) => void;
     onLayerChange?: (layerId: string, layer: VisualliLayer) => void;
+    onNodeHover?: (nodeId: string | null) => void;
     renderOverlay?: (params: {
         isDark: boolean;
+        theme: string;
         containerWidth: number;
         containerHeight: number;
     }) => React$1.ReactNode;
@@ -141,10 +228,15 @@ declare const useNodeStore: zustand.UseBoundStore<zustand.StoreApi<INodeStore>>;
 interface IViewportStore extends ViewportState {
     canvasWidth: number;
     canvasHeight: number;
+    /** The layer's fit to view (scale and centre): zoom is shown and limited (VIEW) relative to it, as in the design system. */
+    fitScale: number;
+    fitCenterX: number;
+    fitCenterY: number;
     pan: (deltaX: number, deltaY: number) => void;
     zoom: (delta: number, pivotX?: number, pivotY?: number) => void;
     setCenter: (x: number, y: number) => void;
     setZoom: (level: number) => void;
+    setFit: (scale: number, centerX: number, centerY: number) => void;
     updateCanvasSize: (width: number, height: number) => void;
     getVisibleBounds: () => ViewportState['visibleBounds'];
     worldToScreen: (x: number, y: number) => {
@@ -171,98 +263,107 @@ 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;
 }
-declare function useKonvaRenderer({ containerRef, stageRef, enabled, }: UseKonvaRendererOptions): UseKonvaRendererReturn;
+declare function useKonvaRenderer({ containerRef, enabled, }: UseKonvaRendererOptions): UseKonvaRendererReturn;
 
+/** A viewport to return to: centre and zoom. */
 interface AnimatorViewport {
     centerX: number;
     centerY: number;
     zoomLevel: number;
 }
-interface NodeBounds {
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-}
-interface TransitionCallbacks {
-    onUpdate: (state: {
-        viewport: AnimatorViewport;
-        opacity: number;
-        backgroundColor: string;
-    }) => void;
-    onComplete: () => void;
-    onPhaseChange?: (phase: string) => void;
-}
-declare class KonvaLayerTransitionAnimator {
-    private rafId;
-    private timers;
-    private _active;
-    get active(): boolean;
-    cancel(): void;
-    animateZoomIntoLayer(current: AnimatorViewport, targetNode: NodeBounds, childCenter: {
-        x: number;
-        y: number;
-    }, fromColor: string, toColor: string, cb: TransitionCallbacks, targetZoom?: number, canvasWidth?: number, canvasHeight?: number): void;
-    animateZoomOutToParent(current: AnimatorViewport, parent: AnimatorViewport, fromColor: string, toColor: string, cb: TransitionCallbacks): void;
-    private _complete;
-}
-declare const konvaLayerTransitionAnimator: KonvaLayerTransitionAnimator;
-
-interface LayerTransitionOptions {
-    /** Ref to the Konva Stage for imperative position/scale updates each frame. */
+interface LayerChoreographyOptions {
     stageRef: React.RefObject<Konva.Stage | null>;
-    /** Ref to the wrapping div whose CSS `opacity` is driven during transitions. */
+    /** The element around the Konva stage; the zoom, fade and settle play on it. */
     canvasWrapperRef: React.RefObject<HTMLDivElement | null>;
-    /** Ref to the background color div. */
-    bgRef?: React.RefObject<HTMLDivElement | null>;
-    /** Called at the content-swap point — use to switch the displayed layer. */
-    onSwapLayer: (newLayerId: string) => void;
-    /** Called when a zoom-out swap happens — use to update the nav stack. */
+    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 after the transition fully completes. */
+    /** Called once the new layer has settled. */
     onComplete: () => void;
-    /**
-     * GPU CSS-transform mode: called each rAF frame instead of applyViewport.
-     * When provided, the caller is responsible for moving the canvas content.
-     */
-    onViewportFrame?: (vp: AnimatorViewport) => void;
-    /**
-     * Called once when the animation reaches its final viewport.
-     * When provided, replaces the default applyViewport call at completion.
-     */
-    onViewportFinal?: (vp: AnimatorViewport) => void;
-    /**
-     * Called at phase-change points ('swap', 'zoom-back') in addition to the
-     * internal content-swap logic. Use to reset CSS transforms before Konva redraws.
-     */
-    onPhaseChange?: (phase: string) => void;
-    /**
-     * Called with 'start' before the animator fires its first frame and with
-     * 'end' after onComplete. Use to set up / tear down GPU hints (willChange, etc.).
-     */
-    onTransitionLifecycle?: (phase: 'start' | 'end') => void;
+    /** 'start' before anything moves, 'end' after the new layer has settled (pause hit-testing, GPU hints). */
+    onLifecycle?: (phase: 'start' | 'end') => void;
 }
-interface LayerTransitionHandlers {
-    zoomIntoLayer: (doc: VisualliDocument, targetNode: FlatNode, childLayerId: string, childNodes: FlatNode[], fromColor: string, toColor: string) => void;
-    zoomOutToParent: (parentViewport: AnimatorViewport, fromColor: string, toColor: string) => void;
+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;
 }
-declare function useKonvaLayerTransition(opts: LayerTransitionOptions): LayerTransitionHandlers;
+declare function useLayerChoreography(o: LayerChoreographyOptions): LayerChoreography;
 
 declare function useViewportNodes(nodes: FlatNode[], levelFilter?: number, skipCulling?: boolean, 
 /** When true, skip culling so dragged nodes are always visible and the
  *  spatial index (keyed on layout positions) is not consulted. */
 isDragging?: boolean): FlatNode[];
 
-interface BlobPoint {
+interface NodeShadow {
     x: number;
     y: number;
+    blur: number;
+    color: string;
+}
+interface Design {
+    theme: ThemeName;
+    comfort: ResolvedComfort;
+    tokens: Readonly<Record<string, string>>;
+    metrics: Metrics;
+    isDark: boolean;
+    /** CSS font stacks, already switched to the readable face when that comfort setting is on. */
+    fontHand: string;
+    fontNote: string;
+    fontUi: string;
+    /** Multiplier for label sizes (`--vi-label-scale`). */
+    labelScale: number;
+    /** Idea drop shadow for this theme; null when the theme turns it off (high contrast). */
+    nodeShadow: NodeShadow | null;
+    /** Attributes the spec CSS keys off; put them on the renderer's root element. */
+    attrs: Record<string, string>;
+    /** Canvas weight/size for connector labels (the readable face is smaller and bolder). */
+    edgeLabel: {
+        weight: number;
+        size: number;
+    };
+}
+declare function makeDesign(theme: ThemeName, comfortIn: ResolvedComfort): Design;
+declare const DEFAULT_DESIGN: Design;
+interface DesignProps {
+    /**
+     * One of the 8 design-system themes ('light', 'dark', 'focus-light', 'focus-dark',
+     * 'colorsafe-light', 'colorsafe-dark', 'contrast-light', 'contrast-dark'), a family
+     * ('focus' | 'colorsafe' | 'contrast') or 'auto' (follow the reader's colour scheme).
+     */
+    theme?: ThemeInput;
+    /** @deprecated use `theme`. Kept for one release: true -> 'dark', false -> 'light'. */
+    isDark?: boolean;
+    /** Readable type, larger text, reduced motion. */
+    comfort?: Comfort;
+    /** Switch to the matching high-contrast theme under forced-colors (Windows high contrast etc.). Default true. */
+    respectForcedColors?: boolean;
 }
-type BlobShape = ReadonlyArray<BlobPoint>;
-declare function buildBlobPathData(_shape: BlobShape, cx: number, cy: number, width: number, height: number): string;
+/** Resolve props + reader environment (colour scheme, forced colours, reduced motion) to a Design. */
+declare function resolveDesign(props: DesignProps, env: {
+    prefersDark: boolean;
+    forcedColors: boolean;
+    prefersReducedMotion: boolean;
+}): Design;
+
+/** The reader's current preferences. */
+declare function useReaderEnv(): {
+    prefersDark: boolean;
+    forcedColors: boolean;
+    prefersReducedMotion: boolean;
+};
+declare function useDesign(props: DesignProps): Design;
 
 interface KonvaStageProps {
     children: React$1.ReactNode;
@@ -285,8 +386,10 @@ interface KonvaNodeProps {
     isExternallyHovered?: boolean;
     /** True while this node is being pressed/dragged. */
     isExternallyPressed?: boolean;
-    /** True while any node is being dragged — disables expensive shadows. */
+    isSelected?: boolean;
+    /** True while any node is being dragged — disables the drop shadow. */
     isDragging?: boolean;
+    design?: Design;
 }
 declare const KonvaNode: React$1.NamedExoticComponent<KonvaNodeProps>;
 
@@ -294,42 +397,134 @@ interface KonvaEdgeProps {
     sourceNode: FlatNode;
     targetNode: FlatNode;
     connection?: MindMapConnection;
+    /** @deprecated pass `design`. */
     isDark?: boolean;
+    /** @deprecated connectors use the design system's edge colour; kept so existing callers compile. */
     colorOverride?: string;
     zoomLevel?: number;
+    design?: Design;
 }
 declare const KonvaEdge: React$1.NamedExoticComponent<KonvaEdgeProps>;
 
+/** How an idea looks mid-arrival (multiplies its resting look). */
+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. */
+interface EdgeArrival {
+    alpha: number;
+    draw: number;
+}
+/** The timeline of one layer's arrival. Shared by the idea layer and the connector layer. */
+declare class RevealClock {
+    private t0;
+    private end;
+    private plan;
+    private reduced;
+    private center;
+    private order;
+    private listeners;
+    private timer;
+    /** Begin a layer's arrival. `reduced` (reduced motion or instant reveal): everything fades in together. */
+    start(nodes: ReadonlyArray<FlatNode>, edgeCount: number, reduced: boolean, now?: number): void;
+    /** Jump to the finished state (e.g. on unmount). */
+    stop(): void;
+    /** True while the layer is still arriving. */
+    active(now?: number): boolean;
+    /** Called with true when an arrival starts and false when it has finished. Returns the unsubscribe function. */
+    subscribe(fn: (running: boolean) => void): () => void;
+    private emit;
+    /** 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;
+    /** Fills `out` with connector `i`'s arrival look. Returns false when it has arrived. */
+    edge(i: number, dashed: boolean, now: number, out: EdgeArrival): boolean;
+}
+
 interface KonvaNodeLayerProps {
     nodes?: FlatNode[];
     isTransitioning?: boolean;
     isDragging?: boolean;
     hoveredNodeId?: string | null;
     pressedNodeId?: string | null;
+    selectedNodeId?: string | null;
+    /** Idea with keyboard focus (accessible layer). */
+    focusedNodeId?: string | null;
+    design?: Design;
+    /** The layer's arrival timeline (bloom). Omit for no arrival animation. */
+    clock?: RevealClock;
+    /** Touch layout (`.vi-map.is-touch`): the other ideas fade while one is peeked. */
+    touch?: boolean;
+    /** Idea whose peek (sheet) is open on touch. */
+    peekedNodeId?: string | null;
 }
-declare function KonvaNodeLayer({ nodes: propNodes, isTransitioning, isDragging, hoveredNodeId, pressedNodeId, }: KonvaNodeLayerProps): React$1.JSX.Element;
+declare function KonvaNodeLayer({ nodes: propNodes, isDragging, hoveredNodeId, pressedNodeId, selectedNodeId, focusedNodeId, design, clock, touch, peekedNodeId, }: KonvaNodeLayerProps): React$1.JSX.Element;
 
 interface KonvaEdgeLayerProps {
     nodes: FlatNode[];
     connections: MindMapConnection[];
     currentLevel?: number;
+    /** @deprecated pass `design`; kept so existing callers still compile. */
     isDark?: boolean;
-    /** Pass true while a node is being dragged to skip viewport culling. */
+    /** Pass true while an idea is being dragged (connectors are always drawn then). */
     isDragging?: boolean;
+    design?: Design;
+    /** The layer's arrival timeline (connectors draw in after the ideas). Omit for no arrival animation. */
+    clock?: RevealClock;
 }
-declare function KonvaEdgeLayer({ nodes, connections, currentLevel, isDark, isDragging, }: KonvaEdgeLayerProps): React$1.JSX.Element;
+declare function KonvaEdgeLayer({ connections, isDragging, design, clock }: KonvaEdgeLayerProps): React$1.JSX.Element;
 
 interface KonvaContainerProps {
     /** All nodes in this container group (already resolved from nodeMap). */
     nodes: FlatNode[];
-    /** Label text shown on the pill badge. */
+    /** The group's name, drawn as a pill on the hull. */
     label?: string;
-    /** Unused – kept for API compat; stroke is always #747270. */
+    /** @deprecated unused: the hull and name use the design system's container style. */
     color?: string;
+    /** @deprecated pass `design`. */
     isDark?: boolean;
+    zoomLevel?: number;
+    design?: Design;
 }
 declare const KonvaContainer: React$1.NamedExoticComponent<KonvaContainerProps>;
 
+interface ContainerInput {
+    id: string;
+    label?: string;
+    nodeIds: string[];
+}
+interface ConnectionInput {
+    from: string;
+    to: string;
+}
+interface PlacedPill {
+    text: string;
+    x: number;
+    y: number;
+    side: LabelSide;
+    w: number;
+    h: number;
+}
+interface PlacedContainer {
+    id: string;
+    hull: Hull;
+    pill: PlacedPill | null;
+}
+/** The pill's box in world units for `text` (ellipsised past labelMaxWidth), with the text grown by `k`. */
+declare function measurePill(text: string, d: Design, k: number, c?: CanvasRenderingContext2D | null): PlacedPill;
+/**
+ * Hulls and name positions for a layer's containers, in file order (each name
+ * avoids the ones placed before it). Placement uses the names' size at 100%
+ * (k = 1), so they don't hop while zooming; they follow ideas that are dragged.
+ */
+declare function layoutContainers(containers: ReadonlyArray<ContainerInput>, nodes: ReadonlyMap<string, FlatNode>, connections: ReadonlyArray<ConnectionInput>, d: Design): PlacedContainer[];
+/** The dashed hull (beneath connectors and ideas). */
+declare function drawHull(c: CanvasRenderingContext2D, h: Hull, d: Design): void;
+/** The name pill (above connectors and ideas), its text growing like idea labels when zoomed out (labelGrowth). */
+declare function drawPill(c: CanvasRenderingContext2D, p: PlacedPill, d: Design, zoom: number): void;
+
 interface ContainerGroup {
     id: string;
     label?: string;
@@ -337,39 +532,102 @@ interface ContainerGroup {
     level: number;
 }
 interface KonvaContainerLayerProps {
-    /** Layout-snapshot nodes — used only as a seed for initial IDs. */
+    /** Layout-snapshot nodes (kept for API compatibility). */
     nodes: FlatNode[];
     containers: ContainerGroup[];
+    /** The layer's connections: container names are placed clear of them. */
+    connections?: ConnectionInput[];
+    /** @deprecated pass `design`. */
+    isDark?: boolean;
+    design?: Design;
+}
+declare function KonvaContainerLayer({ containers, connections, design }: KonvaContainerLayerProps): React$1.JSX.Element | null;
+
+interface KonvaContainerLabelLayerProps {
+    containers: ContainerGroup[];
+    connections?: ConnectionInput[];
+    design?: Design;
+}
+declare function KonvaContainerLabelLayer({ containers, connections, design }: KonvaContainerLabelLayerProps): React$1.JSX.Element | null;
+
+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;
 }
-declare function KonvaContainerLayer({ nodes, containers, isDark }: KonvaContainerLayerProps): React$1.JSX.Element | null;
+declare const ZoomControls: React$1.NamedExoticComponent<ZoomControlsProps>;
+/** An idea's colour: its topic, or a custom colour drawn as given (FlatNode.topic / FlatNode.custom). */
+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). */
+declare function paintVars(p: IdeaPaint): {
+    fill: string;
+    ring: string;
+};
+/** 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). */
+interface TrailEntry {
+    layerId: string;
+    label: string;
+    level: number;
+    paint: IdeaPaint;
+}
+interface DepthTrailProps {
+    stack: TrailEntry[];
+    onNavigateBack: (index: number) => void;
+}
+declare const DepthTrail: React$1.NamedExoticComponent<DepthTrailProps>;
+/** Split `text` into plain runs and runs that match an anchor word (longest word wins, whole words only). */
+declare function splitTerms(text: string, anchors: ReadonlyArray<SemanticAnchor>): Array<string | SemanticAnchor>;
+declare const TermCard: ({ anchor, inSheet }: {
+    anchor: SemanticAnchor;
+    inSheet?: boolean;
+}) => React$1.JSX.Element;
+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$1.ReactNode;
+}
+declare const PeekCard: React$1.NamedExoticComponent<PeekCardProps>;
 
 interface NavStackEntry {
     layerId: string;
     layer: VisualliLayer;
     label: string;
+    /** Colour of the idea this layer opens from (the design system's TRAIL: the clicked idea's own colour); the first
+     *  entry, the map's title, is TRAIL.rootTopic. */
+    paint?: IdeaPaint;
 }
 interface NavigationStackProps {
     stack: NavStackEntry[];
     onNavigateBack: (index: number) => void;
+    /** @deprecated theme comes from the surrounding data-theme. */
     isDark?: boolean;
+    /** Override the trail's default offset from the top-left corner. */
     top?: string;
     left?: string;
 }
 declare const NavigationStack: React$1.NamedExoticComponent<NavigationStackProps>;
 
-interface ZoomControlsProps {
-    isDark?: boolean;
+interface A11yLayerProps {
+    nodes: FlatNode[];
+    /** Accessible name of the list, e.g. the layer title. */
+    label: string;
+    hasChildLayer: (nodeId: string) => boolean;
+    onActivate: (node: FlatNode) => void;
+    onFocusNode: (nodeId: string | null) => void;
+    /** Spoken when the layer changes. */
+    announcement?: string;
 }
-declare const ZoomControls: React$1.NamedExoticComponent<ZoomControlsProps>;
+declare const A11yLayer: React$1.NamedExoticComponent<A11yLayerProps>;
 
-interface SketchyBoxKonvaProps {
-    children: React$1.ReactNode;
-    fill: string;
-    stroke: string;
-    backStroke: string;
-    padding?: string;
-}
-declare const SketchyBoxKonva: React$1.FC<SketchyBoxKonvaProps>;
+/** Width of a label in `d`'s idea face (cached per face, size, text and font load). */
+declare function ideaMeasure(d: Pick<Design, 'fontHand' | 'comfort'>): IdeaMeasure;
 
-export { type AnimatorViewport, type ContainerGroup, type INodeStore, type IViewportStore, KonvaContainer, KonvaContainerLayer, KonvaEdge, KonvaEdgeLayer, type KonvaEdgeProps, KonvaLayerTransitionAnimator, KonvaNode, KonvaNodeLayer, type KonvaNodeProps, KonvaStage, type KonvaStageProps, type LayerTransitionHandlers, type NavStackEntry, NavigationStack, SketchyBoxKonva, type TransitionCallbacks, type UseKonvaRendererOptions, type UseKonvaRendererReturn, VisualliCanvas, type VisualliCanvasProps, type VisualliContextValue, VisualliProvider, type VisualliProviderProps, VisualliRenderer, type VisualliRendererProps, type VisualliTheme, ZoomControls, buildBlobPathData, konvaLayerTransitionAnimator, useKonvaLayerTransition, useKonvaRenderer, useNodeStore, useRenderConfigStore, useSelectionStore, useViewportNodes, useViewportStore, useVisualli };
+export { A11yLayer, type AnimatorViewport, type ContainerGroup, DEFAULT_DESIGN, DepthTrail, type DepthTrailProps, type Design, type DesignProps, type DesignSystemAssets, type INodeStore, type IViewportStore, type IdeaPaint, KonvaContainer, KonvaContainerLabelLayer, KonvaContainerLayer, KonvaEdge, KonvaEdgeLayer, type KonvaEdgeProps, KonvaNode, KonvaNodeLayer, type KonvaNodeProps, KonvaStage, type KonvaStageProps, type LayerChoreography, type LayerChoreographyOptions, type NavStackEntry, NavigationStack, PeekCard, type PeekCardProps, type PlacedContainer, type PlacedPill, TermCard, type TrailEntry, type UseKonvaRendererOptions, type UseKonvaRendererReturn, VisualliCanvas, type VisualliCanvasProps, type VisualliContextValue, VisualliProvider, type VisualliProviderProps, VisualliRenderer, type VisualliRendererProps, type VisualliTheme, ZoomControls, drawHull, drawPill, ensureDesignSystemStyles, ideaMeasure, layoutContainers, loadCanvasFonts, makeDesign, measurePill, paintVars, resolveDesign, splitTerms, useDesign, useKonvaRenderer, useLayerChoreography, useNodeStore, useReaderEnv, useRenderConfigStore, useSelectionStore, useViewportNodes, useViewportStore, useVisualli };