# What Does the Nodeterm Canvas Lock Feature Do?

> Discover how the nodeterm canvas lock feature enhances usability by disabling pan and zoom while keeping node interactions fully functional. Learn more about this valuable tool.

- Repository: [eneskirca/nodeterm](https://github.com/eneskirca/nodeterm)
- Tags: deep-dive
- Published: 2026-08-26

---

**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`](https://github.com/eneskirca/nodeterm/blob/main/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`](https://github.com/eneskirca/nodeterm/blob/main/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:

```tsx
// 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`](https://github.com/eneskirca/nodeterm/blob/main/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:

```tsx
// 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:

```tsx
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`](https://github.com/eneskirca/nodeterm/blob/main/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`](https://github.com/eneskirca/nodeterm/blob/main/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`](https://github.com/eneskirca/nodeterm/blob/main/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`](https://github.com/eneskirca/nodeterm/blob/main/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.