You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
<p>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.</p>
29
+
30
+
<h3>Data Flow:</h3>
31
+
<ol>
32
+
<li>When a document is opened or modified, VS Code fires an event that is picked up by the <code>DocumentModel</code>.</li>
33
+
<li>The <code>DocumentModel</code> uses the <code>DocumentParser</code> to create or update the <code>DocumentTree</code>, an immutable, hierarchical representation of the document's text.</li>
34
+
<li>The <code>DocumentModel</code> notifies the <code>DecorationManager</code> of the change.</li>
35
+
<li>The <code>DecorationManager</code>, using debouncing and viewport-aware logic, retrieves the visible <code>BlockNode</code>s from the <code>DocumentTree</code>.</li>
36
+
<li>It passes these nodes to the <code>DecorationCalculator</code>, which determines the appropriate decorations for each node based on its properties (e.g., <code>bulletType</code>).</li>
37
+
<li>The <code>DecorationManager</code> applies these decorations to the active editor, styling the existing text.</li>
38
+
</ol>
39
+
40
+
<h2>Key Design Decisions</h2>
41
+
42
+
<h3>Immutable Document Model</h3>
43
+
<p>The use of an immutable <code>DocumentTree</code> and <code>BlockNode</code>s 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.</p>
44
+
45
+
<h3>Design Philosophy: Insertion vs. Styling</h3>
46
+
<p>A critical distinction in Point Blank's architecture is the separation between one-time character <strong>insertion</strong> and continuous visual <strong>styling</strong>.</p>
47
+
<ul>
48
+
<li><strong>Insertion</strong>: For user convenience, some features will insert text directly into the document. For example, the <code>expandTemplate</code> command writes a new block of text, and the extension can be configured to add a bullet point on a new line.</li>
49
+
<li><strong>Styling</strong>: 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 <strong>only styles what it sees</strong>; it does not use rendering tricks to display characters that aren't physically present in the file.</li>
50
+
</ul>
51
+
<p>This "real character" styling philosophy is the result of a major refactor to improve stability and interoperability. It provides key benefits:</p>
52
+
<ul>
53
+
<li><strong>Robustness & Interoperability</strong>: 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.</li>
54
+
<li><strong>No "Ghost" Characters</strong>: 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.</li>
55
+
</ul>
56
+
57
+
<h3>Separation of Concerns</h3>
58
+
<p>The architecture enforces a strong separation of concerns:</p>
59
+
<ul>
60
+
<li><strong>Parsing (<code>DocumentParser</code>):</strong> Solely responsible for converting text to a <code>DocumentTree</code>.</li>
61
+
<li><strong>State (<code>DocumentModel</code>, <code>ExtensionState</code>):</strong> Manages the state of the document and the extension.</li>
62
+
<li><strong>Rendering (<code>DecorationManager</code>):</strong> Manages the application of decorations to the editor.</li>
63
+
<li><strong>Logic (<code>DecorationCalculator</code>):</strong> Contains the stateless logic for determining which decorations to apply.</li>
64
+
</ul>
65
+
66
+
<h3>Performant Decorations</h3>
67
+
<p>To ensure a smooth user experience, the decoration engine includes two key performance optimizations:</p>
68
+
<ul>
69
+
<li><strong>Debouncing:</strong> Decoration updates are debounced to prevent rapid, flickering updates while the user is typing.</li>
70
+
<li><strong>Viewport-Aware Rendering:</strong> The <code>DecorationManager</code> only processes the visible portion of the document (plus a small buffer), which significantly improves performance in large files.</li>
:root { --background-color:#22272e; /* Dark background */--text-color:#adbac7; /* Light grey text */--primary-color:#80cbc4; /* Light teal for links/accents */--hover-color:#b2dfdb; /* Lighter teal for hover */--secondary-text-color:#808080; /* Blockquote/secondary text */--border-color:#444c56; /* Subtle border for elements */--header-bg:#2d333b; /* Slightly lighter dark for header */--footer-bg:#2d333b; /* Slightly lighter dark for footer */ }
2
+
3
+
body { font-family: -apple-system, BlinkMacSystemFont,"Segoe UI", Helvetica, Arial, sans-serif,"Apple Color Emoji","Segoe UI Emoji"; margin:0; padding:0; background-color:var(--background-color); color:var(--text-color); line-height:1.6; }
navul { padding:0; list-style: none; display: flex; flex-wrap: wrap; /* Allow items to wrap to the next line */justify-content: center; margin-top:1.5em; /* Increased margin to prevent overlap */ }
10
+
11
+
navulli { margin:020px; }
12
+
13
+
main { padding:40px20px; background-color:#2d333b; /* Slightly lighter dark for content area */border-radius:6px; box-shadow:04px12pxrgba(0,0,0,0.3); margin:20px; /* Add margin to main content for smaller screens */ }
0 commit comments