@fraczak/k 6.3.3 → 6.5.0

package/DOCS/PROFILING_AND_TRACING.md

@@ -0,0 +1,196 @@
+# Profiling and Execution Tracing in k
+
+This document describes the performance benchmarking, macro-phase execution tracing,
+and function-level call profiling infrastructure for `k` backends.
+
+The profiling framework allows fine-grained performance analysis of polymorphic `k`
+programs across multiple execution targets:
+- **Linux ARM64** (native standalone ELF executable via direct kVM assembly emission)
+- **WebAssembly** (in-process Wasm module via single-pass kVM lowering)
+- **LLVM** (native specialized executable via KIR-P lowering)
+- **kVM Interpreter** (in-process TypeScript/JavaScript kVM evaluator)
+- **Native JS Baselines** (envelope-aware and envelope-free reference runs)
+
+---
+
+## 1. Motivation: Apples-to-Apples Backend Comparison
+
+When measuring end-to-end request latency across backends, wall-clock time can be
+dominated by factors outside the core relation algorithm:
+- **Process IPC**: Out-of-process native executables (ARM64, LLVM) communicate via stdin/stdout pipes, incurring OS context switches and pipe buffer copies.
+- **Wire Codec**: Decoding and validating the binary wire format (`pattern + value`) and encoding the response.
+- **In-Memory Representation**: WebAssembly converts incoming values into a flat linear memory arena layout.
+- **Pure Evaluation**: The actual relational instruction loop performing the algorithm.
+
+Without detailed accounting, native ARM64 or LLVM binaries communicating over pipes can
+appear slower than in-process WebAssembly or the interpreter simply because of IPC overhead.
+The tracing infrastructure breaks request latency down into nanosecond-level phases so that
+pure execution time can be measured and compared directly.
+
+In addition, **per-function invocation profiling** verifies that every backend performs the
+exact same number of relational evaluations and loop iterations for a given input.
+
+---
+
+## 2. Test Workload: Polymorphic List Operations (`Examples/poly.k`)
+
+The primary benchmark for polymorphic kVM execution is [`Examples/poly.k`](../Examples/poly.k),
+which defines canonical polymorphic operations over recursive lists:
+- `reverse`: Linear reverse using an accumulator.
+- `concat`: Polymorphic list concatenation.
+- `split_by`: Splits a list at index $N$ into `{ first, second }`.
+- `get_nth`: Retrieves the $N$-th element (0-indexed).
+- `length`: Computes list length using arbitrary-precision Peano/bit integers.
+
+### Modular Compilation and Name Isolation
+
+`Examples/poly.k` depends on integer and list operations defined in [`Examples/arithmetics.k`](../Examples/arithmetics.k).
+Following `k`'s canonical content-addressed design:
+- `arithmetics.k` is compiled as a separate library (`--lib`).
+- Only required symbols (`0`, `int`, `inc`, `dec`, `nat`, `zero_int?`, `nil`, `cons`, `car`, `cdr`) are exported into `poly.k`'s scope.
+- Bitstring `concat` in `arithmetics.k` remains strictly private and does not conflict with polymorphic list `concat` in `poly.k`. Each function receives its own unique canonical content hash.
+
+---
+
+## 3. Macro-Phase Execution Tracing (Level 1)
+
+When tracing is enabled, each request is instrumented to measure 7 discrete phases with nanosecond precision:
+
+| Phase | Description | Linux ARM64 | LLVM | WebAssembly | kVM Interp |
+| :--- | :--- | :---: | :---: | :---: | :---: |
+| **1. IPC Read (Pipe In)** | Waiting for and reading input payload from stdin | Yes | Yes | N/A (in-process) | N/A (in-process) |
+| **2. Wire Decode & Validate** | Decoding wire buffer and validating against pattern | Yes | Yes | N/A (in-process) | N/A (in-process) |
+| **3. Flat Input Prep (Arena)** | Flattening decoded structures into linear arena memory | Yes | N/A | Yes | N/A |
+| **4. Pure Evaluation** | Core relational execution loop | **Yes** | **Yes** | **Yes** | **Yes** |
+| **5. Flat Output Prep (Arena)** | Serializing/reading in-memory representations | Yes | N/A | Yes | N/A |
+| **6. Wire Encode** | Encoding result to canonical wire format | Yes | Yes | N/A (in-process) | N/A (in-process) |
+| **7. IPC Write (Pipe Out)** | Writing output wire bytes to stdout pipe | Yes | Yes | Yes (driver) | N/A |
+
+### Phase Timing Output Example
+
+```text
+--- Operation: reverse (len 40) ---
+Phase                    | Linux ARM64   | LLVM          | WebAssembly   | kVM Interp
+-------------------------+---------------+---------------+---------------+---------------
+1. IPC Read (Pipe In)    |    169.83 µs  |    161.42 µs  |       -       |       -     
+2. Wire Decode & Validate |      2.04 µs  |      1.58 µs  |       -       |       -     
+3. Flat Input Prep (Arena) |      3.08 µs  |       -       |     80.88 µs  |       -     
+4. Pure Evaluation       |      0.46 µs  |      0.54 µs  |      1.71 µs  |     26.04 µs
+5. Flat Output Prep (Arena) |      2.67 µs  |       -       |     76.71 µs  |       -     
+6. Wire Encode           |      1.96 µs  |      4.88 µs  |       -       |       -     
+7. IPC Write (Pipe Out)  |     11.29 µs  |     11.08 µs  |      0.62 µs  |       -     
+-------------------------+---------------+---------------+---------------+---------------
+Total Request Time       |    191.33 µs  |    179.50 µs  |    159.92 µs  |     26.04 µs
+```
+
+**Key Takeaways**:
+- **Pure evaluation** in Linux ARM64 native code (`0.46 µs`) is ~3.7× faster than WebAssembly (`1.71 µs`) and ~56× faster than the interpreter (`26.04 µs`).
+- **End-to-end request time** for native binaries is dominated by pipe IPC read (`~160–170 µs`).
+- **WebAssembly overhead** is concentrated in flat arena conversion (`~80 µs` in, `~76 µs` out).
+
+---
+
+## 4. Per-Function Invocation Profiling (Level 2)
+
+Per-function profiling increments dedicated counters at the entry point of every relation
+body and tail-call loop. This proves semantic equivalence across targets by verifying that
+every backend executes the exact same call path.
+
+### Function Profile Output Example
+
+```text
+  Function Call Profile: reverse
+  Function Name            | Linux ARM64 Calls | WebAssembly Calls | kVM Interp Calls
+  -------------------------+-------------------+-------------------+------------------
+  reverse                  |                 - |                 1 |                1
+  _reverse                 |                 - |                41 |               41
+  @dhiaXnh7AYZnewyvbXdh... |                 1 |                 - |                -
+  @EwQ2P3yZ8v4z2qA7kF...   |                41 |                 - |                -
+  car                      |                40 |                40 |               40
+  cdr                      |                40 |                40 |               40
+  cons                     |                40 |                40 |               40
+  nil                      |                 1 |                 1 |                1
+  -------------------------+-------------------+-------------------+------------------
+  Total Calls              |               163 |               163 |              163
+```
+
+*(Note: ARM64 displays canonical content hashes `@hash` for unaliased internal relations.
+All three backends arrive at the exact same total call count: 163 calls for reversing a list of length 40).*
+
+---
+
+## 5. Usage & Commands
+
+### Running Benchmarks
+
+```bash
+# Standard end-to-end benchmark across all 6 lanes
+npm run perf:poly
+
+# Benchmark with macro-phase breakdown tracing and function profiling
+npm run perf:poly:trace
+
+# Or run the script directly:
+node scripts/perf-poly.mjs --trace
+```
+
+### Environment Variables
+
+| Variable | Default | Description |
+| :--- | :---: | :--- |
+| `LIST_LENGTH` | `40` | Number of elements in test lists. |
+| `ITERATIONS` | `3` | Number of iterations for the benchmark summary table. |
+| `TRACE_SAMPLES` | `5` | Repetitions sampled and averaged for phase timings. |
+| `TRACE` | `0` | Set to `1` (or pass `--trace`) to enable phase breakdown. |
+| `PROFILE` | `1` (with trace) | Set to `0` to disable function call counters. |
+| `ARM64_OPT` | `-O2` | Optimization level for the native ARM64 runtime (`-O0`, `-O1`, `-O2`, `-O3`). |
+| `WASM_RESET` | `1` | Reset the WebAssembly linear memory arena between calls (`1` or `0`). |
+| `ARM64_ONLY` | `0` | Run only the Linux ARM64 native target. |
+| `WASM_ONLY` | `0` | Run only the WebAssembly target. |
+| `LLVM_ONLY` | `0` | Run only the LLVM target. |
+| `BACKENDS_ONLY` | `0` | Skip the native JS baseline lanes. |
+
+### Practical Examples
+
+```bash
+# Fast smoke check with list length 10 and 1 iteration:
+ITERATIONS=1 LIST_LENGTH=10 npm run perf:poly:trace
+
+# Measure high-optimization ARM64 (-O3) vs WebAssembly on large lists (100 elements):
+LIST_LENGTH=100 ARM64_OPT=-O3 npm run perf:poly:trace
+
+# Isolate ARM64 native execution:
+ARM64_ONLY=1 npm run perf:poly:trace
+```
+
+---
+
+## 6. Implementation Architecture
+
+### Linux ARM64 Backend
+- **Code Emission** ([`backends/arm64/src/kvm2arm64.mjs`](../backends/arm64/src/kvm2arm64.mjs)): When `options.profile` is active, each function emits counter increment instructions in its entry sequence:
+  ```asm
+      adrp  x9, k_prof_<func>
+      add   x9, x9, :lo12:k_prof_<func>
+      ldr   x10, [x9]
+      add   x10, x10, #1
+      str   x10, [x9]
+  ```
+  Counters are emitted into a dedicated `.data` section, and an exported metadata table `k_profile_entries[]` is generated.
+- **Runtime Reporting** ([`backends/arm64/src/runtime.c`](../backends/arm64/src/runtime.c)):
+  - Nanosecond phase timestamps are sampled via `clock_gettime(CLOCK_MONOTONIC, ...)` and emitted over stderr formatted as:
+    ```text
+    K_TRACE_PHASES backend=arm64 ipc_read_ns=... decode_ns=... flat_in_ns=... eval_ns=... flat_out_ns=... encode_ns=... ipc_write_ns=... total_ns=...
+    ```
+  - `dump_profile_counts()` emits nonzero function call counts between `K_PROFILE_BEGIN` and `K_PROFILE_END` tags.
+
+### WebAssembly Backend
+- **Code Emission** ([`backends/wasm/src/kvm2wasm.mjs`](../backends/wasm/src/kvm2wasm.mjs)): Emits mutable 64-bit Wasm globals:
+  ```wat
+  (global $prof_<name> (export "prof_<name>") (mut i64) (i64.const 0))
+  ```
+  Inside the function/tail-loop body, `(global.set $prof_<name> (i64.add (global.get $prof_<name>) (i64.const 1)))` increments the counter.
+- **Harness Integration** ([`backends/wasm/tests/perf-support.mjs`](../backends/wasm/tests/perf-support.mjs)): `readWasmProfile` and `resetWasmProfile` read and zero the exported globals directly from the Wasm instance exports.
+
+### kVM Interpreter
+- **Evaluation Loop** ([`kvm.mjs`](../kvm.mjs)): When `context.profile` is provided, `executeKVM` resolves the active function name or hash via `context.hashToName` and increments `context.profile[name]`.

package/DOCS/REPL.md

@@ -40,13 +40,17 @@ complete.
 | `:def name = expr` | Alias for `:rel` |
 | `:run expr` | Evaluate `expr` on the current value |
 | `:eval expr` | Alias for `:run` |
+| `:time expr` | Evaluate `expr` and report compilation and execution time |
+| `:timing [on\|off]` | Toggle compilation and execution timing reporting for all evaluations |
 | `:t name` | Show relation input/output filters |
 | `:d name` | Show relation definition |
 | `:C name` | Show canonical code definition |
 | `:codes` | List type aliases |
 | `:rels` | List relation aliases |
-| `:codec load file` | Load an importable REPL codec module |
-| `:codec list` | List loaded REPL codecs |
+| `:codec load name\|file` | Load a built-in codec (`int`, `utf8`, `json`, `ieee`, `unit`) or an ES module file |
+| `:codec define n t b` | Define an inline custom codec: `name type { parse: ..., print: ... }` |
+| `:codec unload name` | Unload a registered codec |
+| `:codec list` | List loaded REPL codecs (alias: `:codecs`) |
 | `:input type [codec]` | Read the next line as codec input for a type |
 | `:load [--no-alias] file` | Load `.k` source or `.klib` into the current state |
 | `:klib file` | Export the active relation closure as a `.klib` library |
@@ -163,9 +167,19 @@ for codec dispatch. A codec may also export `universal = true` to make it
 available for any type selected by `:input`; the parsed value is still validated
 against the requested type before it enters the session.
 
-### `:codec load file`
+For a complete guide to writing a new codec module, see
+[`CODECS.md`](./CODECS.md).
 
-Loads an importable ES module that exports a codec shape:
+### `:codec load name|file`
+
+Loads either a built-in codec by name (`int`, `utf8`, `json`, `ieee`, `unit`) or an ES module file. Loading a built-in codec automatically loads its corresponding `.k` definition file if not already present:
+- `int` auto-loads `Examples/arithmetics.k`
+- `ieee` auto-loads `Examples/ieee.k`
+- `utf8`, `json`, `unit` auto-load `Examples/core.k`
+
+Loading a codec also creates code aliases matching the codec name (e.g. `$ int = @...`, `$ float64 = @...`, `$ utf8 = @...`).
+
+An external codec module exports:
 
 ```js
 export const name = "utf8";
@@ -179,6 +193,19 @@ property-list pattern that can be canonicalized to a code hash, and that hash is
 recalculated by the REPL. A universal codec exports `universal = true` instead
 of `codes` or `patterns`.
 
+### `:codec define name type { parse: ..., print: ... }`
+
+Registers a dynamic custom codec directly from the REPL:
+
+```k
+> :type bool = <{} true, {} false>
+> :codec define yn bool ({ parse: (t) => Value.variant(t.trim() === 'yes' ? 'true' : 'false', Value.product({})), print: (v) => v.tag === 'true' ? 'YES' : 'NO' })
+```
+
+### `:codec unload name`
+
+Unloads a previously registered codec by name.
+
 ### `:input type [codec]`
 
 Resolves `type` to a canonical code hash, selects the registered codec, and
@@ -187,6 +214,36 @@ canonical code hash, or an inline type expression such as
 `<{} true, {} false>`. The parsed value is validated against that type before
 becoming the current value.
 
+## Timing and Profiling
+
+### `:time expr`
+
+Evaluates `expr` and reports the elapsed time broken down into compilation
+(type derivation + WebAssembly lowering/compilation) and runtime execution:
+
+```text
+> :time {10 int x, 5 int y} plus
+{}|_|1|1|1|1|+ ?<{} _, ...>
+/* comp: 12.4ms, exec: 0.8ms */
+```
+
+### `:timing [on|off]`
+
+Toggles automatic timing reporting for every snippet or expression evaluated in
+the session.
+
+## Web REPL (Studio)
+
+The repository provides a standalone, single-file browser REPL: `repl.html`.
+
+- **Zero-install in-browser execution**: Powered by WebAssembly (`wasm-in-process`) and virtual filesystem (VFS).
+- **Interactive UI**: Tab autocompletion, persistent text selection, execution timing badges (`comp: Xms | exec: Yms`), interactive Codecs management modal, and interactive `:input` popup modal.
+- **Build**: Generate `repl.html` locally using:
+  ```bash
+  npm run build:repl-html
+  ```
+- **Live Demo**: Automatically deployed to GitHub Pages via `.github/workflows/pages.yml`.
+
 ## Export
 
 ### `:klib file`

package/DOCS/WEB_REPL_REQUIREMENTS.md

@@ -0,0 +1,135 @@
+# Web REPL Requirements & Architecture Specification
+
+**Branch**: `web-repl`  
+**Status**: Approved Specification  
+**Target Area**: Web REPL UI (`browser/repl-browser.mjs`), Build Pipeline (`scripts/build-repl-html.mjs`), and REPL Engine (`repl.mjs`, `repl-codecs.mjs`)
+
+---
+
+## 1. Context & Objectives
+
+The goal of this initiative is to improve the user experience, robustness, and out-of-the-box readiness of the K Web REPL.
+
+The scope encompasses four primary objectives:
+1. **Console Text Selection**: Ensure all output in the terminal console is smoothly selectable and copyable across all desktop and mobile browsers without focus-stealing interference.
+2. **Prioritize `core.k`**: Make `core.k` the default first choice for loading, examples, dropdowns, and quick exploration.
+3. **Curate VFS Files**: Restrict the bundled Virtual File System (VFS) to verified, useful `.k` files (`core.k`, `Examples/arithmetics.k`, `Examples/ieee.k`, `Examples/poly.k`), auditing and verifying types used by REPL codecs.
+4. **Automatic Dependency Loading & Type Aliasing for Codecs**:
+   - Automatically load the required `.k` source file whenever a codec is loaded, ensuring that necessary type aliases, canonical codes, and operational relations are present before the user attempts `:input` or evaluations.
+   - Establish bidirectional type alias naming so codec names are direct aliases to the underlying type hashes (e.g. `$ieee` and `$float64` both point to `@AR4s...`, `$utf8` and `$string` both point to `@Pt3Mw...`, and `$int` points to `@Nws3v...`).
+
+---
+
+## 2. Detailed Requirements & Architectural Decisions
+
+### Objective 1: Selectable Console Output
+
+#### Current Problem
+- When users highlight and copy output text from `#terminal-output`:
+  1. A global click event listener on `document` listens for clicks to focus `#repl-input`:
+     ```js
+     document.addEventListener("click", (e) => {
+       if (!e.target.closest("button, select, input, textarea, .modal, .quick-link, .btn-copy-entry")) {
+         inputEl.focus();
+       }
+     });
+     ```
+  2. Clicking or releasing a drag selection within `#terminal-output` does not match the excluded selector list.
+  3. Consequently, `inputEl.focus()` is called immediately upon `mouseup`/`click`.
+  4. In modern browsers (Chromium, Firefox, Safari), focusing a text input field collapses the window's text selection, destroying the active selection.
+  5. In addition, double-clicking or triple-clicking a word or line in the terminal is aborted.
+
+#### Requirements
+1. **Selection Preservation**: Users must be able to click, drag-select, double-click, and triple-click any text inside the terminal output without losing selection.
+2. **Clipboard Compatibility**: Standard copy shortcuts (`Ctrl+C`, `Cmd+C`) must copy the selected text, not the input buffer.
+3. **Styling & Presentation**:
+   - Terminal entries (`.terminal-entry`, `.entry-command`, `.entry-line`, `.line-output`, `.line-error`, `.line-warning`, `.system-msg`) must have explicit `user-select: text; -webkit-user-select: text;`.
+   - Prompt decorations (`.entry-prompt`, `.entry-meta`, `.prompt-label`) retain `user-select: none;` to avoid cluttering copied text with prompt symbols (`> `).
+4. **Smart Focus Restoration**:
+   - If `window.getSelection() && !window.getSelection().isCollapsed && window.getSelection().toString().trim().length > 0`, the click handler must **never** steal focus to `#repl-input`.
+   - Clicking directly inside `#terminal-output` on text content should allow text cursor placement and selection without snapping focus away.
+   - Only clicking on empty dead space or background when no text is selected should optionally focus the input.
+
+---
+
+### Objective 2: Prioritize `core.k` as the First Choice
+
+#### Requirements
+1. **Dropdown Ordering**: In `#example-select`, `core.k` must be the top-most option under standard examples.
+2. **Onboarding Banner**: The welcome message and quick-start hints in `browser/repl-browser.mjs` must showcase `:load core.k` as the primary recommended action.
+3. **Quick Expressions**: Ensure the quick expressions section provides expressions compatible with `core.k` out-of-the-box (e.g. `1 succ`, `10`, `$bits`, `$string`).
+
+---
+
+### Objective 3: Verified Useful Files in VFS & Codec Type Audit
+
+#### Curated File Set
+The bundled VFS and UI examples must include only verified useful files:
+- `core.k` — The foundational standard library (bits, arithmetic on bits, Unicode `$unicode`, `$string`, `$pattern`).
+- `Examples/arithmetics.k` — Arbitrary-precision signed integers (`$int`), rationals (`$rat`), GCD/LCM, factorial, Fibonacci.
+- `Examples/ieee.k` — IEEE-754 double-precision floating point type (`$float64`) and arithmetic operations.
+- `Examples/poly.k` — Polymorphic list functions (`concat`, `reverse`, `length`, `get_nth`, `split_by`, `take`, `drop`, `zip`).
+
+#### Dependency Management for `poly.k`
+- `Examples/poly.k` depends on `dec`, `nat`, and `zero_int?` from `Examples/arithmetics.k`.
+- Loading `Examples/poly.k` on a fresh session will automatically ensure `Examples/arithmetics.k` is loaded first if not already loaded in the session.
+
+---
+
+### Objective 4: Auto-Loading `.k` Files on Codec Load & Code Aliasing
+
+#### Requirements
+1. **Codec-to-File Auto-Loading**:
+   When a codec is registered or loaded (via `:codec load <name>`, REPL initialization, or UI action):
+   - Check if the required `.k` file is already loaded in `state.loadedFiles`.
+   - If not loaded, automatically load and evaluate the corresponding `.k` file before completing codec registration:
+     - `int` -> auto-loads `Examples/arithmetics.k`
+     - `utf8` -> auto-loads `core.k`
+     - `json` -> auto-loads `core.k`
+     - `ieee` -> auto-loads `Examples/ieee.k`
+   - Print an informative message, e.g.: `(auto-loaded Examples/arithmetics.k for codec 'int')`.
+
+2. **Bidirectional Code Aliasing**:
+   Establish code aliasing so that codec names and their standard type names are both valid aliases pointing to the same canonical type hash:
+   - **IEEE / Float64**:
+     - Canonical Hash: `@AR4sFGMwXgjj5p7dhi8sJKDWNbrXxLefQUCBRNm5fP6t`
+     - Aliases: `$float64` and `$ieee`
+   - **UTF-8 / String**:
+     - Canonical Hash: `@Pt3MwQwzUPxQKu58zXR3qUBHWTzfycx5bSZGzcK6EZQK`
+     - Aliases: `$string` and `$utf8`
+   - **Int**:
+     - Canonical Hash: `@Nws3vysWqC9PznraTP4kWPp44Rd77NAqrx9dgbtHAjGA`
+     - Alias: `$int`
+   This guarantees that both `:input utf8` and `:input string`, as well as `:input ieee` and `:input float64`, work seamlessly.
+
+3. **Idempotence**:
+   - `state.loadedFiles = new Set()` tracks loaded file paths (normalized).
+   - Re-running `:codec load` or loading multiple codecs referencing the same file (`utf8` and `json` both referencing `core.k`) will not recompile or reload the file redundantly.
+
+---
+
+### Phase 2: Curated VFS, Browser Buffer & Selection Persistence
+
+#### 1. Curated Files Explorer
+In the Web REPL "Files" (VFS) explorer, the visible files are strictly curated to verified examples and codecs:
+- **k-codes**: `core.k`, `arithmetics.k`, `ieee.k`
+- **codecs**: `json.mjs`, `utf8.mjs`, `int.mjs`, `unit.mjs`, `ieee.mjs`
+- User-created or uploaded files remain visible.
+- Internal runtime artifacts (`backends/wasm/runtime.wat`) and redundant directory prefixes (`Examples/`, `codecs/`) are kept accessible internally but hidden from the default file listing.
+- Clicking "Load" on a `.mjs` file automatically executes `:codec load <filename>`.
+
+#### 2. Browser Buffer 64-bit Float & Int Methods
+`browser/shims/buffer.mjs` implements:
+- `writeDoubleBE`, `readDoubleBE`, `writeDoubleLE`, `readDoubleLE`
+- `writeFloatBE`, `readFloatBE`, `writeFloatLE`, `readFloatLE`
+- `writeBigUInt64BE`, `readBigUInt64BE`, `writeBigUInt64LE`, `readBigUInt64LE`
+- `writeBigInt64BE`, `readBigInt64BE`, `writeBigInt64LE`, `readBigInt64LE`
+- Complete integer read/write methods (`UInt32`, `Int32`, `UInt16`, `Int16`, `UInt8`, `Int8`).
+- `globalThis.Buffer = Buffer` set unconditionally in the browser environment.
+This fixes `:input {string a, float64 n}` number parsing in JSON and IEEE codecs in browser runtime.
+
+#### 3. Persistent Console Selection
+- Replaced the global document click focus-stealer with:
+  - Click listener on `.terminal-input-bar` (clicking prompt line focuses input).
+  - Keydown typing handler on `window` (typing printable characters outside modals/inputs focuses input).
+- Mouse selection in `.terminal-output` never collapses on click/mouseup.

package/DOCS/dependency-graph.md

@@ -0,0 +1,144 @@
+# Project Dependency Graph
+
+_Auto-generated by scripts/generate-dependency-graph.mjs._
+
+```mermaid
+graph TD
+    classDef default fill:#fff,stroke:#333,stroke-width:2px,color:#000;
+
+    Graph_mjs["Graph.mjs (1.9 KB)<br/>██"]
+    TypeGraph_mjs["TypeGraph.mjs (1.1 KB)<br/>█"]
+    TypePatternGraph_mjs["TypePatternGraph.mjs (8.0 KB)<br/>████████"]
+    Value_mjs["Value.mjs (5.4 KB)<br/>█████"]
+    augmentation_mjs["augmentation.mjs (6.9 KB)<br/>███████"]
+    codecs_example_pipeline_mjs["codecs/example-pipeline.mjs (5.1 KB)<br/>█████"]
+    codecs_ieee_mjs["codecs/ieee.mjs (4.3 KB)<br/>████"]
+    codecs_int_mjs["codecs/int.mjs (3.5 KB)<br/>████"]
+    codecs_json_codec_mjs["codecs/json-codec.mjs (6.2 KB)<br/>██████"]
+    codecs_json_mjs["codecs/json.mjs (1.5 KB)<br/>██"]
+    codecs_k_parse_mjs["codecs/k-parse.mjs (3.0 KB)<br/>███"]
+    codecs_k_print_mjs["codecs/k-print.mjs (1.5 KB)<br/>██"]
+    codecs_runtime_codec_mjs["codecs/runtime/codec.mjs (25.7 KB)<br/>████████████████████"]
+    codecs_runtime_ieee_pattern_mjs["codecs/runtime/ieee-pattern.mjs (1.1 KB)<br/>█"]
+    codecs_runtime_pattern_json_mjs["codecs/runtime/pattern-json.mjs (3.5 KB)<br/>███"]
+    codecs_runtime_prefix_codec_mjs["codecs/runtime/prefix-codec.mjs (13.7 KB)<br/>██████████████"]
+    codecs_runtime_show_value_mjs["codecs/runtime/show-value.mjs (2.1 KB)<br/>██"]
+    codecs_runtime_test_codec_mjs["codecs/runtime/test-codec.mjs (3.0 KB)<br/>███"]
+    codecs_runtime_typeFromValue_mjs["codecs/runtime/typeFromValue.mjs (0.9 KB)<br/>█"]
+    codecs_runtime_unicode_string_mjs["codecs/runtime/unicode-string.mjs (7.5 KB)<br/>████████"]
+    codecs_show_mjs["codecs/show.mjs (1.5 KB)<br/>██"]
+    codecs_string_codec_mjs["codecs/string-codec.mjs (4.5 KB)<br/>█████"]
+    codecs_unit_mjs["codecs/unit.mjs (1.6 KB)<br/>██"]
+    codecs_utf16_mjs["codecs/utf16.mjs (2.2 KB)<br/>██"]
+    codecs_utf8_mjs["codecs/utf8.mjs (1.3 KB)<br/>█"]
+    codes_mjs["codes.mjs (9.9 KB)<br/>██████████"]
+    compiler_mjs["compiler.mjs (3.9 KB)<br/>████"]
+    convergence_mjs["convergence.mjs (6.5 KB)<br/>██████"]
+    export_mjs["export.mjs (5.2 KB)<br/>█████"]
+    hash_mjs["hash.mjs (1.1 KB)<br/>█"]
+    index_mjs["index.mjs (1.9 KB)<br/>██"]
+    k_mjs["k.mjs (2.7 KB)<br/>███"]
+    object_mjs["object.mjs (26.3 KB)<br/>████████████████████"]
+    pretty_mjs["pretty.mjs (5.6 KB)<br/>██████"]
+    repl_mjs["repl.mjs (29.3 KB)<br/>████████████████████"]
+    run_mjs["run.mjs (14.4 KB)<br/>██████████████"]
+    symbol_table_mjs["symbol-table.mjs (2.7 KB)<br/>███"]
+    typing_mjs["typing.mjs (4.9 KB)<br/>█████"]
+    unification_mjs["unification.mjs (5.4 KB)<br/>█████"]
+    valueIO_mjs["valueIO.mjs (1.8 KB)<br/>██"]
+
+    TypePatternGraph_mjs --> Graph_mjs
+    TypePatternGraph_mjs --> unification_mjs
+    TypePatternGraph_mjs --> TypeGraph_mjs
+    augmentation_mjs --> codes_mjs
+    codecs_example_pipeline_mjs --> codecs_runtime_codec_mjs
+    codecs_example_pipeline_mjs --> codecs_runtime_prefix_codec_mjs
+    codecs_example_pipeline_mjs --> codecs_runtime_pattern_json_mjs
+    codecs_example_pipeline_mjs --> Value_mjs
+    codecs_example_pipeline_mjs --> hash_mjs
+    codecs_ieee_mjs --> Value_mjs
+    codecs_ieee_mjs --> codecs_runtime_prefix_codec_mjs
+    codecs_ieee_mjs --> codecs_runtime_ieee_pattern_mjs
+    codecs_int_mjs --> Value_mjs
+    codecs_int_mjs --> codecs_runtime_prefix_codec_mjs
+    codecs_json_codec_mjs --> Value_mjs
+    codecs_json_codec_mjs --> codecs_string_codec_mjs
+    codecs_json_codec_mjs --> codecs_runtime_ieee_pattern_mjs
+    codecs_json_mjs --> codecs_runtime_prefix_codec_mjs
+    codecs_json_mjs --> codecs_json_codec_mjs
+    codecs_k_parse_mjs --> index_mjs
+    codecs_k_parse_mjs --> valueIO_mjs
+    codecs_k_parse_mjs --> codecs_runtime_codec_mjs
+    codecs_k_parse_mjs --> codecs_runtime_pattern_json_mjs
+    codecs_k_parse_mjs --> codecs_runtime_prefix_codec_mjs
+    codecs_k_print_mjs --> codecs_runtime_prefix_codec_mjs
+    codecs_runtime_codec_mjs --> Value_mjs
+    codecs_runtime_codec_mjs --> TypePatternGraph_mjs
+    codecs_runtime_codec_mjs --> typing_mjs
+    codecs_runtime_codec_mjs --> codes_mjs
+    codecs_runtime_codec_mjs --> codecs_runtime_pattern_json_mjs
+    codecs_runtime_ieee_pattern_mjs --> codes_mjs
+    codecs_runtime_ieee_pattern_mjs --> codecs_runtime_codec_mjs
+    codecs_runtime_ieee_pattern_mjs --> codecs_runtime_pattern_json_mjs
+    codecs_runtime_prefix_codec_mjs --> Value_mjs
+    codecs_runtime_prefix_codec_mjs --> codecs_runtime_codec_mjs
+    codecs_runtime_prefix_codec_mjs --> codecs_runtime_pattern_json_mjs
+    codecs_runtime_prefix_codec_mjs --> codecs_runtime_unicode_string_mjs
+    codecs_runtime_show_value_mjs --> Value_mjs
+    codecs_runtime_test_codec_mjs --> codecs_runtime_codec_mjs
+    codecs_runtime_test_codec_mjs --> codecs_runtime_prefix_codec_mjs
+    codecs_runtime_test_codec_mjs --> codecs_runtime_pattern_json_mjs
+    codecs_runtime_test_codec_mjs --> Value_mjs
+    codecs_runtime_test_codec_mjs --> hash_mjs
+    codecs_runtime_typeFromValue_mjs --> Value_mjs
+    codecs_runtime_unicode_string_mjs --> Value_mjs
+    codecs_show_mjs --> codecs_runtime_prefix_codec_mjs
+    codecs_show_mjs --> codecs_runtime_show_value_mjs
+    codecs_string_codec_mjs --> codecs_runtime_codec_mjs
+    codecs_string_codec_mjs --> codecs_runtime_prefix_codec_mjs
+    codecs_string_codec_mjs --> codecs_runtime_pattern_json_mjs
+    codecs_string_codec_mjs --> codecs_runtime_unicode_string_mjs
+    codecs_unit_mjs --> Value_mjs
+    codecs_unit_mjs --> codecs_runtime_prefix_codec_mjs
+    codecs_utf16_mjs --> codecs_string_codec_mjs
+    codecs_utf8_mjs --> codecs_string_codec_mjs
+    codes_mjs --> hash_mjs
+    compiler_mjs --> hash_mjs
+    compiler_mjs --> TypePatternGraph_mjs
+    compiler_mjs --> Graph_mjs
+    compiler_mjs --> codes_mjs
+    compiler_mjs --> augmentation_mjs
+    compiler_mjs --> export_mjs
+    compiler_mjs --> convergence_mjs
+    convergence_mjs --> pretty_mjs
+    convergence_mjs --> typing_mjs
+    export_mjs --> hash_mjs
+    export_mjs --> pretty_mjs
+    index_mjs --> Value_mjs
+    index_mjs --> valueIO_mjs
+    index_mjs --> compiler_mjs
+    index_mjs --> run_mjs
+    index_mjs --> codes_mjs
+    k_mjs --> index_mjs
+    k_mjs --> codecs_runtime_prefix_codec_mjs
+    k_mjs --> object_mjs
+    object_mjs --> index_mjs
+    object_mjs --> run_mjs
+    object_mjs --> codes_mjs
+    object_mjs --> TypePatternGraph_mjs
+    object_mjs --> pretty_mjs
+    pretty_mjs --> TypePatternGraph_mjs
+    repl_mjs --> index_mjs
+    repl_mjs --> run_mjs
+    repl_mjs --> codes_mjs
+    repl_mjs --> Value_mjs
+    repl_mjs --> pretty_mjs
+    repl_mjs --> object_mjs
+    repl_mjs --> codecs_runtime_show_value_mjs
+    run_mjs --> Value_mjs
+    run_mjs --> codecs_runtime_codec_mjs
+    run_mjs --> codecs_runtime_pattern_json_mjs
+    symbol_table_mjs --> hash_mjs
+    typing_mjs --> TypePatternGraph_mjs
+    valueIO_mjs --> Value_mjs
+```