Read-Only Ranges

Lock specific line ranges while keeping the rest of the document fully editable. Useful for boilerplate headers, licence blocks, generated output sections, or tutorial scaffolding where users should only fill in defined areas.

Basic Usage

Pass a readOnlyRanges array to createEditor(). Indices are 0-based and inclusive on both ends:

read-only-ranges.ts

import { createEditor } from '@synclineapi/editor';
import type { ReadOnlyRange } from '@synclineapi/editor';

const editor = createEditor(container, {
  value: sourceCode,
  readOnlyRanges: [
    { start: 0,  end: 4  },  // lines 1–5 locked (0-based indices, inclusive)
    { start: 8,  end: 15 },  // lines 9–16 locked
  ],
});

ReadOnlyRange Type

ReadOnlyRange.ts

interface ReadOnlyRange {
  /** First locked line, 0-based, inclusive. */
  start: number;
  /** Last locked line, 0-based, inclusive. */
  end: number;
}

Visual Treatment

Element	Appearance
Background	Subtle amber tint (ThemeTokens.roBg) on every locked row.
Left stripe	3 px orange edge indicator on each locked row (ThemeTokens.orange).
Cursor	not-allowed cursor when hovering over locked content.
Insert indicators	Orange divider line + circular + badge at the top and bottom of the block when hovered.

Insert-Line Affordance

When you hover inside a locked block, two insert controls appear — one at the top edge and one at the bottom edge of the block. Each is a full-width orange divider line with a circular + badge on the right. Click either to insert a new blank, editable line immediately above or below the block. The cursor is automatically placed on the new line.

When a single-row block is hovered, both the "insert above" and "insert below" indicators appear simultaneously — one at the top and one at the bottom of the same row.

What Is Blocked

· All edits — typing, paste, delete, backspace, indent, dedent, comment-toggle

· Autocomplete popup and trigger

· Emmet and snippet expansion

· Cursor placement by direct click into the range

· Arrow navigation into the block (Up/Down skip over locked rows)

· Gutter click-to-select on locked lines

What Still Works

· Hover documentation card

· Selection via Shift+Click and keyboard selection shortcuts

· Copy (Ctrl/Cmd+C)

· Find (Ctrl/Cmd+F) and Go-to-line (Ctrl/Cmd+G)

Partial-Selection Delete

When a selection spans both protected and writable rows (e.g. after Ctrl+A then Delete), only the writable portions are deleted — the locked rows survive exactly in place, and the RO range positions are preserved correctly in the undo/redo stack.

Range Shifting

Structural edits (typing, Enter, backspace, Alt+Up/Down) that insert or remove lines inside a writable area automatically shift all downstream protected ranges to keep them anchored to the correct content. The ranges remain accurate through unlimited undo/redo operations and across complex multi-line deletions.

Updating Ranges at Runtime

update-ranges.ts

// Replace the entire set of locked ranges at any time
editor.updateConfig({
  readOnlyRanges: [
    { start: 0, end: 2  },
    { start: 50, end: 60 },
  ],
});

// Unlock everything
editor.updateConfig({ readOnlyRanges: [] });

Ranges use 0-based line indices. If the document content is replaced programmatically via editor.setValue(), the ranges are reset from the current config.readOnlyRanges.

Theme Tokens

Two theme tokens control the visual appearance of locked ranges:

Token	CSS variable	Controls
`roBg`	`--ro-bg`	Background tint of locked rows and insert-button hover highlight.
`orange`	`--orange`	Left-edge stripe colour and insert indicator / badge colour.

ro-theme.ts

import type { ThemeDefinition } from '@synclineapi/editor';

// Override the locked-row background and orange stripe colour
editor.registerTheme({
  ...myTheme,
  tokens: {
    ...myTheme.tokens,
    roBg:   'rgba(255, 165, 0, 0.06)',  // subtle amber tint on locked rows
    orange: '#f59e0b',                   // left stripe and insert-indicator colour
  },
});

Languages

Runtime API

Docs Playground npm