paperos 0.2.0

A programmable editor built on the Runact actor runtime
Documentation
# Customizing paperOS

paperOS is customized entirely through Lua. On startup the editor loads
`init.lua` from your config directory:

- `$PAPEROS_CONFIG/init.lua` (if the env var is set)
- otherwise `~/.config/paperos/init.lua`

Everything in the `paper.*` namespace is available in that file. User Lua
modules colocated with `init.lua` are loadable via `require` (the config
dir is prepended to `package.path`).

## Quick start

```lua
-- ~/.config/paperos/init.lua
paper.config.set("ui.line_numbers", "false")
paper.config.set("statusline.format", " %m :: %f ")

paper.theme.set("cursor-normal", "magenta")
paper.theme.set("border", "blue")

paper.keys.map("normal", "U", "upper-word")
```

## Reference

### paper.config

Typed settings, stored as strings.

- `paper.config.set(key, value)` — set at config time
- `paper.config.get(key)` — read back

| Key | Values | Default | Effect |
|-----|--------|---------|--------|
| `ui.line_numbers` | `"true"` / `"false"` | `"true"` | Line-number gutter |
| `statusline.format` | template | `" %m  %f %l:%c %("` | Statusline layout |

Statusline tokens: `%m` mode, `%f` file name, `%l` line, `%c` column,
`%(` modified marker (shows `[+]` when the buffer is modified, else empty).

### paper.theme

`paper.theme.set(name, color)` — any of: `black red green yellow blue
magenta cyan gray darkgray white reset`, or `#rrggbb`.

| Name | Default | Controls |
|------|---------|----------|
| `cursor-normal` | `yellow` | Cursor block in Normal/Visual |
| `cursor-insert` | `white` | Cursor block in Insert |
| `cursor-visual` | `yellow` | Cursor in Visual |
| `border` | `cyan` | Editor panel border |
| `line-number-fg` | `darkgray` | Gutter numbers |
| `statusbar-fg` / `statusbar-bg` | `black` / `cyan` | Statusline colors |
| `candidate-fg` / `candidate-bg` | `black` / `white` | Minibuffer input |
| `candidate-sel-bg` | `darkgray` | Candidate list / echo bg |
| `echo-fg` | `white` | Echo line text |

### paper.commands

```lua
paper.commands.register("greet", function(args)
  return "hello " .. (args[1] or "world")
end, "Greet the user")
```

Registered commands are real editor commands: they appear in `M-x`
completion and can be bound with `paper.keys.map`.

### paper.events

```lua
paper.events.on("file.saved", function(payload)
  -- payload is a table: { path = "...", bytes = 123 }
  paper.cmd("message saved: " .. payload.path)
end)
```

Built-in events:

| Event | Payload |
|-------|---------|
| `file.saved` | `{ path, bytes }` |
| `buffer.changed` | `{ command, buffer }` |

`paper.events.publish(name, payload_table)` queues a custom event; Lua
handlers run when the event loop drains it.

### paper.keys

```lua
paper.keys.map(mode, key, command)
```

- `mode`: `"normal"`, `"insert"`, `"visual"`, or `"*"` (all modes)
- `key`: e.g. `"U"`, `"<C-t>"`, `"gg"`
- `command`: any registered command name (built-in or `paper.commands.register`)

Keymaps resolve on mode only — there is no buffer-kind concept.

### paper.buffer

Direct access to the document buffer:

- `paper.buffer.content()` — full text
- `paper.buffer.set_content(text)`
- `paper.buffer.insert_text(text)` — at cursor
- `paper.buffer.cursor()` — `{ row, col }` (1-based)
- `paper.buffer.move_to(row)` — move cursor to row

### paper.cmd / paper.open / paper.save

Queue an editor command for the event loop:

```lua
paper.cmd("down")            -- any M-x command
paper.open("/path/to/file")  -- sugar for paper.cmd("open ...")
paper.save()                 -- sugar for paper.cmd("save")
```

Commands run through the real command registry; errors are echoed.

### paper.after

```lua
paper.after(500, function()
  paper.cmd("message half a second passed")
end)
```

Schedules a Lua callback after `ms` milliseconds. Timers fire on the
editor's event loop (same tick as their queued side effects) — no
threads, no busy waiting.

### paper.terminal

```lua
paper.terminal.open()          -- focus the terminal panel (Terminal mode)
paper.terminal.send("ls -la")  -- write text to the terminal's shell
```

The terminal panel is a real buffer (named "terminal"): switch to it,
search it, yank from it. Its lines always mirror what is on screen —
the styled cell grid lives in the terminal extension, which claims the
panel's rendering.

The terminal scrolls: PageUp/PageDown page through history (10,000
rows), the mouse wheel scrolls it too, and any keypress snaps back to
the live output.

Escape hatches (usable inside Terminal mode):

- `M-x` — command prompt (minibuffer)
- `M-n` / `M-p` — next / previous buffer
- `Esc` — leave Terminal mode, back to Normal
- `Ctrl-q` — quit

Esc exits Terminal mode back to Normal. Ctrl-q still quits from anywhere.

### paper.panels

Panels are named buffers — same mechanism as the built-in `statusbar`
and `echo` panels:

```lua
paper.panels.create("notes")
paper.panel.write("notes", "hello from lua")
```

`paper.panel.write` calls made during config load are queued and flushed
once the panels exist; later writes deliver on the next event-loop tick.

### paper.extensions

`paper.extensions.list()` — names of active extensions.

## Extensions

Installable extensions live in `~/.config/paperos/extensions/<name>/`
with a `manifest.json`:

```json
{
  "name": "hello",
  "version": "0.1.0",
  "description": "Greets",
  "author": "you",
  "depends": [],
  "provides": []
}
```

Enable by symlinking into `extensions-active/`:

```bash
ln -s ~/.config/paperos/extensions/hello ~/.config/paperos/extensions-active/hello
```

Active extensions' `init.lua` files execute at startup in dependency
order (topological sort of `depends`).

## User modules

Any `.lua` file next to `init.lua` is requireable:

```lua
-- mymod.lua
return { setup = function() paper.config.set("ui.line_numbers", "false") end }

-- init.lua
require("mymod").setup()
```