Adds internal documentation

.vscodeignore

@@ -5,6 +5,7 @@
 **/*.ts
 **/eslint.config.mjs
 **/tsconfig.json
+diagrams/**
 esbuild.mjs
 media/**
 node_modules/**

CONTRIBUTING.md

@@ -0,0 +1,29 @@
+# Contributing
+
+If you'd like to contribute, the best way right now is to open a bug report, suggestion, or question on [Dim GitHub Discussions](https://github.com/ufukty/dim/discussions). PRs and issues aren't being accepted from users at this stage.
+
+## Internals
+
+Dim's code may not be straightforward to follow, as it employs several optimization techniques that scatter and intertwine logic across files.
+
+### Overview
+
+The extension starts with the lifecycle controller. It is responsible for routing user events received from VS Code to the correct units. Units include the compiled user-config cache and individual editor decorators. Events include changes in the config, active and visible editors, and selections.
+
+<picture>
+  <source srcset="./diagrams/structure@2x.png 2x">
+  <img srcset="./diagrams/structure@2x.png 2x">
+</picture>
+
+An editor decorator instance is responsible for a single `TextEditor` instance. It holds the UI state, including the per-document toggle and the ranges decorated at the previous iteration.
+
+### Compiled user-config cache
+
+A Dim user-config may contain many RegExes, so compiled results are cached. The compiled config is sensitive to the scope of `TextEditor`. That's a shallow handle VS Code uses to represent a tab's session. Cache invalidation is triggered by the Extensions API event `onDidChangeConfiguration`.
+
+<picture>
+  <source srcset="./diagrams/config-cache@2x.png 2x">
+  <img srcset="./diagrams/config-cache@2x.png 2x">
+</picture>
+
+Cache keys may shift as VS Code returns different `TextEditor` instances for the same "tab" when the user switches between them.

diagrams/config-cache.mmd

@@ -0,0 +1,12 @@
+ishikawa-beta
+  Recompile user-configuration
+    Raw user-configuration
+      File
+        Editor
+        Workspace
+      Scope
+        Top-level
+        Language-specific
+    Editor scope
+      Document URI
+      Language mode

diagrams/structure.mmd

@@ -0,0 +1,20 @@
+block
+
+columns 3
+
+space:2 ConfigReader
+space:3
+space:2 ConfigCompiler
+space:3
+EditorDecorator space ConfigCache
+space:3
+LifecycleCtrl:3
+space:3
+ExtensionHost:3
+
+ConfigCompiler--"Scope"-->ConfigReader
+ConfigCache--"Scope"-->ConfigCompiler
+LifecycleCtrl--"Invalidate"-->ConfigCache
+LifecycleCtrl--"Event, Command"-->EditorDecorator
+ExtensionHost--"Events, Commands"-->LifecycleCtrl
+EditorDecorator--"Scope"-->ConfigCache

diagrams/watch.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+
+fswatch diagrams/*.mmd | while read -r FILE; do 
+  mmdc -i "$FILE" -o "${FILE/.mmd/@2x.png}" -s 2 -t neutral; 
+done