@awebai/oats 0.67.1 → 0.68.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (64) hide show
  1. package/bin/oats.mjs +112 -16
  2. package/docs/capabilities.md +54 -5
  3. package/docs/capability-manifest.schema.json +4 -0
  4. package/docs/design/2026-10-22-module-upgrade.md +192 -0
  5. package/docs/design/README.md +4 -0
  6. package/docs/desktop-cli-api.md +248 -9
  7. package/docs/desktop.md +316 -63
  8. package/docs/first-team.md +5 -3
  9. package/docs/implementation.md +42 -3
  10. package/docs/integrations.md +16 -4
  11. package/docs/knowledge.md +44 -27
  12. package/docs/layers.md +2 -2
  13. package/docs/official-catalog.md +5 -5
  14. package/docs/packages.md +14 -14
  15. package/docs/release-notes/v0.68.0.md +504 -0
  16. package/docs/release-notes/v0.68.1.md +102 -0
  17. package/docs/servers.md +6 -1
  18. package/docs/souls-and-instances.md +38 -3
  19. package/docs/tui.md +663 -243
  20. package/docs/upgrading.md +66 -6
  21. package/docs/workspaces.md +2 -2
  22. package/lib/capability-contract.mjs +6 -5
  23. package/lib/core.mjs +222 -38
  24. package/lib/instance-events.mjs +1 -1
  25. package/lib/instance-resolution.mjs +5 -5
  26. package/lib/instance-upgrade.mjs +1445 -0
  27. package/lib/materialize.mjs +225 -78
  28. package/lib/servers.mjs +11 -7
  29. package/lib/upgrade-state.mjs +101 -0
  30. package/lib/workspace.mjs +4 -1
  31. package/lib/worktree.mjs +103 -12
  32. package/package-catalog.json +5 -4
  33. package/package.json +1 -1
  34. package/packages/client/cli-adapter.mjs +15 -1
  35. package/packages/client/cli-locator.mjs +2 -2
  36. package/packages/client/deployment-panel.mjs +6 -2
  37. package/packages/client/instance-display-name.mjs +18 -0
  38. package/packages/client/keymap.mjs +89 -45
  39. package/packages/client/keys-file.mjs +9 -5
  40. package/packages/client/panel-views.mjs +16 -3
  41. package/packages/client/spawn-naming.mjs +7 -6
  42. package/packages/client/spawn-preview-cli.mjs +37 -1
  43. package/packages/client/spawn-preview-contract.mjs +35 -0
  44. package/packages/client/spawn-preview.mjs +35 -2
  45. package/packages/client/team-members.mjs +4 -1
  46. package/packages/client/workspace-step.mjs +25 -0
  47. package/packages/tui/README.md +5 -5
  48. package/packages/tui/lib/actions.mjs +51 -27
  49. package/packages/tui/lib/client.mjs +4 -2
  50. package/packages/tui/lib/config.mjs +4 -4
  51. package/packages/tui/lib/main.mjs +27 -13
  52. package/packages/tui/lib/model.mjs +143 -21
  53. package/packages/tui/lib/store.mjs +343 -68
  54. package/packages/tui/lib/term/keys.mjs +5 -3
  55. package/packages/tui/lib/term/kitty.mjs +28 -10
  56. package/packages/tui/lib/term/screen.mjs +15 -6
  57. package/packages/tui/lib/term/through.mjs +33 -28
  58. package/packages/tui/lib/views/capabilities.mjs +6 -6
  59. package/packages/tui/lib/views/frame.mjs +88 -109
  60. package/packages/tui/lib/views/help.mjs +57 -35
  61. package/packages/tui/lib/views/instances.mjs +48 -30
  62. package/packages/tui/lib/views/souls.mjs +9 -8
  63. package/packages/tui/lib/views/workspaces.mjs +55 -0
  64. package/skills/oats-getting-started/SKILL.md +92 -43
@@ -14,7 +14,7 @@ import { resolve } from "node:path";
14
14
  import { bindings } from "./actions.mjs";
15
15
  import { TERMS, capabilityCatalogKey, cliDeploymentList, deploymentsListSupported, createCapabilityCatalog, createLifecycleBoundary, createLifecycleConfirmation, createRetiresInFlight, createSoulCatalog, createSpawnApplyBoundary, createSpawnPreview, createSpawnTransaction, displayLine, heldHome, pendingEntry, prepareRemoteTerm, sessionAttachArgv, soulCatalogKey, startInstance } from "./client.mjs";
16
16
  import { loadConfig, loadKeys } from "./config.mjs";
17
- import { ACT_WORDS, LIST_WORDS, actContext, actCwd, localDeployments, model, outcomeOf, reachedMachines, roster, spawnContext } from "./model.mjs";
17
+ import { ACT_WORDS, LIST_WORDS, actContext, actCwd, listRowsOf, localDeployments, model, outcomeOf, reachedMachines, roster, spawnContext } from "./model.mjs";
18
18
  import { createPanel, sweep } from "./panel.mjs";
19
19
  import { CHANGE_FILES, admitDeployment, createIdentityReads, createReader, findDeployment, leaveInstance, probeKernel, realpath, startExec, tellable } from "./read.mjs";
20
20
  import { initialState, reduce } from "./store.mjs";
@@ -145,7 +145,7 @@ export async function main({ argv, stdin, stdout, stderr, env, proc = process, n
145
145
  if (!isTerminal({ stdin, stdout, env })) { stderr.write(`${NO_TERMINAL}\n`); return 1; }
146
146
  const config = effects.loadConfig({ env, home, platform: proc.platform });
147
147
  if (!config.ok) { stderr.write(config.lines.map((line) => `${line}\n`).join("")); return 1; }
148
- // keys.json, the chord family (docs/tui.md, "Switch to Ctrl+Shift"): read once, here, and never
148
+ // keys.json, the chord family (docs/tui.md, "Switch family"): read once, here, and never
149
149
  // a reason not to start: what is wrong with it is the default, and the help says why.
150
150
  const keysRead = effects.loadKeys({ env, home });
151
151
  const found = effects.findDeployment(resolve(cwd(), options.dir ?? "."));
@@ -167,7 +167,7 @@ export async function main({ argv, stdin, stdout, stderr, env, proc = process, n
167
167
  const clock = () => new Date(now()).toISOString();
168
168
  const look = glyphs(env, { ascii: options.ascii || config.ascii });
169
169
  const screen = createScreen({ ...look, color: colorEnabled(env) });
170
- let state = initialState({ deployment: found.ok ? found.deployment : null, cli: probe.cli, home, entry: found.ok ? pendingEntry(null, clock()) : null, actions: config.actions, ascii: look.ascii, platform: proc.platform, detachKey: config.detachKey, keysRead });
170
+ let state = initialState({ deployment: found.ok ? found.deployment : null, cli: probe.cli, home, entry: found.ok ? pendingEntry(null, clock()) : null, actions: config.actions, ascii: look.ascii, colour: colorEnabled(env), platform: proc.platform, detachKey: config.detachKey, keysRead });
171
171
  const keymap = bindings(state.actions);
172
172
  // THE KITTY KEYBOARD PROTOCOL (docs/tui.md, "Chords"): asked for as the terminal is taken (the
173
173
  // guard's PUSH and QUERY), "asking" until it answers or KEYBOARD_WAIT_MS passes, then the flags
@@ -612,14 +612,19 @@ export async function main({ argv, stdin, stdout, stderr, env, proc = process, n
612
612
  // The focused group's screen as the Instances view gives it, also behind the help or another
613
613
  // overlay, which draw no panel (round 1 of T3's review).
614
614
  const region = placed()?.focused ?? { cols: Math.max(1, size.cols), rows: Math.max(1, size.rows - 6) };
615
- const mine = { id, panel: null, cols: region.cols, rows: region.rows };
615
+ const mine = { id, panel: null, asked: false, cols: region.cols, rows: region.rows };
616
616
  viewers.set(id, mine);
617
617
  // Shown or hidden as this frame draws the panel: behind an overlay it shows once that closes.
618
618
  fitPanel(composed().made);
619
+ // The window is asked for after this step's effects: one closed by then (a workspace left in the
620
+ // same read of input) is never asked for, and a window made for a viewer the loop no longer
621
+ // holds (closed, or replaced) is closed, not left open in the panel.
619
622
  Promise.resolve()
620
- .then(() => panel.open({ argv: [process.execPath, bin, ...args], cols: region.cols, rows: region.rows, instead: null }))
621
- .then(({ id: made }) => {
622
- if (viewers.get(id) !== mine) return;
623
+ .then(() => { if (viewers.get(id) !== mine) return null; mine.asked = true; return panel.open({ argv: [process.execPath, bin, ...args], cols: region.cols, rows: region.rows, instead: null }); })
624
+ .then((opened) => {
625
+ if (opened === null) return;
626
+ const made = opened.id;
627
+ if (viewers.get(id) !== mine) { panel.close(made); return; }
623
628
  mine.panel = made;
624
629
  // The panel displays it, and it takes the keys; a frame of another size meanwhile is the
625
630
  // next fitPanel's.
@@ -641,7 +646,8 @@ export async function main({ argv, stdin, stdout, stderr, env, proc = process, n
641
646
  const v = viewers.get(id);
642
647
  if (v === undefined) return;
643
648
  forgetViewer(v);
644
- if (v.panel === null) panel.close(); else panel.close(v.panel);
649
+ if (v.panel !== null) panel.close(v.panel);
650
+ else if (v.asked) panel.close();
645
651
  }
646
652
  /** The panel brought to what the frame drew (`made.regions`, one per group drawn): shown or not
647
653
  * (no capture runs while it is hidden, and one runs when it shows again); every tab of a drawn
@@ -686,7 +692,7 @@ export async function main({ argv, stdin, stdout, stderr, env, proc = process, n
686
692
  const under = state.view === "help" || state.view === "act" ? state.back : state.view;
687
693
  const listing = under === "switcher";
688
694
  const r = listing ? { notice: null, note: null } : roster(state, at);
689
- const g = layout(r.notice, size, { note: r.note, ascii: state.ascii, outcome: listing ? null : outcomeOf(state), terminal: state.tabs.length > 0, open: listing ? null : under });
695
+ const g = layout(r.notice, size, { note: r.note, ascii: state.ascii, outcome: listing ? null : outcomeOf(state), terminal: state.tabs.length > 0, open: listing ? null : under, list: listRowsOf(state, at) });
690
696
  const area = mainArea(g, size.cols).cols;
691
697
  const m = { ...model(state, { page: g.page, body: g.body, now: now(), at, cols: g.listCols, area }), screen: screens.get(state.terminal?.id) ?? null, screens };
692
698
  return { size, g, m, area };
@@ -707,8 +713,8 @@ export async function main({ argv, stdin, stdout, stderr, env, proc = process, n
707
713
  * read is dropped: it cancels the leader (a paste), and it is not the agent's either. */
708
714
  function typed(events) {
709
715
  for (const event of events) {
710
- if (event.input) { if (keysReady()) panel.input(event.input); }
711
- else if (event.paste !== undefined) { if (keysReady()) panel.paste(event.paste); }
716
+ if (event.input) { if (keysReady()) panel.input(event.input); passed(); }
717
+ else if (event.paste !== undefined) { if (keysReady()) panel.paste(event.paste); passed(); }
712
718
  else if (event.keyboard !== undefined) answered(event.keyboard);
713
719
  else if (event.back) {
714
720
  parser = newParser();
@@ -724,6 +730,13 @@ export async function main({ argv, stdin, stdout, stderr, env, proc = process, n
724
730
  }
725
731
  watchThrough();
726
732
  }
733
+ /** What the store does not see, a key typed to the agent or a resize, told to it while a line of
734
+ * one key stands (the store's `passed`): it goes, and the frame with it. */
735
+ function passed() {
736
+ if (state.outcome?.once !== true) return;
737
+ took(reduce(state, { passed: true }, keymap));
738
+ guard.draw();
739
+ }
727
740
  /** The terminal's answer to the protocol's query (`flags`), or none in time (null): the protocol is
728
741
  * read from now on when the answer holds flag 1, and popped otherwise; an answer after that is
729
742
  * not taken. The parser or the scanner that read the answer reads the rest of its read as it
@@ -780,7 +793,7 @@ export async function main({ argv, stdin, stdout, stderr, env, proc = process, n
780
793
  if (typing()) return typed(through.feed(bytes));
781
794
  act(parser.feed(bytes)); watchEscape();
782
795
  },
783
- onResize() { full = true; guard.draw(); },
796
+ onResize() { full = true; passed(); guard.draw(); },
784
797
  // Ctrl+L and the return from a stop: the whole screen, and the open terminal captured afresh.
785
798
  onRedraw() { full = true; if (viewers.size) panel.refresh(); guard.draw(); },
786
799
  // A cycle in flight when the process stops is no evidence about the deployment (lib/read.mjs):
@@ -801,7 +814,8 @@ export async function main({ argv, stdin, stdout, stderr, env, proc = process, n
801
814
  onEnd() { ended = true; spawnTimers.end(); dismiss(confirmation?.n); panel.end(); identities.stop(); reader.stop(); if (dir !== null) { try { effects.removeDir(dir); } catch { /* not empty, or gone */ } } },
802
815
  });
803
816
  function refresh(how) { Promise.resolve(reader.request(how)).catch(() => {}); }
804
- /** A preflight under way when the process stops: given up, and the store told. */
817
+ /** A preflight under way when the process stops: given up, and the store told. Its state alone is
818
+ * taken, as of the other events the store names UNTAKEN (store.mjs): a restore steps on none. */
805
819
  function stopPreflight() {
806
820
  if (preflight === null) return;
807
821
  giveUpPreflight();
@@ -7,7 +7,7 @@
7
7
  // in. What it adds is the TUI's: the window, the clock times, and which fact stands on which line.
8
8
  import {
9
9
  TERMS, panelData, displayLine, DETAIL_WITHHELD, originLead, instanceId, instanceVisibleInTree, waitingRollup, collapseKey, filterInstanceTree,
10
- hasInstanceChildren, heldHome, instanceSiblings, siblingText, rosterSections, deploymentState, rowStale, primaryDeployment, isMultiDeployment, runtimeState, runtimeCounts, instanceColor,
10
+ hasInstanceChildren, heldHome, instanceSiblings, siblingText, rosterSections, deploymentState, rowStale, primaryDeployment, isMultiDeployment, runtimeState, runtimeCounts, instanceColor, instanceDisplayName,
11
11
  waitingClaim, waitingLabel, waitedText, waitingClock, waitingBelowText, instanceActs, rowReason,
12
12
  identityMemory, viewModel, listedViews, workspaceChoices, workspaceChoiceRows, choiceMatches, UNMATCHED_SECTION, shortPath, machineLabels,
13
13
  openAct, deployments as heldDeployments, attachExit, preflightFailure, kernelLines,
@@ -65,6 +65,19 @@ export function workspaceOf(state, id, at) {
65
65
  if (id === null) return null;
66
66
  return viewModel(heldOf(state, at), TERMS).views.find((v) => v.id === id || v.deployments.includes(id))?.id ?? null;
67
67
  }
68
+ /** What a workspace's memory for the run is kept under (docs/tui.md, "Tabs"): the workspace that
69
+ * holds deployment `id` (workspaceOf), so another of its deployments finds the same memory; a
70
+ * deployment that reports no workspace, by its own id. Null for no deployment. */
71
+ export const memoryKey = (state, id, at) => (id === null ? null : workspaceOf(state, id, at) ?? id);
72
+ /** The palette's recency of the open workspace (`recent`, per memoryKey): its instances opened or
73
+ * shown in this run, the latest first. */
74
+ export const recentOf = (state, at) => state.recent.get(memoryKey(state, state.open, at)) ?? [];
75
+ /** The memoryKeys the views hold now (each view's id, and its deployments'), and the one each
76
+ * deployment whose read failed with nothing kept was in when it was last read (`unreadKeys`): it is
77
+ * in no view but its own until it is read again, so that view may only seem gone. */
78
+ export function memoryKeys(state, at) {
79
+ return new Set([...viewModel(heldOf(state, at), TERMS).views.flatMap((v) => [v.id, ...v.deployments]), ...state.unreadKeys.values()]);
80
+ }
68
81
 
69
82
  const text = (value) => typeof value === "string" && value !== "";
70
83
  const pad = (n) => String(n).padStart(2, "0");
@@ -240,8 +253,8 @@ function build(state, at) {
240
253
  status,
241
254
  workspace: text(panel?.workspace?.name) ? panel.workspace.name : "",
242
255
  machines, here,
243
- // The one machine of a view that holds no deployment of this machine: nothing else names it,
244
- // since a view of one deployment has no heading.
256
+ // The one machine of a view that holds no deployment of this machine: a view of one deployment
257
+ // has no heading, so the detail names it (detailOf).
245
258
  machine: !here && away.length === 1 ? away[0] : null,
246
259
  // The counts in the order they are drawn. `shared`: the word is the shared home's.
247
260
  counts: [
@@ -317,14 +330,26 @@ export function disclosure(state, r, item) {
317
330
  return !r.filtering && state.collapsed.has(collapseKey(state.open, item.id)) ? "closed" : "open";
318
331
  }
319
332
 
333
+ /** An instance's name as its row draws it: the shared `instanceDisplayName`, the Desktop's sidebar
334
+ * label (`oats-expert` is drawn "Oats expert"; a name of nothing but `-` as it is). The display
335
+ * filter is asked about the name first, as it came: a name it withholds is passed on unchanged, so
336
+ * shown() withholds it in the view, since the words could hide what made it unsafe (a `-` in a
337
+ * credential's URL becomes a space; a control character at an end is trimmed). */
338
+ const rowName = (name) => (displayLine(name) === DETAIL_WITHHELD ? name : instanceDisplayName(name) || name);
320
339
  /** One row of the list: its mark, its name, the word its mark cannot say (or null), whether it
321
340
  * waits, and on a folded row only, how many instances are folded away under it (`folded`) and how
322
341
  * many of those wait (`below`). A row that is not folded says nothing of its children: they
323
- * stand under it, indented. */
342
+ * stand under it, indented. `selected` the selected row, `cursor` whether it carries `>`.
343
+ * The name is drawn as words (rowName): it is what the row shows and nothing else. The filter, the
344
+ * palette, the detail, the tabs, a confirmation and every change sent to the kernel keep the
345
+ * instance's name. */
324
346
  function listRow(state, r, item) {
325
347
  const closed = disclosure(state, r, item) === "closed";
326
348
  return {
327
- id: item.id, name: item.row.instance, depth: item.depth, selected: item.id === state.selected,
349
+ id: item.id, name: rowName(item.row.instance), depth: item.depth, selected: item.id === state.selected,
350
+ // The selected row keeps its reverse video while the list of workspaces has the focus, but not the
351
+ // cursor: only the region with the focus draws `>`.
352
+ cursor: item.id === state.selected && state.focus !== "workspaces",
328
353
  mark: markOf(item.row), color: rowColour(item.row), word: wordOf(item.row, state.ascii),
329
354
  waiting: waitingClaim(item.row, { stale: r.stale(item.row) }) !== null,
330
355
  folded: closed ? r.folded.get(item.id) ?? 0 : 0,
@@ -372,6 +397,11 @@ const LEADER_CLOSE = LEADER.find((entry) => entry.does === "close-terminal").key
372
397
  export const TAB_WORDS = Object.freeze({
373
398
  full: (limit, leader) => [{ own: `${limit} terminals are open; close one with ` }, { own: `${leader} ${keyLabel(LEADER_CLOSE)}`, whole: true }, { own: "." }],
374
399
  });
400
+ /** The line of a leader whose key came in its own read (docs/tui.md, "The leader"): dropped, and
401
+ * why. */
402
+ export const LEADER_WORDS = Object.freeze({
403
+ merged: (leader) => [{ own: leader, whole: true }, { own: " and the next key came in one read, so nothing ran: press them one after the other." }],
404
+ });
375
405
  /** The lines of a split that is not made (docs/tui.md, "Splits"): a second split, and a panel too
376
406
  * small for two groups (`min` views/split.mjs SPLIT_MIN). */
377
407
  export const SPLIT_WORDS = Object.freeze({
@@ -473,10 +503,12 @@ function detailOf(state, r, item, now, acts) {
473
503
  const row = item.row, facts = [];
474
504
  const add = (label, value, form = "line") => { if (text(value)) facts.push({ label, value, form }); };
475
505
  add("soul", row.agent);
506
+ // Which machine the instance is on: in a view of two or more deployments, and in one whose only
507
+ // deployment is another machine's, where no heading and no row of the list of workspaces names it.
508
+ if (r.multi || r.machine !== null) add("machine", row.deployment?.machine);
476
509
  if (r.multi) {
477
- // Which machine the instance is on, and, when that deployment is not live, the whole
478
- // sentence that says why: a heading has room for the short reason only.
479
- add("machine", row.deployment?.machine);
510
+ // When that deployment is not live, the whole sentence that says why: a heading has room for
511
+ // the short reason only.
480
512
  const of = r.deployments.find((d) => d.id === row.deployment?.id);
481
513
  const said = of ? deploymentState(of) : null;
482
514
  if (said && said.key !== "live") add("", said.detail, "wrap");
@@ -531,6 +563,20 @@ export const LIST_WORDS = Object.freeze({
531
563
  leaving: "oats: a change to this computer's list of deployments is still running; `oats deployments` shows the list.",
532
564
  });
533
565
 
566
+ /** The lines of the list of workspaces (docs/tui.md, "The list of workspaces"): the leader's Up or
567
+ * Down at an end of it, and a row picked there that is not a deployment any more. */
568
+ export const WORKSPACE_WORDS = Object.freeze({
569
+ above: () => [{ own: "No workspace above this one." }],
570
+ below: () => [{ own: "No workspace below this one." }],
571
+ refused: (name) => [{ shown: name }, { own: ": not an OATS deployment any more." }],
572
+ });
573
+ /** The switcher's choices with no filter, in its order (workspaceList's rows are their keys). */
574
+ export const listChoices = (state, at = new Date(0).toISOString()) => switcherOf(state, at, "").made.items.filter((item) => item.key !== undefined);
575
+ /** The switcher's choice of key `key`, with no filter, or null. */
576
+ export const listChoice = (state, key, at) => listChoices(state, at).find((item) => item.key === key) ?? null;
577
+
578
+ /** The help's `keys` on macOS (views/help.mjs chordFamilyLines): no family, no file's note. */
579
+ const MAC_KEYS = Object.freeze({ family: null, label: null, note: null, mac: true });
534
580
  /** What the switcher says above its rows, as views/switcher.mjs leadRows reads it. */
535
581
  const leadOf = (state) => ({ said: state.switcher.line, failure: state.listed.failure?.message ?? null, removing: state.switcher.removing !== null });
536
582
  /** How many rows stand above the switcher's choices in an area `cols` wide (the switcher's is the
@@ -572,13 +618,18 @@ function indicatorState(info) {
572
618
  * cuts the path and keeps it).
573
619
  * `keys` are the choices in order; `selected` is the key the selection stands on (the first choice
574
620
  * when the state's own is not listed). */
575
- export function switcher(state, at = new Date(0).toISOString()) {
621
+ export const switcher = (state, at = new Date(0).toISOString()) => switcherOf(state, at, state.switcher.query).made;
622
+ /** The switcher's rows for `query` (`made`), and of each workspace's key whether some instance of it
623
+ * needs input (`waits`), which the list of workspaces says (workspaceList). */
624
+ function switcherOf(state, at, query) {
576
625
  const held = heldOf(state, at);
577
626
  const unserved = state.listed.rows.filter((row) => !state.ctxs.includes(row.path));
578
627
  // Only a row the kernel says is a deployment is matched: a stale one (missing, not one any more) says so instead.
579
628
  const views = listedViews(held, unserved.filter((row) => row.state === "ok"), TERMS);
580
- const rows = workspaceChoiceRows(workspaceChoices(held, TERMS, views));
581
- const query = state.switcher.query;
629
+ const choices = workspaceChoices(held, TERMS, views), rows = workspaceChoiceRows(choices);
630
+ // Whether some instance of a workspace needs input: what this run observes of it alone, the shared
631
+ // choice's `waiting` (its served deployments' reads; unknown or stale is not).
632
+ const waits = new Map(choices.map((choice) => [`view\u0000${choice.id}`, choice.waiting === true]));
582
633
  const viewOf = (id) => views.views.find((v) => v.id === id);
583
634
  const openView = state.open === null ? null : views.views.find((v) => v.id === state.open || v.deployments.includes(state.open))?.id ?? null;
584
635
  const items = [];
@@ -610,10 +661,72 @@ export function switcher(state, at = new Date(0).toISOString()) {
610
661
  );
611
662
  const keys = items.filter((item) => item.key !== undefined).map((item) => item.key);
612
663
  const total = rows.length + unserved.filter((row) => !taken.has(row.path)).length;
613
- return {
664
+ const made = {
614
665
  items, keys, selected: keys.includes(state.switcher.selected) ? state.switcher.selected : keys[0] ?? null,
615
666
  empty: keys.length ? null : total ? "nomatch" : "none",
616
667
  };
668
+ return { made, waits };
669
+ }
670
+ /** THE LIST OF WORKSPACES (docs/tui.md, "The list of workspaces"): one row per workspace the switcher
671
+ * offers, by its name, whatever machines it is on, in the switcher's order, at the top of the
672
+ * sidebar. A workspace only this machine's deployments not opened make is not one of them, nor a
673
+ * view with nothing to open, nor a row of this computer's list: the switcher keeps those (`w` `w`).
674
+ * `lines`: a row `{ key, label, current, waiting }`: `current` the open workspace's row; `waiting`
675
+ * whether some instance of it needs input, as far as this run observes it (an unknown never says
676
+ * so). `rows`: the rows as `{ key, openable }`, for workspaceStep (every row opens). `current`: the
677
+ * open row's key, or null. Kept while what it is made from (LIST_MADE_FROM) is the same: every
678
+ * frame and every key asks for it, and the shared home walks every machine to make it, so it is
679
+ * not asked again for a key or a paint that changed none of that (as `roster` is kept). */
680
+ const LIST_MADE_FROM = ["entries", "remote", "memory", "notes", "rosterAt", "collecting", "ctxs", "open", "cli", "home", "identities", "listed"];
681
+ let listKept = null;
682
+ export function workspaceList(state, at) {
683
+ if (listKept !== null && LIST_MADE_FROM.every((name) => listKept.state[name] === state[name])) return listKept.list;
684
+ const lines = [], { made, waits } = switcherOf(state, at, "");
685
+ for (const item of made.items) {
686
+ if (item.key === undefined || item.path !== undefined) continue;
687
+ const notOpened = item.join?.length > 0 && item.join.length === item.opens.length;
688
+ const opens = item.join?.length > 0 || item.primary !== null;
689
+ if (notOpened || !opens) continue;
690
+ lines.push(Object.freeze({ key: item.key, label: item.label, current: item.open === true, waiting: waits.get(item.key) === true }));
691
+ }
692
+ const list = Object.freeze({ lines: Object.freeze(lines), rows: Object.freeze(lines.map(({ key }) => Object.freeze({ key, openable: true }))), current: lines.find((line) => line.current)?.key ?? null });
693
+ listKept = { state, list };
694
+ return list;
695
+ }
696
+ /** The most lines the list stands on; more are windowed, and the last line says how many are not
697
+ * shown (`+N`), with the dot when an instance of one of them needs input. */
698
+ export const LIST_LINES = 5;
699
+ /** How many rows stand at the top of the sidebar (views/frame.mjs layout's `list`): the list's,
700
+ * LIST_LINES at most, while a workspace is open and the switcher is not shown; else the title's
701
+ * one. */
702
+ export function listRowsOf(state, at) {
703
+ const under = state.view === "help" || state.view === "act" ? state.back : state.view;
704
+ const list = listModel(state, under, at);
705
+ return list === null ? 1 : list.lines.length + (list.more > 0 ? 1 : 0);
706
+ }
707
+ /** The list as the sidebar draws it (views/workspaces.mjs): its lines windowed around the cursor
708
+ * while the list has the focus, else around the open workspace's row; `more` how many are not
709
+ * shown, and `moreWaiting` whether one of those is waiting; `focused`; `cursor` the cursor's row
710
+ * key, null without the focus. Null while nothing is listed (no workspace open, or the switcher
711
+ * shown): the title stands there. */
712
+ function listModel(state, under, at) {
713
+ if (under === "switcher" || state.open === null) return null;
714
+ const list = workspaceList(state, at);
715
+ if (!list.lines.length) return null;
716
+ const focused = state.view === "instances" && state.focus === "workspaces";
717
+ const cursor = focused ? (list.rows.some((row) => row.key === state.workspaceCursor) ? state.workspaceCursor : list.current) : null;
718
+ return { ...listWindow(list.lines, cursor ?? list.current), focused, cursor };
719
+ }
720
+ /** The lines the list draws, windowed around `keep` (the focused row, else the open one): all of
721
+ * them when they fit, else LIST_LINES - 1 of them, and `more`, how many are not shown, and
722
+ * `moreWaiting`, whether one of those is `waiting`. */
723
+ export function listWindow(lines, keep) {
724
+ if (lines.length <= LIST_LINES) return { lines, more: 0, moreWaiting: false };
725
+ const height = LIST_LINES - 1, at = Math.max(0, lines.findIndex((line) => line.key === keep));
726
+ const top = Math.min(Math.max(0, at - Math.floor(height / 2)), lines.length - height);
727
+ const shown = lines.slice(top, top + height);
728
+ const moreWaiting = lines.some((line, i) => (i < top || i >= top + height) && line.waiting);
729
+ return { lines: shown, more: lines.length - shown.length, moreWaiting };
617
730
  }
618
731
  /** The window of the switcher's `items` in a pane `height` rows tall, from `top`, that holds the choice
619
732
  * `key` and, while they fit, the indicator lines under it (scroll.mjs windowOf, asked to keep the last
@@ -669,7 +782,7 @@ export function paletteItems(state, at = new Date(0).toISOString()) {
669
782
  const r = roster(state, at);
670
783
  const openable = r.instances.filter((row) => openDecision(state, row, instanceActs(row)).open);
671
784
  // The record of focus the shared order reads: larger is more recent, `recent` is the latest first.
672
- const lastFocus = new Map(state.recent.map((id, i) => [id, state.recent.length - i]));
785
+ const recent = recentOf(state, at), lastFocus = new Map(recent.map((id, i) => [id, recent.length - i]));
673
786
  const item = (row) => {
674
787
  const machine = elsewhere(row) ? row.deployment?.machine ?? row.server : null;
675
788
  // `sibling`: the shared words for its siblings, or null; never part of what a query matches.
@@ -721,9 +834,9 @@ export function paletteItems(state, at = new Date(0).toISOString()) {
721
834
  const items = runs.flat(), selectable = items.filter((each) => each.kind !== "group"), instances = selectable.filter((each) => each.kind === "instance");
722
835
  // With nothing chosen yet, the first row that can be selected; but in the palette as it opens (no
723
836
  // query), when that is the shown tab's instance (the most recent), the instance shown before it
724
- // (`recent`'s second, wherever its group puts it), else the second instance: the palette and Enter
725
- // go back to the terminal before it, as the Desktop's recent group did.
726
- const before = instances.find((each) => each.id === state.recent[1]) ?? instances[1];
837
+ // (the second of this workspace's recency, wherever its group puts it), else the second instance:
838
+ // the palette and Enter go back to the terminal before it, as the Desktop's recent group did.
839
+ const before = instances.find((each) => each.id === recentOf(state, at)[1]) ?? instances[1];
727
840
  const first = p.query === "" && instances.length > 1 && selectable[0] === instances[0] && instances[0].id === state.terminal?.id ? before : selectable[0];
728
841
  return {
729
842
  items, runs: runs.map((run) => run.filter((each) => each.kind !== "group").map((each) => each.key)),
@@ -776,12 +889,19 @@ export function model(state, { page, body = page, now, at, cols, area = cols })
776
889
  workspace: r.workspace, machines: r.machines, here: r.here, machine: r.machine, counts: r.counts, readAt: r.readAt, notice: r.notice, note: r.note, empty: r.empty, observed: r.observed,
777
890
  detailTop: state.detailTop, helpTop: state.helpTop, open: state.open !== null,
778
891
  detachKey: state.detachKey, opening: state.opening, openable: false,
779
- // The chords read now, `[key id, does]` (actions.mjs chordsRead), and whether the terminal
780
- // confirms the kitty keyboard protocol: then the help and a terminal's cheat sheet lead with them.
892
+ // The chords read now, `[key id, does]` (actions.mjs chordsRead), whether the terminal confirms
893
+ // the kitty keyboard protocol, and whether every chord bound is read now (under the protocol, or
894
+ // the Alt family, whose keys all come without it): then the help and a terminal's cheat sheet
895
+ // lead with them.
781
896
  chords: [...chordsRead(state.chords, state.keyboard !== null)], kitty: state.keyboard !== null,
897
+ chordsLead: state.chords.size > 0 && chordsRead(state.chords, state.keyboard !== null).size === state.chords.size,
898
+ // Whether a chord shows the Nth tab (tab-1 to tab-9): the tabs carry their numbers only then
899
+ // (views/frame.mjs stripRow). On macOS none does: ⌥⌘N never reaches a terminal.
900
+ tabNumbers: [...state.chords.values()].some((does) => /^tab-[1-9]$/.test(does)),
782
901
  // The family the chords are bound in (keys.json, lib/config.mjs loadKeys), its name, and the line that says
783
902
  // why the file was not taken, or null (the shared chordFamilyNote): the help's chords section names both.
784
- keys: state.keysRead ? Object.freeze({ family: state.keysRead.family, label: CHORD_FAMILY_LABELS[state.keysRead.family] ?? CHORD_FAMILY_LABELS[DEFAULT_CHORD_FAMILY], note: chordFamilyNote(state.keysRead) }) : null,
903
+ // macOS has no family (`mac`): its chords are the arrows, whatever keys.json says.
904
+ keys: state.mac === true ? MAC_KEYS : state.keysRead ? Object.freeze({ family: state.keysRead.family, label: CHORD_FAMILY_LABELS[state.keysRead.family] ?? CHORD_FAMILY_LABELS[DEFAULT_CHORD_FAMILY], note: chordFamilyNote(state.keysRead) }) : null,
785
905
  // The palette's own keys, `[key id, does]` (actions.mjs paletteKeys; none on macOS): its cheat
786
906
  // sheet and the help name them.
787
907
  paletteKeys: [...state.paletteKeys],
@@ -792,13 +912,15 @@ export function model(state, { page, body = page, now, at, cols, area = cols })
792
912
  split: state.split, group: state.group, panelOpen: state.tabs.length > 0, groups: groupsOf(state),
793
913
  tabs: groupsOf(state)[state.group].tabs,
794
914
  act: state.view === "act" && state.act ? actView(state) : null,
795
- // The leader waits for its key (the cheat sheet is its hint), and the palette, while it is open.
796
- leader: state.leader?.waiting === true, palette: state.palette === null ? null : paletteView(state, body, at),
915
+ // The palette, while it is open.
916
+ palette: state.palette === null ? null : paletteView(state, body, at),
797
917
  souls: under === "souls" ? soulsView(state, page, at) : null,
798
918
  capabilities: under === "capabilities" ? capabilitiesView(state, page, at) : null,
799
919
  spawn: state.spawn === null ? null : spawnView(state, body, at),
800
920
  // The line under the sidebar's title: the last outcome, else a spawn under way (outcomeOf).
801
921
  outcome: outcomeOf(state),
922
+ // The list of workspaces at the top of the sidebar, and whether colour may say the dot.
923
+ workspaces: listModel(state, under, at), colour: state.colour !== false,
802
924
  };
803
925
  if (under === "switcher") {
804
926
  const s = switcher(state, at);