@webship.co/workspace 1.0.0-beta1 → 1.0.0-beta2

package/core/workspace-app/tests/unit/tab-modal.test.js

@@ -0,0 +1,69 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const path = require('path');
+const { tabModalHtml } = require('../../tab-modal');
+
+const root = path.join(__dirname, '..', '..');
+const read = (...p) => fs.readFileSync(path.join(root, ...p), 'utf8');
+const groups = [
+  { id: 'a', label: 'First', tabs: [
+    { id: 'one', label: 'One', url: '/x/one', hint: 'The first' },
+    { id: 'two', label: 'Two <b>', url: '/x/two', badge: '3' } ] },
+  { id: 'b', label: 'Second', tabs: [{ id: 'three', label: 'Three', url: '/x/three' }] },
+];
+
+test('tabs are buttons in a vertical tablist, one selected, each loading its own fragment', () => {
+  const html = tabModalHtml({ id: 'demo', title: 'Demo', groups, active: 'two' });
+  assert.match(html, /role="tablist" aria-orientation="vertical"/);
+  assert.equal((html.match(/role="tab"/g) || []).length, 3);
+  assert.equal((html.match(/aria-selected="true"/g) || []).length, 1);
+  assert.match(html, /id="tm-demo-two"[^>]*aria-selected="true"/);
+  assert.match(html, /hx-get="\/x\/three" hx-target="#tm-demo-pane"/);
+  assert.match(html, /id="tm-demo-pane" role="tabpanel"/);
+  assert.match(html, /hx-get="\/x\/two" hx-trigger="load"/, 'the pane loads the open tab');
+});
+
+test('an unknown tab opens the first, and labels are escaped', () => {
+  const html = tabModalHtml({ id: 'demo', title: 'Demo', groups, active: 'nope' });
+  assert.match(html, /id="tm-demo-one"[^>]*aria-selected="true"/);
+  assert.doesNotMatch(html, /Two <b>/);
+  assert.match(html, /Two &lt;b&gt;/);
+});
+
+test('the address is kept only when the modal asks for it, and a back link is a button', () => {
+  assert.doesNotMatch(tabModalHtml({ id: 'demo', title: 'Demo', groups }), /data-hash/);
+  assert.match(tabModalHtml({ id: 'demo', title: 'Demo', groups, hash: true }), /data-tabmodal="demo" data-hash/);
+  const back = tabModalHtml({ id: 'demo', title: 'Demo', groups, back: { label: 'Workitems', url: '/list' } });
+  assert.match(back, /<button type="button" class="tabmodal-back" hx-get="\/list"/);
+});
+
+test('the settings modal is built from it, and plugins get it through api.lib', () => {
+  const server = read('server.js');
+  assert.match(server, /tabModal\.tabModalHtml\(\{ id: 'settings'/);
+  assert.match(read('plugin-loader.js'), /tabModalHtml,/, 'a plugin (the Jira workitem modal) builds on the same');
+  assert.match(server, /const isFragment = \(req\)/);
+  assert.match(server, /if \(options\.fragment\) return/);
+});
+
+test('the rail Settings tile opens the modal and keeps its address for a new tab', () => {
+  const server = read('server.js');
+  assert.match(server, /'\/fragments\/settings\/modal'\)/);
+  assert.match(server, /data-tabmodal-open=/);
+  const ui = read('public', 'ui.js');
+  assert.match(ui, /\[data-tabmodal-open\]/);
+  assert.match(ui, /\^#\(settings\)\\\/\(\[\^\/\]\+\)\$/);
+});
+
+test('behaviour: selection, arrow keys, a filter, links stay in the pane', () => {
+  const ui = read('public', 'ui.js');
+  assert.match(ui, /'ArrowDown', 'ArrowUp', 'Home', 'End'/);
+  assert.match(ui, /tabmodal-filter/);
+  assert.match(ui, /\.tabmodal-pane a\[href\^="\/settings"\]/);
+  assert.match(ui, /aria-selected/);
+});
+
+test('the styles use tokens only', () => {
+  const css = read('public', 'css', 'components', 'tab-modal.css');
+  assert.doesNotMatch(css, /#[0-9a-fA-F]{3,8}\b/);
+});

package/core/workspace-app/tests/unit/tab-title.test.js

@@ -0,0 +1,37 @@
+/**
+ * The tab says when a session is waiting.
+ *
+ * A session that stops to ask something is a run that is not happening until somebody answers, and the dashboard
+ * is usually in another tab. Vercel shows a build's state in the tab; this does the same for the one state that
+ * needs a person. Only "waiting" goes in the title: a count of detached sessions is noise.
+ */
+
+const { test } = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const path = require('path');
+
+const ui = fs.readFileSync(path.join(__dirname, '..', '..', 'public/ui.js'), 'utf8');
+const block = ui.slice(ui.indexOf('const BASE_TITLE = document.title;'), ui.indexOf('/* ---------------- the rail, arranged'));
+
+test('the page title is kept, and a waiting session is put in front of it', () => {
+  assert.match(block, /const BASE_TITLE = document\.title;/);
+  assert.match(block, /document\.title = `✋ \$\{n\} waiting · \$\{BASE_TITLE\}`;/);
+  assert.match(block, /if \(!w\) \{ document\.title = BASE_TITLE; return; \}/, 'and it goes back when nothing waits');
+});
+
+test('it reads what the toolbar already shows, rather than asking the server again', () => {
+  assert.match(block, /document\.querySelector\('\.screens-count \.screens-waiting'\)/);
+  assert.match(block, /replace\(\/\[\^0-9\]\/g, ''\)/);
+});
+
+test('it runs whenever the badge changes, however it was rewritten, and once at load', () => {
+  assert.match(block, /new MutationObserver\(syncTitleState\)\.observe\(screensCountEl, \{ childList: true, subtree: true, characterData: true \}\)/);
+  assert.match(block, /document\.body\.addEventListener\('htmx:after:swap'/, 'the swap event still counts too');
+  assert.match(block, /\nsyncTitleState\(\);\n/);
+});
+
+test('the fragment it reads marks a waiting session, and only then', () => {
+  const server = fs.readFileSync(path.join(__dirname, '..', '..', 'server.js'), 'utf8');
+  assert.match(server, /waiting\.length \? ` <span class="uk-label uk-label-warning screens-waiting"/);
+});

package/core/workspace-app/tests/unit/template-literals.test.js

@@ -0,0 +1,52 @@
+const { test } = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const APP = path.join(__dirname, '..', '..');
+const FILES = ['server.js', 'screens.js', 'jobs.js', 'assistant.js', 'ai-items.js', 'ddev.js'];
+
+// A backtick inside an HTML comment inside a template literal ENDS THE LITERAL and takes the
+// whole app down with a syntax error. CLAUDE.md warns about it; it has still happened three
+// times, because the comment reads perfectly well to a person and the failure appears
+// hundreds of lines away.
+//
+// This is the cheap guard: an HTML comment inside these files must not contain a backtick.
+// It costs one rule — write `update.sh --check` as update.sh --check inside a comment — and
+// removes a class of bug whose symptom is "the dashboard will not start".
+test('no HTML comment carries a backtick', () => {
+  const offenders = [];
+  for (const f of FILES) {
+    const src = fs.readFileSync(path.join(APP, f), 'utf8');
+    const lines = src.split('\n');
+    let inComment = false;
+    lines.forEach((line, i) => {
+      if (line.includes('<!--')) inComment = true;
+      if (inComment && line.includes('`')) offenders.push(`${f}:${i + 1}: ${line.trim().slice(0, 70)}`);
+      if (line.includes('-->')) inComment = false;
+    });
+  }
+  assert.deepEqual(offenders, [],
+    'a backtick in an HTML comment inside a template literal ends the literal — write it without one');
+});
+
+// The belt to that braces: whatever the rule above misses, the file must still parse. Cheap,
+// and it is the actual property that matters.
+test('every dashboard module parses', () => {
+  for (const f of FILES.concat(['workspaces.js', 'urls.js', 'checks.js', 'public/ui.js', 'public/suggest.js'])) {
+    execFileSync('node', ['--check', path.join(APP, f)]);
+  }
+});
+
+// Security headers are set ONCE in the request handler, because they were previously set at
+// three writeHead sites out of fifty-six — so every page but the graph viewer went without.
+// A regression here is invisible in the UI, which is exactly why it needs a test.
+test('the request handler sets the security headers centrally', () => {
+  const src = fs.readFileSync(path.join(APP, 'server.js'), 'utf8');
+  const handler = src.slice(src.indexOf('const server = http.createServer'), src.indexOf('const server = http.createServer') + 1600);
+  for (const h of ['X-Content-Type-Options', 'Referrer-Policy', 'X-Frame-Options']) {
+    assert.ok(handler.includes(h), `${h} is no longer set at the top of the request handler`);
+  }
+  assert.ok(handler.includes("'nosniff'"), 'nosniff value changed');
+});

package/core/workspace-app/tests/unit/terminal-scrollback.test.js

@@ -0,0 +1,61 @@
+/**
+ * Scrolling back in a terminal window.
+ *
+ * This looked impossible for a while, and the reason is worth keeping written down: the obvious
+ * implementation defeats itself. `Ctrl-A Esc` opens screen's copy mode, and then an ARROW KEY closes
+ * it again — the arrow sequence starts with Esc, and Esc in copy mode means abort — so the gesture
+ * opens and closes copy mode in one motion and types the rest of the sequence into the shell. The
+ * first attempt at this shipped that behaviour for a few minutes and was reverted: a window that
+ * appears to scroll and instead types into your session is worse than one that does not scroll.
+ *
+ * What works is screen's own movement keys, which are plain characters.
+ */
+
+const { test } = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const path = require('path');
+
+const client = fs.readFileSync(path.join(__dirname, '../../public/terminal.js'), 'utf8');
+const screens = fs.readFileSync(path.join(__dirname, '../../screens.js'), 'utf8');
+
+test('xterm keeps no scrollback of its own, and says why', () => {
+  // screen holds its client on the alternate buffer whatever runs inside it, so nothing ever scrolls
+  // off into xterm: a buffer here would hold nothing and cost memory.
+  assert.match(client, /scrollback: 0,/);
+  assert.match(client, /ALTERNATE buffer/);
+  assert.match(client, /baseY stays 0/, 'measured, not assumed');
+});
+
+test('copy mode is entered with Ctrl-A then Esc', () => {
+  assert.match(client, /const enterCopyMode = \(\) => \{ send\(String\.fromCharCode\(1\)\); send\(String\.fromCharCode\(27\)\); \};/);
+});
+
+test('the wheel moves with screen\'s own keys, never with an arrow', () => {
+  // The whole bug: an arrow starts with Esc, and Esc in copy mode aborts.
+  assert.match(client, /const HALF_UP = String\.fromCharCode\(21\);/, 'Ctrl-U');
+  assert.match(client, /const HALF_DOWN = String\.fromCharCode\(4\);/, 'Ctrl-D');
+  const wheel = client.slice(client.indexOf("el.addEventListener('wheel'"), client.indexOf('{ capture: true, passive: false }'));
+  assert.doesNotMatch(wheel, /\\x1b\[A|\\x1b\[B/, 'no arrow sequences reach a session in copy mode');
+  assert.match(client, /An ARROW KEY ABORTS IT/, 'and the reason is written where the next person will look');
+});
+
+test('only scrolling UP opens copy mode', () => {
+  // There is nothing below the last line to reach, so a wheel-down at the bottom must not open it.
+  const wheel = client.slice(client.indexOf("el.addEventListener('wheel'"), client.indexOf('{ capture: true, passive: false }'));
+  assert.match(wheel, /if \(e\.deltaY < 0\) enterCopyMode\(\);/);
+});
+
+test('whether it is in copy mode is SCREEN\'s answer, not a hopeful flag', () => {
+  // The first version set the flag when it sent the keys, and was wrong whenever copy mode did not
+  // open — and then every wheel notch typed into the shell.
+  assert.match(client, /if \(\/Copy mode aborted\/\.test\(text\)\) \{/);
+  assert.match(client, /\} else if \(\/Copy mode\/\.test\(text\)\) \{/);
+  assert.match(client, /never a\s*\n?\s*\/\/ flag set hopefully/);
+});
+
+test('there is a button as well as a wheel', () => {
+  assert.match(screens, /term-scrollback/);
+  assert.match(client, /const back = e\.target\.closest\('\.term-scrollback'\);/);
+  assert.match(client, /win\.__scrollBack\(\)/);
+});

package/core/workspace-app/tests/unit/terminal-size.test.js

@@ -0,0 +1,103 @@
+/**
+ * How big a terminal window opens, and what happens when it is resized.
+ *
+ * Three faults, each of which made the window show the wrong thing rather than merely look wrong:
+ *
+ *   1. **It opened too narrow.** The default was `innerWidth * 0.52` capped at 860px, which on a
+ *      1100px screen is 572px — 70 columns. 80x24 is what every TUI assumes, so everything inside
+ *      folded, and wrapped output reads as a broken program rather than as a small window.
+ *   2. **A resize did not reach the session.** The PTY is sized once, by the `stty` the server runs
+ *      before `screen -x`, and every socket message goes to the session's stdin — so there is no
+ *      resize channel to use. xterm re-fitted locally while screen went on painting for the old width.
+ *   3. **Attaches leaked.** `SIGHUP` to `script` left the `screen -x` client behind, one per window
+ *      and then one per resize — and screen fits a window to EVERY attached display, so a pile of
+ *      stale clients pins the session to the smallest one and the size can never be corrected.
+ */
+
+const { test } = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const path = require('path');
+
+const client = fs.readFileSync(path.join(__dirname, '../../public/terminal.js'), 'utf8');
+const server = fs.readFileSync(path.join(__dirname, '../../server.js'), 'utf8');
+const screens = fs.readFileSync(path.join(__dirname, '../../screens.js'), 'utf8');
+
+test('the sizes offered are the ones the Ubuntu terminal offers', () => {
+  // A terminal is measured in columns and rows: 132x43 means something to anyone who has used one,
+  // and "1057 by 741" means nothing. These four are GNOME/Ubuntu's own profile presets, so the list
+  // is familiar rather than invented here.
+  assert.match(client, /const PRESETS = \[\s*\{ cols: 80, rows: 24 \},\s*\{ cols: 80, rows: 43 \},\s*\{ cols: 132, rows: 24 \},\s*\{ cols: 132, rows: 43 \},/);
+  // The menu is one loop over the same four, so assert the LIST and the template rather than the
+  // rendered strings — matching my own interpolation would test nothing.
+  assert.match(screens, /\[\[80, 24\], \[80, 43\], \[132, 24\], \[132, 43\]\]/);
+  assert.match(screens, /data-term-size="\$\{c\}x\$\{r\}"/);
+  assert.match(screens, /data-term-size="fit"/, 'and the default, said in words');
+});
+
+test('a window opens at 132x43, clamped to the display', () => {
+  // 80x24 is the floor, not the default — it is cramped for a build log or an agent's output, which is
+  // most of what these windows hold. And NOT "the biggest that fits", which was tidy and wrong: the
+  // window is draggable and resizable, so a few pixels past the edge is something you move, while a
+  // terminal that opened too small is something you have to notice and correct. Measured: 1700x1000
+  // opens 132x43 and 1100x800 clamps to 129x42, both fully on screen.
+  assert.match(client, /const DEFAULT_PRESET = \{ cols: 132, rows: 43 \};/);
+  assert.match(client, /function defaultPreset\(\) \{ return DEFAULT_PRESET; \}/);
+  // From a measured cell, because the font is the user's monospace stack at whatever size the browser
+  // gives it — a character width is not something this file can know.
+  assert.match(client, /term\._core\._renderService\.dimensions\.css\.cell/);
+});
+
+test('a size somebody chose is never overridden', () => {
+  // The correction applies to a window that merely opened narrow, not to one deliberately made small.
+  assert.match(client, /if \(!pane\.dataset\.geom && term\.cols < defaultPreset\(\)\.cols\)/);
+  assert.match(client, /if \(remembered\) win\.dataset\.geom = '1';/);
+  assert.match(client, /win\.dataset\.geom = '1';\s*\/\/ it has a size somebody chose now/);
+});
+
+test('a resize re-attaches, because there is no resize channel', () => {
+  assert.match(client, /const wire = \(\) => \{/);
+  assert.match(client, /pane\.__resized = resized;/);
+  // Debounced, and only when the size in CHARACTERS changed: two pixels is not a reconnect.
+  assert.match(client, /if \(term\.cols === attachedAt\.cols && term\.rows === attachedAt\.rows\) return;/);
+  // The debounce body is long enough that a bounded [\s\S] window is a test about its length rather
+  // than its behaviour; assert the two things that matter instead.
+  assert.match(client, /resizeTimer = setTimeout\(/);
+  const body = client.slice(client.indexOf('resizeTimer = setTimeout('));
+  assert.match(body.slice(0, 700), /wire\(\);/, 'and it re-attaches');
+});
+
+test('the old attach detaches itself before the new one opens', () => {
+  // Ctrl-A d is screen's own detach for THIS display. Without it the size correction is defeated by
+  // the clients left behind.
+  assert.match(client, /ws\.send\(String\.fromCharCode\(1\)\); ws\.send\('d'\);/);
+});
+
+test('the server adapts the window and reaps the whole attach', () => {
+  assert.match(server, /exec screen -A -x \$\{session\}/, '-A adapts the window to this display');
+  assert.match(server, /detached: true/, 'its own process group');
+  assert.match(server, /process\.kill\(-child\.pid, 'SIGHUP'\)/, 'so the group can be killed, not just script');
+  assert.match(server, /screen fits a window to EVERY attached display/, 'and the reason is written down');
+});
+
+test('reset lands on the same size a window opens at', () => {
+  // The menu entry and the double-click go to the default, and the label says which size that is —
+  // "biggest that fits this display" described the old behaviour and would now be a lie.
+  assert.match(screens, /Reset to 132 &times; 43/);
+  assert.match(screens, /term-fit/);
+  assert.match(client, /const sizePick = e\.target\.closest\('\[data-term-size\]'\);/);
+  assert.match(client, /Double-click the title bar puts a window back/);
+  // And the stored geometry is forgotten, or it would come back the next time it opens.
+  assert.match(client, /delete all\[win\.dataset\.session\];/);
+});
+
+test('nothing but a real child may go in termChildren', () => {
+  // It is BOTH the shutdown list and what MAX_TERMINALS counts. A helper object was added to it so
+  // shutdown could kill the process group — it was never removed, so after eight opens every further
+  // WebSocket upgrade answered 503 and the terminal opened blank. The group kill belongs in the
+  // shutdown loop, over the real children.
+  const adds = [...server.matchAll(/termChildren\.add\(([^)]*)\)/g)].map((m) => m[1].trim());
+  assert.deepEqual(adds, ['child'], 'only the child itself');
+  assert.match(server, /for \(const c of termChildren\) \{[\s\S]{0,200}process\.kill\(-c\.pid, 'SIGHUP'\)/);
+  assert.match(server, /it is also what MAX_TERMINALS counts, so nothing else may ever be put in it/);
+});

package/core/workspace-app/tests/unit/terminal-style.test.js

@@ -0,0 +1,84 @@
+/**
+ * How a terminal looks: the Ubuntu face and palette by default, a larger text size, and a style
+ * the user can change the way the dashboard's own style is changed.
+ */
+
+const { test } = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const path = require('path');
+
+const PUBLIC = path.join(__dirname, '../../public');
+const client = fs.readFileSync(path.join(PUBLIC, 'terminal.js'), 'utf8');
+const base = fs.readFileSync(path.join(PUBLIC, 'css/base.css'), 'utf8');
+const css = fs.readFileSync(path.join(PUBLIC, 'css/components/terminals.css'), 'utf8');
+const { TERM_STYLES, termPaneHtml } = require('../../screens.js');
+
+test('the face is Ubuntu Mono, vendored with its licence and waited for before xterm measures', () => {
+  assert.ok(fs.existsSync(path.join(PUBLIC, 'vendor/fonts/ubuntu-mono-latin-wght-normal.woff2')));
+  assert.ok(fs.existsSync(path.join(PUBLIC, 'vendor/fonts/ubuntu-mono-LICENSE.txt')));
+  assert.match(base, /font-family: 'Ubuntu Mono';[\s\S]{0,120}font-weight: 400 700;/);
+  assert.match(client, /const TERM_FONT = '"Ubuntu Mono", /);
+  assert.match(client, /document\.fonts\.load\(/);
+});
+
+test('the default text size is larger than the 13px it was', () => {
+  const m = client.match(/const FONT_DEFAULT = (\d+);/);
+  assert.ok(m && Number(m[1]) >= 16, 'at least the 16px of the Ubuntu terminal');
+  assert.match(client, /fontSize: look\.size,/);
+});
+
+test('the menu offers exactly the styles terminal.js has a palette for', () => {
+  const ids = TERM_STYLES.map(([id]) => id);
+  const order = (client.match(/const STYLE_ORDER = \[([^\]]+)\]/) || [])[1] || '';
+  assert.deepEqual(order.split(',').map((s) => s.trim().replace(/'/g, '')), ids);
+  assert.equal(ids[0], 'ubuntu', 'Ubuntu is the default and the first');
+  const html = termPaneHtml('s');
+  for (const id of ids) assert.match(html, new RegExp(`data-term-style="${id}"`));
+});
+
+test('text size: buttons, Ctrl and plus, minus and zero, and Ctrl and the wheel', () => {
+  const html = termPaneHtml('s');
+  for (const how of ['down', 'up', 'reset']) assert.match(html, new RegExp(`data-term-font="${how}"`));
+  assert.match(client, /attachCustomKeyEventHandler/);
+  assert.match(client, /if \(e\.ctrlKey\) \{ stepFont\(/);
+  assert.match(client, /const FONT_MIN = 11;/);
+  assert.match(client, /const FONT_MAX = 32;/);
+});
+
+test('the look is a per-browser preference applied to every open window', () => {
+  assert.match(client, /const FONT_KEY = 'ws-term-font';/);
+  assert.match(client, /const STYLE_KEY = 'ws-term-style';/);
+  assert.match(client, /function paintLook\(\) \{[\s\S]{0,260}windows\(\)\.forEach/);
+  assert.match(client, /the Dashboard style is read from the page's tokens|The Dashboard style is read from the page's tokens/);
+});
+
+test('the window wears the palette, set as properties and never written as colours', () => {
+  for (const v of ['--term-bg', '--term-fg', '--term-bar', '--term-bar-ink']) {
+    assert.ok(css.includes(`var(${v}`), `${v} is read by the stylesheet`);
+    assert.ok(client.includes(`'${v}'`), `${v} is set by terminal.js`);
+  }
+  assert.doesNotMatch(css, /#[0-9a-fA-F]{3,8}\b/, 'no hex in a component');
+});
+
+test('the header wraps and the buttons keep one square size at every width', () => {
+  assert.match(css, /\.term-window-head \{[^}]*flex-wrap: wrap;/);
+  assert.match(css, /@container term \(min-width: 56rem\)/);
+  assert.match(css, /container: term \/ inline-size;/);
+});
+
+test('a window never opens taller than the room under its top edge', () => {
+  assert.match(client, /window\.innerHeight - top - 8/);
+});
+
+test('a click inside a window is only taken by the look menu, because the window itself carries the style', () => {
+  assert.match(client, /closest\('\.term-look-menu \[data-term-style\]'\)/);
+  assert.match(client, /closest\('\.term-look-menu \[data-term-font\]'\)/);
+  assert.doesNotMatch(client, /closest\('\[data-term-style\]'\)/);
+});
+
+test('a terminal opened from the Screens modal closes the modal first, so the keyboard reaches it', () => {
+  assert.match(client, /modal && modal\.contains\(open\) && window\.UIkit/);
+  assert.match(client, /window\.UIkit\.modal\(modal\)\.hide\(\)/);
+  assert.match(client, /__term\.focus\(\)/);
+});

package/core/workspace-app/tests/unit/terminal-windows.test.js

@@ -0,0 +1,154 @@
+/**
+ * The screen terminals: floating windows, several at once.
+ *
+ * Most of this is about the two things that made only ONE terminal possible, both of which look fine
+ * in isolation and neither of which a page renders differently:
+ *
+ *   - the markup addressed its parts by ID, so a second terminal's script found the first one's status
+ *     line, buttons and mount point;
+ *   - the mount waited for `offsetParent`, which is null for a `position: fixed` element by
+ *     definition — so with the panes turned into floating windows, every one of them reported itself
+ *     hidden and none ever connected.
+ */
+
+const { test } = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const path = require('path');
+
+const { termPaneHtml, termLayerHtml } = require('../../screens');
+
+const app = (f) => fs.readFileSync(path.join(__dirname, '../..', f), 'utf8');
+const server = app('server.js');
+const client = app('public/terminal.js');
+const css = app('public/css/components/terminals.css');
+const screensJs = app('screens.js');
+const screenActions = app('actions/screens.js');
+
+const html = termPaneHtml('dev--blog1--claude-1234');
+
+test('a terminal is a window of its own, named by the session', () => {
+  assert.match(html, /class="term-window" data-session="dev--blog1--claude-1234"/);
+  assert.match(html, /role="dialog"/, 'it is a window, and says so to a screen reader');
+  assert.match(html, /aria-label="Terminal — dev--blog1--claude-1234"/);
+});
+
+test('nothing in a terminal is addressed by id', () => {
+  // The whole reason only one could be open: a second window found the first one's elements.
+  assert.doesNotMatch(html, /\sid="/, 'ids are what two windows collide over');
+  for (const part of ['term-screen', 'term-status', 'term-reconnect', 'term-fullscreen', 'term-close']) {
+    assert.ok(html.includes(`class="${part}"`) || html.includes(`${part}`), `${part} is a class`);
+  }
+});
+
+test('the session\'s own verbs are on the window, not only on the row behind it', () => {
+  // Acting on the session you are watching used to start with closing the terminal you were watching
+  // it in.
+  assert.match(html, /term-interrupt/);
+  assert.match(html, /term-detach/);
+  assert.match(html, /term-kill/);
+  assert.match(html, /Interrupt what runs in dev--blog1--claude-1234/);
+  assert.match(html, /Kill the session dev--blog1--claude-1234/);
+  // And the window's own controls, which are a different thing — hence the divider between them.
+  assert.match(html, /term-verbs-sep/);
+  assert.match(html, /Close this terminal \(dev--blog1--claude-1234 keeps running\)/,
+    'closing a window must never read as ending the session');
+});
+
+test('every verb that ends something goes through the one confirm dialog', () => {
+  for (const verb of ['term-interrupt', 'term-detach', 'term-kill']) {
+    const at = html.indexOf(verb);
+    assert.ok(at > 0, `${verb} is there`);
+    const button = html.slice(at, html.indexOf('</button>', at));
+    assert.match(button, /arm-step/, `${verb} is armed`);
+  }
+  // The two that go to the server fire on the dialog's Yes alone.
+  assert.match(html.slice(html.indexOf('term-detach')), /hx-trigger="confirmed-remove"/);
+});
+
+test('Ctrl-C goes down the window\'s own socket, not to an endpoint that cannot reach the host', () => {
+  // onHostScreen says it itself: "the runner does not proxy them yet" — so /actions/screen-interrupt
+  // answers 500 for a session on the host, which is every session. The window is already attached.
+  assert.match(screensJs, /the runner does not\s+proxy them yet/,
+    'the reason is written down where the button is made');
+  const button = html.slice(html.indexOf('term-interrupt'), html.indexOf('</button>', html.indexOf('term-interrupt')));
+  assert.doesNotMatch(button, /hx-post/, 'it does not post anywhere');
+  assert.match(client, /String\.fromCharCode\(3\)/, 'terminal.js sends the byte');
+});
+
+test('a killed session closes its window', () => {
+  // A terminal left open on a dead session is one you can still type into, with nothing on the end.
+  assert.match(screenActions, /HX-Trigger.*screen-killed/s);
+  assert.match(client, /screen-killed/);
+});
+
+test('the mount tests the RECTANGLE, never offsetParent', () => {
+  // A fixed element's offsetParent is null by definition, so the obvious test reports every floating
+  // terminal as hidden and none of them ever connects. This one cost a debugging round.
+  assert.match(client, /getBoundingClientRect\(\);\s*\n\s*return r\.width > 0 && r\.height > 0/);
+  // Not a blunt search for the word: the comment above the fix names it, which is the point of it.
+  assert.doesNotMatch(client, /\.offsetParent\s*(!==|===)/,
+    'offsetParent cannot answer this for a fixed window, so nothing may branch on it');
+});
+
+test('a window declares its own footprint', () => {
+  // Without border-box the measured rectangle was re-applied as a CONTENT width, so every drag grew
+  // the window by its padding and border — 18px a time. The rails hit the same trap.
+  assert.match(css, /\.term-window \{[^}]*box-sizing: border-box/s);
+});
+
+test('the window remembers where it was put, and is clamped back into view', () => {
+  assert.match(client, /ws-term-windows/, 'geometry is per browser, like the theme');
+  assert.match(client, /ws-term-layout/);
+  assert.match(client, /window\.addEventListener\('resize'/,
+    'a display that got smaller must not leave a window off it');
+});
+
+test('list and grid arrange every open window', () => {
+  assert.match(client, /function arrange\(how\)/);
+  assert.match(server, /data-term-layout="list"/);
+  assert.match(server, /data-term-layout="grid"/);
+});
+
+test('the terminals bar is in the top bar, beside Screens', () => {
+  // One glance, two facts: the sessions running on this machine, and the terminals open in this
+  // browser. It was a pill floating over the bottom right corner — a second place to look for a thing
+  // that belongs with Screens, sitting on top of whatever was in that corner of the page.
+  const group = server.slice(server.indexOf("groups.push({ id: 'screens'"));
+  const entry = group.slice(0, group.indexOf('] });'));
+  assert.match(entry, /id: 'terminals'/, 'in the same navigation group as the session count');
+  assert.match(entry, /id="term-bar"/);
+  assert.match(entry, /topbar: 'end'/);
+  // Its own entry, so it can be moved or hidden in Settings → Navigation without taking the session
+  // count with it.
+  assert.match(entry, /label: 'Terminals'/);
+  // And BEFORE it, so the pair reads inwards — the terminals you have open, then the sessions they are
+  // open on — and Screens keeps the end of the top bar, where it has always been.
+  assert.ok(entry.indexOf("id: 'terminals'") < entry.indexOf("id: 'open-screens'"),
+    'the terminals bar sits to the left of the session count');
+  assert.doesNotMatch(client, /createElement\('div'\);\s*\n\s*bar\.id/, 'the client no longer makes one');
+});
+
+test('the bar says nothing until there is something to say', () => {
+  // The count is not the server's to know — a window exists in the browser that opened it — so the
+  // markup ships empty and hidden, and the client unhides it.
+  const group = server.slice(server.indexOf("groups.push({ id: 'screens'"));
+  assert.match(group.slice(0, group.indexOf('] });')), /id="term-bar"[^`]*hidden/);
+  assert.match(client, /bar\.hidden = !n;/);
+});
+
+test('the layer is empty until something is opened', () => {
+  assert.equal(termLayerHtml(), '<div id="term-windows"></div>');
+  assert.match(termLayerHtml(['a1']), /term-window" data-session="a1"/);
+});
+
+test('every way in opens a window, and none of them fills the editor modal', () => {
+  // Two places in the core open a terminal — the Screens row and the SCREENS dropdown on a project —
+  // and plugins (Jira's agent button) use the same attribute; each used to replace the one modal, which
+  // is what made a second one impossible.
+  const openers = (server + screensJs).match(/data-open-terminal=/g) || [];
+  assert.ok(openers.length >= 2, `every opener is declarative (found ${openers.length})`);
+  assert.doesNotMatch(server + screensJs,
+    /screen-term\/\$\{[^}]*\}"\s+hx-target="#editor-modal-body"/,
+    'a terminal never goes into the editor modal again');
+});