slosh.git/docs/design.md, branch master

docs: deprecate boring design narrative, more trimming and culling

2026-09-02T10:32:45Z

docs: less wordy

2026-08-29T18:25:39Z

gitignore: DESIGN.md and .fastfeedback are local, not the project

2026-08-28T13:38:41Z

DESIGN.md was a scratch design doc and .fastfeedback a per-repo tool cache; neither belongs in the tree. Both stay on disk, ignored. Everything that pointed at DESIGN.md now points at docs/design.md, and the decision counts quoted from it (which had already drifted: the README said twenty-one, the docs said twenty-two) are gone with it.

README/docs: stop leaning on the aside dash

2026-08-27T14:11:26Z

Some 230 sentences hung their qualifications between dashes, and at that density the tic reads as the writing's signature rather than a tool it occasionally picks up. Each one is now the punctuation the sentence actually wanted: a colon where the aside defines, parentheses where it whispers, a comma where it barely pauses, a full stop where two thoughts were pretending to be one. Definition lists and reference tables take colons throughout. Two double hyphens remain on purpose, both literal: the argv separator in a shell example, and a table cell that means 'takes nothing'.

README/docs: spell the dash --, as the rest of the tree does

2026-08-27T14:04:37Z

Every C comment, commit message and generated config in this repo writes the aside dash as a spaced double hyphen; the Markdown alone used U+2014, some 220 of them. One spelling, and the ASCII one -- the prose now matches the code it documents. Mechanical (every occurrence was the spaced form, checked including the one inside a code fence, where it was comment text), so the words themselves are untouched.

slosh: fold floating panes and the drop grammar into DESIGN.md

2026-08-20T21:29:18Z

D22 records the float contract: the minimized pattern (a flag and a wanted rect on a leaf that keeps its seat), derived-vs-remembered rects, the hit list as the z-order, the pop to the centre, the shadow-not-a-state, the backdrop invariant, edge-pinned resizes, and the key decisions -- with M10c (layout files, dump-layout, placement over the API, graphics occlusion) recorded as still owed. M11 extends the drag machine section with the drop grammar: swap centre plus third-width insert bands, the fill as the promise, release derived from the painted hits, and the sibling-reorder rule. The working plan file served its purpose and goes; git remembers it.

slosh: split app.c into five units, mechanically

2026-08-19T11:47:10Z

app.c was 7k lines wearing section markers; now the markers are files, cut exactly along them, no behaviour change: app.c the session core: config in force, pane and tab lifecycle, walking, input routing, introspection app_layout.c layout, tree edits, resizing, equalising, rotating, focus app_session.c layout files, checking, workspaces, dumping a session app_draw.c drawing, the shader passes, kitty graphics app_ui.c the finder, modals, the palette, the project picker, renaming include/app_internal.h carries what the five share: the tree/tab/app structs, CFG and the palette macros, and the 50-odd formerly static functions the cut made cross-unit, declared where they are defined. They keep their names; only the five units see the header. One test moved with the code: test_portable_layouts' staleness check greps the source for the layouts section, which now lives in app_session.c. Mechanical, so blame for anything in the four new files continues in app.c before this commit.

slosh: rename the project from sl0ppty

2026-08-18T19:26:00Z

sl0p + pty was error-prone to type and the zero made it worse; slosh (slop + sh) is one syllable, impossible to typo, and slosh.foo is ours. Mechanical rename everywhere it appears: binary, env vars (SLOSH, SLOSH_SESSION, SLOSH_BIN, SLOSH_CONFIG), socket dir (/tmp/slosh-, $XDG_RUNTIME_DIR/slosh), config path (~/.config/slosh), header guards, src/sl0ppty.h -> src/slosh.h, contrib/sl0ppty-dev -> contrib/slosh-dev, the driving-slosh skill, docs and tests. The sl0ppi fork references and the sl0p theme stay: one is history, the other is the brand. The rename surfaced a latent bug in test_osc5577: the hello-reply answer always appeared on screen twice (ECHOCTL echo plus cat -v), but a seven-character implementation name happened to wrap the second copy across the 60-column boundary, so counting substrings in wrapped text found one and passed for the wrong reason. A five-character name moved the wrap and exposed it. The loop guard itself is correct -- with echo off before the request there is exactly one reply -- so the test now counts on de-wrapped text and tolerates the pane's own echo.

sl0ppty: make tools, and a ruff version that cannot drift

2026-08-17T12:49:59Z

`ruff` is not a system package on most machines, and `pip install --user ruff` is refused outright on a distro python (PEP 668) -- so the last two commits shipped a formatter nobody could run without knowing to build a venv by hand. `make tools` builds it: $ make tools ruff 0.16.3 in .venv survives make clean; rm -rf .venv to start over clang-format stays a system package, because everywhere it is one. `make tools` says so if it is missing rather than pretending it handled it. **The venv is looked in before `$PATH`, and the order is the point.** `ruff.toml` now pins the version with ruff's own `required-version`, so a ruff of the wrong one refuses to run and names both versions. Preferring `$PATH` would then strand somebody who has 0.14 from their package manager and 0.16.3 sitting in the `.venv` the repo just built for them -- refused by the tool, with the fix already on disk and not being looked at. Tested with exactly that: 0.14.0 on `$PATH`, `make fmt-check` still clean. The pin exists because a formatter whose output moves between releases turns "formatted" into "formatted by whoever committed last", and the diff lands on the next person to touch the file. Refusing loudly is better than reformatting quietly. Bumping it is one line in `ruff.toml`, one in the Makefile, and a reformat commit, which is the honest cost of a new version. The hook resolves ruff the same way, off `git rev-parse --show-toplevel` so it works from a subdirectory, and its "not installed" message now says `make tools` instead of naming three package managers and hoping. Verified from the state a fresh clone is in: with no ruff anywhere, `make fmt` says `ruff not found. run: make tools` and stops; after `make tools` (2.6s) both `fmt` and `fmt-check` work with nothing on `$PATH`; the hook formats a staged Python file using the venv; the venv survives `make clean`; and `.venv/` is ignored. `make fmt` over the whole tree after all this changed nothing, which is the useful part: the pinned version agrees with what is already committed. One near-miss worth recording: the `.gitignore` line for `.venv/` had to be written twice. A `git reset --hard` undoing a throwaway probe commit took the working tree with it, including that edit -- which is what `--hard` does, and why the state was checked afterwards rather than assumed.

sl0ppty: ruff formats the Python, and sorts its imports

2026-08-17T12:35:59Z

The other half of the pre-commit hook. C goes through clang-format, Python through ruff: `ruff check --select I --fix` to sort the imports, then `ruff format` to lay them out. `make fmt` does both, `make fmt-check` reports, `make hooks` installs it. ruff rather than black because it is one static binary instead of a Python dependency chain, and fast enough that a hook is free. Its formatter is black-compatible, so this is the ecosystem's formatting rather than a dialect -- measured at 9,935 changed lines against black's 9,953, which is the same answer. **Left entirely at the defaults**, which is the opposite of what `.clang-format` does. That file argues with LLVM in five places because the C here was hand-formatted into a house style worth keeping. The Python was not, and a formatter of this kind is only worth having when there is nothing left to argue about: every knob turned is an argument somebody has to have again later. 88 columns, double quotes, ruff's own line breaking. **Import sorting is on, and C include sorting stays off.** Not an inconsistency: a C include order can be load-bearing -- `_GNU_SOURCE` ahead of the system headers, and a grouping somebody wrote by hand -- while Python import order is not. Where it genuinely is, a statement between imports ends the block ruff will sort, and the test files lean on exactly that: import sys sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) from harness import Session, check, report `from harness import` cannot be hoisted above the line that makes it importable, because the `sys.path.insert` between them is a barrier. Verified before touching anything, since getting it wrong would have broken every test in the suite at once. Two details in the hook worth naming. `--select I` is passed on the command line as well as set in `ruff.toml`, so a stray `select` in somebody's own config cannot turn a formatting hook into a linter that refuses a commit over an unused variable. And the two tools are named together when either is missing, so setting up a machine installs both at once instead of finding the second one on the next commit. `set -e` and `[ -n "$c_files" ] && clang-format ...` do not mix: when the list is empty the AND-list returns non-zero and the shell exits, so a Python-only commit would have aborted with no message at all. They are `if` blocks. Found by testing the case rather than by reading it. Verified in a scratch clone, seven paths: Python alone, C alone, both in one commit, imports sorted with the `sys.path` barrier intact, a `contrib/` script that is Python with no extension on it, a partly staged Python file refused with `HEAD` unchanged, and a commit with no code in it drawing no comment.