205 lines
14 KiB
Markdown
205 lines
14 KiB
Markdown
# spacesh M2 — design spec
|
||
|
||
> Slice: **M2 — layouts & workspaces** (split tree, LayoutEngine, resize, disk persistence, multi-workspace sidebar with UX-metadata, presets, wizard).
|
||
> Builds on M0+M1 (shipped). Base spec: `DOCS/MAIN.md` §8. Prior slice spec: `DOCS/superpowers/specs/2026-06-09-spacesh-m0-m1-design.md`.
|
||
> Date: 2026-06-09.
|
||
|
||
---
|
||
|
||
## 1. Scope
|
||
|
||
**In (decided in brainstorm):**
|
||
- **Split tree: n-ary** (`Split { orient, ratios, children[] }` + `Leaf { surface_id }`). Maps directly onto presets (3, 4, 2×3, 2×4); resize = editing one node's `ratios`.
|
||
- **Daemon owns the layout tree** (single source of truth, per `DOCS/MAIN.md` §2). GUI renders it and sends commands; CLI parity preserved. No GUI-local layout state.
|
||
- **Disk persistence: single `~/.spacesh/state.json`** behind a `StateStore` trait, atomic write (temp+fsync+rename), debounced ~500ms. SQLite swap is a later, localized change.
|
||
- **Cold daemon start restores structure** from `state.json`; panels come back **`stopped`** (no PTY) unless `autostart` is set (per-surface flag or global `[daemon] autostart_surfaces`, default off → restart on demand).
|
||
- **UX-metadata (§8.5):** colored workspace groups, "не забыть" unread flag, custom order (drag-reorder of workspaces and groups).
|
||
- **10 layout presets** (§8.2) + `apply_preset`. **Wizard** (folder → preset → agent-per-slot → `apply_preset`).
|
||
- New surface lifecycle state **`stopped`** (in tree, no actor) vs **`running`** (has actor). `exit` now transitions `running`→`stopped` (formalizes M1's "stays visible").
|
||
|
||
**Out (later slices):**
|
||
- Status detection / rings colored by agent state (`set_state`, hooks, OSC 133) — **M3**. The sidebar/panel status ring is a placeholder in M2 (aggregate running/stopped only).
|
||
- Auto-unread driven by agent events — M3 (M2 unread is set on creation / manually, cleared on visit).
|
||
- Zoom-panel, scrollback search, CodeMirror diff view, external notifications — **M5**. Remote — **M6**. Auth/account — separate milestone.
|
||
|
||
---
|
||
|
||
## 2. Crate & file changes
|
||
|
||
`spacesh-core` grows from a flat panel set to a layout tree (still I/O-free, unit-testable):
|
||
|
||
```
|
||
Workspace { id: WorkspaceId, path, name, group_id: Option<GroupId>, order: u32,
|
||
unread: bool, layout: LayoutNode, surfaces: Map<SurfaceId, SurfaceSpec> }
|
||
|
||
enum LayoutNode {
|
||
Leaf { surface_id: SurfaceId },
|
||
Split { orient: Orient /* H | V */, ratios: Vec<f32>, children: Vec<LayoutNode> },
|
||
}
|
||
|
||
SurfaceSpec { command: String, args: Vec<String>, cwd: PathBuf,
|
||
agent_label: Option<String>, cols: u16, rows: u16, autostart: bool }
|
||
|
||
Group { id: GroupId, name: String, color: String, order: u32 }
|
||
```
|
||
|
||
| File (new/changed) | Responsibility |
|
||
|---|---|
|
||
| `crates/spacesh-core/src/layout.rs` (new) | `LayoutNode`, `Orient`; ops: `insert_split`, `remove_leaf` (collapse + single-child promote), `set_ratios` (normalize + clamp), `move_leaf`, `find_path`/addressing; the 10 preset generators. Pure, serde. |
|
||
| `crates/spacesh-core/src/workspace.rs` (new) | `Workspace`, `Group`, `SurfaceSpec`, `WorkspaceId`/`GroupId` newtypes (or reuse proto ids), meta mutations. Pure, serde. |
|
||
| `crates/spacesh-core/src/lib.rs` | re-export layout + workspace. |
|
||
| `crates/spaceshd/src/registry.rs` | own `Vec<Workspace>` + `Vec<Group>` (structure) over the M0+M1 actor map (live surfaces); track `running`/`stopped` per surface; dispatch tree ops to `spacesh-core`. |
|
||
| `crates/spaceshd/src/state_store.rs` (new) | `StateStore` trait + `JsonStateStore` (atomic temp+rename, corrupt-file backup). |
|
||
| `crates/spaceshd/src/persist.rs` (new) | debounce scheduler: dirty signal → ~500ms timer → one `save`. |
|
||
| `crates/spaceshd/src/server.rs` | dispatch the new commands; emit the new events; restore on cold start. |
|
||
| `crates/spaceshd/src/surface.rs` | support `stopped` (actor absent) + `restart` from `SurfaceSpec`. |
|
||
| `app/src/LayoutEngine.tsx` (new) | recursive split-tree render, splitter drag → `set_ratios`, stopped-panel restart overlay, geometry-based focus hotkeys. |
|
||
| `app/src/Sidebar.tsx` (new) | groups + workspaces, drag-reorder, unread, counts, context menu. |
|
||
| `app/src/PresetPicker.tsx` (new) | 10 preset thumbnails (used by toolbar + wizard). |
|
||
| `app/src/Wizard.tsx` (new) | folder → preset → agent-per-slot → `apply_preset`. |
|
||
| `app/src/App.tsx`, `socketBridge.ts` | wire new commands/events; subscribe `layout_changed`/`workspace_changed`/`groups_changed`/`surface_restarted`. |
|
||
|
||
`SurfaceSpec` carries everything to recreate a panel, so cold start restores structure without live processes.
|
||
|
||
---
|
||
|
||
## 3. Protocol additions
|
||
|
||
Layered on the M0+M1 subset; same envelope (`req`/`res`/`evt`, length-prefixed JSON).
|
||
|
||
### New commands
|
||
|
||
| Command | Args | Res | Purpose |
|
||
|---|---|---|---|
|
||
| `split_surface` | `{ surface_id, dir: "right"\|"down", command?, args? }` | `{ surface_id }` | split a panel, create the neighbor (running) |
|
||
| `close` (extended) | `{ surface_id }` | `{}` | kill PTY + **collapse** the tree node (parent ratios recomputed, single-child promoted) |
|
||
| `set_ratios` | `{ workspace_id, node_path: [u32], ratios: [f32] }` | `{}` | resize: one split node's ratios; node addressed by child-index path from root |
|
||
| `move_surface` | `{ surface_id, target_surface_id, edge: "left"\|"right"\|"top"\|"bottom" }` | `{}` | drag a panel to a new tree position |
|
||
| `apply_preset` | `{ workspace_id, preset_id, slots: [{ command?, args? }] }` | `{ surface_ids: [...] }` | build the preset tree + spawn panels per slot |
|
||
| `restart_surface` | `{ surface_id }` | `{}` | re-spawn PTY from `SurfaceSpec` for a `stopped` panel |
|
||
| `close_workspace` | `{ workspace_id }` | `{}` | close a workspace (live-panel confirmation is GUI-side) |
|
||
| `set_workspace_meta` | `{ workspace_id, name?, group_id?, unread?, order? }` | `{}` | name / group / unread / order |
|
||
| `create_group` | `{ name, color }` | `{ group_id }` | new colored group |
|
||
| `set_group` | `{ group_id, name?, color?, order? }` | `{}` | edit group |
|
||
| `delete_group` | `{ group_id }` | `{}` | delete group (members become ungrouped) |
|
||
|
||
### New events (push, multi-client sync)
|
||
|
||
| Event | Data | Purpose |
|
||
|---|---|---|
|
||
| `layout_changed` | `{ workspace_id, layout }` | tree changed (split/close/move/ratios/preset) |
|
||
| `workspace_changed` | `{ workspace }` | workspace meta changed or workspace created |
|
||
| `workspace_closed` | `{ workspace_id }` | workspace closed |
|
||
| `groups_changed` | `{ groups: [...] }` | groups created/edited/reordered/deleted |
|
||
| `surface_restarted` | `{ surface_id }` | a `stopped` panel is `running` again |
|
||
|
||
### Changed
|
||
|
||
`status` now returns workspaces with full `layout` tree, `groups[]`, and per-surface `running`/`stopped` + `SurfaceSpec`. `surface_created` / `surface_closed` retained. **`exit` semantics:** the panel is kept and transitions `running`→`stopped` (no longer removed); the tree is unchanged.
|
||
|
||
**Addressing:** leaves by `surface_id`; split nodes (for `set_ratios`) by `node_path` (vec of child indices from root). `move_surface` uses target `surface_id` + `edge`.
|
||
|
||
---
|
||
|
||
## 4. Persistence
|
||
|
||
`StateStore` trait isolates the backend (SQLite swap later stays localized):
|
||
|
||
```rust
|
||
trait StateStore {
|
||
fn load(&self) -> Result<PersistState>;
|
||
fn save(&self, state: &PersistState) -> Result<()>; // atomic
|
||
}
|
||
```
|
||
|
||
`~/.spacesh/state.json` — snapshot of structure (NOT live processes):
|
||
|
||
```jsonc
|
||
{
|
||
"version": 1,
|
||
"groups": [{ "id": "g_1", "name": "production", "color": "#F4544E", "order": 0 }],
|
||
"workspaces": [{
|
||
"id": "w_1", "path": "~/infra-platform", "name": "infra-platform",
|
||
"group_id": "g_1", "order": 0, "unread": false,
|
||
"layout": { "split": { "orient": "v", "ratios": [0.5, 0.5], "children": [
|
||
{ "leaf": { "surface_id": "s_1" } },
|
||
{ "split": { "orient": "h", "ratios": [0.5, 0.5], "children": [
|
||
{ "leaf": { "surface_id": "s_2" } }, { "leaf": { "surface_id": "s_3" } } ] } } ] } },
|
||
"surfaces": {
|
||
"s_1": { "command": "claude", "args": [], "cwd": "~/infra-platform",
|
||
"agent_label": "claude", "cols": 80, "rows": 24, "autostart": false }
|
||
}
|
||
}]
|
||
}
|
||
```
|
||
|
||
- **Write:** atomic (`state.json.tmp` → fsync → rename), **debounced ~500ms** after any structural/meta change; bursts coalesce into one `save` (scheduler in `persist.rs`: dirty channel → timer → save).
|
||
- **Cold start** (no live sessions): `load` → restore groups/workspaces/trees/`SurfaceSpec`. All panels `stopped`. If a surface's `autostart == true` or global `[daemon] autostart_surfaces` is set → immediately `restart_surface`. Default → `stopped`.
|
||
- **`stopped` lifecycle:** panel present in the tree and in `status` with a `stopped` flag, no actor/PTY. `restart_surface` spawns the PTY from `SurfaceSpec`, marks `running`, emits `surface_restarted`. `exit` → `running`→`stopped` (panel + tree preserved).
|
||
- **Not persisted:** live grids / scrollback / snapshots (ephemeral; screen restoration is M1 live-reattach only — survives GUI death, not a cold daemon restart).
|
||
- **Corrupt `state.json` on load:** rename to `state.json.corrupt-<ts>`, log, start empty.
|
||
|
||
---
|
||
|
||
## 5. Frontend
|
||
|
||
**`LayoutEngine.tsx`** — recursive render of `LayoutNode`:
|
||
- `Split` → flex container (`orient` h/v), children grow per `ratios`, splitter handles between children (drag → `set_ratios`, throttled ~30ms during drag, final on mouseup; col/row-resize cursor).
|
||
- `Leaf` → M0+M1 `TerminalView` by `surface_id`. `stopped` panel → overlay "Process exited · ⏎ Restart" calling `restart_surface`.
|
||
- Hotkeys (`DOCS/MAIN.md` §11): split `⌘⇧T` (`split_surface dir=right`), neighbor focus `⌘⌥←↑→↓` (geometry-based over the tree), close panel.
|
||
- Reacts to `layout_changed` for live multi-client sync; no GUI-local layout state.
|
||
|
||
**`Sidebar.tsx`** (§8.5):
|
||
- Groups (color swatch + name + chevron) with workspaces beneath. Workspace row: status ring (M2 placeholder: aggregate running/stopped color), name, unread dot, panel count.
|
||
- Drag-reorder of workspaces (incl. across groups) → `set_workspace_meta { order, group_id }`; drag groups → `set_group { order }`.
|
||
- Selecting a workspace makes it active and clears unread (`set_workspace_meta unread=false`). Context menu on group: rename / color / delete.
|
||
- `+ New workspace` (`⌘N`) → Wizard.
|
||
|
||
**`PresetPicker` + `Wizard`** (mockups already approved in `DOCS/space-sh.pen`):
|
||
- 10 presets §8.2: `1, 2↔, 2↕, 2+1, 1+2, 3, 2×2, 4, 2×3, 2×4` — each a `LayoutNode` generator (pure fn in `spacesh-core/layout.rs`, shared by daemon).
|
||
- Wizard: folder (`open`) → preset → agent per slot → `apply_preset`. Center toolbar presets re-split the active workspace via `apply_preset`.
|
||
|
||
**States** (Web App guide §6): empty workspace (no panels → preset CTA), stopped panel (restart overlay), empty sidebar (no workspaces → onboarding CTA).
|
||
|
||
---
|
||
|
||
## 6. Errors, tree edge-cases, testing
|
||
|
||
**Tree edge-cases** (core correctness, `spacesh-core` unit tests):
|
||
- `close` last leaf of a split → node collapses, parent ratios recomputed; closing the last panel of a workspace → empty tree (preset CTA).
|
||
- `close` that leaves a split with one child → node replaced by that child (no dangling single-child splits).
|
||
- `set_ratios`: `ratios.len() == children.len()`, sum normalized to 1.0, min-clamp (panel can't collapse to 0; floor e.g. 0.05).
|
||
- `move_surface`: remove (with collapse) + insert by `edge` at target leaf; forbid moving onto itself; moving the sole leaf is a no-op.
|
||
- `apply_preset` over a non-empty workspace: kills current panels (GUI confirms) → builds new tree.
|
||
- out-of-range `node_path` / unknown `surface_id`/`workspace_id`/`group_id` → `NOT_FOUND`.
|
||
|
||
**Protocol errors:** invalid `preset_id` → `BAD_REQUEST`; `restart_surface` on a `running` surface → no-op `ok`; `set_ratios` with wrong length → `BAD_REQUEST`. Persist disk failure → log, best-effort, never crashes the daemon; corrupt `state.json` on load → backup + empty start.
|
||
|
||
**Tests:**
|
||
|
||
| Level | What |
|
||
|---|---|
|
||
| `spacesh-core/layout` (unit) | split/close/collapse/single-child-promote; `set_ratios` normalize+clamp; `move_leaf` for all 4 edges; all 10 preset generators (tree shape); `LayoutNode` serde round-trip |
|
||
| `spacesh-core/workspace` (unit) | group/order/unread mutations; `SurfaceSpec` serde round-trip |
|
||
| `spaceshd/state_store` (unit) | save→load round-trip; atomic (tmp+rename); corrupt json → backup + empty |
|
||
| `spaceshd/persist` (unit) | debounce coalesces a burst into one save |
|
||
| `spaceshd` (integration, serial-guard as in M1) | open→apply_preset→status tree; split→close collapses; restart_surface revives stopped; cold daemon restart restores structure (panels stopped); move_surface |
|
||
| `app` (manual) | mouse split/resize; sidebar drag-reorder; wizard→apply_preset; restart stopped panel; daemon restart → structure intact |
|
||
|
||
**Budgets:** `set_ratios` during drag throttled ~30ms; persist debounce 500ms; structure restore on daemon start < 200ms on a typical config.
|
||
|
||
---
|
||
|
||
## 7. Implementation order (within the slice)
|
||
|
||
1. `spacesh-core/layout.rs` — `LayoutNode`, ops, preset generators + tests.
|
||
2. `spacesh-core/workspace.rs` — `Workspace`/`Group`/`SurfaceSpec` + meta + tests.
|
||
3. `spacesh-proto` — new command/event variants + serde tests.
|
||
4. `spaceshd/state_store.rs` + `persist.rs` — persistence + tests.
|
||
5. `spaceshd` registry/surface — workspace structure, `stopped`/`restart`, tree dispatch.
|
||
6. `spaceshd/server.rs` — new commands/events, cold-start restore + integration tests.
|
||
7. `app` — `LayoutEngine`, splitter resize, stopped overlay.
|
||
8. `app` — `Sidebar` (groups/unread/drag-reorder), `PresetPicker`, `Wizard`, bridge wiring.
|
||
|
||
End of slice: multi-workspace, n-ary split grids resizable by mouse, presets + wizard, layout & metadata persisted, cold daemon restart restores structure (panels stopped, restart on demand).
|