JSVision

Appearance

@jsvision/code-editor / CodeEditorController

Class: CodeEditorController ​

Defined in: code-editor/src/controller.ts:134

Owns public editor state and funnels every source mutation through document transactions.

Example ​

ts
const controller = new CodeEditorController({ document });

Constructors ​

Constructor ​

new CodeEditorController(options): CodeEditorController

Defined in: code-editor/src/controller.ts:174

Parameters ​

options ​

CreateCodeEditorControllerOptions

Returns ​

CodeEditorController

Properties ​

degradation ​

readonly degradation: CodeEditorDegradationState

Defined in: code-editor/src/controller.ts:137

document ​

readonly document: CodeEditorDocumentModel

Defined in: code-editor/src/controller.ts:135

limits ​

readonly limits: CodeEditorLimits

Defined in: code-editor/src/controller.ts:136

observations ​

readonly observations: CodeEditorObservabilityChannel

Defined in: code-editor/src/controller.ts:138

Accessors ​

diagnostics ​

Get Signature ​

get diagnostics(): readonly object[]

Defined in: code-editor/src/controller.ts:450

Maps sanitized LSP diagnostics into document-offset presentation spans.

Returns ​

readonly object[]

foldableRegions ​

Get Signature ​

get foldableRegions(): readonly object[]

Defined in: code-editor/src/controller.ts:340

Current validated multi-line structural regions, expressed as inclusive logical lines.

Returns ​

readonly object[]

folds ​

Get Signature ​

get folds(): readonly object[]

Defined in: code-editor/src/controller.ts:350

Current collapsed structural regions.

Stale language results never hide source: when the document revision advances, this getter returns an empty list until matching fresh analysis is installed.

Returns ​

readonly object[]

Set Signature ​

set folds(regions): void

Defined in: code-editor/src/controller.ts:361

Compatibility assignment for the original writable fold collection.

Only ranges that exactly match current parser-validated structures are accepted. New code should use the explicit fold commands so selection relocation and intent remain clear.

Parameters ​
regions ​

readonly object[]

Returns ​

void

languageResult ​

Get Signature ​

get languageResult(): LocalLanguageResult | undefined

Defined in: code-editor/src/controller.ts:329

Current validated local syntax/structure result, if available.

Returns ​

LocalLanguageResult | undefined

metrics ​

Get Signature ​

get metrics(): CodeEditorControllerMetrics

Defined in: code-editor/src/controller.ts:234

Returns a current immutable observability snapshot.

Returns ​

CodeEditorControllerMetrics

presentation ​

Get Signature ​

get presentation(): CodeEditorControllerPresentation

Defined in: code-editor/src/controller.ts:243

Returns the immutable assistance and service snapshot consumed by terminal views.

Returns ​

CodeEditorControllerPresentation

publicState ​

Get Signature ​

get publicState(): CodeEditorControllerPublicState

Defined in: code-editor/src/controller.ts:280

Returns current content-free state for status and accessibility adapters.

Returns ​

CodeEditorControllerPublicState

retainedState ​

Get Signature ​

get retainedState(): object

Defined in: code-editor/src/controller.ts:307

Returns content-free counters for controller-owned retained resources.

Returns ​

object

completions ​

readonly completions: number

diagnostics ​

readonly diagnostics: number

folds ​

readonly folds: number

historyBytes ​

readonly historyBytes: number

requests ​

readonly requests: number

symbols ​

readonly symbols: number

telemetryEvents ​

readonly telemetryEvents: number

snippets ​

Get Signature ​

get snippets(): readonly object[]

Defined in: code-editor/src/controller.ts:471

Maps current snippet placeholders into document-offset presentation spans.

Returns ​

readonly object[]

Methods ​

applyDocumentEdits() ​

applyDocumentEdits(edits, selection): boolean

Defined in: code-editor/src/controller.ts:566

Applies a validated editor transaction while recording which collapsed structures it touches.

This shared mutation boundary lets fresh parser analysis preserve a fold after one unrelated edit while conservatively expanding touched or ambiguously shifted structures.

Parameters ​

edits ​

readonly DocumentEditInput[]

Replacement list to apply as one typing transaction.

selection ​

DocumentSelectionInput

Selection installed after successful application.

Returns ​

boolean

true only when the complete transaction is accepted.

applyMutation() ​

applyMutation(input): DocumentMutationResult

Defined in: code-editor/src/controller.ts:509

Applies one origin-aware transaction and publishes exactly one accepted document event.

Rejected, stale, overlapping, read-only, and over-limit requests remain semantically inert and do not notify parsers, protocol synchronization, or terminal views.

Parameters ​

input ​

CodeEditorMutationInput

Untrusted mutation request to snapshot, validate, and apply atomically.

Returns ​

DocumentMutationResult

The accepted result or a typed reason for an inert rejection.

Example ​

ts
controller.applyMutation({
  edits: [{ range: { from: 0, to: 0 }, text: 'const ' }],
  origin: 'external',
});

caretChanged() ​

caretChanged(): void

Defined in: code-editor/src/controller.ts:813

Dismisses caret-context overlays after a local selection or caret change.

Returns ​

void

Example ​

ts
document.setSelection({ anchor: 4, head: 4 });
controller.caretChanged();

dismissAssistance() ​

dismissAssistance(): void

Defined in: code-editor/src/controller.ts:724

Dismisses completion and other transient assistance without changing the document.

Returns ​

void

dispose() ​

dispose(): void

Defined in: code-editor/src/controller.ts:1183

Releases controller-owned presentation, callback, and protocol resources.

Returns ​

void

fold() ​

fold(): void

Defined in: code-editor/src/controller.ts:871

Collapses the structural region starting at the active line, when one exists.

Returns ​

void

foldAll() ​

foldAll(): void

Defined in: code-editor/src/controller.ts:885

Collapses every currently validated structural region.

Returns ​

void

foldLine() ​

foldLine(line): void

Defined in: code-editor/src/controller.ts:908

Collapses a validated structural region by its logical header line.

Parameters ​

line ​

number

Returns ​

void

hostAction() ​

hostAction(kind): Promise<boolean>

Defined in: code-editor/src/controller.ts:571

Sends a bounded, typed editor action to the embedding host.

Parameters ​

kind ​

"save" | "close" | "navigate"

Returns ​

Promise<boolean>

navigateBack(): boolean

Defined in: code-editor/src/controller.ts:863

Returns to the latest bounded same-document navigation origin.

Returns ​

boolean

true when a previous location was restored.

Example ​

ts
if (controller.navigateBack()) {
  // The document caret now points at the previous local location.
}

navigateDiagnostic(direction): boolean

Defined in: code-editor/src/controller.ts:832

Moves to the next or previous diagnostic and opens its sanitized detail row.

Parameters ​

direction ​

-1 | 1

1 selects the next diagnostic; -1 selects the previous one.

Returns ​

boolean

true when a diagnostic was available.

Example ​

ts
controller.navigateDiagnostic(1);

openCompletion() ​

openCompletion(items): boolean

Defined in: code-editor/src/controller.ts:703

Opens one bounded manual completion list in the controller-owned assistance model.

Parameters ​

items ​

readonly CodeEditorCompletionItem[]

Host candidates to sanitize, detach, and retain within configured limits.

Returns ​

boolean

true when the list is safe, including a safe empty list.

Example ​

ts
controller.openCompletion([{ label: 'console', insertText: 'console' }]);

replaceSelection() ​

replaceSelection(text): boolean

Defined in: code-editor/src/controller.ts:482

Applies one text replacement at the current selection.

Parameters ​

text ​

string

Returns ​

boolean

requestAssistance() ​

requestAssistance(): void

Defined in: code-editor/src/controller.ts:613

Requests completion through the optional document-scoped LSP coordinator.

Returns ​

void

requestClose() ​

requestClose(): Promise<boolean>

Defined in: code-editor/src/controller.ts:601

Requests host confirmation to close the current clean or modified document.

Returns ​

Promise<boolean>

requestDefinition() ​

requestDefinition(): boolean

Defined in: code-editor/src/controller.ts:685

Requests definition navigation at the current caret.

Returns ​

boolean

true when a language-service request was issued.

Example ​

ts
if (!controller.requestDefinition()) await controller.hostAction('navigate');

requestDocumentSymbols() ​

requestDocumentSymbols(): void

Defined in: code-editor/src/controller.ts:669

Requests a bounded document-symbol chooser through the optional language service.

Returns ​

void

Example ​

ts
controller.requestDocumentSymbols();

requestFormatting() ​

requestFormatting(): void

Defined in: code-editor/src/controller.ts:786

Requests range formatting for a selection, or whole-document formatting without one.

Read-only documents and unavailable coordinators are left unchanged.

Returns ​

void

Example ​

ts
controller.requestFormatting();

requestHover() ​

requestHover(): void

Defined in: code-editor/src/controller.ts:652

Requests hover information for the current caret through the optional language service.

Returns ​

void

Example ​

ts
controller.requestHover();

resolveExternalChange() ​

resolveExternalChange(input): Promise<CodeEditorExternalChangeResult>

Defined in: code-editor/src/controller.ts:607

Resolves an already-detected external change using one explicit host decision.

Parameters ​

input ​

CodeEditorExternalChangeInput

Returns ​

Promise<CodeEditorExternalChangeResult>

revealOffset() ​

revealOffset(offset): boolean

Defined in: code-editor/src/controller.ts:939

Expands a collapsed structure when an editor action targets one of its hidden lines.

Parameters ​

offset ​

number

Returns ​

boolean

true when a fold was expanded.

routeAssistanceKey() ​

routeAssistanceKey(key): "completion" | "snippet" | "editor" | "unhandled" | "dismissal"

Defined in: code-editor/src/controller.ts:745

Routes assistance navigation before editor commands and text insertion.

Manual and protocol completion share selection, acceptance, dismissal, and stale-revision behavior even though the coordinator retains protocol-specific edit validation.

Parameters ​

key ​

Canonical terminal key routed by the active editor.

key ​

string

shift? ​

boolean

text? ​

string

Returns ​

"completion" | "snippet" | "editor" | "unhandled" | "dismissal"

The interaction owner that consumed the key, or unhandled.

save() ​

save(): Promise<boolean>

Defined in: code-editor/src/controller.ts:595

Saves one exact current revision through the host-owned persistence boundary.

Returns ​

Promise<boolean>

setLanguageResult() ​

setLanguageResult(result): void

Defined in: code-editor/src/controller.ts:391

Replaces local presentation data only when it matches the active document identity.

Fold ranges are treated as hostile adapter output even though the TypeScript contract is typed. Invalid, crossing, duplicate, single-line, and over-limit ranges are removed before any presentation consumer can hide source.

Parameters ​

result ​

LocalLanguageResult | undefined

Returns ​

void

subscribe() ​

subscribe(listener): CodeEditorDisposable

Defined in: code-editor/src/controller.ts:265

Subscribes to coalesced presentation and accepted-document changes.

Notifications normally run in a microtask. Accepted mutations retain their order, while a presentation update in the same logical operation is folded into the final mutation event. A hostile synchronous burst is drained at a fixed ceiling instead of growing without bound.

Parameters ​

listener ​

(event) => void

Callback invoked for each accepted mutation and coalesced presentation update.

Returns ​

CodeEditorDisposable

An idempotent handle that stops future callbacks.

Throws ​

When the bounded listener capacity has been reached.

Example ​

ts
const subscription = controller.subscribe(() => render());
subscription.dispose();

toggleFold() ​

toggleFold(): void

Defined in: code-editor/src/controller.ts:901

Toggles the structural region at the active line.

Returns ​

void

toggleFoldLine() ​

toggleFoldLine(line): void

Defined in: code-editor/src/controller.ts:927

Toggles a structural region by its logical header line.

Parameters ​

line ​

number

Returns ​

void

triggerAssistance() ​

triggerAssistance(character): void

Defined in: code-editor/src/controller.ts:635

Requests completion or signature help after one accepted trigger-character insertion.

Call this only after the document has accepted the typed character. The coordinator orders the request behind the corresponding document synchronization.

Parameters ​

character ​

string

The single inserted character to compare with negotiated trigger sets.

Returns ​

void

Example ​

ts
if (editor.insertText('.')) controller.triggerAssistance('.');

unfold() ​

unfold(): void

Defined in: code-editor/src/controller.ts:878

Expands the collapsed structural region starting at the active line.

Returns ​

void

unfoldAll() ​

unfoldAll(): void

Defined in: code-editor/src/controller.ts:893

Expands every collapsed structural region.

Returns ​

void

unfoldLine() ​

unfoldLine(line): void

Defined in: code-editor/src/controller.ts:917

Expands a collapsed structural region by its logical header line.

Parameters ​

line ​

number

Returns ​

void