linework 0.0.3

The linework protocol: line-keyed, two-wave code paint and facts — engine-neutral types and the Limner trait binding language intelligence to editors
Documentation
# linework

**An engine-neutral protocol for binding language intelligence to a code
editor.** Line-keyed, two-wave code paint plus on-demand facts, behind one
trait an editor widget can be generic over.

Zero dependencies. This crate knows nothing about any particular parser,
language runtime, or editor.

```toml
[dependencies]
linework = "0.0.2"
```

## What it is for

An editor that wants syntax colouring, go-to-definition and inline hints
normally couples itself to whatever produces them. Swap the engine and the
widget is rewritten; support a second language and the widget grows a second
integration.

`linework` is the seam. One side implements [`Limner`]; the other consumes
it. Neither needs the other's types:

```
   your editor widget  ──►  dyn Limner  ◄──  your intelligence engine
      (consumes)                                  (implements)
```

## The shape, and why

**Paint is line-keyed.** Each line is a vector of `Run`s — 4-byte cells
`{len, style, mods}` tiling that line's bytes exactly. Runs are
line-*relative*, so a line that merely shifts down re-emits nothing. Editing
line 3 of a 10,000-line file does not repaint 9,997 unchanged lines.

**Paint is two-wave.** `style` is the lexical class, available synchronously
with a keystroke from the damaged lines alone. `mods` carries semantic bits —
definition, resolved or unresolved reference, exported, foreign, typed — that
arrive later and **never change a style**. Refinement is strictly additive, so
the first frame is already correct and nothing flickers as understanding
deepens.

**A delta names only what changed.** A `PaintDelta` carries a spliced window
of lines plus semantic-only repaints by line number. That repaint set is the
edit's semantic blast radius, made explicit rather than guessed at.

**Facts are lookups, not requests.** `FactCard` answers "what *is* this name"
— definition site, problem, display type, namespace — against warm state.
`Hint`s carry inline decorations.

## The trait

```rust
pub trait Limner {
    fn open(&mut self, text: &str) -> Paint;
    fn edit(&mut self, edit: &LineEdit) -> PaintDelta;
    fn facts(&mut self, offset: u32) -> Option<FactCard>;
    fn hints(&mut self) -> Vec<Hint>;
    fn legend(&self) -> Vec<String>;
    fn text(&mut self) -> String;
}
```

`legend()` names the style classes by index, so the editor maps indices to
its own theme and the engine never speaks in colours.

## Conventions

- **Offsets and lengths are bytes** of UTF-8 text. Consumers that index by
  character (ropes, for instance) convert at the boundary.
- **The wire form is the memory form**, little-endian — see `encode_lines` /
  `decode_lines`. Decoding is bounds checks, not parsing, so the protocol
  crosses a process boundary without a serialisation format.

## Status

Pre-1.0 and evolving. The types are small and the surface is deliberately
narrow, but expect breaking changes before 1.0. Pin an exact version.

## Licence

MIT OR Apache-2.0, at your option.