Point Blank Documentation

Architecture Overview

The extension's architecture is designed to be modular, performant, and maintainable, centered around an immutable document model that serves as the single source of truth.

Data Flow:

  1. When a document is opened or modified, VS Code fires an event that is picked up by the DocumentModel.
  2. The DocumentModel uses the DocumentParser to create or update the DocumentTree, an immutable, hierarchical representation of the document's text.
  3. The DocumentModel notifies the DecorationManager of the change.
  4. The DecorationManager, using debouncing and viewport-aware logic, retrieves the visible BlockNodes from the DocumentTree.
  5. It passes these nodes to the DecorationCalculator, which determines the appropriate decorations for each node based on its properties (e.g., bulletType).
  6. The DecorationManager applies these decorations to the active editor, styling the existing text.

Key Design Decisions

Immutable Document Model

The use of an immutable DocumentTree and BlockNodes is a cornerstone of the architecture. When the document changes, a new tree is created rather than modifying the old one. This provides predictability, simplifies state management, and makes the flow of data easy to trace.

Design Philosophy: Insertion vs. Styling

A critical distinction in Point Blank's architecture is the separation between one-time character insertion and continuous visual styling.

  • Insertion: For user convenience, some features will insert text directly into the document. For example, the expandTemplate command writes a new block of text, and the extension can be configured to add a bullet point on a new line.
  • Styling: This is the core of the rendering engine. After a character has been inserted (or typed by the user), it is treated like any other character in the document. The decoration engine only styles what it sees; it does not use rendering tricks to display characters that aren't physically present in the file.

This "real character" styling philosophy is the result of a major refactor to improve stability and interoperability. It provides key benefits:

  • Robustness & Interoperability: Because the document is always the single source of truth for rendering, it remains pure markdown. This prevents conflicts with other VS Code extensions and ensures the file is portable.
  • No "Ghost" Characters: The previous architecture attempted to render visual-only characters, which led to conflicts with the document model and other editor features. The current approach eliminates this entire class of bugs.

Separation of Concerns

The architecture enforces a strong separation of concerns:

  • Parsing (DocumentParser): Solely responsible for converting text to a DocumentTree.
  • State (DocumentModel, ExtensionState): Manages the state of the document and the extension.
  • Rendering (DecorationManager): Manages the application of decorations to the editor.
  • Logic (DecorationCalculator): Contains the stateless logic for determining which decorations to apply.

Performant Decorations

To ensure a smooth user experience, the decoration engine includes two key performance optimizations:

  • Debouncing: Decoration updates are debounced to prevent rapid, flickering updates while the user is typing.
  • Viewport-Aware Rendering: The DecorationManager only processes the visible portion of the document (plus a small buffer), which significantly improves performance in large files.