# Web shell: one sidebar (S1) — playbook

Branch `web-shell-sidebar`, cut from `dioxus-web-shell`. The worklog lives in
`todo.md` (nit 14 and what follows it); this document is the plan and the
decisions, updated as phases land.

## Why

The web shell had grown five places to look — the hamburger's document menu,
the breadcrumb, the gear's popover, the navigator (History, Parts) and ⌘K —
and a document list would have added a sixth. Three whole-screen structures
were sketched (design canvas, page "Structure, round 3":
https://claude.ai/artifact/LoHxGQ9zXmHZKdRnab97Ey). Decided 2026-09-15:

> Go with S1. It feels the most familiar, and will probably lead to a simpler
> learning curve.

Refinements the same day:

- The sidebar's panels **float over the diagram** rather than pushing it
  aside, so the bottom toolbar never moves.
- The toolbar keeps the S1 sketch's icons.
- Tools run from most to least used, left to right: **Select, New block, Add
  block pin, Route, Add icon, Add sheet port, Add text, Comment** (Add text
  beside Comment, both being annotations).
- The web shell goes first; the egui desktop shell follows in a later pass, at
  rough parity meanwhile.

## The shape

| Region | Treatment | Contents |
|---|---|---|
| Top bar | docked, flat | the breadcrumb (document chip as its root) · undo, redo, go up, fit |
| Activity bar | docked, flat, left edge under the top bar | Diagrams, Parts, History; Settings at its foot |
| Sidebar panel | floating glass over the diagram, beside the activity bar — translucent and blurred like the toolbar, so the diagram shows through | the one section the activity bar has open |
| Toolbar | floating, bottom centre | the eight tools, in use order |
| Status line | plain text, bottom right | unchanged content; moved out from under the panel |
| Notices | top right, under undo, redo, fit | unchanged content; moved out from under the panel |
| Selection overlay, ⌘K | unchanged | |

Gone: the hamburger and its document menu, the gear and its popover, Browse,
the right-hand navigator.

Every non-editing thing has one address. ⌘K still reaches anything by name.

## Spec changes (`docs/cad-ui-spec.md`)

Amended in P0, before any code, so the code is built against the spec it
claims:

- **§2 Frame**: the three regions become top bar, activity bar with its
  floating panel, and the bottom toolbar. The elevation rule stands: the
  activity bar is docked chrome; the panel and the toolbar are floating.
- **§2.0 Top bar**: left is the breadcrumb; right is undo, redo, fit. No
  document menu, no Browse.
- **§2.1 Safe insets**: the open panel and the bottom toolbar are measured
  bands like the rail and the navigator were.
- **§4.1 / §4.2**: document switching happens in the Diagrams section, which is
  also where "opening replaces this diagram" is said.
- **§8 Navigator** becomes **§8 Sidebar**. Parts and History keep every rule
  they had (one form at every size, every pick completes a hand-off and leaves
  the panel open, only working dismisses it, Escape closes it first). The
  "nothing in it mutates the document" rule stays true of Parts and History;
  Diagrams and Settings are declared as the sections that act on documents and
  preferences.
- **§5 Tools**: the band order, as above.

## Phases

Each phase is one commit, passes `cargo xtask ci`, and is walked in Chrome.
What each has to prove is listed with it.

### P0 — Branch, playbook, spec — done

Cut the branch, commit this playbook and the spec amendments.

### P1 — Tool order and faces (shared) — done

- Reorder `BAND_TOOLS` (`crates/editor/src/names.rs`). It is the one order: the
  web rail, the desktop band, the registry and the digit bindings all read it.
  **Behaviour change on both shells**: the digit shortcuts follow the new
  order (1 Select … 8 Add image), and the desktop's band reorders now.
- Replace the tool faces in `icons/` with the S1 sketch's (select, block,
  area, port, pin, image, text, route), in the set's own style (24 px grid,
  stroke). The desktop draws the same files, so its faces change too.
- Prove: the registry and binding tests (`every_toolbar_tool_is_bound_and_no_
  chord_is_shared` and friends) against the new order; the desktop's kittest
  pictures and the web snapshots regenerated and their diffs reviewed.

### P2 — The bottom toolbar (web) — done

- `tool_cluster.rs`: horizontal, floating, bottom centre of the viewport.
  Select first, then a rule, then the rest, as today.
- It measures itself as `Band::Rail` from the bottom edge, so a fit clears it.
- The status line moves to the bottom right (`status_line.rs`), the notice
  stack to the top right (`notices.rs`), and the confirmation toast, which sits
  bottom centre today, rises above the toolbar. Check none of them overlaps the
  toolbar or an open panel at 1024 px and at a phone width.
- Prove: a fit leaves the diagram clear of the toolbar (the existing safe-region
  tests, with the band moved); the walk's tool presses still arm tools.

### P3 — Activity bar and the floating panel (web) — done

- New `sidebar.rs`: the bar, one cell per section, the open one marked;
  pressing the open one shuts the panel. It also hosts the panel: left edge,
  beside the activity bar, floating glass (no reflow), the dismissal rules of
  §8, measured as `Band::Sheet` from the left. `sheet.rs` keeps Parts and
  History as the panel's content.
- Parts and History move in unchanged. The right-hand navigator and Browse go.
- Prove: the navigator walk checks, re-aimed at the sidebar (a tree row selects
  and leaves the panel open; a press on the diagram dismisses it; Escape closes
  it first); the toolbar's position is unchanged with the panel open.

### P4 — Settings section (web) — done

- The approved Preferences (built in `settings.rs`) move from the popover into
  the Settings section. The gear goes.
- Prove: the nits probe's Preferences checks (three modes, six schemes, four
  faces, a pick takes), aimed at the section.

### P5 — Diagrams section (web) — done

- Built from the approved hi-fi mockup of the section (design canvas, page
  "S1: Diagrams section").
- This diagram at the top: name (rename in place), save state, Export SVG /
  PNG / PDF / .bwx.zip, Delete. Then search, New diagram, Import .bwx.zip, and
  every diagram the browser holds, newest first, the current one marked, each
  row's menu offering Rename / Export / Delete.
- "Edited … · rev N" needs each container's newest manifest row: a small
  library read (`blockworx-opfs` / `blockworx-store`), cached per listing.
- The hamburger and its document menu go; their doors (New, Open, Import,
  Export, Rename, Delete) are all here.
- The breadcrumb's root segment opens this section.
- Prove: the storage walk (reload lands on a newborn, the earlier document
  opens from the Diagrams section, its rev survived, a second tab is refused
  the lock) re-aimed at the section; export and import through it.

### P6 — Top bar and cleanup (web) — done

- Top bar: breadcrumb left; undo, redo, go up, fit right. The time-machine's
  amber mode is unchanged.
- Delete what nothing reaches any more (`top_bar.rs`'s document menu, the
  gear's popover shell, Browse); `cargo xtask ci`'s grep gates still pass.
- Prove: the whole walk (Chrome and Firefox), the snapshots reviewed, and a
  last pass of the nits probe.

### Later — the desktop (egui) shell

A pass of its own, porting the same structure onto `src/shell/*`, with a
playbook of its own.

## Settled along the way

- **"Add icon"** in the tool order is today's image cell (the rail's
  `AddImage`, which places artwork as an image of its own), not the block
  verb that adds an icon to a block. (2026-09-15)
- **The Diagrams section gets a hi-fi mockup before P5 builds it**, in the
  S1 sidebar, light and dark; the other phases do not wait for it.
  (2026-09-15)

- **The toolbar has three sections** — Select | the block tools (New block,
  Add block pin, Route) | the sheet tools (Add sheet port, Add text, Comment,
  Add image) — with a rule between each. The group is data on `BAND_TOOLS`, so
  every shell rules the same boundaries. On the web the sheet tools fold into
  one cell (design canvas round 5, option B): it wears the sheet tool used
  last, a press arms that one again, and its caret (or a long press) opens all
  four with their keys. Digits run in bar order, 1 Select … 8 Add image.
  (2026-09-15)

- **Go up stays on the top bar**, beside fit. It left with the rest of the
  right side when the bar was trimmed, and the user asked for it back: the
  breadcrumb names levels but says nothing about stepping out of one.
  (2026-09-15)
- **The root segment opens Diagrams** while the canvas stands at the top
  level; below it, the same press still goes back up to the top. A double
  click renames either way. (2026-09-15)
- **A row's menu renames only this tab's diagram, for now.** The rename box is
  the breadcrumb's, and a row would need one of its own; the storage can
  rename a closed container, so it is a follow-up in `todo.md`, not a limit.
  Export and Delete work on any row, and Delete refuses a diagram another tab
  has open. (2026-09-15)

## Open

- Keyboard entries for the sections (e.g. a chord per section) — not decided;
  ⌘K reaches them meanwhile.