@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
@@ -45,6 +45,7 @@ import { publicDeployment } from './deployment-panel.mjs';
45
45
  import { teamMembers } from './team-members.mjs';
46
46
  import { requireTerms } from './client-terms.mjs';
47
47
  import { ROSTER_WORKSPACE_KEY } from './cli-adapter.mjs';
48
+ import { waitingClaim } from './waiting-on-you.mjs';
48
49
 
49
50
  /** Roots come ONLY from the kernel's observed `status.root`; before (or
50
51
  * without) an observation there is nothing to act on. No layout guess. */
@@ -359,14 +360,25 @@ export function panelData(held, wsId, terms) {
359
360
  };
360
361
  }
361
362
 
363
+ /** Whether deployment `d` (a `deployments` entry) is live and current and one of its instance rows has a
364
+ * claim a row may show (waiting-on-you.mjs `waitingClaim`). Its rows are its own panel's
365
+ * (`deploymentPanel`: a local entry's rows, a remote group's), read from what the client holds. Not live
366
+ * (`info.live`: a stale or kept-failure local entry, a kept or unreached remote group, a deployment not
367
+ * observed) is never waiting: what it last said is unknown now. */
368
+ const deploymentWaits = (held, d, info) => info?.live === true && (deploymentPanel(held, d).instances || []).some((row) => waitingClaim(row) !== null);
369
+
362
370
  /** The switcher's list: views, not deployments. Each names its deployments (a client lets a caller
363
- * select any of these ids); an unattached view keeps today's remote fields and says why. `model` is a
364
- * view model already built for this call (`viewModel`); without one, it is built here. */
371
+ * select any of these ids); an unattached view keeps today's remote fields and says why. `waiting`
372
+ * (boolean): some deployment of the view is live and has an instance that needs input
373
+ * (`deploymentWaits`), from what the client holds, with no read: a view the client does not serve has no
374
+ * row here, and so no dot. `model` is a view model already built for this call (`viewModel`); without
375
+ * one, it is built here. */
365
376
  export function workspaceChoices(held, terms, model) {
366
377
  requireTerms(terms, 'workspaceChoices');
367
378
  if (model === undefined) model = viewModel(held, terms);
379
+ const served = deployments(held);
368
380
  return model.views.map((v) => {
369
- const primary = deployments(held).find((w) => w.id === v.primary);
381
+ const primary = served.find((w) => w.id === v.primary);
370
382
  const remoteOnly = v.deployments.every((id) => !model.infos.get(id)?.local);
371
383
  // Without the CLI's workspace-identity feature nothing can match: every deployment keeps its own entry, listed as
372
384
  // before views, not as "not matched" (each deployment's own reason still says why).
@@ -377,6 +389,7 @@ export function workspaceChoices(held, terms, model) {
377
389
  // The switcher's one-liner (UI spec, #482): the machines, in order and once each, and how many deployments aren't live.
378
390
  machines: [...new Set(v.deployments.map((id) => model.infos.get(id)?.machine).filter(Boolean))],
379
391
  notLive: v.deployments.filter((id) => !model.infos.get(id)?.live).length,
392
+ waiting: v.deployments.some((id) => { const d = served.find((w) => w.id === id); return !!d && deploymentWaits(held, d, model.infos.get(id)); }),
380
393
  ...(v.key ? { key: v.key } : {}), ...(unmatched ? { unattached: true } : {}), ...(unmatched && v.reason ? { reason: v.reason } : {}), ...(unmatched && v.short ? { short: v.short } : {}), ...(unmatched && v.ref ? { ref: v.ref } : {}),
381
394
  ...(remoteOnly && primary?.remote ? { server: primary.server, remote: true } : {}) };
382
395
  });
@@ -3,16 +3,17 @@
3
3
  * remembers an answer, and how it says a numbered one. */
4
4
  import { HARNESS_NAMES } from './harness-names.mjs';
5
5
 
6
- /** How long the task text must rest before the dialog asks (about 1.5 s): never on each keystroke. */
7
- export const SUGGEST_PAUSE_MS = 1500;
8
- /** The words a task needs before the dialog asks while it is typed. Spawn asks whatever the length. */
9
- export const SUGGEST_MIN_WORDS = 3;
6
+ /** The debounce before the dialog asks: it only keeps typing from making one read per keystroke. */
7
+ export const SUGGEST_DEBOUNCE_MS = 300;
8
+ /** The words a task needs before the dialog asks while it is typed (more than six). Spawn asks whatever the length. */
9
+ export const SUGGEST_MIN_WORDS = 7;
10
10
 
11
11
  /** The words of `text`: whitespace-separated runs that hold a letter or a digit. */
12
12
  export const taskWords = text => (String(text ?? '').match(/\S+/g) || []).filter(w => /[\p{L}\p{N}]/u.test(w)).length;
13
13
 
14
- /** What an answer is remembered by: the exact task text and the soul (its root and name). */
15
- export const namingKey = (selector, text) => JSON.stringify([selector?.agentsRoot ?? null, selector?.soul ?? null, String(text ?? '')]);
14
+ /** What an answer is remembered by: the exact task text, the soul (its root and name) and, for a spawn on another
15
+ * machine, that machine (`target`, its server id; null on this computer), so one host's answer never names another's. */
16
+ export const namingKey = (selector, text, target = null) => JSON.stringify([selector?.agentsRoot ?? null, selector?.soul ?? null, String(text ?? ''), target || null]);
16
17
 
17
18
  const harnessName = harness => HARNESS_NAMES[harness] ?? (typeof harness === 'string' && harness ? harness : 'the harness');
18
19
  /** Why a spawn was numbered, in the Desktop's words. The kernel's `message` is never shown: it can carry an exit
@@ -1,7 +1,8 @@
1
1
  /** Fixed read-only API2 argv. Never dispatch API1 or fall back to spawn. */
2
2
  import { execFile } from 'node:child_process';
3
3
  import { parseEnvelope, writeTaskFile } from './cli-adapter.mjs';
4
- import { previewChoices, previewTarget, previewSupported, previewFailure, choiceArgv, suggestSupported, suggestTask } from './spawn-preview-contract.mjs';
4
+ import { previewChoices, previewTarget, previewSupported, previewFailure, choiceArgv, suggestSupported, suggestTask, absolute,
5
+ instanceSuggestSupported, instanceSuggestRequest, instanceSuggestion } from './spawn-preview-contract.mjs';
5
6
  /** A refusal, in the kernel's own shape (`{ code, message, details: { fix } }`). `previewFailure` decides what of the
6
7
  * kernel's travels: its message when that is printable and within the bound, and its `fix` only beside that message.
7
8
  * No other key of `details` travels. */
@@ -52,3 +53,38 @@ export function cliSpawnPreview(cli, options = {}, io = {}) {
52
53
  } catch { resolve(failure('E_CLI_FAILED')); }
53
54
  });
54
55
  }
56
+
57
+ /** `oats instance suggest-name` (feature instance-suggest-name, awebai/oats#1490 §2): a name for a spawn on another
58
+ * machine, chosen here through this computer's harness and model. `request` is the dialog's (instanceSuggestRequest),
59
+ * `dir` the local deployment whose launch configurations the kernel reads. The task travels in a private temporary
60
+ * `--task-file`, removed on every path; never `--launch-config` (the dialog's configurations are the host's) and never
61
+ * `--server` (the kernel refuses it: the name is decided here). `signal` ends it as it ends a suggest read. Answers the
62
+ * kernel's envelope with its result re-validated (instanceSuggestion), or a failure in the kernel's shape. */
63
+ export function cliInstanceSuggestName(cli, { request, dir, signal } = {}, io = {}) {
64
+ if (!instanceSuggestSupported(cli)) return Promise.resolve(failure('E_UNSUPPORTED_OPTION'));
65
+ const asked = instanceSuggestRequest(request);
66
+ if (!asked || !absolute(dir) || signal !== undefined && !(signal instanceof AbortSignal)) return Promise.resolve(failure('E_BAD_ARGS'));
67
+ if (signal?.aborted) return Promise.resolve(failure('E_SUPERSEDED'));
68
+ let taskFile;
69
+ try { taskFile = writeTaskFile(asked.task, io); } catch { return Promise.resolve(failure('E_CLI_FAILED')); }
70
+ const argv = ['instance', 'suggest-name', '--soul', asked.soul, '--task-file', taskFile.file,
71
+ ...(asked.harness ? ['--harness', asked.harness] : []), ...(asked.model ? ['--model', asked.model] : []), '--dir', dir, '--json'];
72
+ const env = { ...(io.env ?? process.env) };
73
+ for (const k of ['PI_AGENTS_ROOT', 'OATS_DEPLOYMENT', 'OATS_RESOLUTION', 'OATS_PREVIEW_PREFLIGHT_BUDGET_MS']) delete env[k];
74
+ return new Promise(done => {
75
+ const resolve = v => { taskFile.cleanup(); done(v); };
76
+ try {
77
+ // The kernel bounds its call at 20 s (NAMING_TIMEOUT_MS) and its output at 4 KiB; this deadline adds the process's own start.
78
+ (io.exec ?? execFile)(cli.bin, argv, { cwd: dir, env, shell: false, encoding: 'utf8', timeout: 30000, maxBuffer: 64 * 1024, ...(signal ? { signal } : {}) }, (err, stdout) => {
79
+ if (err?.name === 'AbortError' || signal?.aborted) return resolve(failure('E_SUPERSEDED'));
80
+ if (err?.code === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER') return resolve(failure('E_CLI_OUTPUT_LIMIT'));
81
+ if (err?.killed) return resolve(failure('E_CLI_TIMEOUT'));
82
+ const doc = parseEnvelope(stdout);
83
+ if (doc?.ok === false) return resolve(failure(doc.error?.code, doc.error?.message, doc.error?.details?.fix));
84
+ if (err) return resolve(failure('E_CLI_FAILED'));
85
+ const result = doc?.ok === true ? instanceSuggestion(doc.result) : null;
86
+ resolve(result ? { schemaVersion: 1, ok: true, result } : failure('E_CLI_PROTOCOL'));
87
+ });
88
+ } catch { resolve(failure('E_CLI_FAILED')); }
89
+ });
90
+ }
@@ -146,6 +146,41 @@ export function namingOf(v) {
146
146
  if (v.source === 'numbered') return NAMING_REASONS.includes(v.reason) ? { source: 'numbered', reason: v.reason, ms: v.ms } : null;
147
147
  return null;
148
148
  }
149
+ /** How long the kernel's naming call may take (its own bound, the preview's and the apply's): an apply that also names
150
+ * its instance (`--suggest-name`) may take this much longer, and a caller's deadline allows for it. */
151
+ export const NAMING_TIMEOUT_MS = 20_000;
152
+ /** Feature instance-suggest-name (awebai/oats#1490 §2): `oats instance suggest-name` names, on this computer, a spawn that
153
+ * lands on another machine. The Desktop asks only where it can pass the name on (`spawn-name`). */
154
+ export const INSTANCE_SUGGEST_FEATURE = 'instance-suggest-name';
155
+ export const instanceSuggestSupported = cli => cli?.ok === true && absolute(cli.bin) && Array.isArray(cli.features)
156
+ && cli.features.includes(INSTANCE_SUGGEST_FEATURE) && cli.features.includes('spawn-name');
157
+ /** Feature spawn-apply-suggest-name (awebai/oats#1490 §3): an apply with `--suggest-name` names its instance itself, on the
158
+ * machine that spawns. Routed, the host must advertise it too: the route refuses the flag toward one that doesn't. */
159
+ export const APPLY_SUGGEST_FEATURE = 'spawn-apply-suggest-name';
160
+ /** The harnesses a suggest-name call may name (codex answers numbered, `unsupported-harness`, with no call). */
161
+ export const SUGGEST_HARNESSES = ['claude', 'pi', 'codex'];
162
+ /** The exact name a suggestion gives: the kernel's slug, within its cap. */
163
+ const SUGGESTED = new RegExp(`^(?=.{1,${INSTANCE_NAME_MAX}}$)[a-z0-9]+(?:-[a-z0-9]+)*$`);
164
+ /** `oats instance suggest-name`'s answer, `{ name?, naming }`, or null when it is malformed: `naming` as a preview's
165
+ * (namingOf), and `name` exactly when it was suggested. */
166
+ export function instanceSuggestion(v) {
167
+ if (!record(v) || Object.keys(v).some(k => !['name', 'naming'].includes(k))) return null;
168
+ const naming = namingOf(v.naming);
169
+ if (!naming) return null;
170
+ if (naming.source === 'suggested') return typeof v.name === 'string' && SUGGESTED.test(v.name) ? { name: v.name, naming } : null;
171
+ return Object.hasOwn(v, 'name') ? null : { naming };
172
+ }
173
+ /** The request of the dialog's suggest-name read: `{ action: 'suggest-name', soul, task, harness?, model? }`, or null.
174
+ * The soul is only a name (the host's, which needn't exist here); the model goes only with pi, the one harness whose
175
+ * naming follows it. */
176
+ export function instanceSuggestRequest(v) {
177
+ if (!exact(v, ['action', 'soul', 'task', 'harness', 'model']) || v.action !== 'suggest-name' || !soulName(v.soul) || !suggestTask(v.task)) return null;
178
+ if (v.harness !== undefined && !SUGGEST_HARNESSES.includes(v.harness)) return null;
179
+ if (v.model !== undefined && (v.harness !== 'pi' || !arg(v.model, 256))) return null;
180
+ return { action: 'suggest-name', soul: v.soul, task: v.task, ...(v.harness !== undefined ? { harness: v.harness } : {}), ...(v.model !== undefined ? { model: v.model } : {}) };
181
+ }
182
+ /** A soul's name as the kernel reads one: `<soul>`, `<package>/<soul>` or `<package>--<soul>`. */
183
+ const soulName = v => typeof v === 'string' && v.length <= 256 && v.split('/').length <= 2 && v.split('/').every(name);
149
184
  export function previewSelector(v) {
150
185
  return exact(v, ['soul', 'agentsRoot']) && name(v.soul) && absolute(v.agentsRoot) ? { soul: v.soul, agentsRoot: v.agentsRoot } : null;
151
186
  }
@@ -13,9 +13,10 @@
13
13
  * refused there (E_DECISION_STALE, read as drifted), never applied. */
14
14
  import { dirname } from 'node:path';
15
15
  import { performance } from 'node:perf_hooks';
16
- import { cliSpawnPreview } from './spawn-preview-cli.mjs';
16
+ import { cliSpawnPreview, cliInstanceSuggestName } from './spawn-preview-cli.mjs';
17
17
  import { admitInstance } from './instance-admission.mjs';
18
- import { absolute, record, previewSelector, previewChoices, previewSupported, previewFailure, previewData, previewComposedFrom, suggestSupported, suggestTask } from './spawn-preview-contract.mjs';
18
+ import { absolute, record, previewSelector, previewChoices, previewSupported, previewFailure, previewData, previewComposedFrom, suggestSupported, suggestTask,
19
+ instanceSuggestSupported, instanceSuggestRequest, instanceSuggestion } from './spawn-preview-contract.mjs';
19
20
  /** One preview's flights: its two-slot budget (`slots`), the flights in the air per invoker (`byInvoker`, where
20
21
  * exact duplicates coalesce), and the monotonic clock that stamps each flight's start (`started`). The cache is
21
22
  * given the same clock: it orders flight starts against invalidations, so a flight that started before its
@@ -182,11 +183,42 @@ export function createSpawnSuggestBoundary({ invoke = cliSpawnPreview, cache = n
182
183
  finally { if (lane && lanes.get(workspace) === lane) lanes.delete(workspace); }
183
184
  };
184
185
  }
186
+ /** The suggest-name read (feature instance-suggest-name, awebai/oats#1490 §2): a name, chosen on this computer, for a spawn
187
+ * on another machine, `{ action: 'suggest-name', soul, task, harness?, model? }` (instanceSuggestRequest). It is addressed
188
+ * to one of this computer's deployments, whose launch configurations the kernel reads (`--dir`); nothing of the soul is
189
+ * admitted here (it is the host's). One read per deployment: a newer one ends the older (its CLI gets SIGTERM, which ends
190
+ * the kernel's naming call too) and the older answers E_SUPERSEDED. Nothing is cached here (the dialog caches by task).
191
+ * Answers `{ spawnPreviewViewApi: 1, status: 'available', workspace, data: { name?, naming }, reason: null }`. */
192
+ export function createInstanceSuggestBoundary({ invoke = cliInstanceSuggestName, exec } = {}) {
193
+ const lanes = new Map(), io = exec ? [{ exec }] : [];
194
+ return async function suggestName(request, getContext) {
195
+ let lane = null, workspace = null;
196
+ try {
197
+ const asked = instanceSuggestRequest(request);
198
+ if (!asked) return previewFailure('E_BAD_ARGS');
199
+ const { workspace: w, cli } = getContext();
200
+ if (!w || typeof w.id !== 'string' || !w.id || !absolute(w.scope)) return previewFailure('E_WORKSPACE_UNKNOWN');
201
+ if (w.remote || w.server) return previewFailure('unsupported-remote-operation');
202
+ if (!instanceSuggestSupported(cli)) return previewFailure('E_UNSUPPORTED_OPTION');
203
+ workspace = w.id;
204
+ lanes.get(workspace)?.abort();
205
+ lane = new AbortController(); lanes.set(workspace, lane);
206
+ const envelope = await invoke(cli, { request: asked, dir: w.scope, signal: lane.signal }, ...io);
207
+ if (lane.signal.aborted) return previewFailure('E_SUPERSEDED');
208
+ if (envelope?.schemaVersion !== 1 || envelope.ok !== true) return previewFailure(envelope?.error?.code, null, envelope?.error?.message, envelope?.error?.details?.fix);
209
+ const data = instanceSuggestion(envelope.result);
210
+ if (!data) return previewFailure('E_CLI_PROTOCOL');
211
+ return { spawnPreviewViewApi: 1, status: 'available', workspace, data, reason: null };
212
+ } catch { return previewFailure('E_CLI_FAILED'); }
213
+ finally { if (lane && lanes.get(workspace) === lane) lanes.delete(workspace); }
214
+ };
215
+ }
185
216
  export const PREVIEW_MAX_AGE_S = 60;
186
217
  /** One client's spawn preview: `{ read, prepareRead, suggest, cache }`.
187
218
  * read the dialog's read, through the cache; its kernel reads may reuse recent member heads (maxAge,
188
219
  * where the CLI declares spawn-preview-max-age)
189
220
  * suggest the suggest read (createSpawnSuggestBoundary): its own lane, one per workspace, the newer ending the older
221
+ * suggestName the suggest-name read (createInstanceSuggestBoundary): a name chosen here for a spawn on another machine
190
222
  * prepareRead prepare's read (spawn-apply.mjs createSpawnApplyBoundary's `read`), through the same cache,
191
223
  * taking a held answer up to `prepareReuseMs` old (PREPARE_REUSE_MS), never with maxAge; a reusing
192
224
  * read and a live one never coalesce
@@ -204,6 +236,7 @@ export function createSpawnPreview({ invoke = cliSpawnPreview, exec, now = () =>
204
236
  read: createSpawnPreviewBoundary({ invoke, cache, maxAge, heldMs: ttlMs, flights, exec }),
205
237
  prepareRead: createSpawnPreviewBoundary({ invoke, cache, heldMs: prepareReuseMs, flights, exec }),
206
238
  suggest: createSpawnSuggestBoundary({ invoke, cache, maxAge, flights, exec }),
239
+ suggestName: createInstanceSuggestBoundary({ exec }),
207
240
  cache: { invalidate: workspace => cache.invalidate(workspace), size: () => cache.size() },
208
241
  };
209
242
  }
@@ -33,7 +33,10 @@ export function teamMembers({ deployments = [], groups = [] }) {
33
33
  for (const row of rows.filter(r => team(r))) members.push(member(row, { deployment, server: group.server, serverLabel: label }));
34
34
  servers.push({ server: group.server, label, group: group.id, deployment: deployment.id, reached: group.probe?.ok === true,
35
35
  error: group.probe?.ok === true ? null : text(group.probe?.error?.message) ?? 'Server is unreachable',
36
- registered: group.registrationPresent === true });
36
+ registered: group.registrationPresent === true,
37
+ // The host's own kernel features as this computer's CLI relays them (server-probe-features): a list only
38
+ // when this read reached it and the list is one, else null (unknown, which is not supported).
39
+ features: group.probe?.ok === true && Array.isArray(group.probe.features) ? [...group.probe.features] : null });
37
40
  // A failed group holding no rows (last-known or current) is a server we have nothing to show for.
38
41
  if (group.probe?.ok !== true && !rows.length) notReached.push({ server: group.server, label, deployment: deployment.id });
39
42
  }
@@ -0,0 +1,25 @@
1
+ /** The workspace the leader's ↑ and ↓ move to (keymap.mjs `workspace-previous`, `workspace-next`): the
2
+ * next openable row of the sidebar's list of workspaces, as each client draws it, in one direction. Both
3
+ * clients read it; each draws its own list and opens what this answers.
4
+ *
5
+ * Pure: arguments in, a key out, nothing changed. A page loads this module: it imports nothing. */
6
+
7
+ /**
8
+ * The key of the next row with `openable` true from the row `currentKey`, in the direction `step`
9
+ * (+1, down the list; −1, up it), or null at an end: the list does not wrap. Rows that are not
10
+ * openable are passed over. With `currentKey` not among the rows (null included: nothing is open, or
11
+ * what is open is not listed), the first openable row for +1 and the last for −1, or null when none is.
12
+ * @param {{ key: string, openable: boolean }[]} rows the list as drawn, in its order
13
+ * @param {string | null} currentKey the row the client is on
14
+ * @param {1 | -1} step
15
+ * @returns {string | null}
16
+ */
17
+ export function workspaceStep(rows, currentKey, step) {
18
+ const list = Array.isArray(rows) ? rows : [];
19
+ const at = currentKey === null || currentKey === undefined ? -1 : list.findIndex((row) => row?.key === currentKey);
20
+ const dir = step < 0 ? -1 : 1;
21
+ for (let i = at === -1 ? (dir === 1 ? 0 : list.length - 1) : at + dir; i >= 0 && i < list.length; i += dir) {
22
+ if (list[i]?.openable === true) return list[i].key;
23
+ }
24
+ return null;
25
+ }
@@ -20,16 +20,16 @@ never does.
20
20
  | path | contents |
21
21
  |---|---|
22
22
  | `bin/tui.mjs` | the entry `bin/oats.mjs` loads: it imports the whole module graph, then runs `main()` |
23
- | `lib/main.mjs` | the start (arguments, environment, terminal, `tui.json`, deployment, kernel, and outside every deployment this computer's list of deployments) and the loop: events through `reduce`, effects out, the frame drawn; the list's reads, the add of the deployment the run starts in and the switcher's Remove, through the shared `cliDeploymentList` |
23
+ | `lib/main.mjs` | the start (arguments, environment, terminal, `tui.json`, deployment, kernel, and outside every deployment this computer's list of deployments) and the loop: events through `reduce`, effects out, the frame drawn; the list's reads, the add of the deployment the run starts in and the switcher's Remove, through the shared `cliDeploymentList`; a resize and the keys typed to an agent told to the store (`passed`), which ends a line of one key |
24
24
  | `lib/actions.mjs` | the action table and its default keys: the reducer, the cheat sheet and the help read the effective one. The keys shared with the Desktop are not written here: the leader's table and the plain keys of the list come from `packages/client/keymap.mjs`, and `test/keymap.test.mjs` fails on a row of the shared table the TUI does not handle |
25
25
  | `lib/config.mjs` | `tui.json` (`~/.oats/config/tui.json`): moved once from where earlier versions read it, read once, checked, and the effective action table; the default leader is the shared one (`keymap.mjs` `leaderKey`, Ctrl+X on every platform) |
26
26
  | `lib/client.mjs` | the one module that imports the shared readers (`packages/client/`), and the client's terms |
27
27
  | `lib/panel.mjs` | the open terminals, as tabs: the run's private tmux server (one control client, one window per tab, up to `MAX_TERMINALS`, each at the size its caller gives), the kernel's `oats session attach` in a pane of each, captures of the displayed tabs only (up to `MAX_SHOWN`, one per group of a split) when tmux says their pane changed, a hidden tab's output marking it, keys typed into the shown tab, and the sweep of what a dead run left; the only module that runs tmux (THE TABS in its header) |
28
28
  | `lib/read.mjs` | the effects of reading: the deployment, the kernel record, the observer of every deployment opened in the run, the roster of other machines (`oats server roster --json`), the refresh loop, the liveness collector, ending every read, the identity reads of this computer's listed deployments the run has not opened (`createIdentityReads`: one at a time, under a budget, never on a timer), the changes (a stop or retire apply, a start or restart: never ended, their output in files of the run's private directory), the one look at the file system the switcher needs (whether a picked row is a deployment), and `startExec`, the exec of the list's read before the terminal is taken |
29
- | `lib/store.mjs` | the state and `reduce(state, event)`: pure. It holds the tabs' order, their groups, the shown one of each and the rule for the neighbour after a close (`TAB_LIMIT`, held to the panel's `MAX_TERMINALS` by a test) |
30
- | `lib/model.mjs` | from the state to the rows and the detail to draw, and to the switcher's rows (a workspace and a line per deployment of it, matched by the shared `listedViews` over the served deployments and the identities the reads learned), by calling the shared readers: pure, no cell position |
29
+ | `lib/store.mjs` | the state and `reduce(state, event)`: pure. It holds the tabs' order, their groups, the shown one of each and the rule for the neighbour after a close (`TAB_LIMIT`, held to the panel's `MAX_TERMINALS` by a test), and each workspace's memory for the run (THE MEMORY OF A WORKSPACE: its place, its palette recency, and its tabs as it was left, opened again one at a time when it is opened again); the list of workspaces' focus and cursor, and the leader's moves between workspaces (the shared `workspaceStep`) |
30
+ | `lib/model.mjs` | from the state to the rows and the detail to draw (an instance row's name as words, the shared `instanceDisplayName`, which the row alone shows: the views import nothing of the shared home), and to the switcher's rows (a workspace and a line per deployment of it, matched by the shared `listedViews` over the served deployments and the identities the reads learned), and from those the list of workspaces (`workspaceList`: one row per workspace the switcher offers, by name, and its dot from what this run observes; `listWindow`: five rows at most), by calling the shared readers: pure, no cell position |
31
31
  | `lib/term/keys.mjs` | bytes to key events: a pure parser with an injected clock; under the kitty keyboard protocol it reads a `CSI … u` key as its legacy bytes read, a chord as its own id |
32
- | `lib/term/kitty.mjs` | the kitty keyboard protocol: the flags asked for, a `CSI … u` key read, and the bytes the same key sends without the protocol (`legacyBytes`), which is what an agent is typed |
32
+ | `lib/term/kitty.mjs` | the kitty keyboard protocol: the flags asked for, a `CSI … u` key read, and the bytes the same key sends without the protocol (`legacyBytes`), which is what an agent is typed; and the chords a terminal sends the same way without it (`legacyChordText`: Alt with a letter or a digit, the Alt and Alt+Shift arrows), which the TUI takes in every terminal |
33
33
  | `lib/term/width.mjs` | the cells a grapheme takes |
34
34
  | `lib/term/text.mjs` | safe text, the only thing the screen draws: `lit()` and `shown()` |
35
35
  | `lib/term/style.mjs` | style values: the TUI's own (the sixteen ANSI colours and four attributes) and an agent's (its colours, 256 and RGB included, and attributes, from a capture) |
@@ -37,7 +37,7 @@ never does.
37
37
  | `lib/term/through.mjs` | the bytes typed while a terminal has the focus: the back key's grammar and bytes, and the scanner that takes the back key, a chord and a bracketed paste out of them and, under the kitty keyboard protocol, types every other key as its legacy bytes |
38
38
  | `lib/term/screen.mjs` | the cell buffer and the bytes of a frame |
39
39
  | `lib/term/tty.mjs` | the guard: enter, leave, signals, suspend, resize, one write per frame; the kitty keyboard protocol pushed, asked about and popped on every way out |
40
- | `lib/views/` | pure functions from the model and a size to rows of spans: the frame (the sidebar: its title, the accordion of the three views and the cheat sheet; the main area beside it), the list, the detail, the Capabilities view (`capabilities.mjs`), the switcher, the help, the confirmation of an act (`act.mjs`), the spawn prompt (`spawn.mjs`), the split's geometry (`split.mjs`) |
40
+ | `lib/views/` | pure functions from the model and a size to rows of spans: the frame (the sidebar: the list of workspaces (`workspaces.mjs`) or its title, the accordion of the three views and the cheat sheet; the main area beside it), the list, the detail, the Capabilities view (`capabilities.mjs`), the switcher, the help, the confirmation of an act (`act.mjs`), the spawn prompt (`spawn.mjs`), the split's geometry (`split.mjs`) |
41
41
 
42
42
  Rules the tests pin (`test/tui-boundary.test.mjs` reads the files):
43
43
 
@@ -10,6 +10,8 @@
10
10
  // leader's table is the shared one (LEADER, below). What only the TUI has (q, Ctrl+C, Ctrl+Z, Ctrl+L,
11
11
  // Ctrl+K, Tab, Esc, Delete, C, i) keeps its keys here. packages/tui/test/keymap.test.mjs pins both.
12
12
  import { CHORDS, DEFAULT_CHORD_FAMILY, LEADER_TABLE, PALETTE_KEYS, chordKeyOf, plainKeys } from "./client.mjs";
13
+ // An action's words, for the help (views/help.mjs): a view takes the shared home's keymap through this module only.
14
+ export { doesLabel } from "./client.mjs";
13
15
  import { legacyChord } from "./term/kitty.mjs";
14
16
  import { isBackKey } from "./term/through.mjs";
15
17
 
@@ -51,11 +53,14 @@ export const ACTIONS = Object.freeze([
51
53
  { id: "tab-previous", label: "previous tab", views: [["instances", "show the terminal of the tab before the shown one"]] },
52
54
  { id: "tab-next", label: "next tab", views: [["instances", "show the terminal of the tab after the shown one"]] },
53
55
  // The split (docs/tui.md, "Splits"): two groups of tabs at most, side by side or one above the
54
- // other. `group-next`, `tab-move` and `group-close` have no key of their own here by default
55
- // (Tab is the detail's, and `m` and `x` are often a tui.json's): the leader's are.
56
+ // other. `group-next`, `group-previous`, `tab-move` and `group-close` have no key of their own
57
+ // here by default (Tab is the detail's, and `m` and `x` are often a tui.json's): the leader's are.
58
+ // With two groups at most, the previous group is the other one, as the next is: `group-previous`
59
+ // is the shared table's own row (the Desktop's splits have more), and does what `group-next` does.
56
60
  { id: "split-right", label: "split right", views: [["instances", "split the panel side by side; the new group, on the right, is empty and focused"]] },
57
61
  { id: "split-down", label: "split down", views: [["instances", "split the panel one above the other; the new group, below, is empty and focused"]] },
58
62
  { id: "group-next", keys: [], label: "next group", views: [["instances", "go to the other group's terminal, or to the focused group's from the list"]] },
63
+ { id: "group-previous", keys: [], label: "previous group", views: [["instances", "the same as next group: a split has two groups"]] },
59
64
  { id: "tab-move", keys: [], label: "move tab", views: [["instances", "move the shown tab to the other group, and go there"]] },
60
65
  { id: "group-close", keys: [], label: "close group", views: [["instances", "close the focused group while it is empty"]] },
61
66
  // The four acts on an instance: each opens a confirmation, and nothing is done before a move and
@@ -80,28 +85,31 @@ export const ACTIONS = Object.freeze([
80
85
  /** THE LEADER'S TABLE (docs/tui.md, "The leader"): the keys read after the leader (tui.json's
81
86
  * open.detachKey) and what each does, from every focus. It is the shared one, the Desktop's too
82
87
  * (packages/client/keymap.mjs LEADER_TABLE), in its order, with its labels and its `terminal`
83
- * rows: named in the hint only while a terminal is open, and nothing without one. What the TUI
84
- * adds to a row is its own, keyed by `does`: the hint's filters (views/frame.mjs leaderHints:
85
- * the tab keys only with two tabs or more, the split's only where they apply). Fixed: tui.json's
88
+ * rows, which do nothing without a terminal open. Nothing is drawn while the leader waits: the
89
+ * help lists the table (views/help.mjs). Fixed: tui.json's
86
90
  * `keys` rebinds the plain keys of ACTIONS only. Each `does` is handled by the TUI
87
91
  * (leaderHandles); the leader pressed again is not in the table, as it is the user's key: from the
88
92
  * open terminal's focus it types the leader's own bytes into the agent, the focus staying there,
89
- * and from any other focus it only closes the hint (lib/store.mjs `twice`). */
93
+ * and from any other focus it only cancels the leader (lib/store.mjs `twice`). */
90
94
  export const LEADER = LEADER_TABLE;
91
- /** What the leader does that no action of ACTIONS does (lib/store.mjs `led`): `previous` and
92
- * `next` (the instance before or after the shown terminal's, or the selection's: its tab shown,
93
- * or opened as a new one, with the focus in it) and `list` (the list's focus, which Esc gives). */
94
- export const LEADER_OWN = Object.freeze(["previous", "next", "list"]);
95
+ /** What the leader does that no action of ACTIONS does (lib/store.mjs `led`): `workspace-previous`
96
+ * and `workspace-next` (the workspace before or after the open one in the list of workspaces) and
97
+ * `list` (the list's focus, which Esc gives). */
98
+ export const LEADER_OWN = Object.freeze(["workspace-previous", "workspace-next", "list"]);
95
99
  /** What a chord does that neither the leader's table nor an action does (lib/store.mjs `led`):
96
100
  * `tab-1` to `tab-8`, the focused group's Nth tab shown, and `tab-9`, its last (as the Desktop and
97
101
  * the browsers do). No key after the leader does them: LEADER has no row for them. */
98
102
  export const CHORD_OWN = Object.freeze(Array.from({ length: 9 }, (_, i) => `tab-${i + 1}`));
103
+ /** The chords' moves between instances, which no key after the leader does either (the leader's Up
104
+ * and Down move between workspaces): `previous` and `next`, the instance before or after the shown
105
+ * terminal's, or the selection's, its tab shown, or opened as a new one, with the focus in it. */
106
+ export const CHORD_MOVES = Object.freeze(["previous", "next"]);
99
107
  /** Whether the TUI acts on `does`, a `does` of the shared leader table or of the chords: it is one
100
108
  * of the leader's own (LEADER_OWN), of the chords' own (CHORD_OWN), or the id of an action of
101
109
  * ACTIONS, which lib/store.mjs `led` runs as its key runs it, or in its own way from the leader
102
110
  * (the terminal's keys, the acts, the spawns). A `does` the TUI does not handle is a failure of
103
111
  * packages/tui/test/keymap.test.mjs or chords.test.mjs, never a key that does nothing. */
104
- export const leaderHandles = (does) => LEADER_OWN.includes(does) || CHORD_OWN.includes(does) || ACTIONS.some((action) => action.id === does);
112
+ export const leaderHandles = (does) => LEADER_OWN.includes(does) || CHORD_OWN.includes(does) || CHORD_MOVES.includes(does) || ACTIONS.some((action) => action.id === does);
105
113
  /** key id -> what the leader then does (LEADER's `does`). */
106
114
  export const LEADER_KEYS = new Map(LEADER.flatMap((entry) => entry.keys.map((key) => [key, entry.does])));
107
115
 
@@ -109,18 +117,30 @@ export const LEADER_KEYS = new Map(LEADER.flatMap((entry) => entry.keys.map((key
109
117
  * CHORDS) on macOS (`isMac`) or elsewhere, in the table's order, each doing what the leader then
110
118
  * its key does, or a tab by its place (CHORD_OWN; lib/store.mjs `led`), from every focus. Each
111
119
  * row's key is the one of `family` (keymap.mjs chordKeyOf: CHORD_FAMILIES, keys.json's `chords`,
112
- * lib/config.mjs loadKeys): `ctrl+alt`, the default, binds the `other` keys; `ctrl+shift` the
113
- * `shift` ones (seven rows move, the others keep their key); macOS ignores it. Left out: a chord
114
- * with `cmd+` (a terminal never passes macOS's Command to a program: with the shared table that is
115
- * every chord of macOS), and one whose key an action of `actions` binds (a user's tui.json keeps
116
- * its key, row by row, whichever the family), and one whose `does` the TUI does not handle
117
- * (leaderHandles: a row may be the Desktop's alone): packages/tui/test/chords.test.mjs. `chords`
118
- * is the shared table. Which of them are read depends on the kitty keyboard protocol (chordsRead). */
119
- export function chordKeys(isMac, actions = ACTIONS, chords = CHORDS, family = DEFAULT_CHORD_FAMILY) {
120
+ * lib/config.mjs loadKeys): `alt`, the default, binds the `alt` keys; `ctrl+alt` the `other`
121
+ * ones; `ctrl+shift` the `shift` ones (seven rows move, the others keep their `other` key); macOS
122
+ * ignores it. A key is the TUI's key id (tuiChordKey): Alt+Shift with a letter is `alt+E`, as a
123
+ * terminal sends it. Left out: a row with no key there (a `null` key: the Ctrl+Alt and Ctrl+Shift
124
+ * families leave the workspace moves to the program, and none is borrowed from another family), a
125
+ * chord with `cmd+` (a terminal never passes macOS's Command to a program: with the shared table
126
+ * that is every chord of macOS but the six ⌥ arrows), one whose key an action of `actions` binds (a user's tui.json keeps its
127
+ * key, row by row, whichever the family), one whose key is `leader` (the leader's key id, null for
128
+ * none: a tui.json's open.detachKey M-o is Alt+O, and the leader wins, in the list and in a
129
+ * terminal), and one whose `does` the TUI does not handle (leaderHandles: a row may be the
130
+ * Desktop's alone): packages/tui/test/chords.test.mjs. `chords` is the shared table. Which of them
131
+ * are read depends on the kitty keyboard protocol (chordsRead). */
132
+ export function chordKeys(isMac, actions = ACTIONS, chords = CHORDS, family = DEFAULT_CHORD_FAMILY, leader = null) {
120
133
  const bound = new Set(actions.flatMap((action) => action.keys));
121
- return new Map(chords.map((entry) => [chordKeyOf(entry, isMac, family) ?? entry.other, entry.does]).filter(([key, does]) => !key.startsWith("cmd+") && !bound.has(key) && leaderHandles(does)));
134
+ return new Map(chords.map((entry) => [chordKeyOf(entry, isMac, family), entry.does])
135
+ .filter(([key]) => key !== null && !key.startsWith("cmd+")).map(([key, does]) => [tuiChordKey(key), does])
136
+ .filter(([key, does]) => !bound.has(key) && key !== leader && leaderHandles(does)));
122
137
  }
123
138
 
139
+ /** A shared chord's key (keymap.mjs's spelling) as the TUI's key id (term/keys.mjs keyId): Alt+Shift
140
+ * with a letter is `alt+E`, the capital after ESC that a terminal sends for it; every other key is
141
+ * spelled the same in both. */
142
+ export const tuiChordKey = (key) => (/^alt\+shift\+[a-z]$/.test(key) ? `alt+${key.at(-1).toUpperCase()}` : key);
143
+
124
144
  /** THE PALETTE'S OWN KEYS (docs/tui.md, "The palette"): key id -> `does`, the shared ones
125
145
  * (packages/client/keymap.mjs PALETTE_KEYS) on macOS (`isMac`) or elsewhere, in the table's order:
126
146
  * `palette-next-group` and `palette-previous-group`, the first row of the next group or of the one
@@ -137,12 +157,14 @@ export function paletteKeys(isMac, table = PALETTE_KEYS) {
137
157
  }
138
158
 
139
159
  /** The chords of `chords` (chordKeys) the TUI reads while the terminal confirms the kitty keyboard
140
- * protocol (`kitty`) or not: all of them under it; without it only the Alt+Shift arrows
141
- * (term/kitty.mjs LEGACY_CHORDS), whose sequence is their own, in either family. A Ctrl+Alt chord
142
- * without the protocol is the bytes of two keys (ESC, then Ctrl+K), the agent's, and in the list
143
- * no key. A Ctrl+Shift one is Ctrl and its letter's byte, the same as Ctrl alone (Ctrl+Shift+D is
144
- * 0x04, EOF; Ctrl+Shift+M is 0x0d, Enter): never a chord, the agent's in its terminal and the
145
- * list's key in the list (term/kitty.mjs kittyId reads one only from the protocol's event). */
160
+ * protocol (`kitty`) or not: all of them under it; without it those whose bytes are their own
161
+ * (term/kitty.mjs legacyChordText): every chord of the Alt family (Alt with a letter or a digit is
162
+ * ESC and the character, an Alt arrow `CSI 1 ; 3 A`, an Alt+Shift one `CSI 1 ; 4 A`), and the
163
+ * arrow chords of the other two. A Ctrl+Alt chord without the protocol is the bytes of two
164
+ * keys (ESC, then Ctrl+K), the agent's, and in the list no key. A Ctrl+Shift one is Ctrl and its
165
+ * letter's byte, the same as Ctrl alone (Ctrl+Shift+D is 0x04, EOF; Ctrl+Shift+M is 0x0d, Enter):
166
+ * never a chord, the agent's in its terminal and the list's key in the list (term/kitty.mjs kittyId
167
+ * reads one only from the protocol's event). */
146
168
  export function chordsRead(chords, kitty) {
147
169
  return kitty ? chords : new Map([...chords].filter(([key]) => legacyChord(key)));
148
170
  }
@@ -158,9 +180,11 @@ export function bindings(actions = ACTIONS) {
158
180
  }
159
181
 
160
182
  const NAMES = Object.freeze({ escape: "Esc", enter: "Enter", tab: "Tab", backspace: "Backspace", space: "Space", up: "Up", down: "Down", left: "Left", right: "Right", home: "Home", end: "End", pageup: "PageUp", pagedown: "PageDown", insert: "Insert", delete: "Delete", ctrl: "Ctrl", alt: "Alt", shift: "Shift" });
161
- /** A key id as a person reads it: `ctrl+c` is `Ctrl+C`, `escape` is `Esc`, `?` is `?`. */
183
+ /** A key id as a person reads it: `ctrl+c` is `Ctrl+C`, `escape` is `Esc`, `?` is `?`, and `alt+E`,
184
+ * Alt with a capital, is `Alt+Shift+E`, the keys pressed for it. */
162
185
  export function keyLabel(key) {
163
186
  if (key.length === 1) return key;
187
+ if (/^alt\+[A-Z]$/.test(key)) return `Alt+Shift+${key.at(-1)}`;
164
188
  const parts = key.split("+"), last = parts.pop();
165
189
  const name = NAMES[last] ?? (/^f\d+$/.test(last) ? last.toUpperCase() : parts.length && last.length === 1 ? last.toUpperCase() : last);
166
190
  return [...parts.map((part) => NAMES[part] ?? part), name].join("+");
@@ -17,6 +17,7 @@ export { createRefreshLoop } from "../../client/refresh-loop.mjs";
17
17
  export { rosterRows, livenessInput, livenessAnswers, panelInstances, pendingEntry, failedEntry, observedEntry } from "../../client/deployment-panel.mjs";
18
18
  export { panelData, cliReadsRemotes, workspaceChoices, viewModel, listedViews, deployments } from "../../client/panel-views.mjs";
19
19
  export { cliDeploymentIdentity, identityReadable, identityTimedOut } from "../../client/deployment-identity.mjs";
20
+ export { workspaceStep } from "../../client/workspace-step.mjs";
20
21
  export { remoteRosterState } from "../../client/remote-roster.mjs";
21
22
  export { observeIdentities, identityMemory } from "../../client/remote-identity-memory.mjs";
22
23
  export { workspaceChoiceRows, choiceMatches, UNMATCHED_SECTION } from "../../client/workspace-choices.mjs";
@@ -24,6 +25,7 @@ export { shortPath, deploymentLabel, machineLabels } from "../../client/deployme
24
25
  export { instanceId, instanceVisibleInTree, waitingRollup, collapseKey, filterInstanceTree, hasInstanceChildren, heldHome, instanceSiblings } from "../../client/instance-tree.mjs";
25
26
  export { rosterSections, deploymentState, rowStale, primaryDeployment, isMultiDeployment } from "../../client/roster-sections.mjs";
26
27
  export { runtimeState, runtimeCounts, originLead, siblingText, instanceColor } from "../../client/instance-presentation.mjs";
28
+ export { instanceDisplayName } from "../../client/instance-display-name.mjs";
27
29
  export { waitingClaim, waitingLabel, waitedText, waitingClock, waitingBelowText } from "../../client/waiting-on-you.mjs";
28
30
  export { instanceActs, openAct } from "../../client/instance-acts.mjs";
29
31
  export { rowReason } from "../../client/remote-address.mjs";
@@ -51,8 +53,8 @@ export { subsequenceScore } from "../../client/subsequence-score.mjs";
51
53
  export { createCapabilityCatalog, capabilityCatalogKey } from "../../client/capability-catalog.mjs";
52
54
  export { memberNames, capabilitySource, groupCapabilities, hostKeyOf, capabilitySections, matchCapabilities, soulsComposition, rosterAgentName, layerLabel, capabilityUsers } from "../../client/capability-rows.mjs";
53
55
  export { capabilityFacts, CAPABILITY_COPY } from "../../client/capability-facts.mjs";
54
- export { CHORDS, CHORD_FAMILY_LABELS, DEFAULT_CHORD_FAMILY, LEADER_TABLE, PALETTE_KEYS, PLAIN_KEYS, chordKeyOf, leaderKey, plainKeys } from "../../client/keymap.mjs";
55
- // keys.json, the chord family both clients bind (docs/tui.md, "Switch to Ctrl+Shift"): the TUI reads the file
56
+ export { CHORDS, CHORD_FAMILY_LABELS, DEFAULT_CHORD_FAMILY, LEADER_TABLE, PALETTE_KEYS, PLAIN_KEYS, chordKeyOf, doesLabel, leaderKey, plainKeys } from "../../client/keymap.mjs";
57
+ // keys.json, the chord family both clients bind (docs/tui.md, "Switch family"): the TUI reads the file
56
58
  // itself, at its start (lib/config.mjs loadKeys), and the shared reader says what its text means.
57
59
  export { KEYS_LIMIT, chordFamilyFrom, chordFamilyNote, keysPath } from "../../client/keys-file.mjs";
58
60
 
@@ -345,13 +345,13 @@ export function loadConfig({ env = process.env, home = homedir(), io = NODE_IO,
345
345
  * file is never opened: a FIFO would hold the start until something wrote to it. */
346
346
  const NOT_A_FILE = Object.freeze({ reason: "not a regular file" });
347
347
 
348
- /** Read keys.json, once, at the start (docs/tui.md, "Switch to Ctrl+Shift"): the chord family the
348
+ /** Read keys.json, once, at the start (docs/tui.md, "Switch family"): the chord family the
349
349
  * TUI binds on Linux and Windows, as the shared reader (packages/client/keys-file.mjs
350
350
  * chordFamilyFrom) says it, a frozen `{ family, why }`. The file is the clients' and the user's:
351
- * `config/keys.json` beside tui.json (keysPath), `{ "chords": "ctrl+alt" | "ctrl+shift" }`. The
352
- * TUI only reads it, and never refuses to start for it: no file, a file that cannot be read, one
351
+ * `config/keys.json` beside tui.json (keysPath), `{ "chords": "alt" | "ctrl+alt" | "ctrl+shift" }`.
352
+ * The TUI only reads it, and never refuses to start for it: no file, a file that cannot be read, one
353
353
  * that is not a regular file, over KEYS_LIMIT, not JSON or naming no family it knows are all the
354
- * default, Ctrl+Alt, with `why` saying which (the help says it: chordFamilyNote). A change is read
354
+ * default, Alt, with `why` saying which (the help says it: chordFamilyNote). A change is read
355
355
  * at the next start. macOS has no family; the answer is read there too, and ignored.
356
356
  *
357
357
  * `io` is the file system (node:fs when omitted): `io.stat(path)` as loadConfig's, and