aboutsummaryrefslogtreecommitdiffstats
path: root/docs/design.md
diff options
context:
space:
mode:
authoruser <user@clank>2026-08-15 23:53:30 +0200
committeruser <user@clank>2026-08-15 23:53:30 +0200
commit4dc055692c56324a94d1087331da8862ea650d2b (patch)
tree5ddec99f7cf6b144ede4138b6e952c84379725aa /docs/design.md
parentsl0ppty: marks a font actually draws at cell size (diff)
downloadslosh-4dc055692c56324a94d1087331da8862ea650d2b.tar.gz
slosh-4dc055692c56324a94d1087331da8862ea650d2b.tar.xz
slosh-4dc055692c56324a94d1087331da8862ea650d2b.zip
sl0ppty: a README you can read, and docs/ for the rest
The README was 331 lines and had become a manual with a title. Everything in it was true and most of it was the wrong thing to hand somebody who has just arrived: five pages of shader expression semantics before they have split a pane. So the front page is 60 lines -- what it is, install, run, where the docs are, and six bullets on what is actually different about it -- and the detail moved into docs/, nine pages that each answer one question: index.md what it is, install, run, where to go keys.md the leader, every default, rebinding, direct binds panes.md splitting, resizing, the mouse, dead panes, small terminals config.md the file, live reload, include, themes, the knobs shaders.md the passes, the built-ins, the expression language chrome.md where="chrome", channel, since, the perimeter trick layouts.md a session as a file, and writing one back out scripting.md the control socket, OSC 5577, headless design.md the two decisions, and a map of the source docs/nav holds the order and the grouping and nothing else -- titles come from each page's own heading, so a renamed page cannot end up with two names. It is what the site generator will read. Reference material that only existed in code comments is written down for the first time: every action that can be bound (including the two with no default key, which is what the palette is for), every control verb, the built-in shaders with what each takes, the pane-state ranking, and the layout file's shape. Two things I got wrong on the first pass and fixed before committing: the docs linked repo files through github.com URLs for a project whose remote is a private git server, so those are inline paths now; and the README advertised `make docs`, which does not exist yet. It will in the next commit, and it can be advertised then.
Diffstat (limited to 'docs/design.md')
-rw-r--r--docs/design.md50
1 files changed, 50 insertions, 0 deletions
diff --git a/docs/design.md b/docs/design.md
new file mode 100644
index 0000000..5d08d86
--- /dev/null
+++ b/docs/design.md
@@ -0,0 +1,50 @@
+# How it works
+
+Two decisions do most of the work. The rest — twenty numbered decisions, each
+with what it cost to get wrong — is in
+`DESIGN.md`.
+
+## One geometry
+
+**Everything drawn registers what it is, as it is drawn**, and a click is a
+lookup in that list. Drawing and hit-testing cannot disagree, because there is
+only one of them. The dashed guide that shows where a split would land is drawn
+from the same rect the click will resolve against, in the same pass — so a
+preview that lies is not a bug you can have.
+
+The same rule applies to state that could be derived: the layout is a pure
+function of the tree and the terminal's size, recomputed every frame. Nothing
+stores where a pane is. That is why a small terminal can collapse a tab to a list
+of headers and come back to exactly the layout you had, and why a pane cannot be
+left greyed out by the one code path that forgot to clear a flag.
+
+Sizes are **weights**, so an even split is equal weights and resizing is not a
+special case of anything.
+
+## It runs headless
+
+`sl0ppty --script` is the whole thing without a terminal: commands in, the
+composited screen out as JSON. The interactive client and the test suite drive
+the same object through the same commands, so there is exactly one implementation
+of what a key does.
+
+That is what makes the tests real: they type keys and assert on the screen a
+client would have seen, rather than on the internals. 700-odd checks in about
+eight seconds, plus unit tests for the parts that are pure functions (the KDL
+parser, the shader pass, the expression compiler).
+
+## The shape of it
+
+```
+src/app.c the session: tree, layout, chrome, input routing, control API
+src/pane.c one pty + one libghostty-vt terminal, composed into the screen
+src/screen.c our cell buffer, and the minimal byte stream to update a terminal
+src/server.c the session process: socket, poll loop, config watcher
+src/client.c the attached terminal: bytes in, bytes out
+src/config.c the config, the keymap, the cheatsheet's names
+src/shader.c the colour passes; src/expr.c compiles their strengths
+src/kdl.c a hand-rolled KDL subset, for configs and layouts
+```
+
+About 10k lines of C. The vendored terminal core does VT parsing, scrollback,
+selection, images and key encoding; everything above is ours.