What Does the Nodeterm Canvas Lock Feature Do?

The nodeterm canvas lock feature disables camera movements (pan and zoom) while preserving full functionality for node-level interactions such as dragging, resizing, and connecting terminals.

The nodeterm canvas lock feature provides viewport stabilization in the eneskirca/nodeterm terminal-based node editor. This functionality prevents accidental canvas navigation during precision layout work while maintaining unrestricted access to individual node operations. Users activate the lock to "stop the map sliding" when arranging complex node configurations without losing editing capabilities.

How the Canvas Lock Works

Core Mechanism

When enabled, the lock creates a viewport freeze by intercepting camera transformation events at the handler level. The implementation distinguishes between canvas-level navigation (affected by the lock) and node-level interactions (unaffected by the lock).

State Management

The lock state persists in src/renderer/state/canvas.ts, which exports the canvasLocked boolean and the toggleCanvasLock action creator. This module integrates with the application's global state store (Redux or Zustand) to provide reactive updates across components.

User Interface Integration

The CanvasLockButton component in src/renderer/components/CanvasControls.tsx renders the toggle control in the bottom-left corner of the canvas. Clicking this button dispatches the toggle action to flip the lock state:

// src/renderer/components/CanvasControls.tsx
<Button
  title="Lock canvas (stop pan/zoom)"
  onClick={() => dispatch(toggleCanvasLock())}
  className={locked ? "locked" : ""}
/>

Event Handling Implementation

Guarding Pan and Zoom Operations

The usePanZoom hook in src/renderer/hooks/usePanZoom.ts contains the primary defense logic. All mouse-wheel and drag handlers check the canvasLocked flag and return early when the lock is active:

// src/renderer/hooks/usePanZoom.ts
function handleWheel(event: WheelEvent) {
  if (canvasLocked) {
    // Camera movement is disabled – ignore the wheel event
    return;
  }
  // Normal pan/zoom logic follows…
}

This early return prevents any viewport transformation while the flag remains true.

Preserving Node Functionality

Node-level event listeners for drag, resize, and edge-creation operations exist in separate handler chains that do not consult the lock flag. This architectural separation ensures that terminal nodes remain fully interactive regardless of the canvas navigation state.

Programmatic Control

Developers can toggle the lock state programmatically by accessing the store directly:

import { store } from "@/renderer/state/store";
import { toggleCanvasLock } from "@/renderer/state/canvas";

store.dispatch(toggleCanvasLock());   // Enable/disable the lock

Configuration and Scope

User Settings

The src/shared/settings.ts file defines the default behavior for the feature, exposing a user-visible option in Settings → Appearance that controls whether new sessions start with the canvas locked.

System Isolation

Because the lock strictly targets camera controls, it does not interfere with other subsystems including the off-screen release of terminals, WebGL budget calculations, or session persistence mechanisms. The feature operates purely client-side without modifying persisted project data.

Summary

• The nodeterm canvas lock feature freezes viewport navigation (pan and zoom) while keeping nodes fully editable.
• State management occurs in src/renderer/state/canvas.ts with the toggleCanvasLock action.
• The usePanZoom hook enforces the lock by returning early from camera transformation handlers.
• Node interactions bypass the lock flag entirely, ensuring unrestricted access to drag, resize, and connect operations.
• Users control the feature via the CanvasLockButton in the bottom-left UI or through Settings → Appearance.

Frequently Asked Questions

What does the nodeterm canvas lock feature do?

The feature disables camera movements including pan and zoom gestures while maintaining full functionality for node-level interactions. When activated, the viewport remains fixed on its current region, preventing accidental navigation during precise layout work.

How do I enable or disable the canvas lock in nodeterm?

Click the CanvasLockButton located in the bottom-left corner of the interface, or dispatch the toggleCanvasLock() action programmatically through the store. You can also set the default behavior in Settings → Appearance via src/shared/settings.ts.

Does the canvas lock prevent me from moving nodes?

No. The lock specifically targets canvas-level camera controls implemented in usePanZoom. Node drag, resize, and edge-creation handlers operate independently and remain fully functional regardless of the lock state.

Where is the canvas lock state stored?

The canvasLocked boolean resides in src/renderer/state/canvas.ts within the application's global state store. This module provides the toggleCanvasLock action and reactive updates that propagate to the UI controls and event handlers.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}