1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
//! LINEWORK — the drawn marks of an illustration, and here they are
//! keyed by line. The engine-neutral protocol for binding language
//! intelligence to an editor: line-keyed, two-wave code PAINT plus
//! on-demand FACTS, with a trait ([`Limner`]) an editor widget can be
//! generic over.
//!
//! This crate has NO dependencies and knows nothing about any
//! particular engine or editor. An intelligence engine (a parser
//! toolchain, a language runtime) implements [`Limner`]; an editor
//! consumes it. Neither needs the other's types.
//!
//! # The shape
//!
//! * Paint is LINE-KEYED: each line is a vector of [`Run`]s — 4-byte
//! cells `{len, style, mods}` tiling the line's bytes exactly. Runs
//! are line-relative, so a line that merely SHIFTS re-emits
//! nothing.
//! * Paint is TWO-WAVE: `style` is the lexical class (wave 0 —
//! available synchronously with a keystroke, from the damaged lines
//! only), and `mods` carries semantic bits (wave 1 — definition,
//! resolved/unresolved reference, public, foreign, typed) that
//! ARRIVE WITHOUT EVER CHANGING A STYLE. Refinement is additive, so
//! the first frame is already right and nothing flickers.
//! * A [`PaintDelta`] names what one edit changed and nothing else: a
//! spliced window of lines, plus semantic-only repaints by line
//! number. The repaint set is the edit's semantic blast radius,
//! made visible.
//! * [`FactCard`]s answer "what IS this name" — definition site,
//! problem, display type, namespace — and [`Hint`]s carry inline
//! decorations. Both are lookups against warm state, not requests.
//!
//! Offsets and lengths are BYTES of UTF-8 text. Consumers that index
//! by character (ropes) convert at the boundary.
//!
//! The wire form is the memory form, little-endian; see
//! [`encode_lines`]/[`decode_lines`]. Decoding is bounds checks, not
//! parsing.
//!
//! # Both sides of the seam
//!
//! An engine implements [`Limner`]; an editor holds one and asks. This
//! toy engine paints each line's first word as style 0 and marks it a
//! definition — enough to show the shape without being a real
//! highlighter.
//!
//! ```
//! use linework::{FactCard, Hint, LineEdit, Limner, Paint, PaintDelta, Run,
//! MOD_DEF, STYLE_NONE};
//!
//! fn paint_line(line: &str) -> Vec<Run> {
//! if line.is_empty() {
//! return Vec::new();
//! }
//! // Byte indices throughout — never char indices.
//! let head = line.find(' ').unwrap_or(line.len()) as u16;
//! let tail = line.len() as u16 - head;
//! let mut runs = vec![Run { len: head, style: 0, mods: MOD_DEF }];
//! if tail > 0 {
//! runs.push(Run { len: tail, style: STYLE_NONE, mods: 0 });
//! }
//! runs
//! }
//!
//! #[derive(Default)]
//! struct FirstWord { rev: u64, text: String }
//!
//! impl Limner for FirstWord {
//! fn open(&mut self, text: &str) -> Paint {
//! self.text = text.to_string();
//! self.rev += 1;
//! Paint { rev: self.rev, lines: text.lines().map(paint_line).collect() }
//! }
//!
//! fn edit(&mut self, edit: &LineEdit) -> PaintDelta {
//! self.rev += 1;
//! let runs = edit.lines.iter().map(|l| paint_line(l)).collect();
//! // Only the spliced window is re-emitted; untouched lines are
//! // absent from the delta, not repeated.
//! PaintDelta {
//! rev: self.rev,
//! splice: Some(((edit.start, edit.end), runs)),
//! repaints: Vec::new(),
//! }
//! }
//!
//! fn facts(&mut self, _offset: u32) -> Option<FactCard> { None }
//! fn hints(&mut self) -> Vec<Hint> { Vec::new() }
//! fn legend(&self) -> Vec<String> { vec!["keyword".to_string()] }
//! fn text(&mut self) -> String { self.text.clone() }
//! }
//!
//! // --- the editor side: generic over the trait, blind to the engine ---
//! fn total_painted_bytes(limner: &mut dyn Limner, src: &str) -> u32 {
//! let paint = limner.open(src);
//! paint.lines.iter().flatten().map(|r| r.len as u32).sum()
//! }
//!
//! let mut engine = FirstWord::default();
//! assert_eq!(total_painted_bytes(&mut engine, "let x\nlet y"), 10);
//!
//! // An edit returns only what changed.
//! let delta = engine.edit(&LineEdit {
//! start: 1,
//! end: 2,
//! lines: vec!["let zz".to_string()],
//! });
//! assert!(delta.repaints.is_empty());
//! let (range, lines) = delta.splice.unwrap();
//! assert_eq!(range, (1, 2));
//! assert_eq!(lines[0][0].mods, MOD_DEF);
//! ```
// ---------------------------------------------------------------------------
// Modifier bits (wave 1)
// ---------------------------------------------------------------------------
/// This run's bytes are a definition's name.
pub const MOD_DEF: u8 = 1 << 0;
/// A reference that RESOLVES (navigation will land somewhere).
pub const MOD_REF: u8 = 1 << 1;
/// A reference that does not resolve — including "exists but is not
/// exported" and broken qualified paths (the squiggle substrate).
pub const MOD_UNRESOLVED: u8 = 1 << 2;
/// The definition is visible outside its own module or file —
/// whatever the language calls that (`pub`, `export`, `public`).
pub const MOD_PUBLIC: u8 = 1 << 3;
/// The reference resolves into ANOTHER file.
pub const MOD_FOREIGN: u8 = 1 << 4;
/// A type is known for this name. What counts as a type is the
/// engine's business; this bit only says one is available.
pub const MOD_TYPED: u8 = 1 << 5;
/// `style` value for bytes with no declared class (trivia, plain).
pub const STYLE_NONE: u8 = 0xFF;
// ---------------------------------------------------------------------------
// Paint
// ---------------------------------------------------------------------------
/// One horizontal span of identically-painted bytes. Four bytes, by
/// design: a dense 200-column line is a handful of cache lines, and a
/// 10k-line buffer's whole paint fits in ~KBs.
/// A full paint: per-line runs tiling each line exactly (text plus
/// terminator bytes), tagged with the revision they describe.
/// What one edit changed, and nothing else.
// ---------------------------------------------------------------------------
// Edits (editor → limner)
// ---------------------------------------------------------------------------
/// Replace lines `[start, end)` with `lines` (texts WITHOUT
/// terminators). The limner preserves the replaced lines' terminators
/// positionally and uses its default for any extras — a pure-text
/// protocol stays out of the newline-politics business.
// ---------------------------------------------------------------------------
// Facts (hover) and hints (inline decoration)
// ---------------------------------------------------------------------------
/// Everything the engine knows about the name at an offset, in one
/// record. No transport, no markdown — the editor renders it.
/// An inline decoration: `text` rendered at `(line, col)` — e.g. a
/// `: Num` type hint after a definition's name.
// ---------------------------------------------------------------------------
// Marks (document structure: outline, breadcrumbs, folding, sticky context)
// ---------------------------------------------------------------------------
/// One identified, categorized span of document STRUCTURE — the sparse
/// counterpart to the dense paint runs. Marks arrive flat, in document
/// order, with well-nested spans, so containment IS the hierarchy: an
/// ancestor precedes and encloses its descendants, and an editor can
/// rebuild the tree — or just walk a chain — without parent pointers on
/// the wire. One channel feeds breadcrumbs, structure views, sticky
/// context, and folding.
// ---------------------------------------------------------------------------
// The trait: what an editor is generic over
// ---------------------------------------------------------------------------
/// One who limns: the thing that draws a document's linework. An
/// intelligence engine implements this; an editor widget holds one and
/// stays ignorant of everything behind it.
///
/// The contract, in editor terms:
/// * [`open`](Limner::open) once per document (or on wholesale
/// replacement) — full paint back.
/// * [`edit`](Limner::edit) per change, line-shaped — a delta back,
/// synchronously; the wave-0 portion of that delta is expected in
/// MICROSECONDS, so the caller may paint the same frame.
/// * [`facts`](Limner::facts)/[`hints`](Limner::hints) on demand
/// (hover, cursor move) — warm lookups.
/// * [`legend`](Limner::legend) maps `style` bytes to class names the
/// theme understands ("keyword", "string", …).
// ---------------------------------------------------------------------------
// Wire form
// ---------------------------------------------------------------------------
/// `[rev u64][n u32]` then per line `[line u32][nruns u32][runs…]`,
/// each run `[len u16][style u8][mods u8]`, all little-endian.