@azure-id/orc 1.4.0 → 1.4.1

package/bin/webui/js/panels/hookui.js

@@ -14,27 +14,35 @@
    (templates/hooks/orc-statusline-render.js), so the two cannot diverge.
 
    THE PANEL DERIVES NOTHING. Not a component id, not a renderer name, not a
-   glyph set, not a ramp, not a colour token, not a state word, not the board's
-   own rules. All of it arrives from `statusline components --json`, and a test
-   greps this file and both string tables for those literals. (The Flow-stepper
-   rule, on a fourth surface.)
-
-   Loaded by app.html in the order its numeric prefix names. Classic script,
-   no import/export: an ES module import carries no query string, and every
-   static request here needs the per-launch session token. */
+   glyph set, not a ramp, not a colour token, not a separator, not a state word,
+   not the board's own rules. All of it arrives from `statusline components
+   --json`, and a test greps this file and both string tables for those
+   literals. (The Flow-stepper rule, on a fourth surface.)
+
+   v1.4.1 — THE BOARD IS THE ONLY PLACE ANYTHING IS APPLIED, AND EVERY WRITE'S
+   POSITION IS COMPUTED WHEN THAT WRITE RUNS. The list of parts used to carry
+   three `+ line N` buttons per row, so the act of building the bar lived a long
+   way from the bar — and each of those buttons computed a position from the
+   SAVED layout rather than from the layout being staged. Three staged adds all
+   landed on position 1, and the CLI read the second and third as EDITS of the
+   first: that is why adding three parts produced one. Structural edits are now
+   semantic ops against stable refs, replayed by `hkPlan` in order, and every
+   position is derived at the moment that op will execute. The list below the
+   board is a REFERENCE now: it says what each part shows, and it applies
+   nothing. */
 
 /* -------------------------------------------------------------- HOOK UI */
 
 // The preview widths the panel offers. Not a fact about the layout — a fact
 // about terminals people actually use — so it lives here rather than coming
-// from the CLI.
+// from the CLI. They are COLUMN COUNTS: how many character cells wide the
+// terminal is. The card says so out loud, because three bare numbers over a
+// picture is a control nobody can guess the meaning of.
 const HK_WIDTHS = [80, 120, 160];
 let HK_WIDTH = 120;
 let HK_STATE = "healthy";
-// Which chip's editor is open, so a re-render does not close it under the user.
-let HK_OPEN = null;
-// The palette's search box and its open group, both surviving a re-render for
-// the same reason.
+// The reference list's search box and its open group, both surviving a
+// re-render so a paint does not close a list the user just opened.
 let HK_SEARCH = "";
 let HK_GROUP = null;
 // WHICH BOARD. The main status line, or the row Claude Code draws per subagent
@@ -43,6 +51,28 @@ let HK_GROUP = null;
 // a re-render does not put you back on the other one.
 let HK_BOARD = "status";
 
+// THE STAGED OPS, in the order they were made. NOT a map of finished HTTP
+// bodies: a body carries a POSITION, and a position computed when the op was
+// staged is wrong the moment an earlier op shifts the line under it. These are
+// semantic ops against stable refs; `hkPlan` turns them into writes — and
+// recomputes every position — each time the board paints.
+let HK_OPS = [];
+// The chip being dragged. Transient: cleared on every drop and every paint.
+let HK_DRAG = null;
+
+// DRAG IS OFF ON A NARROW SCREEN, and off for real rather than merely restyled:
+// a 40-pixel drop gap on a phone is not a target, so the three buttons on every
+// chip are the path there. The query matches 06-responsive.css's own breakpoint
+// — a chip that still says `draggable` while its handle is hidden is a promise
+// the page cannot keep.
+function hkCanDrag() {
+  try {
+    return !window.matchMedia("(max-width: 600px)").matches;
+  } catch (_) {
+    return true;
+  }
+}
+
 PANELS.hookui = function (host) {
   head(host, t("hookui.title"), t("hookui.sub"));
 
@@ -61,31 +91,39 @@ PANELS.hookui = function (host) {
         out.append(empty(t("hookui.noData")));
         return out;
       }
+      // The effective board: what it WILL be once the staged ops run. Every
+      // count, every slot cap and every legality question downstream reads this
+      // and never `show.lines` directly.
+      const plan = hkPlan(show, cat);
+
       const edits = editSet(() => bar.paint());
       const bar = editBar(edits, {
         onApply: async (b) => {
           await applyActions(edits, b);
-          edits.clear();
+          HK_OPS = [];
           rerender();
         },
         onReset: () => confirmReset(),
         onCancel: () => {
-          edits.clear();
+          HK_OPS = [];
           rerender();
         },
         resetLabel: t("hookui.resetLayout"),
       });
+      // Filled AFTER the bar exists: `editSet`'s onChange paints it, and a
+      // paint before that binding is assigned throws.
+      for (const a of plan.actions) edits.action(a.key, a.route, a.body, a.label);
 
       out.append(boardTabs(cat));
-      out.append(gateCard(show, cat, edits));
+      out.append(gateCard(show, cat));
       // A caution renders ABOVE the preview, never inside a tab — a caution you
       // have to hunt for is a caution nobody reads.
-      if (show.errors.length || show.warnings.length) out.append(cautionCard(show, edits));
-      out.append(previewCard(prev, show));
-      out.append(boardCard(show, cat, edits));
-      out.append(paletteCard(show, cat, edits));
-      out.append(presetsCard(presets));
-      out.append(advancedCard(show, cat, edits));
+      if (show.errors.length || show.warnings.length) out.append(cautionCard(show));
+      out.append(previewCard(prev, plan));
+      out.append(boardCard(cat, plan));
+      out.append(referenceCard(cat));
+      out.append(presetsCard(presets, plan));
+      out.append(advancedCard(cat, plan));
       out.append(bar);
       return out;
     }
@@ -98,6 +136,129 @@ function bd(body) {
   return Object.assign({ board: HK_BOARD }, body);
 }
 
+function rerender() {
+  const h = location.hash;
+  location.hash = "#/";
+  location.hash = h || "#/hookui";
+}
+
+/* ══ the staged plan ══════════════════════════════════════════════════════
+   Replays every staged op onto a working copy of the saved layout and returns
+   BOTH the effective board and the ordered writes that produce it. ONE
+   function, because a second idea of where a part will land is exactly the bug
+   this replaces: the board drew one arrangement and the writes produced
+   another, silently. */
+
+// Ops are staged by REF, never by position. A ref is either an item id the CLI
+// already gave us, or `new:<n>` for something staged in this session.
+function hkOp(op) {
+  // A second edit to the same field of the same part REPLACES the first — one
+  // decision typed twice is one decision, and the pending list has to read as a
+  // list of decisions rather than a list of keystrokes.
+  if (op.op === "set") HK_OPS = HK_OPS.filter((o) => !(o.op === "set" && o.ref === op.ref && o.field === op.field));
+  if (op.op === "sep") HK_OPS = HK_OPS.filter((o) => !(o.op === "sep" && o.line === op.line));
+  if (op.op === "doc") HK_OPS = HK_OPS.filter((o) => !(o.op === "doc" && o.field === op.field));
+  HK_OPS.push(op);
+  rerender();
+}
+
+function hkPlan(show, cat) {
+  const structural = new Set((cat.components || []).filter((c) => c.structural).map((c) => c.id));
+  const lines = (show.lines || []).map((l) => ({
+    line: l.line,
+    separator: l.separator,
+    items: (l.items || []).map((it) => ({ ref: it.id, type: it.type, src: it, over: {}, isNew: false })),
+  }));
+  const actions = [];
+  const doc = { theme: show.theme, glyphs: show.glyphs };
+  const find = (ref) => {
+    for (const l of lines) {
+      const i = l.items.findIndex((x) => x.ref === ref);
+      if (i >= 0) return { l, i, it: l.items[i] };
+    }
+    return null;
+  };
+
+  HK_OPS.forEach((op, oi) => {
+    const key = "op" + (oi + 1);
+    if (op.op === "add") {
+      const l = lines[op.line - 1];
+      if (!l) return;
+      // THE POSITION IS COMPUTED HERE, not when the button was pressed. Three
+      // adds in a row get 1, 2 and 3 and append; three adds computed at stage
+      // time all got 1, and the CLI read 2 and 3 as EDITS of the first.
+      const pos = l.items.length + 1;
+      l.items.push({ ref: "new:" + oi, type: op.type, src: null, over: {}, isNew: true });
+      actions.push({ key, route: "/api/statusline/set", body: bd({ line: op.line, pos, type: op.type }), label: t("hookui.opAdd", { id: op.type, n: op.line }) });
+    } else if (op.op === "remove") {
+      const f = find(op.ref);
+      if (!f) return;
+      actions.push({ key, route: "/api/statusline/remove", body: bd({ at: f.l.line + ":" + (f.i + 1) }), label: t("hookui.opRemove", { id: f.it.type }) });
+      f.l.items.splice(f.i, 1);
+    } else if (op.op === "move") {
+      const f = find(op.ref);
+      if (!f) return;
+      const from = f.l.line + ":" + (f.i + 1);
+      f.l.items.splice(f.i, 1);
+      const dst = lines[op.toLine - 1];
+      if (!dst) return;
+      const at = Math.max(0, Math.min(op.toPos - 1, dst.items.length));
+      dst.items.splice(at, 0, f.it);
+      actions.push({ key, route: "/api/statusline/move", body: bd({ from, to: dst.line + ":" + (at + 1) }), label: t("hookui.opMove", { id: f.it.type, n: dst.line }) });
+    } else if (op.op === "clone") {
+      const f = find(op.ref);
+      if (!f) return;
+      actions.push({ key, route: "/api/statusline/clone", body: bd({ at: f.l.line + ":" + (f.i + 1) }), label: t("hookui.opClone", { id: f.it.type }) });
+      f.l.items.splice(f.i + 1, 0, { ref: "new:" + oi, type: f.it.type, src: f.it.src, over: Object.assign({}, f.it.over), isNew: true });
+    } else if (op.op === "set") {
+      const f = find(op.ref);
+      if (!f) return;
+      f.it.over[op.field] = op.value;
+      if (op.field === "type") f.it.type = op.value;
+      actions.push({ key, route: "/api/statusline/set", body: bd(Object.assign({ line: f.l.line, pos: f.i + 1 }, { [op.field]: op.value })), label: op.label });
+    } else if (op.op === "sep") {
+      const l = lines[op.line - 1];
+      if (!l) return;
+      l.separator = op.value;
+      actions.push({ key, route: "/api/statusline/line", body: bd({ line: op.line, separator: op.value }), label: op.label });
+    } else if (op.op === "doc") {
+      doc[op.field] = op.value;
+      actions.push({ key, route: "/api/statusline/doc", body: bd({ [op.field]: op.value }), label: op.label });
+    }
+  });
+
+  for (const l of lines) {
+    // A spacer is not a thing the line SAYS, so it does not eat one of the
+    // five. Which ids those are is the CLI's answer, carried per component.
+    l.counted = l.items.filter((x) => !structural.has(x.type)).length;
+    l.full = l.counted >= cat.max_per_line;
+  }
+  return { lines, actions, doc, dirty: HK_OPS.length > 0, max: cat.max_per_line };
+}
+
+// The dense-prefix rule, applied to ONE line of the EFFECTIVE board — never the
+// saved one, or a part staged onto line 1 would leave line 2 still refusing.
+// The reason travels with the answer, because a disabled zone with no reason is
+// a shrug.
+function lineLegal(plan, n) {
+  if (n === 1) return { ok: true };
+  const above = plan.lines[n - 2];
+  if (above && above.items.length > 0) return { ok: true };
+  return { ok: false, why: t("hookui.fillFirst", { n: n - 1 }) };
+}
+
+// Why a part cannot go on this line RIGHT NOW; a null answer means it can. Both
+// reasons are the user's to read BEFORE the click, never after it.
+function addBlocked(plan, n) {
+  const legal = lineLegal(plan, n);
+  if (!legal.ok) return legal.why;
+  const line = plan.lines[n - 1];
+  if (!line) return t("hookui.noSuchLine");
+  if (line.full) return t("hookui.lineFull", { n: n, max: plan.max });
+  return null;
+}
+
+/* ══ the board tabs ═══════════════════════════════════════════════════════ */
 // The two boards. Named by the CLI (`boards` in the catalogue), labelled by the
 // panel — the id is data and the label is prose, which is the split everywhere
 // else in this file too.
@@ -116,10 +277,11 @@ function boardTabs(cat) {
     btn.type = "button";
     btn.addEventListener("click", () => {
       if (HK_BOARD === b) return;
+      // Switching boards with ops staged would send them to a board they were
+      // never about: every op carries a board, but the POSITIONS in them were
+      // computed against this one.
+      if (HK_OPS.length) return toast(t("hookui.applyFirst"), "bad");
       HK_BOARD = b;
-      // Opening the other board with a chip's editor still open would open a
-      // drawer for an item that is not there.
-      HK_OPEN = null;
       HK_SEARCH = "";
       rerender();
     });
@@ -130,17 +292,11 @@ function boardTabs(cat) {
   return c;
 }
 
-function rerender() {
-  const h = location.hash;
-  location.hash = "#/";
-  location.hash = h || "#/hookui";
-}
-
-// ── the gate ───────────────────────────────────────────────────────────────
+/* ══ the gate ═════════════════════════════════════════════════════════════ */
 // INVERTED from the Extra panel's. There, nothing exists until you connect;
 // here the board is LIVE WHILE OFF, because you must be able to compose before
 // you arm. What is gated is the switch, not the work.
-function gateCard(show, cat, edits) {
+function gateCard(show, cat) {
   const c = card(t("hookui.gate"));
   const row = el("div", "row-actions");
   row.append(chip(show.enabled ? t("hookui.on") : t("hookui.off"), show.enabled ? "ok" : null));
@@ -172,10 +328,10 @@ function gateCard(show, cat, edits) {
   return c;
 }
 
-// ── cautions ───────────────────────────────────────────────────────────────
+/* ══ cautions ═════════════════════════════════════════════════════════════ */
 // An error is a refusal; a warning is a fact the user then owns. They are drawn
 // differently and they are never merged into one count.
-function cautionCard(show, edits) {
+function cautionCard(show) {
   const c = card(t("hookui.cautions"));
   for (const e of show.errors) {
     const row = el("div", "hk-caution hk-caution-bad");
@@ -192,13 +348,20 @@ function cautionCard(show, edits) {
   return c;
 }
 
-// ── the preview ────────────────────────────────────────────────────────────
+/* ══ the preview ══════════════════════════════════════════════════════════ */
 // Pinned above the board and never scrolled away. `orc statusline preview
 // --json`'s output, rendered as DOM and never as HTML.
-function previewCard(prev, show) {
+//
+// IT DRAWS THE SAVED LAYOUT, and while anything is staged it SAYS SO. The
+// preview renders through the hook's own engine, which reads the file — so a
+// preview of unsaved edits would need a second engine, which is the one thing
+// this design refuses. "These changes are not in the picture yet" is the honest
+// version, and it is also the answer to "I pressed Apply and nothing happened":
+// something did, and this is where it shows up.
+function previewCard(prev, plan) {
   const right = el("div", "row-actions");
   for (const w of HK_WIDTHS) {
-    const b = el("button", "btn btn-xs" + (HK_WIDTH === w ? " btn-primary" : " btn-ghost"), String(w));
+    const b = el("button", "btn btn-xs" + (HK_WIDTH === w ? " btn-primary" : " btn-ghost"), tn(w, "hookui.cols"));
     b.type = "button";
     b.addEventListener("click", () => {
       HK_WIDTH = w;
@@ -207,6 +370,8 @@ function previewCard(prev, show) {
     right.append(b);
   }
   const c = card(t("hookui.preview"), right);
+  c.append(el("div", "note", t("hookui.previewAbout")));
+  if (plan.dirty) c.append(el("div", "note note-warn", t("hookui.previewStale")));
   if (!prev || !prev.ok) {
     c.append(el("div", "note", t("hookui.previewUnavailable")));
     return c;
@@ -214,6 +379,7 @@ function previewCard(prev, show) {
 
   // The fixture picker. `--fixtures` must carry one of every state INCLUDING
   // the ugly ones — you cannot design a degraded line on a healthy session.
+  c.append(el("div", "note", t("hookui.fixturesAbout")));
   const states = el("div", "row-actions hk-fixtures");
   for (const [k, label] of Object.entries(prev.fixtures || {})) {
     const b = el("button", "btn btn-xs" + (HK_STATE === k ? " btn-primary" : " btn-ghost"), label);
@@ -228,7 +394,7 @@ function previewCard(prev, show) {
 
   c.append(ansiBlock(prev.text, "hk-preview"));
 
-  // THE FOUR STRIPPINGS, always visible — not an afterthought tab. You cannot
+  // THE THREE STRIPPINGS, always visible — not an afterthought tab. You cannot
   // design an ASCII fallback you cannot see, and a design whose only
   // distinction is colour becomes ambiguous the moment NO_COLOR is set.
   const deg = el("div", "hk-degrade");
@@ -262,13 +428,20 @@ function ansiBlock(text, cls) {
     // compiler can emit. Anything it does not recognise is DROPPED rather than
     // printed, because a stray escape in the middle of a preview is worse than
     // a missing colour.
-    const re = /\[([0-9;]*)m/g;
+    const re = /\[([0-9;]*)m/g;
     let last = 0;
     let m;
     const push = (s) => {
       if (!s) return;
       const span = el("span", null, s);
-      if (style) span.setAttribute("style", style);
+      // THROUGH CSSOM, NEVER A `style` ATTRIBUTE. This page is served under
+      // `style-src 'self'`, which blocks a parsed style attribute outright —
+      // so every colour this preview drew was thrown away by the browser and
+      // the whole thing rendered grey, with the reason only in a console
+      // nobody had open. Assigning the property is not a parse and is not
+      // blocked, and weakening the policy to `unsafe-inline` for a preview is
+      // not a trade worth making.
+      if (style) for (const k of Object.keys(style)) span.style[k] = style[k];
       row.append(span);
     };
     while ((m = re.exec(line))) {
@@ -277,7 +450,7 @@ function ansiBlock(text, cls) {
       last = m.index + m[0].length;
     }
     push(line.slice(last));
-    if (!row.childNodes.length) row.append(document.createTextNode(" "));
+    if (!row.childNodes.length) row.append(document.createTextNode(" "));
     pre.append(row);
   }
   return pre;
@@ -285,7 +458,7 @@ function ansiBlock(text, cls) {
 
 // The 16 ANSI slots, as the browser's own colours. These are NOT ORC's colour
 // tokens — they are what a terminal would paint, approximated, because the
-// panel cannot know the user's theme and says so.
+// panel cannot know the user's terminal palette and says so.
 const HK_ANSI = [
   "#000000", "#cc0000", "#4e9a06", "#c4a000", "#3465a4", "#75507b", "#06989a", "#d3d7cf",
 ];
@@ -293,226 +466,274 @@ const HK_ANSI_BRIGHT = [
   "#555753", "#ef2929", "#8ae234", "#fce94f", "#729fcf", "#ad7fa8", "#34e2e2", "#eeeeec",
 ];
 
+// An OBJECT of CSS properties rather than a declaration string, because the
+// caller assigns them one at a time through CSSOM — see `push` above.
 function sgrStyle(codes, prev) {
   const parts = String(codes || "0").split(";").filter((x) => x !== "");
   if (!parts.length || parts[0] === "0") return null;
-  const out = [];
-  if (prev) out.push(prev);
+  const out = Object.assign({}, prev || {});
   for (let i = 0; i < parts.length; i++) {
     const n = Number(parts[i]);
-    if (n === 1) out.push("font-weight:700");
-    else if (n === 2) out.push("opacity:.6");
-    else if (n === 3) out.push("font-style:italic");
-    else if (n === 4) out.push("text-decoration:underline");
-    else if (n === 9) out.push("text-decoration:line-through");
-    else if (n === 7) out.push("filter:invert(1)");
-    else if (n >= 30 && n <= 37) out.push("color:" + HK_ANSI[n - 30]);
-    else if (n >= 90 && n <= 97) out.push("color:" + HK_ANSI_BRIGHT[n - 90]);
-    else if (n >= 40 && n <= 47) out.push("background:" + HK_ANSI[n - 40]);
-    else if (n === 39) out.push("color:inherit");
+    if (n === 1) out.fontWeight = "700";
+    else if (n === 2) out.opacity = ".6";
+    else if (n === 3) out.fontStyle = "italic";
+    else if (n === 4) out.textDecoration = "underline";
+    else if (n === 9) out.textDecoration = "line-through";
+    else if (n === 7) out.filter = "invert(1)";
+    else if (n >= 30 && n <= 37) out.color = HK_ANSI[n - 30];
+    else if (n >= 90 && n <= 97) out.color = HK_ANSI_BRIGHT[n - 90];
+    else if (n >= 40 && n <= 47) out.background = HK_ANSI[n - 40];
+    else if (n === 39) out.color = "inherit";
     else if (n === 38 && parts[i + 1] === "2") {
-      out.push("color:rgb(" + parts[i + 2] + "," + parts[i + 3] + "," + parts[i + 4] + ")");
+      out.color = "rgb(" + parts[i + 2] + "," + parts[i + 3] + "," + parts[i + 4] + ")";
       i += 4;
     } else if (n === 48 && parts[i + 1] === "2") {
-      out.push("background:rgb(" + parts[i + 2] + "," + parts[i + 3] + "," + parts[i + 4] + ")");
+      out.background = "rgb(" + parts[i + 2] + "," + parts[i + 3] + "," + parts[i + 4] + ")";
       i += 4;
     }
   }
-  return out.join(";");
+  return out;
 }
 
-// ── the board ──────────────────────────────────────────────────────────────
-// Three drop zones. THE ILLEGAL DROP IS MADE IMPOSSIBLE rather than allowed and
-// then complained about: an illegal zone renders disabled with its reason on
-// the zone itself. A user should never be able to do the wrong thing and then
-// be told off for it.
+/* ══ the board ════════════════════════════════════════════════════════════ */
+// THE ILLEGAL DROP IS MADE IMPOSSIBLE rather than allowed and then complained
+// about: an illegal zone renders disabled with its reason on the zone itself. A
+// user should never be able to do the wrong thing and then be told off for it.
 //
 // The CLI still validates. The board is a convenience; it is never the
 // guarantee.
-function boardCard(show, cat, edits) {
+function boardCard(cat, plan) {
   const c = card(t("hookui.board"));
+  c.append(el("div", "note", t("hookui.boardAbout")));
   c.append(el("div", "note", cat.dense_prefix));
 
-  for (const line of show.lines) {
-    const legal = lineLegal(show, line.line);
-    const wrap = el("div", "hk-line-wrap" + (legal ? "" : " hk-line-blocked"));
+  for (const line of plan.lines) {
+    const legal = lineLegal(plan, line.line);
+    const wrap = el("div", "hk-line-wrap" + (legal.ok ? "" : " hk-line-blocked"));
+
     const h = el("div", "hk-line-head");
-    h.append(el("span", "hk-line-name", tn(line.line, "hookui.lineN")));
-    h.append(el("span", "hk-line-count" + (line.full ? " hk-full" : ""), line.counted + "/" + cat.max_per_line));
+    const title = el("div", "hk-line-title");
+    title.append(el("span", "hk-line-name", tn(line.line, "hookui.lineN")));
+    title.append(el("span", "hk-line-count" + (line.full ? " hk-full" : ""), tn(line.counted, "hookui.slotsUsed", { max: plan.max })));
+    h.append(title);
+    h.append(separatorPicker(cat, line));
     wrap.append(h);
 
     const zone = el("div", "hk-zone");
     zone.setAttribute("role", "list");
-    for (const item of line.items) zone.append(chipEl(item, line, show, cat, edits));
+    for (const item of line.items) zone.append(chipEl(item, line, plan, cat));
 
     if (!legal.ok) {
       const blocked = el("div", "hk-blocked");
       blocked.append(el("span", "hk-caution-mark", "✕"));
       blocked.append(el("span", null, legal.why));
       zone.append(blocked);
-    } else if (!line.full) {
-      const add = el("button", "hk-add", t("hookui.add"));
-      add.type = "button";
-      add.addEventListener("click", () => {
-        HK_GROUP = HK_GROUP || Object.keys(cat.groups)[0];
-        const p = document.querySelector(".hk-palette-search");
-        if (p) p.focus();
-      });
-      zone.append(add);
     }
+    // THE ADD BUTTON ALWAYS RENDERS, and carries its own refusal. A control
+    // that vanishes when it cannot be used teaches nobody why — and the two
+    // refusals are DIFFERENT facts (nothing above it yet · this line is full),
+    // so they are two sentences and never one "invalid".
+    const b = el("button", "hk-add", t("hookui.add"));
+    b.type = "button";
+    if (!legal.ok) {
+      b.disabled = true;
+      b.title = legal.why;
+    } else if (line.full) {
+      b.disabled = true;
+      b.title = t("hookui.lineFull", { n: line.line, max: plan.max });
+    } else {
+      b.addEventListener("click", () => partPicker(cat, plan, line.line, null));
+    }
+    zone.append(b);
+    if (b.disabled && legal.ok) zone.append(el("div", "note note-warn hk-zone-why", b.title));
+    dropTarget(zone, line, plan);
     wrap.append(zone);
-
-    // Per-line options. The separator is what gives a line its rhythm, and it
-    // is the one line-level control worth surfacing on the board itself.
-    const opts = el("div", "hk-line-opts");
-    const sep = el("input", "hk-sep");
-    sep.type = "text";
-    sep.value = line.separator;
-    sep.setAttribute("aria-label", t("hookui.separator"));
-    sep.addEventListener("change", () => {
-      edits.action("line" + line.line, "/api/statusline/line",
-        bd({ line: line.line, separator: sep.value }),
-        t("hookui.sepChange", { n: line.line, s: sep.value }));
-    });
-    opts.append(el("span", "note", t("hookui.separator")), sep);
-    wrap.append(opts);
     c.append(wrap);
   }
+  c.append(el("div", "note", t("hookui.dragHint")));
   return c;
 }
 
-// The dense-prefix rule, applied to ONE line. The reason travels with the
-// answer, because a disabled zone with no reason is a shrug.
-function lineLegal(show, n) {
-  if (n === 1) return { ok: true };
-  const above = show.lines[n - 2];
-  if (above && above.count > 0) return { ok: true };
-  return { ok: false, why: t("hookui.fillFirst", { n: n - 1 }) };
+// THE SEPARATOR IS A DROPDOWN, and its options are the CLI's. A free-text box
+// asked a person to invent a rhythm and then to type a character that may not
+// be on their keyboard. A value the layout already carries that is NOT in the
+// set keeps its slot, leads the list and is disabled — the `fixed_executor`
+// rule: the state must be visible, never re-offerable.
+function separatorPicker(cat, line) {
+  const wrap = el("label", "hk-line-opts");
+  wrap.append(el("span", "note", t("hookui.separator")));
+  const sel = el("select", "hk-select");
+  const known = cat.separators || [];
+  if (!known.some((s) => s.value === line.separator)) {
+    const o = el("option", null, t("hookui.sepCustom", { s: JSON.stringify(line.separator) }));
+    o.value = line.separator;
+    o.disabled = true;
+    o.selected = true;
+    sel.append(o);
+  }
+  for (const s of known) {
+    // The NAME is the CLI's word; the sample is the literal string, shown
+    // between two marks so a run of spaces is visible at all.
+    const o = el("option", null, s.name + "   ‹" + s.value + "›");
+    o.value = s.value;
+    if (s.value === line.separator) o.selected = true;
+    sel.append(o);
+  }
+  sel.addEventListener("change", () => {
+    const hit = known.find((s) => s.value === sel.value);
+    hkOp({ op: "sep", line: line.line, value: sel.value, label: t("hookui.opSep", { n: line.line, s: hit ? hit.name : sel.value }) });
+  });
+  wrap.append(sel);
+  return wrap;
 }
 
+/* ══ a chip ═══════════════════════════════════════════════════════════════ */
 // A chip shows ITS OWN RENDERED OUTPUT, not its component id — that is what the
-// user is arranging. The id lives in the tooltip and in the editor header.
-function chipEl(item, line, show, cat, edits) {
+// user is arranging — with the id and a one-line description under it, because
+// "what is this thing" is the first question anybody asks of a bar full of
+// symbols, and the answer used to live only in a tooltip.
+function chipEl(item, line, plan, cat) {
   const comp = (cat.components || []).find((x) => x.id === item.type);
-  const wrap = el("div", "hk-chip" + (HK_OPEN === item.id ? " hk-chip-open" : ""));
+  const wrap = el("div", "hk-chip" + (item.isNew ? " hk-chip-new" : ""));
   wrap.setAttribute("role", "listitem");
   wrap.setAttribute("tabindex", "0");
-  wrap.title = item.type;
+  wrap.draggable = hkCanDrag();
+  wrap.title = comp && comp.summary ? comp.summary : item.type;
 
   const face = el("div", "hk-chip-face");
-  const sample = comp && comp.previews ? comp.previews[item.render] : null;
-  face.append(ansiBlock(sample || item.type, "hk-preview hk-preview-chip"));
+  face.append(el("span", "hk-grip", "∷"));
+  face.append(ansiBlock(chipSample(item, comp), "hk-preview hk-preview-chip"));
   wrap.append(face);
 
-  const foot = el("div", "hk-chip-foot");
-  foot.append(el("span", "hk-chip-id", item.type));
-  const edit = el("button", "hk-icon", "⋯");
-  edit.type = "button";
-  edit.title = t("hookui.edit");
-  edit.addEventListener("click", () => {
-    HK_OPEN = HK_OPEN === item.id ? null : item.id;
-    rerender();
-  });
-  const rm = el("button", "hk-icon", "×");
-  rm.type = "button";
-  rm.title = t("hookui.remove");
-  rm.addEventListener("click", () => {
-    edits.action("rm" + item.id, "/api/statusline/remove",
-      bd({ at: line.line + ":" + item.pos }),
-      t("hookui.removed", { id: item.type }));
-  });
-  foot.append(edit, rm);
-  wrap.append(foot);
-
-  // THE NON-DRAG PATH, and it is not an afterthought: pointer drag is unusable
-  // for a real fraction of people, so every move a drag can make is on this
-  // menu and on the keyboard.
-  const menu = el("div", "hk-move");
-  for (const target of [1, 2, 3]) {
-    if (target === line.line) continue;
-    const legal = lineLegal(show, target);
-    const b = el("button", "btn btn-xs btn-ghost", tn(target, "hookui.toLine"));
-    b.type = "button";
-    if (!legal.ok) {
-      b.disabled = true;
-      b.title = legal.why;
-    } else {
-      b.addEventListener("click", () => moveTo(item, line, target, 1, edits));
-    }
-    menu.append(b);
-  }
-  if (item.pos > 1) {
-    const b = el("button", "btn btn-xs btn-ghost", "←");
-    b.type = "button";
-    b.title = t("hookui.moveLeft");
-    b.addEventListener("click", () => moveTo(item, line, line.line, item.pos - 1, edits));
-    menu.append(b);
-  }
-  if (item.pos < line.items.length) {
-    const b = el("button", "btn btn-xs btn-ghost", "→");
+  wrap.append(el("div", "hk-chip-id", item.type));
+  if (comp && comp.summary) wrap.append(el("div", "hk-chip-desc", comp.summary));
+
+  // EDIT · MOVE · REMOVE, on the chip. Each opens a modal that says what it is
+  // about to do. The drag is the shortcut, never the mechanism: pointer drag is
+  // unusable for a real fraction of people, and it is switched off entirely
+  // below the width at which a drop gap stops being a target.
+  const acts = el("div", "hk-chip-acts");
+  const mk = (label, cls, fn) => {
+    const b = el("button", "hk-act " + cls, label);
     b.type = "button";
-    b.title = t("hookui.moveRight");
-    b.addEventListener("click", () => moveTo(item, line, line.line, item.pos + 1, edits));
-    menu.append(b);
-  }
-  // CLONE is on every chip: two `config` chips on different keys, or two
-  // token-kind chips on different kinds, is a normal thing to want.
-  const cl = el("button", "btn btn-xs btn-ghost", t("hookui.clone"));
-  cl.type = "button";
-  cl.addEventListener("click", () =>
-    edits.action("cl" + item.id, "/api/statusline/clone",
-      bd({ at: line.line + ":" + item.pos }), t("hookui.cloned", { id: item.type })));
-  menu.append(cl);
-  // EXPAND turns a composite or a group back into its parts — which is how a
-  // three-in-one chip becomes three chips the moment you want to restyle one.
-  if ((comp && comp.composite) || item.type === "group") {
-    const ex = el("button", "btn btn-xs btn-ghost", t("hookui.expand"));
-    ex.type = "button";
-    ex.addEventListener("click", () =>
-      edits.action("ex" + item.id, "/api/statusline/expand",
-        bd({ at: line.line + ":" + item.pos }), t("hookui.expanded", { id: item.type })));
-    menu.append(ex);
-  }
-  wrap.append(menu);
+    b.addEventListener("click", fn);
+    acts.append(b);
+  };
+  mk(t("hookui.edit"), "hk-act-edit", () => editModal(item, line, comp, cat));
+  mk(t("hookui.move"), "hk-act-move", () => moveModal(item, line, plan));
+  mk(t("hookui.remove"), "hk-act-remove", () => removeModal(item, comp));
+  wrap.append(acts);
 
   // Keyboard: the settled pattern, and every drag has an equivalent here. A
   // board only reachable by mouse is a board a lot of people cannot use.
   wrap.addEventListener("keydown", (ev) => {
+    const pos = line.items.indexOf(item) + 1;
     if (ev.key === "Delete" || ev.key === "Backspace") {
       ev.preventDefault();
-      edits.action("rm" + item.id, "/api/statusline/remove",
-        bd({ at: line.line + ":" + item.pos }), t("hookui.removed", { id: item.type }));
+      removeModal(item, comp);
     } else if (ev.key === "e" || ev.key === "E") {
       ev.preventDefault();
-      HK_OPEN = HK_OPEN === item.id ? null : item.id;
-      rerender();
-    } else if (ev.key === "ArrowLeft" && item.pos > 1) {
+      editModal(item, line, comp, cat);
+    } else if (ev.key === "ArrowLeft" && pos > 1) {
       ev.preventDefault();
-      moveTo(item, line, line.line, item.pos - 1, edits);
-    } else if (ev.key === "ArrowRight" && item.pos < line.items.length) {
+      moveTo(item, line.line, pos - 1);
+    } else if (ev.key === "ArrowRight" && pos < line.items.length) {
       ev.preventDefault();
-      moveTo(item, line, line.line, item.pos + 1, edits);
+      moveTo(item, line.line, pos + 1);
     } else if (ev.key === "ArrowUp" || ev.key === "ArrowDown") {
       const target = line.line + (ev.key === "ArrowUp" ? -1 : 1);
-      if (target < 1 || target > 3) return;
+      if (target < 1 || target > plan.lines.length) return;
       ev.preventDefault();
-      const legal = lineLegal(show, target);
-      // An illegal line is SKIPPED and the live region says why — never a
-      // silent no-op.
-      if (!legal.ok) return announce(legal.why);
-      moveTo(item, line, target, 1, edits);
+      const why = addBlocked(plan, target);
+      // A line that cannot take it is SKIPPED and the live region says why —
+      // never a silent no-op.
+      if (why) return announce(why);
+      moveTo(item, target, 1);
     }
   });
 
-  if (HK_OPEN === item.id) wrap.append(editorDrawer(item, line, comp, cat, edits));
+  wrap.addEventListener("dragstart", (ev) => {
+    HK_DRAG = { ref: item.ref, from: line.line };
+    wrap.classList.add("hk-chip-dragging");
+    try {
+      ev.dataTransfer.effectAllowed = "move";
+      ev.dataTransfer.setData("text/plain", item.ref);
+    } catch (_) {}
+  });
+  wrap.addEventListener("dragend", () => {
+    HK_DRAG = null;
+    wrap.classList.remove("hk-chip-dragging");
+    for (const n of document.querySelectorAll(".hk-drop-before, .hk-drop-after"))
+      n.classList.remove("hk-drop-before", "hk-drop-after");
+  });
+  wrap.addEventListener("dragover", (ev) => {
+    if (!HK_DRAG || HK_DRAG.ref === item.ref) return;
+    ev.preventDefault();
+    const r = wrap.getBoundingClientRect();
+    const before = ev.clientX < r.left + r.width / 2;
+    wrap.classList.toggle("hk-drop-before", before);
+    wrap.classList.toggle("hk-drop-after", !before);
+  });
+  wrap.addEventListener("dragleave", () => wrap.classList.remove("hk-drop-before", "hk-drop-after"));
+  wrap.addEventListener("drop", (ev) => {
+    if (!HK_DRAG || HK_DRAG.ref === item.ref) return;
+    ev.preventDefault();
+    ev.stopPropagation();
+    const before = wrap.classList.contains("hk-drop-before");
+    const pos = line.items.indexOf(item) + 1;
+    dropOnto(line, plan, before ? pos : pos + 1);
+  });
   return wrap;
 }
 
-function moveTo(item, line, toLine, toPos, edits) {
-  edits.action("mv" + item.id, "/api/statusline/move",
-    bd({ from: line.line + ":" + item.pos, to: toLine + ":" + toPos }),
-    t("hookui.moved", { id: item.type, n: toLine }));
-  announce(t("hookui.moved", { id: item.type, n: toLine }));
+// What this chip will look like in the bar. A part staged in this session has
+// no rendered sample from the CLI yet, so it borrows its component's default —
+// which is exactly what it will render as until somebody changes its shape.
+function chipSample(item, comp) {
+  if (!comp) return item.type;
+  const render = item.over.render || (item.src ? item.src.render : (comp.defaults && comp.defaults.render) || comp.renderers[0]);
+  const s = comp.previews ? comp.previews[render] : null;
+  return s || item.type;
+}
+
+// A zone is a drop target across its WHOLE area, so a drop past the last chip
+// appends instead of doing nothing.
+function dropTarget(zone, line, plan) {
+  zone.addEventListener("dragover", (ev) => {
+    if (!HK_DRAG) return;
+    if (HK_DRAG.from !== line.line && addBlocked(plan, line.line)) return;
+    ev.preventDefault();
+    zone.classList.add("hk-zone-hot");
+  });
+  zone.addEventListener("dragleave", () => zone.classList.remove("hk-zone-hot"));
+  zone.addEventListener("drop", (ev) => {
+    zone.classList.remove("hk-zone-hot");
+    if (!HK_DRAG) return;
+    ev.preventDefault();
+    dropOnto(line, plan, line.items.length + 1);
+  });
+}
+
+function dropOnto(line, plan, pos) {
+  if (!HK_DRAG) return;
+  const all = plan.lines.reduce((acc, l) => acc.concat(l.items), []);
+  const moving = all.find((x) => x.ref === HK_DRAG.ref);
+  const from = HK_DRAG.from;
+  HK_DRAG = null;
+  if (!moving) return;
+  // Reordering WITHIN a line never changes how many parts it holds, so the
+  // five-slot cap and the dense-prefix rule only apply to a move that crosses
+  // lines.
+  if (from !== line.line) {
+    const why = addBlocked(plan, line.line);
+    if (why) return toast(why, "bad");
+  }
+  moveTo(moving, line.line, pos);
+}
+
+function moveTo(item, toLine, toPos) {
+  hkOp({ op: "move", ref: item.ref, toLine, toPos });
+  announce(t("hookui.opMove", { id: item.type, n: toLine }));
 }
 
 // `aria-grabbed` is deprecated and is not used. State is announced through a
@@ -530,85 +751,278 @@ function announce(msg) {
   region.textContent = msg;
 }
 
-// ── the editor drawer ──────────────────────────────────────────────────────
-// A drawer, not a modal: the preview stays visible while you edit, which is the
-// entire point.
+/* ══ the part picker ══════════════════════════════════════════════════════ */
+// ONE MODAL, one search box, one click. It is the only place a part is ever
+// chosen — for a new slot and for swapping an existing one — so there is
+// exactly one answer to "how do I put something on the bar".
 //
-// NO FIELD NAMES. `min_width` and `hide_when` are the JSON's words; the drawer
-// says "Min width" and "Hide when". The JSON is for the diff, the drawer is for
-// the person — and the ids, renderers and state words that DO appear are the
-// CLI's own and are never translated.
-function editorDrawer(item, line, comp, cat, edits) {
-  const d = el("div", "hk-drawer");
-  if (!comp) {
-    d.append(el("div", "note", t("hookui.unknownComponent")));
-    return d;
-  }
-  const stage = (field, value, label) => {
-    edits.action("set" + item.id + field, "/api/statusline/set",
-      bd(Object.assign({ line: line.line, pos: item.pos }, { [field]: value })),
-      label);
+// `replace` names the chip whose part is being swapped; absent, this is an add.
+function partPicker(cat, plan, line, replace) {
+  let q = "";
+  // NOT named `body`: that name is reserved for a panel's own card container,
+  // which must carry `stack`. This is a modal's contents and spaces itself.
+  const pane = el("div", "hk-picker");
+
+  const searchRow = el("div", "hk-picker-search");
+  const search = el("input", "hk-input hk-picker-input");
+  search.type = "search";
+  search.placeholder = t("hookui.searchPlaceholder");
+  const count = el("span", "note");
+  searchRow.append(search, count);
+  pane.append(searchRow);
+  pane.append(el("div", "note", replace ? t("hookui.pickerReplaceAbout") : tn(line, "hookui.pickerAbout")));
+
+  const list = el("div", "hk-picker-list");
+  pane.append(list);
+
+  const closer = () => close();
+  const paint = () => {
+    list.replaceChildren();
+    const rows = (cat.components || []).filter((c) => (q ? matches(c, q) : true));
+    count.textContent = tn(rows.length, "hookui.matches");
+    if (!rows.length) {
+      list.append(empty(t("hookui.noMatch")));
+      return;
+    }
+    for (const comp of rows) list.append(pickerRow(comp, line, replace, closer));
   };
+  search.addEventListener("input", () => {
+    q = search.value.trim().toLowerCase();
+    paint();
+  });
+  paint();
 
-  d.append(el("div", "hk-drawer-head", comp.id));
-  if (comp.summary) d.append(el("div", "note", comp.summary));
+  const close = modal({
+    title: replace ? t("hookui.pickerReplaceTitle") : tn(line, "hookui.pickerTitle"),
+    body: pane,
+    actions: [{ label: t("common.cancel"), cls: "btn-ghost", onClick: (c) => c() }],
+  });
+  setTimeout(() => search.focus(), 40);
+}
+
+// A row says WHAT the part is, in a sentence, next to what it will look like.
+// A REFUSED part is drawn and is NOT clickable — never a disabled button, and
+// never absent: "we decided against this" and "we forgot" must not look the
+// same, which is why the row exists at all.
+function pickerRow(comp, line, replace, close) {
+  const refused = comp.cost === "refused";
+  const row = el(refused ? "div" : "button", "hk-pick-row" + (refused ? " hk-pick-row-off" : ""));
+  if (!refused) row.type = "button";
+
+  const top = el("div", "hk-pick-top");
+  top.append(el("span", "hk-prow-id", comp.id));
+  // The cost chip is the CLI's own word. A friendlier synonym would be a state
+  // that does not exist.
+  top.append(chip(comp.cost, refused ? "bad" : null));
+  row.append(top);
+  if (comp.summary) row.append(el("div", "hk-pick-desc", comp.summary));
+  const sample = comp.previews && comp.previews[(comp.defaults && comp.defaults.render) || comp.renderers[0]];
+  if (sample) row.append(ansiBlock(sample, "hk-preview hk-preview-chip"));
+  if (refused) {
+    row.append(el("div", "note note-warn", comp.refused_reason));
+    return row;
+  }
+  row.addEventListener("click", () => {
+    if (replace) hkOp({ op: "set", ref: replace.ref, field: "type", value: comp.id, label: t("hookui.opSwap", { id: comp.id }) });
+    else hkOp({ op: "add", line, type: comp.id });
+    close();
+  });
+  return row;
+}
+
+// Fuzzy plus INITIALISM: with a catalogue this size a substring search is not
+// enough — two letters should find a two-word name, which plain substring
+// matching does not.
+function matches(comp, q) {
+  const id = comp.id.toLowerCase();
+  if (id.includes(q)) return true;
+  if ((comp.summary || "").toLowerCase().includes(q)) return true;
+  if ((comp.label || "").toLowerCase().includes(q)) return true;
+  const initials = id.split("-").map((p) => p[0]).join("");
+  if (initials.startsWith(q)) return true;
+  let i = 0;
+  for (const ch of id) if (ch === q[i]) i++;
+  return i === q.length;
+}
+
+/* ══ move ═════════════════════════════════════════════════════════════════ */
+// A modal that says what it is about to do — and on a narrow screen it is the
+// ONLY way to move a chip, because drag is off below the width at which a drop
+// gap stops being a target.
+function moveModal(item, line, plan) {
+  const body = el("div", "stack");
+  body.append(el("div", "note", t("hookui.moveAbout", { id: item.type })));
+
+  for (const target of plan.lines) {
+    const legal = lineLegal(plan, target.line);
+    const sameLine = target.line === line.line;
+    const box = el("div", "hk-move-line");
+    box.append(el("div", "hk-line-name", tn(target.line, "hookui.lineN")));
+    // A LINE THAT CANNOT TAKE IT SAYS SO ONCE. Six identical disabled slots is
+    // the same refusal printed six times, and the reason is about the LINE
+    // rather than about any one slot on it.
+    const blocked = sameLine ? null : addBlocked(plan, target.line);
+    if (blocked) {
+      box.append(el("div", "note note-warn", blocked));
+      body.append(box);
+      continue;
+    }
+    const slots = el("div", "hk-move-slots");
+    const n = Math.max(1, target.items.length + (sameLine ? 0 : 1));
+    for (let p = 1; p <= n; p++) {
+      const b = el("button", "btn btn-xs btn-ghost", tn(p, "hookui.slotN"));
+      b.type = "button";
+      if (sameLine && p === line.items.indexOf(item) + 1) {
+        b.disabled = true;
+        b.title = t("hookui.alreadyHere");
+      } else {
+        b.addEventListener("click", () => {
+          close();
+          moveTo(item, target.line, p);
+        });
+      }
+      slots.append(b);
+    }
+    box.append(slots);
+    body.append(box);
+  }
+
+  const close = modal({
+    title: t("hookui.moveTitle"),
+    body,
+    actions: [{ label: t("common.cancel"), cls: "btn-ghost", onClick: (c) => c() }],
+  });
+}
+
+/* ══ remove ═══════════════════════════════════════════════════════════════ */
+function removeModal(item, comp) {
+  const body = el("div", "stack");
+  body.append(el("div", "note", t("hookui.removeAbout", { id: item.type })));
+  if (comp && comp.summary) body.append(el("div", "note", comp.summary));
+  modal({
+    title: t("hookui.removeTitle"),
+    body,
+    actions: [
+      { label: t("common.cancel"), cls: "btn-ghost", onClick: (c) => c() },
+      {
+        label: t("hookui.remove"),
+        cls: "btn-primary",
+        onClick: (c) => {
+          c();
+          hkOp({ op: "remove", ref: item.ref });
+        },
+      },
+    ],
+  });
+}
+
+/* ══ the part editor ══════════════════════════════════════════════════════ */
+// A MODAL, because the board is what the user is looking at, and a drawer that
+// opened inside a chip pushed the whole board down under the thing being
+// edited.
+//
+// NO FIELD NAMES, AND EVERY CONTROL CARRIES A SENTENCE. `min_width` and
+// `hide_when` are the JSON's words; this says "Least width" and explains what
+// it does. The JSON is for the diff, the editor is for the person — and the
+// ids, renderers and state words that DO appear are the CLI's own and are never
+// translated.
+function editModal(item, line, comp, cat) {
+  // NOT named `body`: that name is reserved for a panel's own card container,
+  // which must carry `stack`. This is a modal's contents and spaces itself.
+  const pane = el("div", "hk-editor");
+  if (!comp) {
+    pane.append(el("div", "note", t("hookui.unknownComponent")));
+    modal({ title: item.type, body: pane, actions: [{ label: t("common.close"), cls: "btn-ghost", onClick: (c) => c() }] });
+    return;
+  }
+  const val = (field, dflt) => (field in item.over ? item.over[field] : item.src && item.src[field] !== undefined && item.src[field] !== null ? item.src[field] : dflt);
+  const stage = (field, value, label) => hkOp({ op: "set", ref: item.ref, field, value, label });
+
+  const live = el("div", "hk-editor-live");
+  live.append(ansiBlock(chipSample(item, comp), "hk-preview hk-preview-sm"));
+  pane.append(live);
+  if (comp.summary) pane.append(el("div", "note", comp.summary));
+
+  // Swapping the part itself, from inside the editor: "this slot, but a
+  // different thing" is a real edit and it should not need a remove and an add.
+  const swap = el("button", "btn btn-xs btn-ghost hk-swap", t("hookui.swap"));
+  swap.type = "button";
+  swap.addEventListener("click", () => {
+    close();
+    partPicker(cat, HK_NO_LINES, 0, item);
+  });
+  pane.append(swap);
 
   // THE SHAPE PICKER IS A GALLERY, NOT A DROPDOWN. Every renderer the component
   // declares, drawn with this component's real current value. A dropdown
-  // containing the word `braille-bar` tells nobody anything, and this is the
+  // containing a renderer's name tells nobody anything, and this is the
   // difference between a feature people use and a settings form they close.
-  d.append(el("div", "hk-section", t("hookui.shape")));
+  pane.append(sectionHead(t("hookui.shape"), t("hookui.shapeAbout")));
   const gallery = el("div", "hk-gallery");
+  const curRender = val("render", (comp.defaults && comp.defaults.render) || comp.renderers[0]);
   for (const r of comp.renderers) {
-    const b = el("button", "hk-sample" + (item.render === r ? " hk-sample-on" : ""));
+    const b = el("button", "hk-sample" + (curRender === r ? " hk-sample-on" : ""));
     b.type = "button";
     b.title = r;
     b.append(ansiBlock(comp.previews && comp.previews[r] ? comp.previews[r] : r, "hk-preview hk-preview-chip"));
     b.append(el("span", "hk-sample-id", r));
-    b.addEventListener("click", () => stage("render", r, t("hookui.shapeChange", { id: comp.id, r })));
+    b.addEventListener("click", () => {
+      close();
+      stage("render", r, t("hookui.shapeChange", { id: comp.id, r }));
+    });
     gallery.append(b);
   }
-  d.append(gallery);
+  pane.append(gallery);
 
-  // The glyph set, same treatment and for the same reason.
-  d.append(el("div", "hk-section", t("hookui.glyphs")));
-  d.append(pickRow(cat.glyph_sets, null, (v) => stage("glyphs", v, t("hookui.glyphChange", { id: comp.id, v }))));
+  pane.append(sectionHead(t("hookui.glyphs"), t("hookui.glyphsAbout")));
+  pane.append(pickRow(cat.glyph_sets, val("glyphs", null), (v) => stage("glyphs", v, t("hookui.glyphChange", { id: comp.id, v }))));
 
-  d.append(el("div", "hk-section", t("hookui.words")));
+  pane.append(sectionHead(t("hookui.words"), t("hookui.wordsAbout")));
   const label = el("input", "hk-input");
   label.type = "text";
-  label.value = item.label == null ? "" : item.label;
+  const cur = val("label", "");
+  label.value = cur == null ? "" : String(cur);
   label.placeholder = t("hookui.labelPlaceholder");
   label.addEventListener("change", () => stage("label", label.value, t("hookui.labelChange", { id: comp.id, v: label.value })));
-  d.append(labelled(t("hookui.label"), label));
-  d.append(labelled(t("hookui.case"), pickRow(cat.cases, item.case, (v) => stage("case", v, t("hookui.caseChange", { id: comp.id, v })))));
-
-  d.append(el("div", "hk-section", t("hookui.colour")));
-  d.append(labelled(t("hookui.labelColour"), pickRow(cat.colors, item.label_color, (v) => stage("label_color", v, t("hookui.colourChange", { id: comp.id, v })))));
-  d.append(labelled(t("hookui.valueColour"), pickRow(cat.colors, item.value_color, (v) => stage("value_color", v, t("hookui.colourChange", { id: comp.id, v })))));
+  pane.append(labelled(t("hookui.label"), label, t("hookui.labelAbout")));
+  pane.append(labelled(t("hookui.case"), pickRow(cat.cases, val("case", null), (v) => stage("case", v, t("hookui.caseChange", { id: comp.id, v }))), t("hookui.caseAbout")));
+  pane.append(labelled(t("hookui.before"), textField(val("prefix", ""), (v) => stage("prefix", v, t("hookui.beforeChange", { id: comp.id, v }))), t("hookui.beforeAbout")));
+  pane.append(labelled(t("hookui.after"), textField(val("suffix", ""), (v) => stage("suffix", v, t("hookui.afterChange", { id: comp.id, v }))), t("hookui.afterAbout")));
+
+  pane.append(sectionHead(t("hookui.colour"), t("hookui.colourAbout")));
+  pane.append(labelled(t("hookui.labelColour"), pickRow(cat.colors, val("label_color", null), (v) => stage("label_color", v, t("hookui.colourChange", { id: comp.id, v }))), t("hookui.labelColourAbout")));
+  pane.append(labelled(t("hookui.valueColour"), pickRow(cat.colors, val("value_color", null), (v) => stage("value_color", v, t("hookui.colourChange", { id: comp.id, v }))), t("hookui.valueColourAbout")));
   if (comp.bounded)
-    d.append(labelled(t("hookui.ramp"), pickRow(Object.keys(cat.ramps), item.ramp, (v) => stage("ramp", v, t("hookui.rampChange", { id: comp.id, v })))));
+    pane.append(labelled(t("hookui.ramp"), pickRow(Object.keys(cat.ramps), val("ramp", null), (v) => stage("ramp", v, t("hookui.rampChange", { id: comp.id, v }))), t("hookui.rampAbout")));
   // R3, AT THE CONTROL, at the moment the choice is made — never in a
   // validation summary later.
-  if (comp.states) d.append(el("div", "note note-warn", t("hookui.stateColourWarn", { s: comp.states.join(", ") })));
+  if (comp.states) pane.append(el("div", "note note-warn", t("hookui.stateColourWarn", { s: comp.states.join(", ") })));
 
-  // "Emphasis", never "font size". A terminal owns its font, and a picker that
+  // "Weight", never "font size". A terminal owns its font, and a picker that
   // did nothing would be worse than not offering one.
-  d.append(labelled(t("hookui.emphasis"), pickRow(cat.emphasis.filter((e) => !cat.refused_emphasis.includes(e)), (item.emphasis || [])[0], (v) => stage("emphasis", v, t("hookui.emphasisChange", { id: comp.id, v })))));
-  d.append(el("div", "note", t("hookui.fontWhy")));
-
-  if (comp.bounded || comp.defaults.format) {
-    d.append(el("div", "hk-section", t("hookui.numbers")));
-    d.append(labelled(t("hookui.format"), pickRow(cat.formats, item.format, (v) => stage("format", v, t("hookui.formatChange", { id: comp.id, v })))));
-    d.append(labelled(t("hookui.compact"), pickRow(cat.compact, item.compact, (v) => stage("compact", v, t("hookui.compactChange", { id: comp.id, v })))));
-    d.append(el("div", "note note-warn", t("hookui.minWidthWarn")));
+  pane.append(labelled(t("hookui.emphasis"), pickRow((cat.emphasis || []).filter((e) => !(cat.refused_emphasis || []).includes(e)), (val("emphasis", []) || [])[0], (v) => stage("emphasis", v, t("hookui.emphasisChange", { id: comp.id, v }))), t("hookui.emphasisAbout")));
+  pane.append(el("div", "note", t("hookui.fontWhy")));
+
+  if (comp.bounded || (comp.defaults && comp.defaults.format)) {
+    pane.append(sectionHead(t("hookui.numbers"), t("hookui.numbersAbout")));
+    pane.append(labelled(t("hookui.format"), pickRow(cat.formats, val("format", null), (v) => stage("format", v, t("hookui.formatChange", { id: comp.id, v }))), t("hookui.formatAbout")));
+    pane.append(labelled(t("hookui.compact"), pickRow(cat.compact, val("compact", null), (v) => stage("compact", v, t("hookui.compactChange", { id: comp.id, v }))), t("hookui.compactAbout")));
+    // `min_width` is not cosmetic: a value that changes width shifts every part
+    // to its right on the keystroke it happens, and that jitter is the main
+    // reason people turn a status line off again.
+    pane.append(labelled(t("hookui.minWidth"), numField(val("min_width", null), 0, 8, (v) => stage("min_width", v, t("hookui.minWidthChange", { id: comp.id, v }))), t("hookui.minWidthWarn")));
+    pane.append(labelled(t("hookui.precision"), numField(val("precision", null), 0, 2, (v) => stage("precision", v, t("hookui.precisionChange", { id: comp.id, v }))), t("hookui.precisionAbout")));
   }
 
+  const rend = cat.renderers[curRender];
+  if (rend && rend.width)
+    pane.append(labelled(t("hookui.width"), numField(val("width", null), rend.width[0], rend.width[1], (v) => stage("width", v, t("hookui.widthChange", { id: comp.id, v }))), t("hookui.widthWhy")));
+
   // A CHECKLIST, not an enum: "hide when zero" and "hide when there is no run"
   // are independent facts and a user wants both at once.
-  d.append(el("div", "hk-section", t("hookui.whenToShow")));
+  pane.append(sectionHead(t("hookui.whenToShow"), t("hookui.whenToShowAbout")));
   const checks = el("div", "hk-checks");
-  const active = new Set(item.hide_when || []);
+  const active = new Set(val("hide_when", []) || []);
   for (const h of cat.hide_when) {
     if (h.id === "never") continue;
     const lab = el("label", "hk-check");
@@ -625,51 +1039,52 @@ function editorDrawer(item, line, comp, cat, edits) {
     lab.append(box, el("span", null, h.id), el("span", "note", h.says));
     checks.append(lab);
   }
-  d.append(checks);
-
-  // The rest of the number controls. `min_width` is not cosmetic: a value that
-  // changes width shifts every component to its right on the keystroke it
-  // happens, and that jitter is the main reason people turn a status line off.
-  if (comp.bounded || comp.defaults.format) {
-    d.append(labelled(t("hookui.minWidth"), numField(item.min_width, 0, 8, (v) =>
-      stage("min_width", v, t("hookui.minWidthChange", { id: comp.id, v })))));
-    d.append(labelled(t("hookui.precision"), numField(item.precision, 0, 2, (v) =>
-      stage("precision", v, t("hookui.precisionChange", { id: comp.id, v })))));
-  }
-  const rend = cat.renderers[item.render];
-  if (rend && rend.width) {
-    d.append(labelled(t("hookui.width"), numField(item.width, rend.width[0], rend.width[1], (v) =>
-      stage("width", v, t("hookui.widthChange", { id: comp.id, v })))));
-    d.append(el("div", "note", t("hookui.widthWhy")));
-  }
-  d.append(labelled(t("hookui.before"), textField(item.prefix, (v) =>
-    stage("prefix", v, t("hookui.beforeChange", { id: comp.id, v })))));
-  d.append(labelled(t("hookui.after"), textField(item.suffix, (v) =>
-    stage("suffix", v, t("hookui.afterChange", { id: comp.id, v })))));
+  pane.append(checks);
 
   // RESPONSIVE WIDTH: the range of terminal widths in which this part is worth
   // its cells. Strictly better than truncating the right of an overflowing
   // line, because the USER chooses what survives a narrow terminal.
-  d.append(el("div", "hk-section", t("hookui.narrow")));
-  d.append(labelled(t("hookui.minCols"), numField(item.min_cols, 0, 200, (v) =>
-    stage("min_cols", v, t("hookui.minColsChange", { id: comp.id, v })))));
-  d.append(labelled(t("hookui.priority"), numField(item.priority, 1, 5, (v) =>
-    stage("priority", v, t("hookui.priorityChange", { id: comp.id, v })))));
-  d.append(el("div", "note", t("hookui.priorityWhy")));
-
-  // WHERE EACH VALUE CAME FROM. It is how a user finds their own overrides
-  // again after a theme change — `orc lane config`'s problem, at component
-  // scale.
-  const ex = el("button", "btn btn-xs btn-ghost", t("hookui.explain"));
-  ex.type = "button";
-  ex.addEventListener("click", async () => {
-    const r = await read("/api/statusline/explain?board=" + HK_BOARD + "&at=" + line.line + ":" + item.pos);
-    if (!r.data || !r.data.ok) return toast(t("hookui.explainFailed"), "bad");
-    const rows = r.data.resolved.map((x) => [x.field, x.source]);
-    modal({ title: comp.id, body: kvList(rows), actions: [] });
+  pane.append(sectionHead(t("hookui.narrow"), t("hookui.narrowAbout")));
+  pane.append(labelled(t("hookui.minCols"), numField(val("min_cols", null), 0, 200, (v) => stage("min_cols", v, t("hookui.minColsChange", { id: comp.id, v }))), t("hookui.minColsAbout")));
+  pane.append(labelled(t("hookui.priority"), numField(val("priority", null), 1, 5, (v) => stage("priority", v, t("hookui.priorityChange", { id: comp.id, v }))), t("hookui.priorityWhy")));
+
+  const close = modal({
+    title: comp.id,
+    body: pane,
+    actions: [
+      // WHERE EACH VALUE CAME FROM. It is how a user finds their own overrides
+      // again after a colour set change — `orc lane config`'s problem, at part
+      // scale. It reads the SAVED item, so it is offered only for one.
+      ...(item.src
+        ? [{
+            label: t("hookui.explain"),
+            cls: "btn-ghost",
+            onClick: async () => {
+              const r = await read("/api/statusline/explain?board=" + HK_BOARD + "&at=" + line.line + ":" + (line.items.indexOf(item) + 1));
+              if (!r.data || !r.data.ok) return toast(t("hookui.explainFailed"), "bad");
+              modal({
+                title: comp.id,
+                pane: kvList(r.data.resolved.map((x) => [x.field, x.source])),
+                actions: [{ label: t("common.close"), cls: "btn-ghost", onClick: (c) => c() }],
+              });
+            },
+          }]
+        : []),
+      { label: t("common.close"), cls: "btn-ghost", onClick: (c) => c() },
+    ],
   });
-  d.append(ex);
-  return d;
+}
+
+// `partPicker` reads a board only to answer "can a part go on that line". A
+// SWAP changes nothing about where the part sits, so it is handed a board with
+// no lines and never asks.
+const HK_NO_LINES = { lines: [], max: 5 };
+
+function sectionHead(name, about) {
+  const w = el("div", "hk-section-wrap");
+  w.append(el("div", "hk-section", name));
+  if (about) w.append(el("div", "note", about));
+  return w;
 }
 
 function numField(value, lo, hi, onSet) {
@@ -690,9 +1105,15 @@ function textField(value, onSet) {
   return i;
 }
 
-function labelled(name, node) {
+// A control, its name, and — because a noun on its own is not an explanation —
+// the sentence that says what it does. That sentence is most of this release:
+// a settings form whose labels are nouns is a form people close.
+function labelled(name, node, about) {
   const row = el("div", "hk-field");
-  row.append(el("span", "hk-field-name", name));
+  const left = el("div", "hk-field-left");
+  left.append(el("span", "hk-field-name", name));
+  if (about) left.append(el("span", "note", about));
+  row.append(left);
   row.append(node);
   return row;
 }
@@ -710,38 +1131,39 @@ function pickRow(options, current, onPick) {
   return row;
 }
 
-// ── the palette ────────────────────────────────────────────────────────────
-function paletteCard(show, cat, edits) {
+/* ══ the reference list ═══════════════════════════════════════════════════ */
+// WHAT EACH PART SHOWS, and nothing else. It used to carry three `+ line N`
+// buttons per row, which put the act of building the bar a long way from the
+// bar — and computed a position against a layout that was no longer the one
+// being staged. Adding happens on the board now; this is a reference.
+function referenceCard(cat) {
   const right = el("div", "row-actions");
-  const search = el("input", "hk-palette-search");
+  const search = el("input", "hk-input hk-palette-search");
   search.type = "search";
   search.value = HK_SEARCH;
   search.placeholder = t("hookui.searchPlaceholder");
-  search.addEventListener("input", () => {
-    HK_SEARCH = search.value;
-    paint();
-  });
   right.append(search);
 
-  const c = card(t("hookui.palette"), right);
+  const c = card(t("hookui.reference"), right);
+  c.append(el("div", "note", t("hookui.referenceAbout")));
   const body = el("div", "stack");
   c.append(body);
 
   function paint() {
     body.replaceChildren();
     const q = HK_SEARCH.trim().toLowerCase();
-    const hits = q ? cat.components.filter((x) => matches(x, q)) : null;
+    const hits = q ? (cat.components || []).filter((x) => matches(x, q)) : null;
     if (hits) {
       body.append(el("div", "note", tn(hits.length, "hookui.matches")));
-      for (const comp of hits) body.append(paletteRow(comp, show, cat, edits));
+      for (const comp of hits) body.append(referenceRow(comp));
       if (!hits.length) body.append(empty(t("hookui.noMatch")));
       return;
     }
     for (const [g, name] of Object.entries(cat.groups)) {
-      const rows = cat.components.filter((x) => x.group === g);
+      const rows = (cat.components || []).filter((x) => x.group === g);
       if (!rows.length) continue;
       const inner = el("div");
-      for (const comp of rows) inner.append(paletteRow(comp, show, cat, edits));
+      for (const comp of rows) inner.append(referenceRow(comp));
       body.append(collapsible({
         title: name,
         count: String(rows.length),
@@ -750,68 +1172,35 @@ function paletteCard(show, cat, edits) {
       }));
     }
   }
+  search.addEventListener("input", () => {
+    HK_SEARCH = search.value;
+    paint();
+  });
   paint();
   return c;
 }
 
-// Fuzzy plus INITIALISM: with 128 components a substring search is not enough —
-// `cw` should find `cache-write`, which plain substring matching does not.
-function matches(comp, q) {
-  const id = comp.id.toLowerCase();
-  if (id.includes(q)) return true;
-  if ((comp.summary || "").toLowerCase().includes(q)) return true;
-  const initials = id.split("-").map((p) => p[0]).join("");
-  if (initials.startsWith(q)) return true;
-  let i = 0;
-  for (const ch of id) if (ch === q[i]) i++;
-  return i === q.length;
-}
-
-function paletteRow(comp, show, cat, edits) {
+function referenceRow(comp) {
   const row = el("div", "hk-prow");
-  row.append(el("span", "hk-prow-id", comp.id));
-  // The cost chip is the CLI's own word. A friendlier synonym would be a state
-  // that does not exist.
-  row.append(chip(comp.cost, comp.cost === "refused" ? "bad" : null));
-  const sample = comp.previews && comp.previews[comp.defaults.render];
-  row.append(ansiBlock(sample || "", "hk-preview hk-preview-chip"));
-
-  // A REFUSED component gets NO BUTTON AT ALL, never a disabled one — the same
-  // rule a connected tool's Connect button follows. "We decided against this"
-  // and "we forgot" must not look the same, which is why the row exists at all.
-  if (comp.cost === "refused") {
-    row.append(el("div", "note note-warn hk-prow-why", comp.refused_reason));
-    return row;
-  }
-  const acts = el("div", "row-actions");
-  for (const n of [1, 2, 3]) {
-    const legal = lineLegal(show, n);
-    const line = show.lines[n - 1];
-    const b = el("button", "btn btn-xs btn-ghost", tn(n, "hookui.addTo"));
-    b.type = "button";
-    if (!legal.ok) {
-      b.disabled = true;
-      b.title = legal.why;
-    } else if (line.full) {
-      b.disabled = true;
-      b.title = t("hookui.lineFull", { n });
-    } else {
-      b.addEventListener("click", () =>
-        edits.action("add" + comp.id + n, "/api/statusline/set",
-          bd({ line: n, pos: line.items.length + 1, type: comp.id }),
-          t("hookui.added", { id: comp.id, n })));
-    }
-    acts.append(b);
-  }
-  row.append(acts);
+  const top = el("div", "hk-prow-head");
+  top.append(el("span", "hk-prow-id", comp.id));
+  top.append(chip(comp.cost, comp.cost === "refused" ? "bad" : null));
+  row.append(top);
+  if (comp.summary) row.append(el("div", "hk-prow-desc", comp.summary));
+  const sample = comp.previews && comp.previews[(comp.defaults && comp.defaults.render) || comp.renderers[0]];
+  if (sample) row.append(ansiBlock(sample, "hk-preview hk-preview-chip"));
+  // A REFUSED part keeps its slot and carries the measurement that refused it:
+  // "we decided against this" and "we forgot" must not look the same.
+  if (comp.cost === "refused") row.append(el("div", "note note-warn hk-prow-why", comp.refused_reason));
   return row;
 }
 
-// ── presets ────────────────────────────────────────────────────────────────
-// Directly below the gate — the `orc diy` presets position. Applying one
-// REPLACES the layout, so it is always confirmed and the loss is NAMED.
-function presetsCard(presets) {
+/* ══ presets ══════════════════════════════════════════════════════════════ */
+// Applying one REPLACES the layout, so it is always confirmed and the loss is
+// NAMED — the `orc diy init --force` rule.
+function presetsCard(presets, plan) {
   const c = card(t("hookui.presets"));
+  c.append(el("div", "note", t("hookui.presetsAbout")));
   if (!presets || !presets.presets) return c;
   for (const p of presets.presets) {
     const row = el("div", "hk-preset");
@@ -825,7 +1214,15 @@ function presetsCard(presets) {
     if (!p.active) {
       const b = el("button", "btn btn-xs btn-ghost", t("hookui.apply"));
       b.type = "button";
-      b.addEventListener("click", () => confirmApply(p.name));
+      // A preset is written STRAIGHT AWAY, so it cannot run while ops are
+      // staged: those ops carry positions computed against a layout the preset
+      // is about to replace.
+      if (plan.dirty) {
+        b.disabled = true;
+        b.title = t("hookui.applyFirst");
+      } else {
+        b.addEventListener("click", () => confirmApply(p.name));
+      }
       row.append(b);
     }
     c.append(row);
@@ -838,13 +1235,15 @@ function confirmApply(name) {
     title: t("hookui.applyTitle", { name }),
     body: el("div", "note", t("hookui.applyWarn")),
     actions: [
-      { label: t("common.cancel"), kind: "ghost" },
+      { label: t("common.cancel"), cls: "btn-ghost", onClick: (c) => c() },
       {
         label: t("hookui.apply"),
-        kind: "primary",
-        onClick: async () => {
+        cls: "btn-primary",
+        onClick: async (c) => {
+          c();
           const r = await post("/api/statusline/apply", bd({ name }));
           if (!r.ok) toast(t("hookui.applyFailed"), "bad", (r.output || "").trim());
+          HK_OPS = [];
           rerender();
         },
       },
@@ -857,12 +1256,14 @@ function confirmReset() {
     title: t("hookui.resetTitle"),
     body: el("div", "note", t("hookui.resetWarn")),
     actions: [
-      { label: t("common.cancel"), kind: "ghost" },
+      { label: t("common.cancel"), cls: "btn-ghost", onClick: (c) => c() },
       {
         label: t("hookui.resetLayout"),
-        kind: "primary",
-        onClick: async () => {
+        cls: "btn-primary",
+        onClick: async (c) => {
+          c();
           await post("/api/statusline/reset", bd({}));
+          HK_OPS = [];
           rerender();
         },
       },
@@ -870,11 +1271,32 @@ function confirmReset() {
   });
 }
 
-// ── advanced ───────────────────────────────────────────────────────────────
-function advancedCard(show, cat, edits) {
+/* ══ more ═════════════════════════════════════════════════════════════════ */
+// THE COLOUR SET IS A DOCUMENT SETTING, and it now goes to the command that
+// writes document settings. It used to be routed through `statusline line 1
+// --theme`, which set ONE line's override while the picker read the document's
+// value back — so the button never moved and only a third of the bar changed.
+// One command per scope, and the panel calls the one that matches the control.
+function advancedCard(cat, plan) {
   const c = card(t("hookui.advanced"));
-  c.append(labelled(t("hookui.theme"), pickRow(Object.keys(cat.themes), show.theme, (v) =>
-    edits.action("theme", "/api/statusline/line", bd({ line: 1, theme: v }), t("hookui.themeChange", { v })))));
+
+  const themes = el("div", "hk-theme-list");
+  for (const name of Object.keys(cat.themes || {})) {
+    const b = el("button", "hk-theme" + (plan.doc.theme === name ? " hk-theme-on" : ""));
+    b.type = "button";
+    b.append(el("span", "hk-theme-name", name));
+    // WHY somebody would pick it — the CLI's sentence, not one written here.
+    const about = (cat.themes_about || {})[name];
+    if (about) b.append(el("span", "note", about));
+    b.addEventListener("click", () => hkOp({ op: "doc", field: "theme", value: name, label: t("hookui.themeChange", { v: name }) }));
+    themes.append(b);
+  }
+  c.append(labelled(t("hookui.theme"), themes, t("hookui.themeAbout")));
+  c.append(el("div", "note", t("hookui.themeOverride")));
+
+  c.append(labelled(t("hookui.glyphs"),
+    pickRow(cat.glyph_sets, plan.doc.glyphs, (v) => hkOp({ op: "doc", field: "glyphs", value: v, label: t("hookui.glyphsDocChange", { v }) })),
+    t("hookui.glyphsDocAbout")));
 
   const re = el("button", "btn btn-sm btn-ghost", t("hookui.recompile"));
   re.type = "button";