@gonrocca/nodd 0.1.2 → 0.2.0

package/extensions/nodd-agents.test.ts

@@ -40,6 +40,16 @@ test("the renderer matches an expected frontmatter and body exactly", () => {
   assert.ok(rendered.endsWith("\n"));
 });
 
+test("the configured thinking level reaches the generated agent", () => {
+  // `/nodd-models` stores a level per slot. If it stops here, the picker is
+  // writing a value nothing reads — a setting that looks applied and is not.
+  const withLevel = buildAgentFile(NODD_AGENTS[2], "anthropic/claude-opus-4-1", "high");
+  assert.match(withLevel, /^thinking: high$/m);
+
+  const withNone = buildAgentFile(NODD_AGENTS[2], "anthropic/claude-opus-4-1", undefined);
+  assert.ok(!/^thinking:/m.test(withNone), "no level rather than an empty one");
+});
+
 test("a slot with no configured model falls back to default, then omits the line", () => {
   const withDefault = buildAgentFile(NODD_AGENTS[0], "anthropic/fallback");
   assert.match(withDefault, /^model: anthropic\/fallback$/m);

package/extensions/nodd-agents.ts

@@ -106,11 +106,18 @@ function enforcementNote(): string {
 }
 
 /** Pure: agent definition plus model in, file text out. */
-export function buildAgentFile(agent: NoddAgent, model: string | undefined): string {
+export function buildAgentFile(
+  agent: NoddAgent,
+  model: string | undefined,
+  thinking?: string | undefined,
+): string {
   const front = ["---", `name: nodd-${agent.slot}`, `description: ${agent.description}`];
   // Omitted rather than emitted empty: a blank `model:` is a value pi cannot
   // resolve, and an unresolvable model fails at the moment it is needed.
   if (model) front.push(`model: ${model}`);
+  // The level `/nodd-models` stored. Without this line the picker would be
+  // writing a setting nothing reads.
+  if (thinking) front.push(`thinking: ${thinking}`);
   front.push(
     `tools: ${agent.tools.join(", ")}`,
     "systemPromptMode: replace",
@@ -133,6 +140,17 @@ export function buildAgentFile(agent: NoddAgent, model: string | undefined): str
   return `${front.join("\n")}\n\n${body}\n`;
 }
 
+/**
+ * The level configured for a slot. Unlike the model there is no `default`
+ * fallback: an unset level means pi's own default, which is the right answer.
+ */
+function thinkingFor(config: Record<string, unknown>, slot: string): string | undefined {
+  const thinking = config.thinking;
+  if (typeof thinking !== "object" || thinking === null) return undefined;
+  const level = (thinking as Record<string, unknown>)[slot];
+  return typeof level === "string" && level !== "" ? level : undefined;
+}
+
 function modelFor(config: Record<string, unknown>, slot: string): string | undefined {
   const models = config.models;
   if (typeof models !== "object" || models === null) return undefined;
@@ -158,7 +176,11 @@ export function provisionAgents(home: string, config: Record<string, unknown>):
   for (const agent of NODD_AGENTS) {
     const name = `nodd-${agent.slot}`;
     try {
-      writeFileSync(join(dir, `${name}.md`), buildAgentFile(agent, modelFor(config, agent.slot)), "utf8");
+      writeFileSync(
+        join(dir, `${name}.md`),
+        buildAgentFile(agent, modelFor(config, agent.slot), thinkingFor(config, agent.slot)),
+        "utf8",
+      );
       result.written.push(name);
     } catch {
       // One agent failing must not block the other two.

package/extensions/nodd-enforcement.test.ts

@@ -40,7 +40,8 @@ function session(options: { cwd?: string; entries?: Array<Record<string, unknown
   const entries = options.entries ?? [];
   const pi = {
     on: (event: string, handler: Handler) => handlers.set(event, handler),
-    registerTool: (name: string, opts: { handler: (args: never) => unknown }) => tools.set(name, opts.handler),
+    // Replica `loader.js:215-222`: pi pasa UN objeto y hace `tools.set(tool.name, …)`.
+    registerTool: (tool: { name: string; handler: (args: never) => unknown }) => tools.set(tool.name, tool.handler),
     appendEntry: (customType: string, data: unknown) => entries.push({ type: "custom", customType, data }),
   };
   const cwd = options.cwd ?? mkdtempSync(join(tmpdir(), "nodd-enforce-"));

package/extensions/nodd-kernel.ts

@@ -57,7 +57,10 @@ type AgentStartEvent = { systemPrompt?: unknown };
 type PiApi = {
   on(event: string, handler: (event: never) => unknown): void;
   appendEntry?(type: string, data?: unknown): void;
-  registerTool?(name: string, options: unknown): void;
+  // Un solo objeto, con el nombre adentro. pi hace `tools.set(tool.name, …)`:
+  // pasarle (name, options) como a registerCommand deja el nombre en undefined
+  // y el provider rechaza el request entero con "tools[N].name is required".
+  registerTool?(tool: { name: string } & Record<string, unknown>): void;
 };
 
 const INTENTS: readonly Intent[] = ["read-only", "change"];
@@ -533,11 +536,13 @@ export default function register(pi?: PiApi, cwd: string = process.cwd()): Kerne
   // one-shot hatches on top of this at runtime.
   kernel.setPolicy(readPolicy());
 
-  pi.registerTool?.("nodd_declare", {
+  pi.registerTool?.({
+    name: "nodd_declare",
     ...DECLARE_SCHEMA,
     handler: (args: DeclareArgs) => kernel.declare(args).text,
   });
-  pi.registerTool?.("nodd_task", {
+  pi.registerTool?.({
+    name: "nodd_task",
     ...TASK_SCHEMA,
     handler: (args: TaskArgs) => kernel.task(args).text,
   });

package/extensions/nodd-models.test.ts

@@ -3,6 +3,7 @@ import assert from "node:assert/strict";
 import { readFileSync } from "node:fs";
 import { MECHANISM_PLACEHOLDER } from "../src/models/slots.ts";
 import register, { runModelsCommand, type ConfigIo } from "./nodd-models.ts";
+import type { EnterResult, PickerState } from "../src/models/picker.ts";
 
 const registry = {
   getAll: () => [
@@ -126,13 +127,38 @@ test("editing a slot with a profile active mirrors into that profile", () => {
 // ---------------------------------------------------------------------------
 // The picker host
 // ---------------------------------------------------------------------------
+
+/** Drive the real picker to a save carrying one staged model. */
+function stageOneModel(): { type: "save"; state: PickerState } {
+  let captured: EnterResult | null = null;
+  const component = register.createComponent(
+    {
+      models: { implement: "anthropic/claude-opus-4-1" },
+      thinking: {},
+      groups: new Map([["anthropic", ["claude-opus-4-1"]]]),
+    },
+    (result: EnterResult) => {
+      captured = result;
+    },
+  );
+  // The menu opens on "nuevo perfil"; save is two rows down.
+  component.handleInput?.("\u001b[B");
+  component.handleInput?.("\u001b[B");
+  component.handleInput?.("\r");
+  assert.ok(captured, "the picker must close with a result");
+  assert.equal(captured!.type, "save");
+  return captured as { type: "save"; state: PickerState };
+}
 test("quitting the picker produces zero writes; saving writes once", async () => {
   const quitIo = memoryIo();
   await register.runPicker({ type: "quit" }, quitIo);
   assert.equal(quitIo.writes.length, 0, "quit writes nothing");
 
+  // A save carries the whole staged state, so it is built from the picker
+  // itself rather than hand-written: a literal would drift from the real shape.
+  const saved = stageOneModel();
   const saveIo = memoryIo({ unrelated: true });
-  await register.runPicker({ type: "save", models: { implement: "anthropic/claude-opus-4-1" } }, saveIo);
+  await register.runPicker(saved, saveIo);
   assert.equal(saveIo.writes.length, 1);
   assert.deepEqual(saveIo.writes[0].models, { implement: "anthropic/claude-opus-4-1" });
   assert.equal(saveIo.writes[0].unrelated, true, "the picker's save preserves unrelated keys");
@@ -147,14 +173,25 @@ test("the command is registered with pi under its own name", () => {
 
 test("the picker component renders rows and is a plain object, no TUI import", () => {
   const component = register.createComponent(
-    { models: { implement: "anthropic/claude-opus-4-1" }, groups: new Map([["anthropic", ["claude-opus-4-1"]]]) },
+    {
+      models: { implement: "anthropic/claude-opus-4-1" },
+      thinking: {},
+      groups: new Map([["anthropic", ["claude-opus-4-1"]]]),
+    },
     () => {},
   );
   const lines = component.render(80);
   assert.ok(Array.isArray(lines), "render returns string[]");
-  assert.ok(lines.length > 7, "every slot row is rendered");
-  assert.ok(lines.some((line) => line.includes(MECHANISM_PLACEHOLDER)), "mechanism rows are visible in the picker");
-  assert.ok(lines.some((line) => line.includes("anthropic/claude-opus-4-1")));
+  assert.ok(lines.some((line) => line.includes("guardar y salir")), "the menu offers save");
+
+  // The slots are one screen in, behind the loose-config row, which is what the
+  // menu offers while no profile exists.
+  component.handleInput?.("\u001b[B");
+  component.handleInput?.("\r");
+  const slots = component.render(80);
+  assert.ok(slots.length > 7, "every slot row is rendered");
+  assert.ok(slots.some((line) => line.includes(MECHANISM_PLACEHOLDER)), "mechanism rows are visible in the picker");
+  assert.ok(slots.some((line) => line.includes("anthropic/claude-opus-4-1")));
 });
 
 // ---------------------------------------------------------------------------

package/extensions/nodd-models.ts

@@ -23,8 +23,10 @@ import { readFileSync, writeFileSync } from "node:fs";
 import { mergeConfig, noddConfigPath } from "../src/config.ts";
 import { SLOT_ROWS } from "../src/models/slots.ts";
 import { assignmentPatch, groupByProvider, parseAssignment, validateAssignment, type RegistryModel } from "../src/models/assign.ts";
-import { applyProfileCommand, isValidProfileName, mirrorToActiveProfile, readActiveProfile, readProfiles } from "../src/models/profiles.ts";
-import { createPickerState, enter, moveCursor, renderRows, stage, type EnterResult, type PickerState } from "../src/models/picker.ts";
+import { applyProfileCommand, isValidProfileName, mirrorToActiveProfile, readActiveProfile, readProfiles, type Profile } from "../src/models/profiles.ts";
+import { back, createPickerState, decodeKey, enter, navigate, pickerTitle, submitText, type EnterResult, type PickerState } from "../src/models/picker.ts";
+import { fitRows, truncateToWidth, usableRows, windowRows } from "../src/models/layout.ts";
+import { isThinkingLevel, type SlotThinking } from "../src/models/thinking.ts";
 
 export type ConfigIo = {
   readConfig(): Record<string, unknown>;
@@ -144,68 +146,169 @@ export function runModelsCommand(args: string, io: ConfigIo, registry?: ModelReg
   return `nodd · ${assignment.slot} → ${patch.models[assignment.slot]}`;
 }
 
-/** Persist a picker outcome. Quit writes nothing; save writes once. */
+/** The thinking map as stored, keeping only the levels that are real. */
+function currentThinking(raw: Record<string, unknown>): SlotThinking {
+  const stored = raw.thinking;
+  const out: SlotThinking = {};
+  for (const [key, value] of Object.entries(typeof stored === "object" && stored !== null ? stored : {})) {
+    if (isThinkingLevel(value)) out[key] = value;
+  }
+  return out;
+}
+
+/** Everything the picker opens on, read from the config in one place. */
+function pickerInput(raw: Record<string, unknown>, groups: Map<string, string[]>) {
+  return {
+    models: currentModels(raw),
+    thinking: currentThinking(raw),
+    groups,
+    profiles: readProfiles(raw).profiles,
+    activeProfile: readActiveProfile(raw),
+  };
+}
+
+/**
+ * Persist a picker outcome. Quit writes nothing; save writes once.
+ *
+ * The picker stages everything — slots, thinking levels and the whole profile
+ * map — and hands back the final state, so this is one write, never one per
+ * keystroke. `activeProfile` and `profiles` are carried through because the
+ * picker can create, delete, duplicate and activate them.
+ */
 function runPicker(result: EnterResult, io: ConfigIo): void {
   if (result.type !== "save") return;
   const raw = io.readConfig();
-  io.writeConfig(mirrorToActiveProfile(mergeConfig(raw, { models: result.models })));
+  const { models, thinking, profiles, activeProfile } = result.state.edits;
+  io.writeConfig(
+    mirrorToActiveProfile(
+      mergeConfig(raw, { models, thinking, profiles, activeProfile }),
+    ),
+  );
 }
 
 /**
- * The `ctx.ui.custom` component. It holds one `PickerState` and forwards
- * keystrokes to the pure state machine; every decision lives there.
+ * The `ctx.ui.custom` component. It holds one `PickerState` and forwards every
+ * keystroke to the pure state machine; no decision lives here.
+ *
+ * Ported from `zero-models.ts:777-926`. Two things it must never do: throw out
+ * of `handleInput` (a transition bug would wedge the pi session, so the whole
+ * body is wrapped and a failure closes the picker), and write anything — only
+ * `runPicker` writes, once, on save.
  */
 function createComponent(
-  input: { models: Record<string, string>; groups: Map<string, string[]> },
+  input: {
+    models: Record<string, string>;
+    thinking: SlotThinking;
+    groups: Map<string, string[]>;
+    profiles?: Record<string, Profile>;
+    activeProfile?: string | null;
+  },
   done: (result: EnterResult) => void,
   requestRender: () => void = () => {},
 ): Component {
   let state: PickerState = createPickerState(input);
-  let choosing: { slot: string; options: string[]; cursor: number } | null = null;
+  // Inline text buffer — non-null only while `state.textPrompt` is open.
+  let buffer: string | null = null;
+
+  function render(width: number): string[] {
+    const inner = Math.max(20, width - 2);
+    // pi hands the component its width but not its height, so the height comes
+    // from the terminal itself, minus what pi's own chrome takes.
+    const maxRows = usableRows(process.stdout?.rows);
+    const head: string[] = [pickerTitle(state), ""];
+    if (state.notice) head.push(state.notice, "");
+
+    if (state.textPrompt) {
+      return fitRows(
+        [...head, state.textPrompt.label, `> ${buffer ?? ""}`, "", "enter confirmar · esc volver"]
+          .map((line) => truncateToWidth(line, inner)),
+        maxRows,
+      );
+    }
+
+    // Reserve the header and footer, then window the list around the cursor so
+    // a long list scrolls instead of overflowing the terminal.
+    const capacity = Math.max(1, maxRows - head.length - 2);
+    const win = windowRows(state.entries.length, state.cursor, capacity);
+    const rows = state.entries.slice(win.start, win.end).map((entry, index) => {
+      const selected = win.start + index === state.cursor;
+      return truncateToWidth(`${selected ? "❯ " : "  "}${entry.label}`, inner);
+    });
+
+    return fitRows(
+      [...head, ...rows, "", truncateToWidth("↑↓ mover · enter elegir · esc volver · q salir", inner)],
+      maxRows,
+    );
+  }
+
+  /** Apply an `EnterResult` — re-render on `state`, close on `save`/`quit`. */
+  function applyResult(result: EnterResult): void {
+    if (result.type === "state") {
+      state = result.state;
+      requestRender();
+      return;
+    }
+    done(result);
+  }
+
+  /** Route a keystroke while the inline text buffer is open. */
+  function handleTextInput(data: string): void {
+    const key = decodeKey(data);
+    if (key === "esc") {
+      // Esc abandons the typed value and returns to the list unchanged:
+      // `submitText` with an empty string is exactly that no-op.
+      state = submitText(state, "");
+      buffer = null;
+    } else if (key === "enter") {
+      state = submitText(state, buffer ?? "");
+      buffer = null;
+    } else if (key === "backspace") {
+      buffer = (buffer ?? "").slice(0, -1);
+    } else if (data.length >= 1 && data.charCodeAt(0) >= 32 && !data.startsWith("\u001b")) {
+      // Printable characters only; control sequences are dropped.
+      buffer = (buffer ?? "") + data;
+    }
+    requestRender();
+  }
 
   return {
-    render(width: number): string[] {
-      const inner = Math.max(20, width - 4);
-      const lines = choosing
-        ? [
-            `elegí un modelo para ${choosing.slot}:`,
-            ...choosing.options.map((option, i) => `${i === choosing!.cursor ? "❯" : " "} ${option}`),
-          ]
-        : [
-            "nodd · modelos (↑↓ mover · enter elegir · q salir)",
-            ...renderRows(state).map((row, i) => {
-              const marker = i === state.cursor ? "❯" : " ";
-              return `${marker} ${row.id.padEnd(20)} →  ${row.value}`;
-            }),
-          ];
-      return lines.map((line) => line.slice(0, inner));
+    render,
+    invalidate(): void {
+      /* stateless render — nothing cached to clear */
     },
-
     handleInput(data: string): void {
-      if (choosing) {
-        if (data === "\r" || data === "\n") {
-          state = stage(state, choosing.slot, choosing.options[choosing.cursor]);
-          choosing = null;
-        } else if (data === "\u001b[A") choosing.cursor = Math.max(0, choosing.cursor - 1);
-        else if (data === "\u001b[B") choosing.cursor = Math.min(choosing.options.length - 1, choosing.cursor + 1);
-        else if (data === "q" || data === "\u001b") choosing = null;
-        requestRender();
-        return;
-      }
+      try {
+        if (state.textPrompt) {
+          handleTextInput(data);
+          return;
+        }
 
-      if (data === "\u001b[A") state = moveCursor(state, -1);
-      else if (data === "\u001b[B") state = moveCursor(state, 1);
-      else if (data === "q" || data === "\u001b") done({ type: "quit" });
-      else if (data === "\r" || data === "\n") {
-        const result = enter(state);
-        if (result.type === "choose") choosing = { slot: result.slot, options: result.options, cursor: 0 };
-        else done(result);
+        const key = decodeKey(data);
+        if (key === "up") state = navigate(state, -1);
+        else if (key === "down") state = navigate(state, 1);
+        else if (key === "enter") {
+          const result = enter(state);
+          // `enter` on a custom-* row opens `textPrompt`; arm the buffer.
+          if (result.type === "state" && result.state.textPrompt) buffer = "";
+          applyResult(result);
+          return;
+        } else if (key === "esc") {
+          applyResult(back(state));
+          return;
+        } else if (data === "q") {
+          done({ type: "quit" });
+          return;
+        }
+        requestRender();
+      } catch {
+        // A transition bug must never wedge the pi session — close instead.
+        done({ type: "quit" });
       }
-      requestRender();
     },
   };
 }
 
+
 type PiApi = {
   registerCommand?(name: string, options: { description?: string; handler: (args: string, ctx: unknown) => unknown }): void;
 };

package/extensions/nodd-tools.test.ts

@@ -12,7 +12,8 @@ function fakePi() {
     tools,
     on() {},
     appendEntry() {},
-    registerTool(name: string, options: any) { tools.set(name, options); },
+    // Replica `loader.js:215-222`: pi pasa UN objeto y hace `tools.set(tool.name, …)`.
+    registerTool(tool: any) { tools.set(tool.name, tool); },
   };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gonrocca/nodd",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Non-negotiable Organic Driven Development — the ODD protocol as runtime mechanism for pi: blocking gates, observed evidence, and promotion to /forge.",
   "type": "module",
   "keywords": [

package/src/config.test.ts

@@ -41,6 +41,17 @@ test("merge writes only the named section", () => {
   assert.deepEqual(merged.gates, { track: { enabled: false } });
 });
 
+// `/nodd-gates` writes through this merge, so a section it does not know about
+// has to survive it. Thinking levels are exactly that section: dropping them on
+// an unrelated gate toggle would silently reset every slot's effort.
+test("merge preserves thinking levels it was not asked to touch", () => {
+  const merged = mergeConfig(
+    { models: { implement: "a/b" }, thinking: { implement: "high" } },
+    { gates: { track: { enabled: false } } },
+  );
+  assert.deepEqual(merged.thinking, { implement: "high" });
+});
+
 test("no NODD source file mentions zero.json", () => {
   const root = dirname(dirname(fileURLToPath(import.meta.url)));
   const walk = (dir: string, out: string[] = []): string[] => {

package/src/models/layout.test.ts

@@ -0,0 +1,122 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import {
+  fitRows,
+  padToWidth,
+  stripAnsi,
+  truncateToWidth,
+  usableRows,
+  visibleWidth,
+  windowRows,
+} from "./layout.ts";
+
+const ESC = "\u001b";
+
+// ---------------------------------------------------------------------------
+// Measuring what the terminal actually shows
+// ---------------------------------------------------------------------------
+test("stripAnsi removes CSI colour runs and leaves the printable text", () => {
+  assert.equal(stripAnsi(`${ESC}[31mrojo${ESC}[0m`), "rojo");
+  assert.equal(stripAnsi("sin escapes"), "sin escapes");
+});
+
+test("visibleWidth counts cells, not code units: escapes are free, wide glyphs cost two", () => {
+  assert.equal(visibleWidth(`${ESC}[31mrojo${ESC}[0m`), 4);
+  assert.equal(visibleWidth("漢字"), 4, "East-Asian wide glyphs take two cells each");
+  assert.equal(visibleWidth("e\u0301"), 1, "a combining accent takes no cell of its own");
+});
+
+// ---------------------------------------------------------------------------
+// Truncating by width, never by index
+// ---------------------------------------------------------------------------
+test("a line that fits is returned untouched", () => {
+  assert.equal(truncateToWidth("corto", 10), "corto");
+});
+
+test("truncation marks the cut and never overshoots the budget", () => {
+  const cut = truncateToWidth("abcdefghij", 5);
+  assert.equal(visibleWidth(cut), 5);
+  assert.ok(cut.endsWith("…"), `the cut must be marked: ${cut}`);
+});
+
+test("a wide glyph is never split in half by the budget", () => {
+  // Budget 4 = ellipsis (1) + 3 cells, and 漢 costs 2: only one glyph fits.
+  const cut = truncateToWidth("漢字漢字", 4);
+  assert.ok(visibleWidth(cut) <= 4, `overshot the budget: ${visibleWidth(cut)}`);
+  assert.ok(!cut.includes("\ufffd"), "no replacement character: a code point was split");
+});
+
+test("a cut inside a styled run appends a reset, so the colour cannot bleed", () => {
+  const cut = truncateToWidth(`${ESC}[31mabcdefghij`, 5);
+  assert.ok(cut.endsWith(`${ESC}[0m`), `a styled cut must close its own run: ${JSON.stringify(cut)}`);
+});
+
+test("a non-positive budget yields an empty line", () => {
+  assert.equal(truncateToWidth("abc", 0), "");
+});
+
+// ---------------------------------------------------------------------------
+// Padding to an exact cell count
+// ---------------------------------------------------------------------------
+test("padToWidth makes a line occupy exactly the width asked for", () => {
+  assert.equal(visibleWidth(padToWidth("ab", 6)), 6);
+  assert.equal(visibleWidth(padToWidth("abcdefghij", 6)), 6, "too long is truncated, not overflowed");
+  assert.equal(visibleWidth(padToWidth("漢字", 6)), 6, "wide glyphs are measured, not counted");
+  assert.equal(padToWidth("x", 0), "");
+});
+
+// ---------------------------------------------------------------------------
+// Windowing a long list around the cursor
+// ---------------------------------------------------------------------------
+test("a list that fits is drawn whole, with nothing hidden", () => {
+  assert.deepEqual(windowRows(5, 0, 10), { start: 0, end: 5, hiddenBefore: 0, hiddenAfter: 0 });
+});
+
+test("the window keeps the cursor on screen and reports what it hides", () => {
+  for (const cursor of [0, 3, 9, 19]) {
+    const win = windowRows(20, cursor, 5);
+    assert.ok(cursor >= win.start && cursor < win.end, `cursor ${cursor} fell outside ${win.start}..${win.end}`);
+    assert.equal(win.end - win.start, 5, "the window always fills its capacity");
+    assert.equal(win.hiddenBefore, win.start);
+    assert.equal(win.hiddenAfter, 20 - win.end);
+  }
+});
+
+test("the window clamps at both ends instead of scrolling past them", () => {
+  assert.deepEqual(windowRows(20, 0, 5), { start: 0, end: 5, hiddenBefore: 0, hiddenAfter: 15 });
+  assert.deepEqual(windowRows(20, 19, 5), { start: 15, end: 20, hiddenBefore: 15, hiddenAfter: 0 });
+});
+
+test("no capacity and no rows are handled, not crashed", () => {
+  assert.deepEqual(windowRows(20, 3, 0), { start: 0, end: 0, hiddenBefore: 0, hiddenAfter: 20 });
+  assert.deepEqual(windowRows(0, 0, 5), { start: 0, end: 0, hiddenBefore: 0, hiddenAfter: 0 });
+});
+
+// ---------------------------------------------------------------------------
+// Fitting the terminal's own height
+// ---------------------------------------------------------------------------
+test("usableRows leaves room for pi's chrome and never returns a useless height", () => {
+  assert.ok(usableRows(40) < 40, "pi's own chrome takes rows off the top");
+  assert.ok(usableRows(40) > 20, "a tall terminal gets most of its rows");
+  assert.ok(usableRows(4) >= 8, "a tiny terminal still gets a minimum block");
+  assert.ok(usableRows(undefined) > 0, "an unknown terminal height still yields a height");
+  assert.ok(usableRows(0) > 0);
+});
+
+test("fitRows keeps the first rows, because the frame top and title matter most", () => {
+  assert.deepEqual(fitRows(["a", "b", "c"], 2), ["a", "b"]);
+  assert.deepEqual(fitRows(["a", "b"], 5), ["a", "b"]);
+  assert.deepEqual(fitRows(["a"], 0), []);
+});
+
+// ---------------------------------------------------------------------------
+// The module boundary: pure, so node --test reaches it with no terminal.
+// ---------------------------------------------------------------------------
+test("the layout helpers import nothing at all", () => {
+  const source = readFileSync(new URL("./layout.ts", import.meta.url), "utf8")
+    .split("\n")
+    .filter((line) => !/^\s*(\/\/|\*|\/\*)/.test(line))
+    .join("\n");
+  assert.ok(!/^import /m.test(source), "the layout must stay dependency-free: no node:*, no pi, no TUI");
+});