aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authoruser <user@clank>2026-08-19 15:25:28 +0200
committeruser <user@clank>2026-08-19 15:25:28 +0200
commit49ac13f70aa3a9224e90699fe68d8463909239db (patch)
tree303c3cee9492e23de6a1f0afc7b2feffeba5c6aa
parentslosh: the logo flies into place -- a particle engine, statelessly (diff)
downloadslosh-49ac13f70aa3a9224e90699fe68d8463909239db.tar.gz
slosh-49ac13f70aa3a9224e90699fe68d8463909239db.tar.xz
slosh-49ac13f70aa3a9224e90699fe68d8463909239db.zip
slosh: layout files are *.layout, not *.layout.kdl
The old name argued that the extension should say how to read the file. The argument lost to a collision: zellij speaks the same KDL syntax under that same extension with a different schema, and to anyone arriving from there .kdl said *whose* file it is -- naming the wrong owner is worse than not naming the parser. So a layout is x.layout, a project's is slosh.layout, the name says what the file is and --check says how it was read. (It is still KDL underneath; point your editor's highlighting at *.layout.) Nobody's checked-in workspace vanishes on upgrade: the project scan still finds slosh.layout.kdl, never writes it, and where both spellings exist the new one wins, because two files disagreeing needs one answer. The unparseable-file heuristic in --check learned the new suffix -- it matched '.layout.' with a trailing dot, which the new name no longer has. The webdemo overlay moves with it (demo.layout), rebuilt and boot-checked.
-rw-r--r--DESIGN.md4
-rw-r--r--config/config.kdl6
-rw-r--r--config/example.layout (renamed from config/example.layout.kdl)6
-rwxr-xr-xcontrib/slosh-dev2
-rw-r--r--docs/layouts.md47
-rw-r--r--docs/workspaces.md12
-rw-r--r--include/app.h2
-rw-r--r--include/config.h2
-rw-r--r--include/project.h12
-rw-r--r--src/app_session.c2
-rw-r--r--src/config.c2
-rw-r--r--src/main.c8
-rw-r--r--src/project.c7
-rw-r--r--tests/test_config.py4
-rw-r--r--tests/test_layout_files.py2
-rw-r--r--tests/test_portable_layouts.py8
-rw-r--r--tests/test_workspaces.py46
17 files changed, 111 insertions, 61 deletions
diff --git a/DESIGN.md b/DESIGN.md
index b23e5f3..312d6f6 100644
--- a/DESIGN.md
+++ b/DESIGN.md
@@ -144,7 +144,7 @@ unreadable.
| # | decision |
|---|---|
| **D1** | **OSC 5577 stays byte-compatible** with the sl0ppi fork, so the five existing pi extensions work unmodified. Delivered by a side-channel scanner on the pty stream (see the correction above), with a versioned `hello` handshake added on top — the fork's protocol is unversioned, which is a known risk — and an APC-based v2 once anything new is written against it. |
-| **D2** | **Config is a hand-rolled KDL subset** (`kdl.c`, 300 lines, no dependency): nodes with arguments, `key=value` properties, children, `//` and `/* */` comments, `;` terminators for single-line nodes. `config/config.kdl` documents every setting by *being* the defaults. A broken file costs a warning on stderr and nothing else; `{"cmd":"reload"}` re-reads it live and refuses a file it cannot parse rather than half-applying it. **Two schemas share the syntax** -- a config and a layout -- so layout files are named `*.layout.kdl`: the extension says how to read the file and the stem says what is in it, the way `docker-compose.yml` does. Naming them something other than KDL would trade one wrong signal for another, since one parser really does read both. A name cannot enforce anything, so each loader also *says* which document it was handed (`this is a layout, not a config`, and the reverse), both answers measured against the same list of settings the loader reads. That list is what makes an unknown top-level node reportable at all: a loader that asks a document only for the keys it knows never notices what it was given, which is why a mistyped setting used to do nothing quietly and a whole layout linted clean. |
+| **D2** | **Config is a hand-rolled KDL subset** (`kdl.c`, 300 lines, no dependency): nodes with arguments, `key=value` properties, children, `//` and `/* */` comments, `;` terminators for single-line nodes. `config/config.kdl` documents every setting by *being* the defaults. A broken file costs a warning on stderr and nothing else; `{"cmd":"reload"}` re-reads it live and refuses a file it cannot parse rather than half-applying it. **Two schemas share the syntax** -- a config and a layout. Layout files were `*.layout.kdl` for a while, on the argument that the extension should say how to read the file; the argument lost to a collision: zellij speaks the same syntax under that same extension with a different schema, and to anyone arriving from there `.kdl` said *whose* file it is -- naming the wrong owner is worse than not naming the parser. So layout files are `*.layout` (a project's is `slosh.layout`): the name says what the file is, and `--check` says how it was read. The old spelling is still found by the project scan, never written. A name cannot enforce anything, so each loader also *says* which document it was handed (`this is a layout, not a config`, and the reverse), both answers measured against the same list of settings the loader reads. That list is what makes an unknown top-level node reportable at all: a loader that asks a document only for the keys it knows never notices what it was given, which is why a mistyped setting used to do nothing quietly and a whole layout linted clean. |
| **D3** | **Clean JSON control API** (one JSON object per line on a unix socket): `{"cmd":"new-tab","purpose":"project:x.deadbeef"}` -> `{"ok":true,"id":2}`. We do *not* mimic `zellij action`'s surface. A bare-verb form (`panes`, `snapshot text`) is kept as a human/harness alias and runs the same code, so a script cannot drift from what the API does. The `sl0ppi` CLI is ported on top later; `up`'s idempotency and D9's fail-open property carry over. |
| **D4** | **Scrollback yes** (free from lib-vt), **copy-mode UI later.** "Free" was true of the *machinery* and quietly false of the *size*: handed no limit, lib-vt picks its own — 10,000 **bytes**, which measured at 622 lines of an 80-column pane, less than one `make` run. A promise to keep history that keeps a screenful of it is the kind of thing a library default gets to decide only once. So `scrollback` is lines, defaulting to the 10,000 every other multiplexer settled on, and `scrollback_bytes` is the ceiling that count runs into: lib-vt applies whichever limit is reached first, and it has to, because a line count cannot see how wide the terminal is or how many styles a program used and a byte count cannot see how many lines that bought. Measured at 10,000 lines of styled output: ~6 MB at 80 columns (the ceiling never bites), ~15 MB at 200 (it costs 2% of the lines), ~32 MB at 400 (it costs half). Invisible at ordinary widths and a brake at extraordinary ones, which is the job. There is deliberately **no unlimited**: the ceiling is per pane, sixty panes is sixty times it, and "unlimited" across that many is a memory leak with a friendly name — a negative is refused rather than wrapped into one. Both are read when a pane is created, so they apply to the next pane you open rather than to panes already holding output somebody is reading, which is the same rule and the same reason as `shell`. |
| **D5** | Binary, session dir, socket and config are all named **`slosh`**. |
@@ -163,7 +163,7 @@ unreadable.
| **D18** | **We decode PNG ourselves, with the stb_image we already vendor.** lib-vt ships no image codec: built as a library its `sys.decode_png` hook is null, and a null hook rejects every `f=100` transmission outright — no image stored, no placement, nothing to re-emit. A program that uploads a PNG (which is what a program with a picture on disk does) drew nothing at all, silently, while raw RGB worked. Found because ida-tui's startup logo never appeared. PNG is the only format this can ever be about: the protocol has exactly three (`f=24`, `f=32`, `f=100`) and the first two are raw pixels lib-vt already handles, and `decode_png` is the only codec hook it has — so there is no scope to creep. Decoding only, never encoding; the client is handed RGBA. The decoder is `vendor/libghostty-vt/src/stb/stb_image.h`, which is **already in the tree and already pinned** by the vendor commit — upstream compiles that same header with the same `STBI_ONLY_PNG` for the same reason (`src/stb/stb.c` says so), it is simply not part of the `-Demit-lib-vt` build. So this is not a new dependency, it is a file we already ship finally being compiled, and `src/png.c` is a hook and a copy around it. Hand-rolling a subset decoder was considered and rejected: the bulk of a PNG decoder is a DEFLATE inflate, and "just the colour type ida-tui uses" breaks on the first palette PNG, which is what every png optimiser emits. That is a lot of new bounds-checked parsing, fed by whatever a pane decides to send, to replace a file already in the repo. Two consequences to know: we re-emit **decoded** pixels, so a 819KB logo goes to the client as 3.3MB of base64 (once per image, again after a reattach clears `sent`) — passing the original PNG through would be cheaper but lib-vt hands back only the decoded form; and lib-vt caps image storage at **10MB** in library builds, so images are bigger than they look. |
| **D19** | **The finder and the command palette are one picker with a subject.** They are the same object — a modal, a query, a filtered list, one selection, the same keys and the same mouse rules — differing only in what fills the rows and what Enter does with one. Building the second as its own machine would have meant two of everything, and the pair would have drifted the way the pane title editor and a tab label editor would have if they had not been made one thing with a subject. So there is one `picker` state (`PICK_FINDER`/`PICK_PALETTE`), one draw, one key handler, and a `pick_row_t` of three columns that both fill: a dim left (a tab, a group), the thing itself, and a dim right (a purpose, the chord). Choosing goes through the row's own action string, so the keyboard and the mouse cannot take different paths to the same row. **The palette lists actions that are not bound to anything**, which the cheatsheet by design cannot — it is built from the binds, so an action with no key does not appear, and that is exactly the action you have no other way to reach. Where a binding does exist the palette shows it, so using the palette teaches the key that would have skipped it; where several exist it shows them all, because a config's binds add to the defaults rather than replacing them and naming only the first would hide the one the user chose. Two actions are left out: `literal-prefix`, which means "type this key" rather than "do this thing" and would send the prefix to a pane hidden behind the list, and `select-tab-N`, which is positional — a row saying "go to that tab" cannot say which. Running is by `action_t`, not by synthesising the keystroke that would have caused it: a palette that had to invent input to do its job would be lying to the rest of the program about what happened. |
| **D20** | **Chrome is a rect too, so it is a pass too.** `where="chrome"` on any entry in `shaders` or in a `states` block runs that pass over a pane's **frame** — border, padding, title, buttons — instead of its contents. Nothing else changes: same registry, same `amount`, same expressions (D16), same chain order, one new word. It is one pass over the frame's *whole* rect with the contents punched out as a hole, not four passes over four sides: an effect has to be able to travel round a border, and four passes would each count `x`/`y` from zero and restart at every corner. The hole is what keeps the two honest — a skipped cell is never visited, so a full-strength chrome tint cannot reach your text and a full-strength content tint cannot reach the border. The chains are stored separately rather than as a flag on each shader, because a pass *is* a chain and a rect, and because `shader_abi.h` has no business knowing where a session chose to run an effect. This is also the only kind of pass that can colour a pane a small window has collapsed to a single row (D6), which is the state where a colour is worth the most. **Animation needs a clock**, so `app_next_deadline_ms` reports one while a chain that reads `t` ran over the last frame — derived from what was applied, like everything else about a frame, so a pulse hung off `dead` costs `anim_ms` while a pane is dead and nothing for the rest of the session. Without it a border froze the moment you stopped typing, which is the bug that makes an animated shader look broken rather than absent. A **`bell` pane state** and a **`since`** variable came with it, because "flash the border when a pane rings" needed both and neither existed: a bell had no state to hang a chain off, and `t` says what time it is rather than how long ago something happened, so a one-shot effect was not expressible at all. `since` is milliseconds since the pane entered its current state, stamped in the one function that decides the state — a transition is the one thing a frame cannot tell you, so it is remembered, but it is remembered where it cannot disagree with the state it dates. `bell` ranks above the ambient states and below `dead`: a pane that rang while you were elsewhere is news, and a pane that rang and then exited is a pane that exited. It ends when you look at the pane, because that is what answering a bell is (the frame clock stops with it). **Shipped on by default**: the compiled-in `bell` state is two tints in theme's `bell` colour whose amounts read `since` — on the frame, three full-strength blinks over the first 900ms and then a slow breathe; on the body, a quiet shimmer — one soft diagonal sheen gliding across, peak strength 95 against the blinks' 255, its colour softened halfway towards `default_fg` (light, not paint), its width breathing on a sine as it travels, gone within those same 900ms — so what you are reading is only touched, gently, while the announcement lasts. Derived after the theme block the way the scrolled wash is, so a theme moves the mark, the flash and the shimmer together. The original objection was that an animated default would spend a frame clock on every session, and the clock's own derivation is what answers it: `since` carries `EXPR_DEP_TIME`, so the `anim_ms` clock runs only while a rung, unanswered pane is actually on screen — an idle session pays nothing. It follows `bell_indicator false` off (that knob's promise is silent *and* invisible), and `states { bell { … } }` — including an empty one — replaces it like any state, tracked across includes like `scrolled`. **`channel="fg"|"bg"|"both"`** came from the first border flash actually being looked at: `tint` mixes both of a cell's colours, and a frame's background is the terminal's own default, so the pass materialised it to our *guess* at that default and mixed towards the colour — a dark rectangle behind the glyphs, left there until the pane changed state. The mask is enforced by the pass, not by the shader: the cell's other colour is snapshotted before materialising and put back after, so it works for a built-in and a plugin alike, an unset colour goes back to *unset* rather than to our guess, and no shader grows an fg-only variant of itself. It is one byte tested once per pass, not per cell, and 0 means both so every shader built before it behaves as it did. |
-| **D21** | **A project is a directory; a workspace is the tab it occupies.** Two words because they are two things, and conflating them is how a session grows a second source of truth about what it is looking at. The directory is found rather than named: a `project_roots "~/dev" "~/work" depth=2` is scanned for subdirectories holding a `slosh.layout.kdl` — or a `.git`, which is the project that has not said what it needs yet, and without which `~/dev` with forty checkouts and three layout files is a picker with three rows. A directory that *is* a project is never descended into, so the walk stays off `node_modules` without anyone writing a rule about `node_modules`. **Identity is the tab's `purpose`**, `project:<name>.<hash8>` of the resolved path — the shape D3 already published — so there is no second field to disagree with it, membership is a string comparison, and a dumped session restores it for free because a dump already writes tab purposes and applying one already locks them (D8). Hashed on the *path* rather than the name, so two worktrees of one repo are two workspaces, which is what they are. A tab whose layout gave it a purpose of its own keeps it and is simply not a member: overwriting a declared purpose is the one thing D8 forbids, and the reply counts the ones it left alone rather than letting that be a surprise later. **Nothing watches the filesystem.** The list is derived when it is asked for — one `readdir` per root and two `stat`s per entry, forty checkouts for eighty-one syscalls next to the keystroke that asked — and an answer nobody remembered cannot be stale, which is a promise no watcher can make on a bind mount. The picker scans once as it opens, not per frame, because `draw_picker` asks for its rows every frame and a `readdir` per repaint is a filesystem walk at 120Hz. The one thing a scan cannot see is a project's layout file changing under a workspace that is already open, and that is deliberately not answered by re-applying it over running processes: `workspaces` reports the file's `mtime`, and drift is derivable outside without this session storing a byte. **Opening is idempotent** (`sl0ppi up`'s property, D3): the same request twice is one workspace, focused, and the answer says which branch it took so a caller never has to ask first. **Saving is the inverse, and it is the whole of onboarding.** `save-workspace` is `dump-layout` for one tab, relative to the project, written beside it — the same dumper, so there is one answer to "what does this tab look like written down". Four things made that possible and none of them were true before: a relative `cwd=` in a layout file now resolves against that file's directory (the rule `include` already followed, applied to the other half of the same syntax), a dump can be asked for one tab against a base, a pane from a split now starts where the pane it came out of stands rather than where the server was launched — which had been quietly writing an absolute path to somebody else's directory into every saved project — and **a dump now records what a pane is actually running**. That last one is what turns arranging a project and writing it down into one act instead of two: `label` only ever knew what a *layout* said, so a pane you split and typed `npm run dev` into had nothing to say for itself and came back as a bare shell. The kernel knows what the label does not — a pty has a foreground process group, and that group is by definition the job that owns the terminal — so the answer is read rather than guessed, the way `live_cwd` already reads `/proc/PID/cwd` rather than trusting where a pane was started. Three things are deliberately not commands: a shell at a prompt (its group is the pane's own, and `command="zsh"` on every idle pane restores a session where each shell runs inside a shell), a background job (it does not own the terminal, and resurrecting `&` jobs in the foreground describes a session nobody had), and an ephemeral pane (restoring one reopens a file somebody finished with). A declared label still outranks a live process, because it survives the program exiting (D14) and re-saving must not degrade `npm run dev` into whatever the process tree looks like this minute. argv is joined with shell quoting, since `command=` is run through `/bin/sh -c` and an argument with a space in it would otherwise come back as two. A saved project defaults to `suspend="commands"`: the pane running this morning's dev server is written asleep, because a *project's* layout is a statement of shape and a *session's* dump is a statement of fact, and starting a dev server on every open is exactly what `suspended` exists to prevent — which is worth much more now that there are commands to suspend. What is **not** built: no guessing commands from `package.json` or `Cargo.toml` (a table of guesses that is wrong on day one and stale by year two — recording what you actually ran makes it unnecessary), no watcher, and no auto-save on close, because a layout file is a commit-sized decision. |
+| **D21** | **A project is a directory; a workspace is the tab it occupies.** Two words because they are two things, and conflating them is how a session grows a second source of truth about what it is looking at. The directory is found rather than named: a `project_roots "~/dev" "~/work" depth=2` is scanned for subdirectories holding a `slosh.layout` — or a `.git`, which is the project that has not said what it needs yet, and without which `~/dev` with forty checkouts and three layout files is a picker with three rows. A directory that *is* a project is never descended into, so the walk stays off `node_modules` without anyone writing a rule about `node_modules`. **Identity is the tab's `purpose`**, `project:<name>.<hash8>` of the resolved path — the shape D3 already published — so there is no second field to disagree with it, membership is a string comparison, and a dumped session restores it for free because a dump already writes tab purposes and applying one already locks them (D8). Hashed on the *path* rather than the name, so two worktrees of one repo are two workspaces, which is what they are. A tab whose layout gave it a purpose of its own keeps it and is simply not a member: overwriting a declared purpose is the one thing D8 forbids, and the reply counts the ones it left alone rather than letting that be a surprise later. **Nothing watches the filesystem.** The list is derived when it is asked for — one `readdir` per root and two `stat`s per entry, forty checkouts for eighty-one syscalls next to the keystroke that asked — and an answer nobody remembered cannot be stale, which is a promise no watcher can make on a bind mount. The picker scans once as it opens, not per frame, because `draw_picker` asks for its rows every frame and a `readdir` per repaint is a filesystem walk at 120Hz. The one thing a scan cannot see is a project's layout file changing under a workspace that is already open, and that is deliberately not answered by re-applying it over running processes: `workspaces` reports the file's `mtime`, and drift is derivable outside without this session storing a byte. **Opening is idempotent** (`sl0ppi up`'s property, D3): the same request twice is one workspace, focused, and the answer says which branch it took so a caller never has to ask first. **Saving is the inverse, and it is the whole of onboarding.** `save-workspace` is `dump-layout` for one tab, relative to the project, written beside it — the same dumper, so there is one answer to "what does this tab look like written down". Four things made that possible and none of them were true before: a relative `cwd=` in a layout file now resolves against that file's directory (the rule `include` already followed, applied to the other half of the same syntax), a dump can be asked for one tab against a base, a pane from a split now starts where the pane it came out of stands rather than where the server was launched — which had been quietly writing an absolute path to somebody else's directory into every saved project — and **a dump now records what a pane is actually running**. That last one is what turns arranging a project and writing it down into one act instead of two: `label` only ever knew what a *layout* said, so a pane you split and typed `npm run dev` into had nothing to say for itself and came back as a bare shell. The kernel knows what the label does not — a pty has a foreground process group, and that group is by definition the job that owns the terminal — so the answer is read rather than guessed, the way `live_cwd` already reads `/proc/PID/cwd` rather than trusting where a pane was started. Three things are deliberately not commands: a shell at a prompt (its group is the pane's own, and `command="zsh"` on every idle pane restores a session where each shell runs inside a shell), a background job (it does not own the terminal, and resurrecting `&` jobs in the foreground describes a session nobody had), and an ephemeral pane (restoring one reopens a file somebody finished with). A declared label still outranks a live process, because it survives the program exiting (D14) and re-saving must not degrade `npm run dev` into whatever the process tree looks like this minute. argv is joined with shell quoting, since `command=` is run through `/bin/sh -c` and an argument with a space in it would otherwise come back as two. A saved project defaults to `suspend="commands"`: the pane running this morning's dev server is written asleep, because a *project's* layout is a statement of shape and a *session's* dump is a statement of fact, and starting a dev server on every open is exactly what `suspended` exists to prevent — which is worth much more now that there are commands to suspend. What is **not** built: no guessing commands from `package.json` or `Cargo.toml` (a table of guesses that is wrong on day one and stale by year two — recording what you actually ran makes it unnecessary), no watcher, and no auto-save on close, because a layout file is a commit-sized decision. |
### D6 — responsive layout as a pure function
diff --git a/config/config.kdl b/config/config.kdl
index 6b45a9b..27f842d 100644
--- a/config/config.kdl
+++ b/config/config.kdl
@@ -406,7 +406,7 @@ modal_scrim 120
// directory that *is* a project is never descended into, which is what keeps
// the scan off node_modules without a rule about node_modules.
//
-// A subdirectory is a project when it has a `slosh.layout.kdl` saying what it
+// A subdirectory is a project when it has a `slosh.layout` saying what it
// needs -- or a `.git`, which is the project that has not said yet. Both,
// because a ~/dev of forty checkouts and three layout files would otherwise be
// a picker with three rows, and `C-a W` writes the missing file from whatever
@@ -423,11 +423,11 @@ modal_scrim 120
// guess about your stack from whatever config files it happens to contain. A
// relative `cwd=` in it binds to whichever project is being opened, not to the
// directory this file lives in, so one file is the shape you start every
-// checkout in -- and a project that grows its own `slosh.layout.kdl` wins
+// checkout in -- and a project that grows its own `slosh.layout` wins
// over it, the way an included file is the base and the file including it wins.
//
// Unset, so a project with no layout is one pane running your shell in it:
-// project_layout "~/.config/slosh/project.layout.kdl"
+// project_layout "~/.config/slosh/project.layout"
// ── shaders ─────────────────────────────────────────────────────────────────
//
diff --git a/config/example.layout.kdl b/config/example.layout
index 8ab914d..04f268f 100644
--- a/config/example.layout.kdl
+++ b/config/example.layout
@@ -1,13 +1,13 @@
-// A session described as a file: slosh --layout project.layout.kdl
+// A session described as a file: slosh --layout project.layout
//
-// Name them `*.layout.kdl`. The syntax is the same KDL subset the config uses --
+// Name them `*.layout`. The syntax is the same KDL subset the config uses --
// one parser reads both -- so the extension says how to read the file and the
// `.layout` says what is in it. Two documents sharing a syntax is only confusing
// while nothing says which is which: hand this file to `slosh --check` and it
// tells you it is a layout, and hand a config to `--layout` and it says that too.
//
// The same shape can be sent to a running session over the control socket:
-// slosh cmd '{"cmd":"apply-layout","path":"/path/to/project.layout.kdl"}'
+// slosh cmd '{"cmd":"apply-layout","path":"/path/to/project.layout"}'
// slosh cmd '{"cmd":"apply-layout","kdl":"layout { tab name=\"x\" { pane } }"}'
// which is how an orchestrator adds one project tab at a time.
diff --git a/contrib/slosh-dev b/contrib/slosh-dev
index aac04f4..5d309c5 100755
--- a/contrib/slosh-dev
+++ b/contrib/slosh-dev
@@ -23,7 +23,7 @@ here=$(cd "$(dirname "$0")" && pwd)
bin="$here/../build/slosh"
SESSION=${SESSION:-dev}
state="${XDG_RUNTIME_DIR:-/tmp}/slosh-dev-$SESSION"
-layout="$state/session.layout.kdl"
+layout="$state/session.layout"
flag="$state/restart"
mkdir -p "$state"
diff --git a/docs/layouts.md b/docs/layouts.md
index 64d0c1f..9f7eabb 100644
--- a/docs/layouts.md
+++ b/docs/layouts.md
@@ -16,16 +16,21 @@ layout {
```
```bash
-slosh --layout project.layout.kdl
+slosh --layout project.layout
```
## What to call them
-**`*.layout.kdl`.** The syntax is the same KDL subset the config uses — one
-parser reads both files — so the extension says how to read it and `.layout`
-says what is in it, the way `docker-compose.yml` and `tsconfig.json` do it.
-Calling it something else would trade one wrong signal for another: it *is*
-KDL, and an editor that highlights KDL is worth keeping.
+**`*.layout`** — a project's is `slosh.layout`. The syntax is still the same
+KDL subset the config uses, one parser reads both files, and for a while the
+files were `*.layout.kdl` on the argument that the extension should say so.
+The argument lost to a collision: zellij speaks the same syntax under that
+same extension with a different schema, and to anyone arriving from there
+`.kdl` said *whose* file it is — naming the wrong owner is worse than not
+naming the parser. The name says what the file is; `slosh --check` says how
+it was read. (Point your editor's KDL highlighting at `*.layout` — it *is*
+still KDL underneath.) The old spelling is still found by the project scan,
+never written.
A filename cannot enforce anything, so **the document decides which schema it is
held to, not the flag that read it**. `slosh --check` reads what is in front of
@@ -38,8 +43,8 @@ layout, not a config` — replied to a question about a file with the name of
another flag.
```
-$ slosh --check project.layout.kdl
-project.layout.kdl: ok, a layout
+$ slosh --check project.layout
+project.layout: ok, a layout
```
A clean layout says which schema it passed, because otherwise a layout nothing
@@ -49,14 +54,14 @@ summary, and exits 1 — the shape [checking a config](config.md#checking-one)
already has, so one editor compile step and one pre-commit hook read both:
```
-$ slosh --check broken.layout.kdl
- broken.layout.kdl:2: unknown pane property: cmd
- broken.layout.kdl:3: split is cols or rows, not `diagonal`
- broken.layout.kdl:4: weight is a number of 150 or more, not `40`
- broken.layout.kdl:5: suspended takes true or false, not `yes`
- broken.layout.kdl:6: purpose is ignored on a pane with panes in it
- broken.layout.kdl:8: a pane holds panes, not `wobble`
-broken.layout.kdl: 6 problems
+$ slosh --check broken.layout
+ broken.layout:2: unknown pane property: cmd
+ broken.layout:3: split is cols or rows, not `diagonal`
+ broken.layout:4: weight is a number of 150 or more, not `40`
+ broken.layout:5: suspended takes true or false, not `yes`
+ broken.layout:6: purpose is ignored on a pane with panes in it
+ broken.layout:8: a pane holds panes, not `wobble`
+broken.layout: 6 problems
```
Those are the mistakes a layout can make that still parses: a property no pane
@@ -105,7 +110,7 @@ That is what lets a layout be checked in beside the project it describes and mea
the same thing in everybody's clone:
```kdl
-// ~/dev/api/slosh.layout.kdl — no absolute path in it anywhere
+// ~/dev/api/slosh.layout — no absolute path in it anywhere
layout {
tab name="api" cwd="." {
pane command="nvim"
@@ -128,12 +133,12 @@ was a base: relative to wherever the session is. Inventing one for text would
mean guessing on behalf of whoever sent it.
A full annotated example is
-`config/example.layout.kdl`.
+`config/example.layout`.
## Writing one back out
```bash
-slosh -s work cmd '{"cmd":"dump-layout"}' > project.layout.kdl
+slosh -s work cmd '{"cmd":"dump-layout"}' > project.layout
```
writes the session as a layout file: tabs, splits, proportions, directories,
@@ -210,7 +215,7 @@ tab and wherever the file happened to begin in the other five.
## Applying one to a running session
```bash
-slosh -s work cmd '{"cmd":"apply-layout","path":"project.layout.kdl"}'
+slosh -s work cmd '{"cmd":"apply-layout","path":"project.layout"}'
slosh -s work cmd '{"cmd":"apply-layout","kdl":"layout { tab { pane } }","replace":true}'
```
@@ -266,7 +271,7 @@ The [finder](panes.md#finding-a-pane) matches on purposes as well as titles, and
## When the layout is found rather than named
Everything above assumes you name the file. When it lives *in* the project —
-`slosh.layout.kdl` beside the `.git` — you do not have to: `C-a w` lists the
+`slosh.layout` beside the `.git` — you do not have to: `C-a w` lists the
projects under the roots you configured and opening one applies the layout it
found there, or a default layout bound to that directory when the project has
none, and `C-a W` writes this tab back out as that file. Same syntax, same
diff --git a/docs/workspaces.md b/docs/workspaces.md
index 4963683..b90c145 100644
--- a/docs/workspaces.md
+++ b/docs/workspaces.md
@@ -17,7 +17,7 @@ A subdirectory of a configured root with one of two markers in it:
| marker | what it is |
|---|---|
-| `slosh.layout.kdl` | a *declared* project — it says what it needs open |
+| `slosh.layout` | a *declared* project — it says what it needs open |
| `.git` | an *inferred* one — you work here, but you have not said how |
Anything else is not a project, and nothing is guessed from what is inside it.
@@ -40,7 +40,7 @@ Two settings, both in your [config](config.md):
```kdl
project_roots "~/dev" "~/work" depth=2
-project_layout "~/.config/slosh/project.layout.kdl"
+project_layout "~/.config/slosh/project.layout"
```
`project_roots` takes more than one directory because people have more than one —
@@ -94,7 +94,7 @@ C-a w picker: ~/work newthing .git · no layout
Enter your project_layout, cwd bound to newthing
C-a Enter, npm run dev arrange it, run things
C-a P service:web Enter tag the pane that matters
-C-a W "wrote slosh.layout.kdl · 4 panes, 2 suspended"
+C-a W "wrote slosh.layout · 4 panes, 2 suspended"
```
Tomorrow, `C-a w Enter` rebuilds that tab with the dev server in the pane you put
@@ -109,9 +109,9 @@ every tab carrying that purpose and says how many.
## Saving one
-`C-a W` writes the focused tab to `slosh.layout.kdl` in the project's directory,
+`C-a W` writes the focused tab to `slosh.layout` in the project's directory,
and the toast says what happened:
-`wrote slosh.layout.kdl · 4 panes, 2 suspended`.
+`wrote slosh.layout · 4 panes, 2 suspended`.
**What each pane is running goes in with it.** That is what makes writing a layout
the same act as arranging one: split the tab, start the dev server, start the log
@@ -155,7 +155,7 @@ the screen — so it says so in the request.
how a hand-arranged tab becomes a project's layout without opening it through the
picker first.
-`slosh --check slosh.layout.kdl` holds the result to the layout schema and
+`slosh --check slosh.layout` holds the result to the layout schema and
prints one `file:line: what` per problem, so a project's layout goes through the
same check as everything else you commit — see
[layouts](layouts.md#what-to-call-them).
diff --git a/include/app.h b/include/app.h
index 33fcbea..d422995 100644
--- a/include/app.h
+++ b/include/app.h
@@ -181,7 +181,7 @@ typedef struct {
} app_workspace_save_t;
/* Write one tab out as a project's layout: the same dump `dump-layout` answers
- * with, relative to the project, into `slosh.layout.kdl` beside it. `tab` 0 is
+ * with, relative to the project, into `slosh.layout` beside it. `tab` 0 is
* the current one; `path` names the project for a tab that is not yet a
* workspace (and saving adopts it, which is the whole of onboarding one).
* Refused without `force` when the project already has a layout: that file is
diff --git a/include/config.h b/include/config.h
index 5aefd01..969136a 100644
--- a/include/config.h
+++ b/include/config.h
@@ -390,7 +390,7 @@ typedef struct {
char *shader_dir;
/* Where projects live: `project_roots "~/dev" "~/work" depth=2`. A project is
- * a subdirectory of one of these with a `slosh.layout.kdl` in it -- or a
+ * a subdirectory of one of these with a `slosh.layout` in it -- or a
* `.git`, which gets `project_layout` instead. Empty means the feature is
* dormant and costs nothing.
*
diff --git a/include/project.h b/include/project.h
index 6bf3021..4cf3bf6 100644
--- a/include/project.h
+++ b/include/project.h
@@ -18,9 +18,15 @@
#include <stdint.h>
/* The file a project uses to say what it needs. One name, so there is no
- * precedence question: a layout file by D2's rule, checked by `--check`, and
- * highlighted by anything that knows KDL. */
-#define PROJECT_LAYOUT_FILE "slosh.layout.kdl"
+ * precedence question. `.layout` rather than `.kdl`: zellij speaks the same
+ * syntax under the same extension with a different schema, and an extension
+ * that names the wrong owner is worse than one that does not name the
+ * parser -- the file says what it is, `--check` says how it was read. */
+#define PROJECT_LAYOUT_FILE "slosh.layout"
+/* The spelling this replaced. Still *found* by the project scan, so nobody's
+ * checked-in workspace vanishes on upgrade; everything slosh writes is the
+ * new name, and the new name wins where both exist. */
+#define PROJECT_LAYOUT_FILE_OLD "slosh.layout.kdl"
/* How many projects one session will look at. A picker is not a filesystem
* browser: past this many the answer to "which project" is a search, not a
diff --git a/src/app_session.c b/src/app_session.c
index a62d4b3..0b228ce 100644
--- a/src/app_session.c
+++ b/src/app_session.c
@@ -228,7 +228,7 @@ bool app_apply_layout_text(app_t *a, const char *text, bool replace, char *err,
bool app_apply_layout_file(app_t *a, const char *path, bool replace, char *err,
size_t errcap) {
- /* Expanded here rather than left to a shell: `--layout "~/x.layout.kdl"` in
+ /* Expanded here rather than left to a shell: `--layout "~/x.layout"` in
* quotes, and every path arriving over the control socket, reach fopen with
* the tilde still on them. */
char pathbuf[1024], dirbuf[1024];
diff --git a/src/config.c b/src/config.c
index 10fe1e9..6060479 100644
--- a/src/config.c
+++ b/src/config.c
@@ -1592,7 +1592,7 @@ char *config_render(const config_t *c) {
if (c->project_layout)
cb_qstr(&b, "project_layout", c->project_layout, NULL);
else
- cb_add(&b, "// project_layout \"~/.config/slosh/project.layout.kdl\"\n");
+ cb_add(&b, "// project_layout \"~/.config/slosh/project.layout\"\n");
cb_add(&b, "\n// ---- colour ----\ntheme {\n");
for (size_t i = 0; i < sizeof THEME_COLORS / sizeof *THEME_COLORS; i++)
diff --git a/src/main.c b/src/main.c
index f3fdd12..b488e56 100644
--- a/src/main.c
+++ b/src/main.c
@@ -48,7 +48,13 @@ static bool looks_like_layout(const char *path) {
char buf[1024];
kdl_node_t *root =
kdl_parse_file(path_expand(path, buf, sizeof buf), NULL, 0);
- if (!root) return strstr(path, ".layout.") != NULL;
+ if (!root) {
+ /* `x.layout` is the spelling, `x.layout.kdl` the one it replaced: both
+ * are somebody's layout, whatever it was that would not parse. */
+ size_t n = strlen(path), s = strlen(".layout");
+ if (n >= s && strcmp(path + n - s, ".layout") == 0) return true;
+ return strstr(path, ".layout.") != NULL;
+ }
bool layout = false;
for (size_t i = 0; i < root->nkids && !layout; i++) {
const char *name = root->kids[i] ? root->kids[i]->name : NULL;
diff --git a/src/project.c b/src/project.c
index 9146971..296cb25 100644
--- a/src/project.c
+++ b/src/project.c
@@ -81,6 +81,13 @@ static bool describe(const char *path, project_t *p) {
p->mtime = (int64_t)lst.st_mtime;
return true;
}
+ /* The old spelling, found but never written: see PROJECT_LAYOUT_FILE_OLD. */
+ if (exists(p->path, PROJECT_LAYOUT_FILE_OLD, &lst)) {
+ snprintf(p->layout, sizeof p->layout, "%s/%s", p->path,
+ PROJECT_LAYOUT_FILE_OLD);
+ p->mtime = (int64_t)lst.st_mtime;
+ return true;
+ }
return exists(p->path, ".git", NULL);
}
diff --git a/tests/test_config.py b/tests/test_config.py
index cb80829..84d73c7 100644
--- a/tests/test_config.py
+++ b/tests/test_config.py
@@ -713,8 +713,8 @@ def test_the_shipped_files_are_what_they_claim():
check(
"config/config.kdl lints clean", conf.returncode == 0, repr(conf.stderr[:160])
)
- lay = root / "config" / "example.layout.kdl"
- check("the example layout is named `*.layout.kdl`", lay.exists(), str(lay))
+ lay = root / "config" / "example.layout"
+ check("the example layout is named `*.layout`", lay.exists(), str(lay))
exl = subprocess.run([BIN, "--check", str(lay)], capture_output=True, text=True)
check("and it lints clean as a layout", exl.returncode == 0, repr(exl.stderr[:200]))
out = subprocess.run(
diff --git a/tests/test_layout_files.py b/tests/test_layout_files.py
index 7bc8285..611c83d 100644
--- a/tests/test_layout_files.py
+++ b/tests/test_layout_files.py
@@ -287,7 +287,7 @@ def test_bad_layouts():
r = s.api("apply-layout", kdl="layout { }")
check("a layout with no tabs is refused", not r["ok"], str(r))
- r = s.api("apply-layout", path="/nonexistent/layout.kdl")
+ r = s.api("apply-layout", path="/nonexistent/x.layout")
check("a missing file is refused", not r["ok"], str(r))
check(
diff --git a/tests/test_portable_layouts.py b/tests/test_portable_layouts.py
index 5b3ccc0..12229ba 100644
--- a/tests/test_portable_layouts.py
+++ b/tests/test_portable_layouts.py
@@ -27,7 +27,7 @@ def project(name, text):
root = tempfile.mkdtemp(prefix="slosh-proj-")
d = os.path.join(root, name)
os.makedirs(os.path.join(d, "src"))
- path = os.path.join(d, "slosh.layout.kdl")
+ path = os.path.join(d, "slosh.layout")
with open(path, "w") as f:
f.write(text)
return d, path
@@ -234,7 +234,7 @@ layout {
)
with Session(SH, layout=path) as s:
first = s.api("dump-layout", tab=s.tabs()[0]["id"], relative_to=d)["kdl"]
- again = os.path.join(d, "again.layout.kdl")
+ again = os.path.join(d, "again.layout")
with open(again, "w") as f:
f.write(first)
with Session(SH, layout=again) as s2:
@@ -278,7 +278,7 @@ layout {
check("it names: " + want, want in said, said)
check(
"every problem carries a file and a line",
- said.count("slosh.layout.kdl:") >= 6,
+ said.count("slosh.layout:") >= 6,
said,
)
@@ -325,7 +325,7 @@ def test_a_syntax_error_in_a_layout_is_reported_as_the_layout_it_is():
code, said = lint(path)
check(
"it says which file and which line the syntax broke on",
- "slosh.layout.kdl:" in said and "unclosed" in said,
+ "slosh.layout:" in said and "unclosed" in said,
said,
)
check(
diff --git a/tests/test_workspaces.py b/tests/test_workspaces.py
index 3a0163d..d691fa2 100644
--- a/tests/test_workspaces.py
+++ b/tests/test_workspaces.py
@@ -1,6 +1,6 @@
"""Workspaces: projects on disk, and the tabs they open as.
-A *project* is a directory somebody works in -- one with a `slosh.layout.kdl`
+A *project* is a directory somebody works in -- one with a `slosh.layout`
saying what it needs, or a `.git` and nothing said yet. A *workspace* is the tab
it occupies here, and membership is that tab's `purpose` in the `project:`
namespace, so there is no second answer to "what is this tab" and a dumped
@@ -48,7 +48,7 @@ def roots(**projects):
if what == "git":
os.makedirs(os.path.join(d, ".git"), exist_ok=True)
elif what:
- with open(os.path.join(d, "slosh.layout.kdl"), "w") as f:
+ with open(os.path.join(d, "slosh.layout"), "w") as f:
f.write(what)
cfg = os.path.join(base, "config.kdl")
with open(cfg, "w") as f:
@@ -70,6 +70,32 @@ def session(cfg, argv=None, **kw):
# ---- discovery -------------------------------------------------------------
+def test_the_old_layout_spelling_is_still_found_never_preferred():
+ """`slosh.layout.kdl` was the name before the extension collided with
+ zellij's. A checked-in workspace must not vanish on upgrade, so the scan
+ still finds the old spelling -- and where both exist, the new one wins,
+ because two files disagreeing needs one answer."""
+ base, dev, cfg = roots(old=None, both=None)
+ with open(os.path.join(dev, "old", "slosh.layout.kdl"), "w") as f:
+ f.write(API_LAYOUT)
+ with open(os.path.join(dev, "both", "slosh.layout"), "w") as f:
+ f.write(API_LAYOUT)
+ with open(os.path.join(dev, "both", "slosh.layout.kdl"), "w") as f:
+ f.write(API_LAYOUT)
+ with session(cfg) as s:
+ got = {w["name"]: w for w in s.api("workspaces")["workspaces"]}
+ check(
+ "a project with only the old name is still a project",
+ "old" in got and got["old"]["layout"].endswith("slosh.layout.kdl"),
+ str(got.get("old")),
+ )
+ check(
+ "where both spellings exist the new one wins",
+ "both" in got and got["both"]["layout"].endswith("/slosh.layout"),
+ str(got.get("both")),
+ )
+
+
def test_a_project_is_a_layout_file_or_a_git():
"""Both, because `~/dev` with forty checkouts and three layout files would
otherwise be a picker with three rows -- and a `.git` is exactly the project
@@ -82,7 +108,7 @@ def test_a_project_is_a_layout_file_or_a_git():
check("a directory that is neither is not listed", "notes" not in got, str(got))
check(
"the declared one names its file",
- got["api"]["layout"].endswith("slosh.layout.kdl"),
+ got["api"]["layout"].endswith("slosh.layout"),
str(got["api"]),
)
check(
@@ -208,7 +234,7 @@ def test_a_project_with_no_layout_opens_as_your_project_layout():
bind to whichever project is opening -- not to the directory the file lives
in, which would open every project in ~/.config."""
base, dev, cfg = roots(web="git")
- shared = os.path.join(base, "project.layout.kdl")
+ shared = os.path.join(base, "project.layout")
with open(shared, "w") as f:
f.write('layout { tab { pane purpose="agent:main"; pane cwd="src" } }\n')
with open(cfg, "a") as f:
@@ -303,7 +329,7 @@ def test_saving_a_tab_writes_a_portable_layout_file():
saved = s.api("save-workspace")
check(
"it says where it wrote",
- saved["path"] == os.path.join(dev, "web", "slosh.layout.kdl"),
+ saved["path"] == os.path.join(dev, "web", "slosh.layout"),
str(saved),
)
check(
@@ -554,7 +580,7 @@ def test_every_verb_has_a_bare_form():
wrote = bare1(s, "save-workspace")
check(
"save-workspace names the file it wrote",
- "slosh.layout.kdl" in wrote,
+ "slosh.layout" in wrote,
repr(wrote),
)
check(
@@ -588,7 +614,7 @@ def test_a_dumped_session_restores_workspace_membership():
with session(cfg) as s:
r = s.api("open-workspace", name="api")
whole = s.api("dump-layout")["kdl"]
- restored = os.path.join(base, "session.layout.kdl")
+ restored = os.path.join(base, "session.layout")
with open(restored, "w") as f:
f.write(whole)
with Session(SH, config=cfg, layout=restored, cols=100, rows=30) as s2:
@@ -609,7 +635,7 @@ def test_the_picker_lists_projects_and_opens_one():
s.key("w")
screen = s.snapshot().screen()
check("it is titled as projects", "projects" in screen, screen)
- check("a declared project shows its file", "slosh.layout.kdl" in screen, screen)
+ check("a declared project shows its file", "slosh.layout" in screen, screen)
check("and one without says so", "no layout" in screen, screen)
s.send("web")
@@ -649,11 +675,11 @@ def test_saving_from_the_keyboard_says_what_it_did():
s.api("open-workspace", name="web")
s.key("W")
screen = s.snapshot().screen()
- check("the toast names the file", "slosh.layout.kdl" in screen, screen)
+ check("the toast names the file", "slosh.layout" in screen, screen)
check("and counts what it wrote", "1 pane" in screen, screen)
check(
"the file is there",
- os.path.exists(os.path.join(dev, "web", "slosh.layout.kdl")),
+ os.path.exists(os.path.join(dev, "web", "slosh.layout")),
screen,
)