node-editor.slint

// Node Editor Library
//
// This library provides a pure Slint NodeEditor component with a three-layer
// architecture. Computation-heavy operations are delegated to the application
// via callbacks.
//
// Usage:
// ```slint
// import { NodeEditor, Link, Pin, PinTypes } from "node-editor.slint";
//
// MainWindow {
//     NodeEditor {
//         pan-x: 0px;
//         pan-y: 0px;
//         zoom: 1.0;
//
//         // Implement computation callbacks
//         request-grid-update => { /* set grid-commands */ }
//         compute-pin-at(x, y) => { /* return pin ID or 0 */ }
//
//         link-requested(start, end) => { /* validate and create link */ }
//
//         // Add nodes
//         for node in nodes: MyNode { ... }
//
//         // Add links
//         for link in links: Link { path-commands: ...; }
//     }
// }
// ```

// Import building blocks and re-export for users
import {
    PinTypes,
    ViewportState,
    DragState,
    GeometryVersion,
    NodeEditorInternalCallbacks,
    LinkCreationState,
    LinkCreation,
    SelectionRequest,
    HoverState,
    NodeEditorComputations,
    NodeStyleDefaults,
    MinimapNode,
    MinimapPosition,
    LinkData,
    LinkStatus,
    LinkStatusColors,
    Minimap,
    Link,
    BaseNode,
    Pin,
} from "node-editor-building-blocks.slint";
export { PinTypes, ViewportState, DragState, GeometryVersion, NodeEditorInternalCallbacks, LinkCreationState, LinkCreation, SelectionRequest, HoverState, NodeEditorComputations, NodeStyleDefaults, MinimapNode, MinimapPosition, LinkData, LinkStatus, LinkStatusColors, Minimap, Link, BaseNode, Pin }

/// Modifier key for triggering box selection over nodes/links
export enum BoxSelectionModifier {
    /// No modifier - box selection only works on empty areas
    none,
    /// Ctrl key enables box selection anywhere
    ctrl,
    /// Alt key enables box selection anywhere
    alt,
    /// Shift key enables box selection anywhere (note: shift is also used for extend-selection)
    shift,
}

/// Pure Slint node editor composite component.
///
/// Provides:
/// - Layer 1: Grid background with pan/zoom input handling
/// - Layer 2: User children (nodes, links via @children)
/// - Layer 3: Selection box and link preview overlays
///
/// Computation-heavy operations are delegated to the application via callbacks.
///
/// NodeEditor inherits FocusScope so it is the keyboard focus surface.
/// Embedders call `editor.focus()` to focus programmatically; `focus-on-click`
/// activates on click. **No key bindings are defined** — embedders own the
/// keymap by wrapping the editor in a parent FocusScope that handles keys.
/// State like `is-creating-link` and operations like `cancel-link-creation()`
/// are exposed for embedders to bind as needed.
///
/// **Note:** Only one NodeEditor per Window is supported. The library uses Slint
/// globals for internal communication between BaseNode/Pin and NodeEditor.
/// Multiple editors in separate windows work fine. This limitation will be
/// lifted once Slint introduces component-scoped globals.
export component NodeEditor inherits FocusScope {
    // === Accessibility ===
    accessible-role: list;
    accessible-label: "Node Editor";

    // === Shared viewport state ===
    in-out property <length> pan-x: 0px;
    in-out property <length> pan-y: 0px;
    in-out property <float> zoom: 1.0;

    // Sync viewport state to global for child components
    init => {
        ViewportState.zoom = root.zoom;
        ViewportState.pan-x = root.pan-x;
        ViewportState.pan-y = root.pan-y;
    }

    // === World content size ===
    /// Size of the world-content container (nodes and links live here).
    /// Must be large enough to contain all graph content at zoom=1.
    in property <length> world-content-size: 100000px;

    // === Grid properties ===
    in property <length> grid-spacing: 24px;
    in property <bool> grid-snapping: true;
    in property <color> grid-color: #404040;
    in property <brush> background-color: #1a1a1a;

    // === Grid commands (set by application via callback) ===
    in-out property <string> grid-commands;

    // === Edge fade (screen-space overlays between grid and world content) ===
    /// Brush for the left edge fade (e.g. a linear-gradient). Transparent = disabled.
    in property <brush> edge-fade-left: transparent;
    /// Width of the left edge fade rectangle.
    in property <length> edge-fade-left-width: 0px;
    /// Brush for the right edge fade. Transparent = disabled.
    in property <brush> edge-fade-right: transparent;
    /// Width of the right edge fade rectangle.
    in property <length> edge-fade-right-width: 0px;

    // === Zoom constraints ===
    in property <float> min-zoom: 0.1;
    in property <float> max-zoom: 3.0;
    /// Enable pinch-to-zoom gesture (trackpad/touch)
    in property <bool> pinch-zoom-enabled: true;

    // === LOD (Level of Detail) configuration ===
    /// Zoom threshold above which nodes render full detail (all widgets)
    in property <float> lod-full-threshold: 0.5;
    /// Zoom threshold above which nodes render simplified detail (title + pins)
    /// Below this threshold, nodes render minimal detail (colored box + title)
    in property <float> lod-simplified-threshold: 0.25;
    /// Minimum width for nodes at any zoom level
    in property <length> min-node-width: 80px;
    /// Minimum height for nodes at any zoom level
    in property <length> min-node-height: 40px;

    // === Link data (set by application) ===
    /// Logical link data - application provides this
    in property <[LinkData]> links: [];

    // === Selection state ===
    out property <bool> is-selecting: root.internal-is-box-selecting;
    out property <length> selection-x: min(root.box-start-x, root.box-current-x);
    out property <length> selection-y: min(root.box-start-y, root.box-current-y);
    out property <length> selection-width: abs(root.box-current-x - root.box-start-x);
    out property <length> selection-height: abs(root.box-current-y - root.box-start-y);
    in-out property <[int]> selected-node-ids: [];
    in-out property <[int]> selected-link-ids: [];

    // === Link creation state ===
    out property <bool> is-creating-link: root.internal-is-creating-link;
    out property <length> link-start-x: root.internal-link-start-x;
    out property <length> link-start-y: root.internal-link-start-y;
    in-out property <length> link-end-x: root.internal-link-end-x;
    in-out property <length> link-end-y: root.internal-link-end-y;
    out property <int> link-start-pin-id: root.internal-link-start-pin;

    // === Link preview (set by application via callback) ===
    in-out property <string> link-preview-path-commands;

    // === Context menu state ===
    out property <length> context-menu-x;
    out property <length> context-menu-y;

    // === Node drag state ===
    out property <bool> is-dragging: root.internal-is-dragging;
    out property <int> dragged-node-id: root.internal-dragged-node-id;
    out property <length> drag-offset-x: root.internal-drag-offset-x;
    out property <length> drag-offset-y: root.internal-drag-offset-y;

    // === Hovered link ===
    out property <int> hovered-link-id: -1;
    in property <length> link-hover-distance: 8px;

    // === Hovered node ===
    // ID of the node currently under the pointer, or 0 if none. Aggregated from
    // BaseNode via the HoverState global (nodes are consumer-instantiated, so this
    // can't be wired in a library-side delegate the way hovered-link-id is).
    // Note: sentinel is 0 (not -1) — negative node IDs are valid, see BaseNode.
    out property <int> hovered-node-id: HoverState.hovered-node-id;
    callback node-hovered();
    changed hovered-node-id => {
        root.node-hovered();
    }

    // === Minimap configuration ===
    in property <bool> minimap-enabled: false;
    in property <MinimapPosition> minimap-position: MinimapPosition.bottom-right;
    in property <[MinimapNode]> minimap-nodes: [];
    in-out property <length> graph-min-x: 0px;
    in-out property <length> graph-min-y: 0px;
    in-out property <length> graph-max-x: 1600px;
    in-out property <length> graph-max-y: 1200px;
    // Path-based minimap rendering (optimization for large graphs)
    in property <string> minimap-nodes-path: "";
    in property <int> minimap-path-version: 0;
    pure callback compute-minimap-nodes-path(/* version */ int, /* scale */ float, /* offset-x */ float, /* offset-y */ float) -> string;

    // === Pin hit radius ===
    in property <length> pin-hit-radius: 10px;

    // === Bezier curve configuration ===
    /// Minimum control point offset for bezier curves (affects link curvature)
    in property <float> bezier-min-offset: 50.0;
    /// Number of samples for link hit-testing (higher = more precise, slower)
    in property <int> link-hit-samples: 20;

    // === Box selection modifier configuration ===
    /// Allow box selection on click on empty area (no modifier needed)
    in property <bool> box-selection-on-empty: true;
    /// Whether link hit-testing is enabled (set to true if compute-link-at is wired)
    in property <bool> has-link-selection: false;
    /// Modifier key that enables box selection even over links/nodes
    in property <BoxSelectionModifier> box-selection-modifier: BoxSelectionModifier.ctrl;

    // === Internal state ===
    property <bool> internal-is-context-menu-dragging: false;
    property <bool> internal-is-panning: false;
    property <length> pan-start-mouse-x;
    property <length> pan-start-mouse-y;
    property <length> pan-start-offset-x;
    property <length> pan-start-offset-y;

    property <bool> internal-is-box-selecting: false;
    property <length> box-start-x;
    property <length> box-start-y;
    property <length> box-current-x;
    property <length> box-current-y;

    property <bool> internal-is-creating-link: false;
    property <int> internal-link-start-pin: 0;
    property <length> internal-link-start-x;
    property <length> internal-link-start-y;
    property <length> internal-link-end-x;
    property <length> internal-link-end-y;

    property <bool> internal-is-dragging: false;
    property <int> internal-dragged-node-id: 0;
    property <length> internal-drag-offset-x: 0px;
    property <length> internal-drag-offset-y: 0px;
    property <length> internal-drag-origin-x: 0px;
    property <length> internal-drag-origin-y: 0px;

    // === Callbacks TO Application (for computation) ===
    /// Called when grid needs to be regenerated (on pan/zoom/resize)
    callback request-grid-update();

    /// Compute pin at position (world coordinates), returns pin ID or 0
    callback compute-pin-at(/* x */ length, /* y */ length) -> int;

    /// Compute link at position (world coordinates), returns link ID or -1
    callback compute-link-at(/* x */ length, /* y */ length) -> int;

    /// Compute nodes in selection box (world coordinates), returns array of IDs
    callback compute-box-selection(/* x */ length, /* y */ length, /* w */ length, /* h */ length) -> [int];

    /// Compute links in selection box (world coordinates), returns array of IDs
    callback compute-link-box-selection(/* x */ length, /* y */ length, /* w */ length, /* h */ length) -> [int];

    /// Select a link (called on click). Rust handles the selection logic.
    callback select-link(/* link-id */ int, /* shift-held */ bool);

    /// Sync selection IDs to node data (called after box selection)
    callback sync-selection-to-nodes([int]);

    /// Notification callback when node selection changes (for application tracking)
    callback node-selected(/* node-id */ int, /* shift-held */ bool);

    /// Notification callback when selection is cleared (for application tracking)
    callback selection-cleared();

    /// Sync selection IDs to link data (called after box selection)
    callback sync-selection-to-links([int]);

    // === Callbacks TO Application (events) ===
    callback link-requested(/* start-pin */ int, /* end-pin */ int);
    callback link-dropped(/* start-pin */ int, /* world-x */ float, /* world-y */ float);
    callback link-cancelled();
    callback link-hovered();
    callback selection-changed();
    callback context-menu-requested();
    callback context-menu-dragged(/* x */ length, /* y */ length);
    callback context-menu-released(/* x */ length, /* y */ length);
    callback node-double-clicked(/* node-id */ int);
    callback node-drag-started(/* node-id */ int);
    callback node-drag-ended(/* delta-x */ float, /* delta-y */ float);

    /// Node rectangle reporting (for application-side tracking)
    callback node-rect-changed(/* id */ int, /* x */ length, /* y */ length, /* width */ length, /* height */ length);

    /// Pin position reporting (for application-side tracking)
    /// Note: node-id and pin-type are passed explicitly so the library doesn't prescribe any pin ID encoding scheme
    callback pin-position-changed(/* pin-id */ int, /* node-id */ int, /* pin-type */ int, /* rel-x */ length, /* rel-y */ length);

    // === Selection version counter (for dependency tracking) ===
    // This counter is incremented whenever selection changes, allowing bindings
    // that reference it to be re-evaluated when selection changes.
    in-out property <int> selection-version: 0;

    // === Geometry version counter (for link path invalidation) ===
    // Increment this when node/pin positions change to force link path recomputation.
    in-out property <int> geometry-version: 0;

    // === Geometry Reporting Functions ===
    // These functions auto-increment geometry-version before calling the callbacks.
    // Use these instead of calling the callbacks directly.

    /// Report node rectangle change. Auto-increments geometry-version.
    public function report-node-rect(id: int, x: length, y: length, w: length, h: length) {
        GeometryVersion.version += 1;
        root.node-rect-changed(id, x, y, w, h);
    }

    /// Report pin position change. Auto-increments geometry-version.
    public function report-pin-position(pin-id: int, node-id: int, pin-type: int, rel-x: length, rel-y: length) {
        GeometryVersion.version += 1;
        root.pin-position-changed(pin-id, node-id, pin-type, rel-x, rel-y);
    }

    // === Helper Functions ===
    pure public function snap-to-grid(value: float) -> float {
        if (root.grid-spacing > 0px) {
            return round(value / (root.grid-spacing / 1px)) * (root.grid-spacing / 1px);
        }
        return value;
    }

    /// Start link creation from a pin
    public function start-link-from-pin(pin-id: int, x: length, y: length) {
        root.internal-is-creating-link = true;
        root.internal-link-start-pin = pin-id;
        root.internal-link-start-x = x;
        root.internal-link-start-y = y;
        root.internal-link-end-x = x;
        root.internal-link-end-y = y;
        root.link-preview-path-commands = NodeEditorComputations.compute-link-preview-path(
            x / 1px, y / 1px, x / 1px, y / 1px, root.zoom, root.bezier-min-offset);
    }

    /// Update link end position during creation
    public function update-link-end(x: length, y: length) {
        root.internal-link-end-x = x;
        root.internal-link-end-y = y;
        root.link-preview-path-commands = NodeEditorComputations.compute-link-preview-path(
            root.internal-link-start-x / 1px, root.internal-link-start-y / 1px,
            x / 1px, y / 1px, root.zoom, root.bezier-min-offset);
    }

    /// Complete link creation
    public function complete-link-creation() {
        if root.internal-is-creating-link {
            // Call compute-pin-at and request link if valid
            // Note: Convert screen coords to world coords since pin positions are stored in world space
            // world = (screen - pan) / zoom
            root.try-complete-link(NodeEditorComputations.compute-pin-at(
                (root.internal-link-end-x - root.pan-x) / root.zoom / 1px,
                (root.internal-link-end-y - root.pan-y) / root.zoom / 1px,
                root.pin-hit-radius / root.zoom / 1px));
            root.internal-is-creating-link = false;
        }
    }

    /// Internal helper to complete link if end pin is valid
    function try-complete-link(end-pin: int) {
        if end-pin != 0 {
            root.link-requested(root.internal-link-start-pin, end-pin);
        } else {
            root.link-dropped(
                root.internal-link-start-pin,
                (root.internal-link-end-x - root.pan-x) / root.zoom / 1px,
                (root.internal-link-end-y - root.pan-y) / root.zoom / 1px);
        }
    }

    /// Cancel link creation
    public function cancel-link-creation() {
        if root.internal-is-creating-link {
            root.internal-is-creating-link = false;
            root.link-cancelled();
        }
    }

    /// Apply zoom with pan adjustment - takes calculated new zoom and mouse position graph coords
    public function apply-zoom-with-adjustment(new-zoom: float, mouse-x: length, mouse-y: length, graph-x: float, graph-y: float) {
        root.zoom = new-zoom;
        root.pan-x = mouse-x - graph-x * new-zoom * 1px;
        root.pan-y = mouse-y - graph-y * new-zoom * 1px;
    }

    /// Zoom sensitivity for scroll-to-zoom (higher = faster zoom)
    in property <float> scroll-zoom-sensitivity: 0.002;

    /// Handle scroll-to-zoom (Ctrl+scroll or pinch gesture)
    /// delta-y: scroll amount (positive = zoom in, negative = zoom out)
    /// mouse-x, mouse-y: screen coordinates to zoom toward
    function handle-scroll-zoom(delta-y: length, mouse-x: length, mouse-y: length) {
        // Convert scroll delta to zoom factor and apply zoom centered on mouse
        // Calculate graph coordinates under mouse, then apply new zoom
        root.apply-zoom-with-adjustment(
            clamp(root.zoom * (1.0 + (delta-y / 1px) * root.scroll-zoom-sensitivity), root.min-zoom, root.max-zoom),
            mouse-x,
            mouse-y,
            (mouse-x - root.pan-x) / root.zoom / 1px,
            (mouse-y - root.pan-y) / root.zoom / 1px);
    }

    /// Handle link click selection - delegates to Rust via callback
    function handle-link-click(link-id: int, shift-held: bool) {
        root.select-link(link-id, shift-held);
    }

    /// Select a node by ID. If shift-held is false, clears existing selection first.
    /// For shift-select (adding to selection), the application must handle via node-selected callback.
    public function select-node(node-id: int, shift-held: bool) {
        if !shift-held {
            // Simple single-node selection: clear and set to this node
            root.selected-node-ids = [node-id];
            root.selected-link-ids = [];
            NodeEditorComputations.sync-selection-to-nodes(root.selected-node-ids);
            root.sync-selection-to-links([]);
            root.selection-version += 1;
            root.selection-changed();
        }
        // Notify application (for shift-select, app handles adding to selection)
        root.node-selected(node-id, shift-held);
    }

    /// Clear all selection
    public function clear-selection() {
        root.selected-node-ids = [];
        root.selected-link-ids = [];
        NodeEditorComputations.sync-selection-to-nodes([]);
        root.sync-selection-to-links([]);
        root.selection-version += 1;
        root.selection-changed();
        root.selection-cleared();
    }

    /// Start node drag
    public function start-node-drag(node-id: int, already-selected: bool, world-x: length, world-y: length) {
        if !already-selected {
            // Select the node when starting to drag an unselected node
            root.select-node(node-id, false);
        }
        root.internal-is-dragging = true;
        root.internal-dragged-node-id = node-id;
        root.internal-drag-offset-x = 0px;
        root.internal-drag-offset-y = 0px;
        root.internal-drag-origin-x = world-x;
        root.internal-drag-origin-y = world-y;
        root.node-drag-started(node-id);
    }

    /// Update node drag
    public function update-node-drag(offset-x: length, offset-y: length) {
        root.internal-drag-offset-x = offset-x;
        root.internal-drag-offset-y = offset-y;
    }

    /// End node drag
    public function end-node-drag(delta-x: length, delta-y: length) {
        // Call callback FIRST so Rust can update model with correct positions
        // When grid-snapping, snap the final position (origin + delta) to grid,
        // then compute the effective delta. This ensures nodes land on grid
        // intersections regardless of their starting position.
        root.node-drag-ended(
            root.grid-snapping ? root.snap-to-grid((root.internal-drag-origin-x + delta-x) / 1px) - root.internal-drag-origin-x / 1px : delta-x / 1px,
            root.grid-snapping ? root.snap-to-grid((root.internal-drag-origin-y + delta-y) / 1px) - root.internal-drag-origin-y / 1px : delta-y / 1px);

        // THEN reset visual offset (now report-rect will find model already updated)
        root.internal-is-dragging = false;
        root.internal-dragged-node-id = 0;
        root.internal-drag-offset-x = 0px;
        root.internal-drag-offset-y = 0px;
    }

    // === Trigger updates on viewport changes ===
    changed pan-x => {
        ViewportState.pan-x = root.pan-x;
        GeometryVersion.version += 1;
        NodeEditorComputations.viewport-changed(root.zoom, root.pan-x / 1px, root.pan-y / 1px);
    }
    changed pan-y => {
        ViewportState.pan-y = root.pan-y;
        GeometryVersion.version += 1;
        NodeEditorComputations.viewport-changed(root.zoom, root.pan-x / 1px, root.pan-y / 1px);
    }
    changed zoom => {
        ViewportState.zoom = root.zoom;
        GeometryVersion.version += 1;
        NodeEditorComputations.viewport-changed(root.zoom, root.pan-x / 1px, root.pan-y / 1px);
    }
    // DragState is synced by BaseNode directly (it initiates drags)
    changed width => {
        NodeEditorComputations.viewport-changed(root.zoom, root.pan-x / 1px, root.pan-y / 1px);
    }
    changed height => {
        NodeEditorComputations.viewport-changed(root.zoom, root.pan-x / 1px, root.pan-y / 1px);
    }
    
    // Watch LinkCreation global for pin-initiated link creation
    property <int> link-creation-watch: LinkCreation.version;
    changed link-creation-watch => {
        if LinkCreation.state == LinkCreationState.started {
            root.start-link-from-pin(LinkCreation.start-pin-id, LinkCreation.current-x, LinkCreation.current-y);
        } else if LinkCreation.state == LinkCreationState.updating {
            root.update-link-end(LinkCreation.current-x, LinkCreation.current-y);
        } else if LinkCreation.state == LinkCreationState.complete {
            root.complete-link-creation();
            LinkCreation.state = LinkCreationState.idle;
        }
    }
    
    // Watch SelectionRequest global for node-initiated selection
    property <int> selection-request-watch: SelectionRequest.version;
    changed selection-request-watch => {
        root.select-node(SelectionRequest.node-id, SelectionRequest.shift-held);
    }

    /// Call this after initial geometry has been reported to force link path recomputation.
    public function refresh-links() {
        GeometryVersion.version += 1;
        // Also trigger viewport-changed to force a repaint
        NodeEditorComputations.viewport-changed(root.zoom, root.pan-x / 1px, root.pan-y / 1px);
    }

    // === Minimap Positioning ===
    in property <length> minimap-size-width: 180px;
    in property <length> minimap-size-height: 135px;
    in property <length> minimap-margin: 24px;

    pure function compute-minimap-x() -> length {
        if (root.minimap-position == MinimapPosition.top-left || root.minimap-position == MinimapPosition.bottom-left) {
            return root.minimap-margin;
        } else {
            return root.width - root.minimap-size-width - root.minimap-margin;
        }
    }

    pure function compute-minimap-y() -> length {
        if (root.minimap-position == MinimapPosition.top-left || root.minimap-position == MinimapPosition.top-right) {
            return root.minimap-margin;
        } else {
            return root.height - root.minimap-size-height - root.minimap-margin;
        }
    }

    // === Layer 1: Background with grid and input handling ===
    Rectangle {
        width: 100%;
        height: 100%;
        background: root.background-color;
        clip: false;  // Don't clip scaled content

        // Grid
        Path {
            width: 100%;
            height: 100%;
            commands: root.grid-commands;
            stroke: root.grid-color;
            stroke-width: 1px;
            fill: transparent;
            viewbox-x: 0;
            viewbox-y: 0;
            viewbox-width: max(self.width / 1px, 1);
            viewbox-height: max(self.height / 1px, 1);
        }

        // Pinch-to-zoom gesture handler (trackpad/touch)
        // Placed before TouchArea so it captures gesture events first.
        // While active, it grabs input and prevents pan/selection.
        pinch-gesture := ScaleRotateGestureHandler {
            enabled: root.pinch-zoom-enabled;

            property <float> zoom-at-start: 1.0;
            property <float> graph-center-x: 0;
            property <float> graph-center-y: 0;

            started => {
                zoom-at-start = root.zoom;
                graph-center-x = (self.center.x - root.pan-x) / root.zoom / 1px;
                graph-center-y = (self.center.y - root.pan-y) / root.zoom / 1px;
            }

            updated => {
                root.apply-zoom-with-adjustment(
                    clamp(zoom-at-start * self.scale, root.min-zoom, root.max-zoom),
                    self.center.x,
                    self.center.y,
                    graph-center-x,
                    graph-center-y);
            }
        }

        // Background TouchArea - handles pan, zoom, box selection, link clicks
        background-ta := TouchArea {
            width: 100%;
            height: 100%;

            // Cached link hit-test result to avoid redundant compute-link-at calls
            property <int> link-at-cursor: -1;
            // Whether a box-selection modifier key is currently held
            property <bool> modifier-forces-box-select: false;

            scroll-event(event) => {
                // Ctrl (or ⌘ on macOS) + scroll zooms, centered on the mouse — but
                // only for a vertical-only gesture. A trackpad pinch/zoom arrives as
                // an emulated Ctrl+scroll with delta-x ≈ 0, whereas a two-finger pan
                // carries a real horizontal component. So a meaningful delta-x means
                // "pan" regardless of the (possibly stale) Ctrl flag: macOS can swallow
                // the Ctrl key-up on some hotkeys (e.g. Ctrl+Shift+Cmd+4 screenshots),
                // which would otherwise leave the canvas stuck in zoom-only mode.
                if (event.modifiers.control || event.modifiers.meta) && abs(event.delta-x) < 1px {
                    // Ctrl/⌘+scroll: Zoom centered on mouse position
                    // Use delta-y for zoom (positive = zoom in, negative = zoom out)
                    // Scale factor: each "click" of scroll changes zoom by ~10%
                    root.handle-scroll-zoom(event.delta-y, self.mouse-x, self.mouse-y);
                } else {
                    // Normal scroll: Pan
                    root.pan-x += event.delta-x;
                    root.pan-y += event.delta-y;
                }
                accept
            }

            pointer-event(event) => {
                if event.kind == PointerEventKind.down {
                    if event.button == PointerEventButton.middle {
                        // Start pan
                        root.internal-is-panning = true;
                        root.pan-start-mouse-x = self.mouse-x;
                        root.pan-start-mouse-y = self.mouse-y;
                        root.pan-start-offset-x = root.pan-x;
                        root.pan-start-offset-y = root.pan-y;
                    } else if event.button == PointerEventButton.left {
                        // Cache link hit-test once per click
                        link-at-cursor = root.has-link-selection
                            ? root.compute-link-at(
                                (self.mouse-x - root.pan-x) / root.zoom,
                                (self.mouse-y - root.pan-y) / root.zoom)
                            : -1;

                        // Check if box selection should start:
                        // - Modifier key forces box selection even over links
                        // - Empty area allows box selection if box-selection-on-empty is true
                        modifier-forces-box-select =
                            (root.box-selection-modifier == BoxSelectionModifier.ctrl && event.modifiers.control)
                            || (root.box-selection-modifier == BoxSelectionModifier.alt && event.modifiers.alt)
                            || (root.box-selection-modifier == BoxSelectionModifier.shift && event.modifiers.shift);

                        if modifier-forces-box-select || (root.box-selection-on-empty && link-at-cursor < 0) {
                            // Start box selection
                            root.internal-is-box-selecting = true;
                            root.box-start-x = self.mouse-x;
                            root.box-start-y = self.mouse-y;
                            root.box-current-x = self.mouse-x;
                            root.box-current-y = self.mouse-y;
                            // Clear existing selection unless shift held
                            if !event.modifiers.shift {
                                root.selected-link-ids = [];
                                root.clear-selection();
                            }
                        } else if link-at-cursor >= 0 {
                            // Clicked on a link - select it
                            root.select-link(link-at-cursor, event.modifiers.shift);
                        }
                    } else if event.button == PointerEventButton.right {
                        root.context-menu-x = self.mouse-x;
                        root.context-menu-y = self.mouse-y;
                        root.internal-is-context-menu-dragging = true;
                        root.context-menu-requested();
                    }
                }
                if event.kind == PointerEventKind.up {
                    if root.internal-is-context-menu-dragging && event.button == PointerEventButton.right {
                        root.internal-is-context-menu-dragging = false;
                        root.context-menu-released(self.mouse-x, self.mouse-y);
                    }
                    if root.internal-is-panning && event.button == PointerEventButton.middle {
                        root.internal-is-panning = false;
                    }
                    if root.internal-is-box-selecting && event.button == PointerEventButton.left {
                        root.internal-is-box-selecting = false;
                        // Convert selection box from screen to world coordinates for node hit testing
                        // For nodes: world = (screen - pan) / zoom
                        root.selected-node-ids = NodeEditorComputations.compute-box-selection(
                            (root.selection-x - root.pan-x) / root.zoom / 1px,
                            (root.selection-y - root.pan-y) / root.zoom / 1px,
                            root.selection-width / root.zoom / 1px,
                            root.selection-height / root.zoom / 1px);
                        root.selected-link-ids = root.compute-link-box-selection(
                            (root.selection-x - root.pan-x) / root.zoom,
                            (root.selection-y - root.pan-y) / root.zoom,
                            root.selection-width / root.zoom,
                            root.selection-height / root.zoom);
                        NodeEditorComputations.sync-selection-to-nodes(root.selected-node-ids);
                        root.sync-selection-to-links(root.selected-link-ids);
                        root.selection-version += 1;
                        root.selection-changed();
                    }
                    if root.internal-is-creating-link && event.button == PointerEventButton.left {
                        root.complete-link-creation();
                    }
                }
                if event.kind == PointerEventKind.move {
                    if root.internal-is-context-menu-dragging {
                        root.context-menu-dragged(self.mouse-x, self.mouse-y);
                    }
                    // Link hover detection when not doing other interactions
                    if root.has-link-selection && !root.internal-is-panning && !root.internal-is-box-selecting && !root.internal-is-creating-link {
                        root.update-link-hover(root.compute-link-at((self.mouse-x - root.pan-x) / root.zoom, (self.mouse-y - root.pan-y) / root.zoom));
                    }
                }
            }

            moved => {
                if root.internal-is-panning {
                    root.pan-x = root.pan-start-offset-x + (self.mouse-x - root.pan-start-mouse-x);
                    root.pan-y = root.pan-start-offset-y + (self.mouse-y - root.pan-start-mouse-y);
                }
                if root.internal-is-box-selecting {
                    root.box-current-x = self.mouse-x;
                    root.box-current-y = self.mouse-y;
                }
                if root.internal-is-creating-link {
                    root.update-link-end(self.mouse-x, self.mouse-y);
                }
            }
        }
    }

    /// Update link hover state
    public function update-link-hover(new-hovered: int) {
        if new-hovered != root.hovered-link-id {
            root.hovered-link-id = new-hovered;
            root.link-hovered();
        }
    }

    // === Edge fades (screen-space, between grid and world content) ===
    if root.edge-fade-left-width > 0: Rectangle {
        x: 0;
        y: 0;
        width: root.edge-fade-left-width;
        height: root.height;
        background: root.edge-fade-left;
    }
    if root.edge-fade-right-width > 0: Rectangle {
        x: root.width - root.edge-fade-right-width;
        y: 0;
        width: root.edge-fade-right-width;
        height: root.height;
        background: root.edge-fade-right;
    }

    // === Layer 2: World Content (scaled) ===
    // Container positioned at pan offset with transform-scale for zoom.
    // Nodes use pure world coordinates (x: world-x, y: world-y).
    // After transform: screen = pan + world * zoom ✓
    world-content := Rectangle {
        x: root.pan-x;
        y: root.pan-y;
        width: root.world-content-size;
        height: root.world-content-size;
        transform-origin: { x: 0, y: 0 };
        transform-scale: root.zoom;
        background: transparent;
        clip: false;

        // Render links from `links` property
        for link in root.links: Link {
            path-commands: NodeEditorComputations.compute-link-path(link.start-pin-id, link.end-pin-id, GeometryVersion.version);
            link-color: link.status == LinkStatus.running ? LinkStatusColors.running
                      : link.status == LinkStatus.succeeded ? LinkStatusColors.succeeded
                      : link.status == LinkStatus.failed ? LinkStatusColors.failed
                      : link.status == LinkStatus.idle ? LinkStatusColors.idle
                      : link.color;  // status < 0 (LinkStatus.none): use explicit color
            line-width: link.line-width > 0 ? link.line-width * 1px : 2px;
            selected: NodeEditorComputations.is-link-selected(link.id, root.selection-version);
            hovered: root.hovered-link-id == link.id;
        }

        // User-provided children (nodes)
        @children
    }

    // === Layer 3: Overlays ===

    // Selection box
    Rectangle {
        visible: root.is-selecting;
        x: root.selection-x;
        y: root.selection-y;
        width: root.selection-width;
        height: root.selection-height;
        background: #4488ff20;
        border-color: #4488ff;
        border-width: 1px;
    }

    // Link preview
    Path {
        visible: root.is-creating-link;
        width: 100%;
        height: 100%;
        commands: root.link-preview-path-commands;
        stroke: #ffffff80;
        stroke-width: 2px * root.zoom;
        fill: transparent;
        viewbox-x: 0;
        viewbox-y: 0;
        viewbox-width: max(self.width / 1px, 1);
        viewbox-height: max(self.height / 1px, 1);
    }

    // === Minimap ===
    if root.minimap-enabled: Minimap {
        x: root.compute-minimap-x();
        y: root.compute-minimap-y();
        nodes: root.minimap-nodes;
        nodes-path: root.minimap-nodes-path;
        path-version: root.minimap-path-version;
        viewport-x: root.pan-x;
        viewport-y: root.pan-y;
        viewport-zoom: root.zoom;
        viewport-width: root.width;
        viewport-height: root.height;
        graph-min-x: root.graph-min-x;
        graph-min-y: root.graph-min-y;
        graph-max-x: root.graph-max-x;
        graph-max-y: root.graph-max-y;
        minimap-width: root.minimap-size-width;
        minimap-height: root.minimap-size-height;

        compute-nodes-path(version, scale, offset-x, offset-y) => {
            root.compute-minimap-nodes-path(version, scale, offset-x, offset-y)
        }

        navigate-to(graph-x, graph-y) => {
            root.pan-x = -graph-x * root.zoom + (root.width / 2);
            root.pan-y = -graph-y * root.zoom + (root.height / 2);
        }

        update-pan(new-pan-x, new-pan-y) => {
            root.pan-x = new-pan-x;
            root.pan-y = new-pan-y;
        }
    }

}