@vecteur/cli 0.9.1 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vecteur/cli",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "type": "module",
   "bin": {
     "vecteur": "bin/vecteur.js"

package/src/input.js

@@ -80,6 +80,20 @@ export class ComposerInput extends EventEmitter {
         this.pasted = ""; this.pasting = false; this.pasteOverflow = false; continue;
       }
       if (this.pending.startsWith(START)) { this.pasting = true; this.pending = this.pending.slice(START.length); continue; }
+      // Terminal replies to the writer's own queries are never keys, early or late: a colour
+      // report (OSC 10/11) is recognised by its own form, any OSC while the writer awaits one.
+      // A bare Alt+] keeps its meaning.
+      const report = /^\x1b\](?:1(?:[01](?:;(?:r(?:g(?:b(?::[0-9a-f/]*)?)?)?)?)?)?)?/i.exec(this.pending)?.[0] ?? "";
+      if (this.pending.startsWith("\x1b]") && (this.expectReports || report.length > 2)) {
+        const end = /\x07|\x1b\\/.exec(this.pending);
+        if (!end && this.pending.length < 256 && (this.expectReports || report.length === this.pending.length)) {
+          this.escapeTimer = setTimeout(() => { this.pending = ""; }, 300); return;
+        }
+        const length = end ? end.index + end[0].length : 2;
+        const reply = this.pending.slice(0, length); this.pending = this.pending.slice(length);
+        if (end) this.emit("report", reply);
+        continue;
+      }
       if (this.pending.startsWith("\x1b")) {
         if (this.pending.startsWith("\x1b\x1b")) {
           // Escape followed by an arrow/Alt-Enter keeps that encoded key intact.
@@ -100,6 +114,7 @@ export class ComposerInput extends EventEmitter {
         const escape = /^\x1b\[[0-?]*[ -/]*[@-~]/.exec(this.pending)?.[0];
         if (escape) {
           this.pending = this.pending.slice(escape.length);
+          if (/^\x1b\[\d+;\d+R$/.test(escape)) { this.emit("report", escape); continue; }
           if (this.handleKey?.(escape)) continue;
           if (escape === "\x1b[D") this.cursor = this.boundary(-1);
           else if (escape === "\x1b[C") this.cursor = this.boundary(1);

package/src/session.js

@@ -13,6 +13,7 @@ import { humanCost, runSections } from "./format.js";
 import { CATALOGUE_ENVELOPE_SHA256, MODEL_CATALOGUE, PRODUCT_ROUTES } from "./contract.js";
 import { openBrowser } from "./browser.js";
 
+export const NEW_FOLDER = "New folder — send an ask or /link an existing Project";
 const AUTH_ERRORS = new Set(["pat_expired", "pat_invalid", "pat_revoked"]);
 const TRANSIENT = new Set(["request_failed", "request_timeout", "terminal_invalid"]);
 const MEDIA = { ".txt": "text/plain", ".md": "text/markdown", ".csv": "text/csv", ".json": "application/json",
@@ -45,6 +46,8 @@ export class Session extends EventEmitter {
       projectLabel: this.project?.name ?? (this.binding ? "Linked Project unavailable" : "New Project on first send"),
       status: activity + (canEdit ? "" : " · Read-only — Viewer") + (projection.terminal ? ` · ${projection.elapsed}` : ""), draft: this.draft, prompt: this.prompt, busy: this.busy,
       offline: this.offline, issue: this.issue, login: this.loginChallenge, release: this.release,
+      // First use: signed in and online, the folder resolved to no binding/Project/Run, nothing pending.
+      firstUse: !!this.account && !this.offline && !this.busy && !this.project && !this.run && this.status === NEW_FOLDER,
       attachments: this.attachments.map(item => ({ path: item.path, size: item.bytes.length })),
       lead: "Laplace", location: "Vecteur cloud", model: modelLabel,
       run: projection, available: { submit: !this.offline && !!this.account && canEdit && !this.busy && !this.run?.open,
@@ -252,7 +255,7 @@ export class Session extends EventEmitter {
       this.project = this.projects.find(project => project.id === binding.projectId) ?? null;
       if (!this.project) { this.status = "Linked Project unavailable — /project or /unlink"; this.change(); return; }
     }
-    this.status = this.project ? "Ready" : "New folder — send an ask or /link an existing Project";
+    this.status = this.project ? "Ready" : NEW_FOLDER;
     const pending = this.registry.state();
     if (pending.pendingRun || pending.pendingCreate) {
       this.followController?.abort(); this.generation++; this.run = null;

package/src/terminal.js

@@ -6,17 +6,36 @@ import { preferences } from "./preferences.js";
 import { openBrowser } from "./browser.js";
 import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
+import { stripVTControlCharacters } from "node:util";
+import stringWidth from "string-width";
 
-/** The only stdout writer. It never clears the screen/scrollback or enters alternate screen. */
+const measure = value => /^[\x20-\x7e]*$/.test(value) ? value.length : stringWidth(value);
+
+/**
+ * The only stdout writer. It never clears the screen/scrollback or enters alternate screen.
+ * Rich mode parks the cursor (hidden) at column 1 of the first live row: everything from there
+ * down is the live region, so one erase-below removes exactly it, even after the terminal has
+ * reflowed it on resize. A cursor-position report places that row; blank rows between the
+ * transcript and the bottom-anchored composer are cursor movement, never printed history.
+ */
 export class TerminalWriter {
-  constructor(stdout, plain) { this.stdout = stdout; this.plain = plain; this.height = 0; }
+  constructor(stdout, plain) {
+    this.stdout = stdout; this.plain = plain; this.drawn = false; this.frame = null;
+    this.row = null; this.awaiting = 0; this.since = 0;
+  }
   erase() {
-    if (!this.height) return "";
-    const move = `\x1b[${this.height}A\r`, bytes = move + "\x1b[2K\n".repeat(this.height) + move;
-    this.height = 0;
-    return bytes;
+    if (!this.drawn) return "";
+    this.drawn = false;
+    return "\r\x1b[J";
+  }
+  clearLive() { this.frame = null; const bytes = this.erase(); if (bytes) this.stdout.write(bytes); }
+  // Display rows the terminal used for appended text; rich lines are narrower than the window.
+  advance(text) {
+    const columns = Math.max(1, this.stdout.columns ?? 80);
+    const rows = text.split("\n").reduce((sum, line) => sum + Math.max(1, Math.ceil(measure(stripVTControlCharacters(line)) / columns)), 0);
+    if (this.awaiting) this.since += rows;
+    else if (this.row) this.row = Math.min(this.stdout.rows ?? 24, this.row + rows);
   }
-  clearLive() { const bytes = this.erase(); if (bytes) this.stdout.write(bytes); }
   progress(view) {
     const subject = view.run?.subject?.id;
     if (subject !== this.subject) { this.subject = subject; this.lastProgress = null; this.lastQuestion = null; }
@@ -30,17 +49,59 @@ export class TerminalWriter {
       if (question) this.append(safe(`Vecteur needs your answer — /answer\n${question.questions.map(row => row.question).join("\n")}`));
     }
   }
-  append(text) { this.stdout.write(`${this.erase()}${text.replace(/\n+$/, "")}\n`); }
-  draw(text) {
+  /** Scrollback text, then the given live frame in the same write: the composer never blinks out. */
+  append(text, frame = null) {
+    const body = text.replace(/\n+$/, "");
+    let bytes = `${this.erase()}${body}\n`;
+    if (!this.plain) this.advance(body);
+    if (frame) { this.frame = frame; bytes += this.render(); }
+    this.stdout.write(bytes);
+  }
+  draw(frame) {
     if (this.plain) return;
+    this.frame = typeof frame === "string" ? { top: [], bottom: frame.replace(/\n+$/, "").split("\n") } : frame;
     // One write per frame: erase and redraw land together, so the spinner never flickers.
-    const lines = text.replace(/\n+$/, "");
-    this.stdout.write(`${this.erase()}${lines}\n`); this.height = lines.split("\n").length;
+    const bytes = this.render();
+    if (bytes) this.stdout.write(bytes);
+  }
+  render() {
+    if (this.plain || !this.frame || this.awaiting) return "";
+    const rows = this.stdout.rows ?? 24;
+    const lines = [...this.frame.top, ...this.frame.bottom].slice(-Math.max(1, rows - 1));
+    const gap = this.row ? Math.max(0, rows - this.row + 1 - lines.length) : 0;
+    const at = Math.max(0, lines.length - this.frame.bottom.length);
+    const body = [...lines.slice(0, at), ...Array(gap).fill(""), ...lines.slice(at)];
+    const up = body.length - 1;
+    if (this.row) this.row = Math.max(1, Math.min(this.row, rows - body.length + 1));
+    const erase = this.erase(); this.drawn = true;
+    return `${erase}${body.join("\n")}${up ? `\x1b[${up}A` : ""}\r`;
+  }
+  /** Ask the terminal where the live region starts; frames wait for the answer (or 300 ms). */
+  locate(query = "") {
+    if (this.plain) return;
+    this.awaiting++; this.since = 0;
+    this.stdout.write(`${query}\x1b[6n`);
+    clearTimeout(this.locateTimer);
+    this.locateTimer = setTimeout(() => { this.awaiting = 0; this.row = null; this.onLocated?.(); }, 300);
+  }
+  located(row, column) {
+    if (!this.awaiting || --this.awaiting) return;
+    clearTimeout(this.locateTimer);
+    const rows = this.stdout.rows ?? 24;
+    let bytes = "";
+    // Another program left the cursor mid-line: start the live region on the next row.
+    if (column > 1 && !this.since) { bytes = "\r\n"; row++; }
+    this.row = Math.max(1, Math.min(rows, row + this.since));
+    if (bytes) this.stdout.write(bytes);
+    this.onLocated?.();
   }
   resized(plain) {
-    // Reflow can collapse old wrapped lines: their old height is no longer a safe erase bound.
-    this.height = 0; this.plain = plain; this.stdout.write("\n");
+    // Reflow moved the old frame but not the parked cursor: erase below it, then re-locate.
+    const bytes = this.drawn ? "\r\x1b[J" : "";
+    this.drawn = false; this.frame = null; this.row = null; this.plain = plain;
+    if (bytes) this.stdout.write(bytes);
   }
+  close() { clearTimeout(this.locateTimer); this.awaiting = 0; }
 }
 
 export async function startTerminal(options = {}, { stdin = process.stdin, stdout = process.stdout, env = process.env } = {}) {
@@ -51,6 +112,8 @@ export async function startTerminal(options = {}, { stdin = process.stdin, stdou
   }
   let rich = !options.plain && !prefs.plain && env.TERM !== "dumb";
   const color = !options.noColor && env.NO_COLOR === undefined;
+  // Colour roles start palette-relative; a terminal that reports its own colours gets exact blends.
+  let theme = color; const reported = {};
   const layout = await import("./tui/view.js");
   const isPlain = () => !rich || ((stdout.columns ?? 80) < 40 || (stdout.rows ?? 24) < 8);
   const writer = new TerminalWriter(stdout, isPlain());
@@ -67,6 +130,9 @@ export async function startTerminal(options = {}, { stdin = process.stdin, stdou
   let vendorOwnsTerminal = false, resizedDuringHandoff = false; const heldMessages = [];
   // Rich scrollback streams each finished step as one line; the answer block then skips them.
   const streamed = { run: null, events: 0, steps: 0 };
+  // The identity header is live until the first transcript block, then committed once.
+  let headerLive = true, cursorHidden = false;
+  const directory = () => session.cwd === homedir() || session.cwd.startsWith(homedir() + "/") ? "~" + session.cwd.slice(homedir().length) : session.cwd;
   const history = []; let historyIndex = 0, historyDraft = "", historyAccount;
   const syncInput = (value, cursor = value === input.text ? input.cursor : value.length) => { suppressed = true; input.set(value); input.cursor = cursor; suppressed = false; };
   const focusChanged = () => {
@@ -82,15 +148,41 @@ export async function startTerminal(options = {}, { stdin = process.stdin, stdou
     if (!input.text || /^[\d, ]+$/.test(input.text)) return prompt.options;
     return prompt.options.filter(item => item.label.toLowerCase().includes(input.text.toLowerCase()));
   };
-  const frameView = () => ({ ...session.view(), version, channel,
+  const frameView = () => ({ ...session.view(), version, channel, header: headerLive, directory: directory(),
     focus: localPicker ?? session.prompt, choices: choices(), selected,
     palette: palette(), paletteSelected, loginAction });
+  const live = () => layout.richLayout(frameView(), input.text, input.cursor,
+    { columns: stdout.columns ?? 80, rows: stdout.rows ?? 24, color: theme, tick: prefs.reducedMotion ? null : tick });
   const draw = () => {
     clearTimeout(frameTimer); frameTimer = null;
     if (vendorOwnsTerminal) return;
-    if (!session.closed && !writer.plain) writer.draw(layout.richFrame(frameView(), input.text, input.cursor,
-      { columns: stdout.columns ?? 80, rows: stdout.rows ?? 24, color, tick: prefs.reducedMotion ? null : tick }));
+    if (!session.closed && !writer.plain) writer.draw(live());
   };
+  // The real cursor stays hidden in rich mode (the composer draws its own caret) and always
+  // returns on exit, error, plain fallback and vendor handoff.
+  const showCursor = visible => {
+    if (env.TERM === "dumb" || visible !== cursorHidden) return;
+    cursorHidden = !visible; stdout.write(visible ? "\x1b[0m\x1b[?25h" : "\x1b[?25l");
+  };
+  const restoreCursor = () => showCursor(true);
+  const commitHeader = () => {
+    if (writer.plain || !headerLive) return;
+    headerLive = false; writer.append(layout.richHeader(frameView(), stdout.columns ?? 80, theme).join("\n"));
+  };
+  // Transcript blocks (asks, answers, steps, usage) commit the header above them; notices printed
+  // before the first ask stay above the live identity, which keeps owning the current facts.
+  const print = (text, transcript = true) => {
+    if (transcript) commitHeader();
+    writer.append(text, writer.plain || session.closed || vendorOwnsTerminal ? null : live());
+  };
+  writer.onLocated = () => {
+    input.expectReports = false;
+    if (theme && reported.fg && reported.bg && theme === color) {
+      theme = layout.paletteTheme(reported, ["truecolor", "24bit"].includes(env.COLORTERM));
+    }
+    draw();
+  };
+  const locate = (query = "") => { if (!writer.plain) { input.expectReports ||= !!query; writer.locate(query); } };
   const schedule = () => { if (!frameTimer && !vendorOwnsTerminal) frameTimer = setTimeout(() => { frameTimer = null; draw(); }, 40); };
   const printPlainPrompt = prompt => writer.append(safe(`${prompt.title}\n${prompt.options.map((row, i) => `${i + 1}. ${row.label}`).join("\n")}\nEnter a choice; Esc returns to your draft.`));
   const maybeUpdate = () => {
@@ -111,8 +203,8 @@ export async function startTerminal(options = {}, { stdin = process.stdin, stdou
         if (event?.kind !== "step_finished") continue;
         const [row] = taskLines([event]);
         if (!row) continue;
-        if (!streamed.steps++) writer.append("");
-        writer.append(layout.richMessage({ kind: "step", text: row.split("\n").map(part => part.trim().replace(/^[▸·]\s*/, "")).filter(Boolean).join(" · ") }, stdout.columns ?? 80, color));
+        if (!streamed.steps++) print("");
+        print(layout.richMessage({ kind: "step", text: row.split("\n").map(part => part.trim().replace(/^[▸·]\s*/, "")).filter(Boolean).join(" · ") }, stdout.columns ?? 80, theme));
       }
     }
     if (process.connected && process.send && env.VECTEUR_UPDATE_SESSION && session.release?.compatible
@@ -146,13 +238,13 @@ export async function startTerminal(options = {}, { stdin = process.stdin, stdou
   });
   session.on("preferences", value => {
     prefs = value; rich = !options.plain && !prefs.plain && env.TERM !== "dumb";
-    writer.resized(isPlain()); session.change(); draw();
+    writer.resized(isPlain()); showCursor(writer.plain); locate(); session.change(); draw();
   });
   session.on("message", message => {
     if (vendorOwnsTerminal) { heldMessages.push(message); return; }
-    writer.append(writer.plain ? safe(message.text) : layout.richMessage(message, stdout.columns ?? 80, color,
-      { stepsShown: message.runId && message.runId === streamed.run ? streamed.steps : 0 }));
-    plainDraft = ""; draw();
+    print(writer.plain ? safe(message.text) : layout.richMessage(message, stdout.columns ?? 80, theme,
+      { stepsShown: message.runId && message.runId === streamed.run ? streamed.steps : 0 }), ["user", "answer", "cost"].includes(message.kind));
+    plainDraft = "";
   });
   session.on("copy", answer => {
     if (vendorOwnsTerminal) return;
@@ -218,7 +310,7 @@ export async function startTerminal(options = {}, { stdin = process.stdin, stdou
     clearTimeout(frameTimer); frameTimer = null; clearInterval(clockTimer); clockTimer = null;
     stdin.off("data", onData); stdin.setRawMode(false); stdin.pause();
     process.off("SIGINT", onSignal);
-    writer.clearLive(); if (env.TERM !== "dumb") stdout.write("\x1b[?2004l");
+    writer.clearLive(); commitHeader(); showCursor(true); if (env.TERM !== "dumb") stdout.write("\x1b[?2004l");
     const { VENDORS, executingServer, runVendor, vendorArgv } = await import("./vendors.js");
     writer.append(`Opening your ${VENDORS[vendor]} terminal with Vecteur attached for this session only. Exit it to return.`);
     let note;
@@ -231,6 +323,8 @@ export async function startTerminal(options = {}, { stdin = process.stdin, stdou
       if (env.TERM !== "dumb") stdout.write("\x1b[?2004h");
       stdin.setRawMode(true); stdin.resume(); stdin.on("data", onData);
     }
+    // The vendor's output is history now; find where it left the cursor before drawing again.
+    writer.resized(isPlain()); showCursor(writer.plain); locate();
     if (resizedDuringHandoff) { resizedDuringHandoff = false; onResize(); }
     for (const message of heldMessages.splice(0)) session.emit("message", message);
     session.message(note); session.change();
@@ -295,7 +389,13 @@ export async function startTerminal(options = {}, { stdin = process.stdin, stdou
     return false;
   };
   input.on("details", () => { if (!session.prompt) void execute("/details"); });
-  input.on("redraw", () => { writer.clearLive(); draw(); });
+  input.on("redraw", () => { writer.clearLive(); locate(); draw(); });
+  input.on("report", report => {
+    const position = /^\x1b\[(\d+);(\d+)R$/.exec(report);
+    if (position) { writer.located(Number(position[1]), Number(position[2])); return; }
+    const value = /^\x1b\]1([01]);rgb:([0-9a-f]+)\/([0-9a-f]+)\/([0-9a-f]+)/i.exec(report);
+    if (value) reported[value[1] === "0" ? "fg" : "bg"] = value.slice(2).map(hex => Math.round(parseInt(hex, 16) / (16 ** hex.length - 1) * 255));
+  });
   input.on("exit", () => { try { session.close(); } catch (error) { session.report(error); } });
   const onData = chunk => {
     if (env.TERM === "dumb" && !input.pasting && (String(chunk).match(/[\r\n]/g)?.length ?? 0) > 1) {
@@ -307,8 +407,8 @@ export async function startTerminal(options = {}, { stdin = process.stdin, stdou
     // The vendor owns the TTY: not one byte; the new geometry is applied once on restore.
     if (vendorOwnsTerminal) { resizedDuringHandoff = true; return; }
     const plain = isPlain(), changed = plain !== writer.plain;
-    writer.resized(plain); lastPlainIdentity = "";
-    if (changed) writer.append(plain ? "Plain view — terminal is small; all actions remain available." : "Rich view restored.");
+    writer.resized(plain); lastPlainIdentity = ""; showCursor(plain); locate();
+    if (changed) print(plain ? "Plain view — terminal is small; all actions remain available." : "Rich view restored.", false);
     session.change(); draw();
   };
   const onSignal = () => { try { session.close(); } catch {} };
@@ -316,15 +416,17 @@ export async function startTerminal(options = {}, { stdin = process.stdin, stdou
   stdin.setRawMode(true); stdin.resume(); stdin.on("data", onData); stdout.on("resize", onResize);
   process.once("SIGTERM", onSignal); process.once("SIGHUP", onSignal); process.once("SIGINT", onSignal);
   if (env.TERM !== "dumb") stdout.write("\x1b[?2004h");
-  writer.append(writer.plain ? `Vecteur ${version}${channel === "preview" ? " · Preview" : ""} · ${safe(session.origin)}` : layout.welcome(version, session.origin, stdout.columns ?? 80, color, channel,
-    session.cwd.startsWith(homedir() + "/") ? "~" + session.cwd.slice(homedir().length) : session.cwd));
+  process.on("exit", restoreCursor);
+  if (writer.plain) writer.append(`Vecteur ${version}${channel === "preview" ? " · Preview" : ""} · ${safe(session.origin)}`);
+  else { showCursor(false); locate(color ? "\x1b]10;?\x1b\\\x1b]11;?\x1b\\" : ""); }
   draw();
   void session.initialize().then(() => { if (!input.text) syncInput(session.draft); draw(); }).catch(error => session.report(error));
   try { await done; }
   finally {
     clearTimeout(frameTimer); clearInterval(clockTimer); input.close(); stdin.off("data", onData); stdout.off("resize", onResize);
     process.off("SIGTERM", onSignal); process.off("SIGHUP", onSignal); process.off("SIGINT", onSignal);
-    writer.clearLive(); if (env.TERM !== "dumb") stdout.write("\x1b[?2004l");
+    writer.clearLive(); writer.close(); commitHeader(); showCursor(true); process.off("exit", restoreCursor);
+    if (env.TERM !== "dumb") stdout.write("\x1b[?2004l");
     stdin.setRawMode(false); stdin.pause();
     stdout.write(session.restart ? "Restarting Vecteur…\n" : session.run?.open ? "Detached. The cloud Run continues; run vecteur here to follow it.\n" : "Session closed.\n");
   }

package/src/tui/view.js

@@ -2,19 +2,101 @@ import stringWidth from "string-width";
 import wrapAnsi from "wrap-ansi";
 import { parseMarkdown } from "../markdown.js";
 import { terminalText } from "../format.js";
-const style = (value, code, color) => color ? `\x1b[${code}m${value}\x1b[0m` : value;
-// One accent (the web's sky cyan, xterm 81), one secondary grey; amber only for attention.
-const ACCENT = "38;5;81", DIM = "90", ATTENTION = "33";
+
+// Colour roles, each one SGR parameter list. A theme of `null` is NO_COLOR / --no-color: no
+// styling at all. Without a palette report every role stays relative to the user's own palette:
+// faint for secondary/quiet text and rules, no input fill (a rule-only composer).
+export const DEFAULT_THEME = Object.freeze({ accent: "38;5;81", attention: "33", secondary: "2", quiet: "2",
+  rule: "2", band: "", strong: "1", em: "3", link: "4" });
+const themeOf = color => color === true ? DEFAULT_THEME : color || null;
+const RESET = { 1: "22", 2: "22", 3: "23", 4: "24", 7: "27", 38: "39", 48: "49" };
+// Targeted resets, never SGR 0: a role inside the input band must not clear the band.
+const style = (value, code, theme) => {
+  if (!theme || !code || !value) return value;
+  const close = []; const parts = code.split(";");
+  for (let i = 0; i < parts.length; i++) {
+    const n = Number(parts[i]);
+    if (n === 38 || n === 48) { close.push(RESET[n]); i += parts[i + 1] === "5" ? 2 : 4; }
+    else close.push(RESET[n] ?? ((n >= 30 && n <= 37) || (n >= 90 && n <= 97) ? "39" : "0"));
+  }
+  return `\x1b[${code}m${value}\x1b[${[...new Set(close)].join(";")}m`;
+};
+const paint = (value, role, theme) => style(value, theme?.[role], theme);
+
+// Terminal palette → roles. The reference values are blends of the terminal's own foreground
+// toward its background; text roles are pulled back toward the foreground until they reach 4.5:1.
+const channel = v => { v /= 255; return v <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4; };
+const luminance = ([r, g, b]) => 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b);
+export const contrast = (a, b) => { const [x, y] = [luminance(a), luminance(b)].sort((p, q) => q - p); return (x + 0.05) / (y + 0.05); };
+const mix = (from, to, t) => from.map((v, i) => Math.round(v + (to[i] - v) * t));
+const cube = [0, 95, 135, 175, 215, 255];
+function xterm256([r, g, b]) {
+  const near = v => cube.reduce((best, c, i) => Math.abs(c - v) < Math.abs(cube[best] - v) ? i : best, 0);
+  const [i, j, k] = [near(r), near(g), near(b)], rgb = [cube[i], cube[j], cube[k]];
+  const level = Math.max(0, Math.min(23, Math.round(((r + g + b) / 3 - 8) / 10))), grey = 8 + level * 10;
+  const distance = c => (c[0] - r) ** 2 + (c[1] - g) ** 2 + (c[2] - b) ** 2;
+  return distance([grey, grey, grey]) < distance(rgb) ? 232 + level : 16 + 36 * i + 6 * j + k;
+}
+// The colour a 256-colour terminal actually shows for an index.
+const shown = index => index >= 232 ? Array(3).fill(8 + (index - 232) * 10)
+  : [Math.floor((index - 16) / 36), Math.floor((index - 16) / 6) % 6, (index - 16) % 6].map(i => cube[i]);
+export function paletteTheme({ fg, bg }, truecolor = false) {
+  // Every check runs on the colour the terminal will render, never on the pre-rounding value.
+  const render = rgb => truecolor ? rgb : shown(xterm256(rgb));
+  const code = (rgb, layer = 38) => truecolor ? `${layer};2;${rgb.join(";")}` : `${layer};5;${xterm256(rgb)}`;
+  const band = render(mix(fg, bg, 0.88));
+  // Pull toward the foreground until legible on the background and, for roles drawn inside the
+  // input band (placeholder, caret), on the band too.
+  const readable = (from, grounds) => {
+    for (let t = 0; t <= 1; t += 0.05) {
+      const value = render(mix(from, fg, t));
+      if (grounds.every(ground => contrast(value, ground) >= 4.5)) return value;
+    }
+    return render(fg);
+  };
+  const dark = luminance(bg) < 0.4;
+  return Object.freeze({ ...DEFAULT_THEME,
+    accent: code(readable(dark ? [105, 215, 239] : [0, 120, 150], [bg, band])),
+    attention: code(readable(dark ? [233, 173, 12] : [154, 103, 0], [bg])),
+    secondary: code(readable(mix(fg, bg, 0.25), [bg, band])), quiet: code(readable(mix(fg, bg, 0.42), [bg])),
+    rule: code(mix(fg, bg, 0.62)), band: code(band, 48) });
+}
+
 const SPINNER = ["·", "✢", "✳", "✶", "✻", "✽", "✻", "✶", "✳", "✢"];
+const PROSE = 88; // readable measure on wide terminals; tables and code may use the full width
+const NEW_PROJECT = "New Project on first send";
 const printableAscii = /^[\x20-\x7e]*$/;
 const measure = value => printableAscii.test(value) ? value.length : stringWidth(value);
+// Each wrapped row closes whatever style is still open and the next row reopens it: a role never
+// rides a line feed into a row that is later dropped or drawn by someone else (wrap-ansi only
+// re-closes the 16-colour codes, not 256/truecolor ones).
+const CLOSE = { 1: "22", 2: "22", 3: "23", 4: "24", 7: "27" };
+function seal(lines) {
+  let open = [];
+  return lines.map(line => {
+    const head = open.length ? `\x1b[${open.join(";")}m` : "";
+    for (const [, list] of line.matchAll(/\x1b\[([0-9;]*)m/g)) {
+      const parts = list.split(";");
+      for (let i = 0; i < parts.length; i++) {
+        const n = Number(parts[i] || 0);
+        if (n === 38 || n === 48) { const width = parts[i + 1] === "5" ? 3 : 5; open = open.filter(g => !g.startsWith(`${n};`)); open.push(parts.slice(i, i + width).join(";")); i += width - 1; }
+        else if (n === 0) open = [];
+        else if (n === 39 || n === 49) open = open.filter(g => !g.startsWith(n === 39 ? "38;" : "48;") && !(n === 39 ? /^(3[0-7]|9[0-7])$/ : /^(4[0-7]|10[0-7])$/).test(g));
+        else if (["22", "23", "24", "27"].includes(String(n))) open = open.filter(g => CLOSE[g] !== String(n));
+        else open.push(String(n));
+      }
+    }
+    const tail = open.length ? `\x1b[${[...new Set(open.map(g => CLOSE[g] ?? (g.startsWith("48") || /^(4[0-7]|10[0-7])$/.test(g) ? "49" : "39")))].join(";")}m` : "";
+    return head + line + tail;
+  });
+}
 const wrapped = new Map();
 const wrap = (value, width, wordWrap = true) => {
   width = Math.max(1, width);
   const key = value.length <= 512 ? `${width}:${wordWrap}:${value}` : null;
   if (key && wrapped.has(key)) return wrapped.get(key);
   const lines = !value.includes("\n") && measure(value) <= width ? [value]
-    : wrapAnsi(value, width, { hard: true, trim: false, wordWrap }).split("\n");
+    : seal(wrapAnsi(value, width, { hard: true, trim: false, wordWrap }).split("\n"));
   if (key) {
     if (wrapped.size === 128) wrapped.delete(wrapped.keys().next().value);
     wrapped.set(key, lines);
@@ -22,62 +104,68 @@ const wrap = (value, width, wordWrap = true) => {
   return lines;
 };
 // Prose wraps at word boundaries and drops the break's leading space; the composer keeps every space.
-const prose = (value, width) => wrapAnsi(value, Math.max(1, width), { hard: true, trim: true }).split("\n");
+const prose = (value, width) => seal(wrapAnsi(value, Math.max(1, width), { hard: true, trim: true }).split("\n"));
+// Key hints fold between their " · " segments, never inside one ("? shortcuts" stays whole).
+const fold = (text, width) => text.split("\n").flatMap(part => part.split(" · ").reduce((rows, segment) => {
+  if (rows.length && measure(rows.at(-1)) + 3 + measure(segment) <= width) rows[rows.length - 1] += " · " + segment;
+  else rows.push(segment);
+  return rows;
+}, [])).flatMap(row => wrap(row, width));
 const pad = (value, width) => value + " ".repeat(Math.max(0, width - measure(value)));
 
-function inline(tokens, color) {
+function inline(tokens, theme) {
   return tokens.map(token => {
     const href = token.href && /^https?:\/\//i.test(token.href) ? ` <${token.href}>` : "";
     const value = token.text + href;
-    return token.kind === "strong" ? style(value, "1", color)
-      : token.kind === "em" ? style(value, "3", color)
-        : token.kind === "code" ? style(value, ACCENT, color)
-          : token.kind === "link" ? style(value, "4", color) : value;
+    return token.kind === "strong" ? paint(value, "strong", theme)
+      : token.kind === "em" ? paint(value, "em", theme)
+        : token.kind === "code" ? paint(value, "accent", theme)
+          : token.kind === "link" ? paint(value, "link", theme) : value;
   }).join("");
 }
 
 const numeric = /^[-+−~≈<>≤≥±]?\s?\d[\d.,]*(?:\s?[^\s\d]\S*)?$/;
-function table(block, width, color) {
-  const grid = [block.header, ...block.rows].map(row => row.map(cell => inline(cell, false)));
+function table(block, width, theme) {
+  const grid = [block.header, ...block.rows].map(row => row.map(cell => inline(cell, null)));
   const columns = Math.max(...grid.map(row => row.length));
   const widths = Array.from({ length: columns }, (_, i) => Math.max(1, ...grid.map(row => measure(row[i] ?? ""))));
   if (widths.reduce((a, b) => a + b, 0) + 3 * (columns - 1) > width) {
     // Too wide for the terminal: one record per row, never a clipped column.
     const lines = [];
     block.rows.forEach((row, index) => {
-      lines.push(style(`Record ${index + 1}`, "1", color));
-      row.forEach((cell, column) => lines.push(...wrap(`${style(grid[0]?.[column] || `Column ${column + 1}`, DIM, color)}  ${inline(cell, color)}`, width)));
+      lines.push(paint(`Record ${index + 1}`, "strong", theme));
+      row.forEach((cell, column) => lines.push(...wrap(`${paint(grid[0]?.[column] || `Column ${column + 1}`, "secondary", theme)}  ${inline(cell, theme)}`, width)));
     });
     return lines;
   }
-  const right = widths.map((_, i) => block.rows.length > 0 && block.rows.every(row => numeric.test(inline(row[i] ?? [], false).trim() || "0")));
+  const right = widths.map((_, i) => block.rows.length > 0 && block.rows.every(row => numeric.test(inline(row[i] ?? [], null).trim() || "0")));
   const cell = (value, i) => right[i] ? " ".repeat(Math.max(0, widths[i] - measure(value))) + value : pad(value, widths[i]);
-  const bar = style(" │ ", DIM, color);
-  return [style(grid[0].map((value, i) => pad(value, widths[i])).join(" │ "), "1", color),
-    style(widths.map(w => "─".repeat(w)).join("─┼─"), DIM, color),
+  const bar = paint(" │ ", "rule", theme);
+  return [paint(grid[0].map((value, i) => pad(value, widths[i])).join(" │ "), "strong", theme),
+    paint(widths.map(w => "─".repeat(w)).join("─┼─"), "rule", theme),
     ...grid.slice(1).map(row => widths.map((_, i) => cell(row[i] ?? "", i)).join(bar))];
 }
 
 /** Shared web grammar; only trusted renderer styling can emit terminal controls. */
 export function markdownView(source, width, color = true) {
-  const lines = [];
+  const theme = themeOf(color), lines = [], measureWidth = Math.min(width, PROSE);
   for (const block of parseMarkdown(terminalText(source))) {
-    if (block.kind === "table") lines.push(...table(block, width, color));
+    if (block.kind === "table") lines.push(...table(block, width, theme));
     else if (block.kind === "codeblock") {
-      if (block.language) lines.push(style(block.language, DIM, color));
-      lines.push(...wrap(block.text, width - 2, false).map(line => style("│ ", DIM, color) + line));
+      if (block.language) lines.push(paint(block.language, "quiet", theme));
+      lines.push(...wrap(block.text, width - 2, false).map(line => paint("│ ", "rule", theme) + line));
     } else if (block.kind === "hr") {
-      lines.push(style("─".repeat(Math.min(width, 48)), DIM, color));
+      lines.push(paint("─".repeat(Math.min(width, 48)), "rule", theme));
     } else if (block.kind === "list") {
       block.items.forEach((item, index) => {
         const prefix = block.ordered ? `${index + 1}. ` : "• ";
-        prose(inline(item, color), width - prefix.length).forEach((line, i) => lines.push((i ? " ".repeat(prefix.length) : style(prefix, DIM, color)) + line));
+        prose(inline(item, theme), measureWidth - prefix.length).forEach((line, i) => lines.push((i ? " ".repeat(prefix.length) : paint(prefix, "quiet", theme)) + line));
       });
     } else {
-      let value = inline(block.inline, color);
-      if (block.kind === "heading") value = style(value, block.level <= 2 ? `1;${ACCENT}` : "1", color);
-      if (block.kind === "quote") lines.push(...prose(value, width - 2).map(line => style("│ ", DIM, color) + line));
-      else lines.push(...prose(value, width));
+      let value = inline(block.inline, theme);
+      if (block.kind === "heading") value = paint(value, "strong", theme);
+      if (block.kind === "quote") lines.push(...prose(value, measureWidth - 2).map(line => paint("│ ", "rule", theme) + line));
+      else lines.push(...prose(value, measureWidth));
     }
     lines.push("");
   }
@@ -88,7 +176,7 @@ export function markdownView(source, width, color = true) {
 // One terminal owns this cache. Cursor movement never rewraps unrelated paragraphs.
 let composerText;
 const composerLayouts = new Map();
-function composerViewport(composer, cursor, width, height) {
+function composerViewport(composer, cursor, width, height, theme) {
   if (composerText !== composer) { composerLayouts.clear(); composerText = composer; }
   let composerLayout = composerLayouts.get(width);
   if (!composerLayout) {
@@ -105,7 +193,9 @@ function composerViewport(composer, cursor, width, height) {
   const paragraph = paragraphs.findLast(row => row.offset <= cursor) ?? paragraphs[0];
   const local = cursor - paragraph.offset;
   const before = terminalText(paragraph.text.slice(0, local));
-  const active = wrap(before + "▌" + terminalText(paragraph.text.slice(local)), width, false);
+  // The caret is the one accent mark inside the input: wrapped on its plain glyph, painted after.
+  const active = wrap(before + "▌" + terminalText(paragraph.text.slice(local)), width, false)
+    .map(line => line.replace("▌", paint("▌", "accent", theme)));
   const cursorRow = paragraph.row + wrap(before + "▌", width, false).length - 1;
   const start = Math.max(0, cursorRow - height + 1);
   const next = paragraphs[paragraphs.indexOf(paragraph) + 1]?.row ?? lines.length;
@@ -115,27 +205,14 @@ function composerViewport(composer, cursor, width, height) {
     scrolling: lines.length > height };
 }
 
-/** One rounded box, the same frame as the prompt: a label may sit in the top or bottom border. */
-function box(rows, width, color, { top = "", bottom = "" } = {}) {
-  const inner = Math.max(1, width - 4);
-  const edge = (left, label, right) => {
-    const text = label ? `─ ${trimEnd(label, inner - 2)} ` : "";
-    return style(left + text + "─".repeat(Math.max(0, width - 2 - measure(text))) + right, DIM, color);
+/** The composer: a filled input band between two rules; a label may sit in either rule. */
+function composerBand(rows, width, theme, { top = "", bottom = "" } = {}) {
+  const rule = label => {
+    const text = label ? `── ${trimEnd(label, width - 4)} ` : "";
+    return paint(text + "─".repeat(Math.max(0, width - measure(text))), "rule", theme);
   };
-  return [edge("╭", top, "╮"), ...rows.map(row => `${style("│", DIM, color)} ${row}${" ".repeat(Math.max(0, inner - measure(row)))} ${style("│", DIM, color)}`),
-    edge("╰", bottom, "╯")];
-}
-
-/** The once-printed welcome: one calm box, a single accent glyph, no ASCII logo. */
-export function welcome(version, origin, columns = 80, color = true, channel, folder) {
-  const width = Math.max(20, columns - 1), inner = width - 4;
-  const label = `${version}${channel === "preview" ? " · Preview" : ""}`;
-  const where = [folder, origin === "https://vecteur.space" ? "" : origin].filter(Boolean).map(terminalText).join(" · ");
-  const head = `${style("▼", ACCENT, color)} ${style("Vecteur", "1", color)} ${style(label, DIM, color)}`;
-  const lines = measure(`▼ Vecteur ${label} · Laplace · Vecteur cloud`) <= inner
-    ? [`${head} ${style("· Laplace · Vecteur cloud", DIM, color)}`] : [head];
-  if (where) lines.push(style(trimEnd(`  ${where}`, inner), DIM, color));
-  return box(lines, width, color).join("\n") + "\n";
+  const band = theme?.band;
+  return [rule(top), ...rows.map(row => band ? style(pad(row, width), band, theme) : row), rule(bottom)];
 }
 
 // Display-cell truncation with an ellipsis; never more work than the visible width needs.
@@ -155,8 +232,46 @@ function trimStart(value, max) {
   return "…" + chars.join("");
 }
 
-/** Bottom-anchored live area: activity, focus, the prompt box, then one or two footer lines. */
-export function richFrame(view, composer, cursor, { columns = 80, rows = 24, color = true, tick = null } = {}) {
+const execution = view => view.location && view.location !== "Vecteur cloud" ? view.location : "Cloud";
+const routeOf = view => `${view.lead ? `${view.lead} · ` : ""}${view.model} · ${execution(view)}`;
+const customOrigin = view => view.origin && view.origin !== "https://vecteur.space" ? view.origin : "";
+
+/**
+ * Identity: `▼ Vecteur <version>` and the folder, the route group on the right (beneath when
+ * narrow). Live while the transcript is empty, then committed once to scrollback.
+ */
+export function richHeader(view, columns = 80, color = true) {
+  const theme = themeOf(color), width = Math.max(20, columns - 1);
+  const label = `${view.version ?? ""}${view.channel === "preview" ? " · Preview" : ""}`;
+  const brand = `${paint("▼", "accent", theme)} ${paint("Vecteur", "strong", theme)} ${paint(label, "quiet", theme)}`;
+  const brandWidth = measure(`▼ Vecteur ${label}`);
+  // Only a signed-in, online session earns the filled dot; it claims nothing about a server.
+  const live = !!view.account && !view.offline;
+  const route = trimEnd(routeOf(view), width - 4);
+  const routeText = `${paint(live ? "●" : "○", live ? "accent" : "quiet", theme)} ${paint(route, "secondary", theme)}`;
+  const routeWidth = measure(route) + 2;
+  const lines = ["", brandWidth + 4 + routeWidth <= width
+    ? brand + " ".repeat(width - brandWidth - routeWidth) + routeText : brand];
+  // A non-production origin is never hidden for visual simplicity.
+  const origin = customOrigin(view), directory = view.directory ? terminalText(view.directory) : "";
+  if (directory && origin && measure(directory) + 3 + measure(origin) <= width - 2) {
+    lines.push(`  ${paint(directory, "quiet", theme)}${paint(" · ", "quiet", theme)}${paint(terminalText(origin), "accent", theme)}`);
+  } else {
+    if (directory) lines.push("  " + paint(trimStart(directory, width - 2), "quiet", theme));
+    if (origin) lines.push("  " + paint(trimEnd(origin, width - 2), "accent", theme));
+  }
+  if (lines[1] === brand) lines.push("  " + routeText);
+  return lines;
+}
+
+// First-use suggestions are plain text, never a menu; existing commands stay authoritative.
+const ONBOARDING = ["Review a mission brief and find the missing inputs",
+  "Compare orbit options for an Earth-observation mission", "Turn requirements into an analysis plan"];
+
+/** The live region: `top` (identity, first-use note) above a flexible gap, `bottom` anchored. */
+export function richLayout(view, composer, cursor, options = {}) {
+  const { columns = 80, rows = 24, color = true, tick = null } = options;
+  const theme = themeOf(color);
   const width = Math.max(20, columns - 1), budget = Math.max(1, rows - 3);
   const active = !!view.run?.subject && !view.run.terminal;
   const readOnly = view.project?.role === "VIEWER", signedOut = view.offline || !view.account;
@@ -164,6 +279,7 @@ export function richFrame(view, composer, cursor, { columns = 80, rows = 24, col
   const runHint = readOnly ? "Read-only · /help · Ctrl+D detach"
     : signedOut ? `${view.offline ? "/resume" : "/login"} · /help · Ctrl+D detach`
       : `${view.run?.question ? "/answer" : "/steer · /answer-now"} · /help${width < 60 ? "\n" : " · "}Esc twice cancel · Ctrl+D detach`;
+  const idleHint = `${readOnly ? "Read-only · /project" : signedOut ? "Enter sign in" : view.busy ? "Please wait" : "Enter send"} · / commands · ? shortcuts`;
   if (rows < 12) {
     const focus = view.focus ?? view.prompt;
     const choices = view.choices ?? focus?.options ?? view.palette ?? [];
@@ -174,17 +290,18 @@ export function richFrame(view, composer, cursor, { columns = 80, rows = 24, col
     const status = wrap(terminalText(content), width).slice(0, 1);
     if (choice) status.push(wrap(terminalText(`› ${selected + 1}/${choices.length} ${choice.label ?? '/' + choice.name}`), width)[0]);
     else if (view.login) status.push(['› Open browser', '› Copy link', '› Work offline'][view.loginAction ?? 0]);
-    const draft = composerViewport(composer, cursor, width - 2, 1).lines[0];
+    const draft = composerViewport(composer, cursor, width - 2, 1, theme).lines[0];
     const hint = focus || choices.length ? '↑↓ Enter choose · Esc back' : view.login ? 'Tab actions · Enter open · Esc offline'
-      : active ? runHint : '? keys · /help · Ctrl+D exit';
-    return [...status, `${style("›", ACCENT, color)} ${draft}`, ...wrap(style(hint, DIM, color), width).slice(0, 2)].slice(0, budget).join("\n");
+      : active ? runHint : idleHint;
+    return { top: [], bottom: [...status, `${paint("›", "accent", theme)} ${draft}`,
+      ...fold(hint, width).slice(0, 2).map(row => paint(row, "secondary", theme))].slice(0, budget) };
   }
-  if (rows < 8) return wrap(`${view.status} · Ctrl+D exit`, width).slice(0, budget).join("\n");
-  const project = view.projectLabel ?? view.project?.name ?? "New Project on first send";
   // The steady footer names the Workspace, never a personal address; /status shows the account.
   const workspaces = view.account?.workspaces ?? [];
   const account = view.account ? (workspaces.find(row => row.id === view.project?.workspace_id) ?? workspaces[0])?.name ?? "Signed in"
     : view.offline ? "Offline" : "Not signed in";
+  const projectLabel = view.projectLabel ?? view.project?.name ?? NEW_PROJECT;
+  const identity = `${account} · ${projectLabel === NEW_PROJECT ? "New project" : projectLabel}`;
   const compact = width < 60 || rows < 18;
   const prompt = view.focus ?? view.prompt;
   const compactFocus = rows < 24 && (view.focus || view.prompt || view.login || view.palette?.length || view.issue);
@@ -194,44 +311,39 @@ export function richFrame(view, composer, cursor, { columns = 80, rows = 24, col
   const hint = prompt ? prompt.multiple ? "Space toggle · ↑↓ move · Enter confirm · Esc back" : "↑↓ choose · Enter confirm · Esc back · Ctrl+D exit"
     : view.login ? "Tab actions · Enter on empty activates · Esc offline"
       : view.palette?.length ? "↑↓ choose · Tab complete · Enter open · Esc close"
-        : active ? runHint
-          : `${readOnly ? "Read-only · /project" : signedOut ? "Enter sign in" : view.busy ? "Please wait" : "Enter send"}`
-            + (width < 60 ? " · /help · Ctrl+D exit" : " · Alt+Enter newline · / commands · ? keys · /help · Ctrl+D exit");
-  const execution = view.location && view.location !== "Vecteur cloud" ? view.location : "Cloud";
-  const context = `${view.lead ? `${view.lead} · ` : ""}${view.model} · ${execution}`;
-  const footer = wrap(style(hint, DIM, color), width - 1).slice(0, 2).map(line => " " + line);
-  const identity = trimEnd(`${project === "New Project on first send" ? "New Project" : project} · ${account}`, width);
-  const where = trimStart(view.folder ?? ".", Math.max(6, width - measure(identity) - measure(context) - 7));
-  const left = where === "." ? identity : `${identity} · ${where}`;
-  if (!compact && measure(left) + measure(context) + 4 <= width) {
-    footer.push(" " + style(left + " ".repeat(width - 2 - measure(left) - measure(context)) + context, DIM, color));
+        : active ? runHint : idleHint;
+  // While the identity header is live it owns the route and origin; afterwards the footer does.
+  const context = view.header ? identity : compact ? routeOf(view) : `${identity} · ${routeOf(view)}`;
+  const footer = [];
+  if (!compact && !hint.includes("\n") && measure(context) + 3 + measure(hint) <= width) {
+    footer.push(paint(context, "secondary", theme) + " ".repeat(width - measure(context) - measure(hint)) + paint(hint, "quiet", theme));
   } else {
-    footer.push(" " + style(trimEnd(context, width - 1), DIM, color));
-    if (!compact && !compactFocus) footer.push(" " + style(trimEnd(left, width - 1), DIM, color));
+    footer.push(...fold(hint, width).slice(0, 2).map(row => paint(row, "quiet", theme)));
+    footer.push(paint(trimEnd(context, width), "secondary", theme));
   }
-  if (view.origin && view.origin !== "https://vecteur.space") footer.push(" " + style(trimEnd(view.origin, width - 1), ACCENT, color));
+  if (!view.header && customOrigin(view)) footer.push(paint(trimEnd(customOrigin(view), width), "accent", theme));
 
   // A breathing line between the scrollback and the live area when the window has room for it.
   const lines = rows >= 18 && !compactFocus ? [""] : [];
   const room = () => budget - footer.length - 3 - lines.length;
-  const line = (value, code, limit = 2) => {
+  const line = (value, role, limit = 2) => {
     const text = terminalText(value);
-    lines.push(...wrap(code ? style(text, code, color) : text, width).slice(0, Math.max(0, Math.min(limit, room()))));
+    lines.push(...wrap(text, width).slice(0, Math.max(0, Math.min(limit, room()))).map(row => paint(row, role, theme)));
   };
   // Activity: the one animated glyph, the current step and the server-anchored clock.
   if (active && !compactFocus) {
     const clock = view.run.elapsed ?? "Elapsed unavailable";
-    const doing = compactRun ? view.status : (view.run.progress || "Working").replace(/^Starting: (.+)$/, "$1") + "…";
-    const head = `${style(glyph, ACCENT, color)} ${terminalText(doing)}`, tail = style(terminalText(clock), DIM, color);
-    if (measure(`${glyph} ${terminalText(doing)} · ${terminalText(clock)}`) <= width) lines.push(`${head} ${style("·", DIM, color)} ${tail}`);
+    const doing = compactRun ? view.status : (view.run.progress || "Working").replace(/^Starting: (.+)$/, "$1").replace(/[.…]+$/, "") + "…";
+    const head = `${paint(glyph, "accent", theme)} ${terminalText(doing)}`, tail = paint(terminalText(clock), "quiet", theme);
+    if (measure(`${glyph} ${terminalText(doing)} · ${terminalText(clock)}`) <= width) lines.push(`${head} ${paint("·", "quiet", theme)} ${tail}`);
     else if (compactRun) lines.push(wrap(head, width)[0], `  ${tail}`);
-    else lines.push(wrap(`${style(glyph, ACCENT, color)} ${tail} · ${terminalText(doing)}`, width)[0]);
-    if (!compactRun && view.status && view.status !== "Running") line(view.status, DIM, 1);
+    else lines.push(wrap(`${paint(glyph, "accent", theme)} ${tail} · ${terminalText(doing)}`, width)[0]);
+    if (!compactRun && view.status && view.status !== "Running") line(`  ${view.status}`, "secondary", 1);
   }
   if (!compactFocus && !compactRun && view.run?.question) line(readOnly ? "Waiting for an editor to answer"
-    : signedOut ? "Question pending — reconnect to answer" : "Your answer is needed · /answer", `1;${ATTENTION}`, 1);
+    : signedOut ? "Question pending — reconnect to answer" : "Your answer is needed · /answer", "attention", 1);
   if (prompt) {
-    line(prompt.title, "1", compactFocus ? 1 : 3);
+    line(prompt.title, "strong", compactFocus ? 1 : 3);
     if (!prompt.typed) {
       const choices = view.choices ?? prompt.options, selected = Math.min(view.selected ?? 0, Math.max(0, choices.length - 1));
       const more = choices.length > 1 && !compactFocus ? 1 : 0;
@@ -240,14 +352,14 @@ export function richFrame(view, composer, cursor, { columns = 80, rows = 24, col
       choices.slice(offset, offset + count).forEach((item, i) => {
         const index = prompt.options.indexOf(item) + 1, current = i + offset === selected;
         const checked = prompt.multiple ? `${composer.split(/[, ]+/).includes(String(index)) ? "[x]" : "[ ]"} ` : "";
-        lines.push(wrap(`${current ? style("›", ACCENT, color) : " "} ${index}. ${checked}${current ? style(terminalText(item.label), ACCENT, color) : terminalText(item.label)}`, width)[0]);
+        lines.push(wrap(`${current ? paint("›", "accent", theme) : " "} ${index}. ${checked}${current ? paint(terminalText(item.label), "accent", theme) : terminalText(item.label)}`, width)[0]);
       });
-      if (!choices.length) line("No matching choices; clear the filter", ATTENTION, 1);
-      if (choices.length > count && more) line(`${selected + 1}/${choices.length} · ↑↓ more choices`, DIM, 1);
+      if (!choices.length) line("No matching choices; clear the filter", "attention", 1);
+      if (choices.length > count && more) line(`${selected + 1}/${choices.length} · ↑↓ more choices`, "quiet", 1);
     }
   } else if (view.login) {
-    line(`Approve code ${view.login.user_code} in your browser`, "1", 1);
-    if (!compactFocus) line(view.login.verification_uri_complete, ACCENT, 2);
+    line(`Approve code ${view.login.user_code} in your browser`, "strong", 1);
+    if (!compactFocus) line(view.login.verification_uri_complete, "accent", 2);
     const actions = ["Open browser", "Copy link", "Work offline"];
     line(compactFocus ? `› ${actions[view.loginAction ?? 0]} (${(view.loginAction ?? 0) + 1}/3)`
       : actions.map((text, i) => `${i === view.loginAction ? "› " : ""}${text}`).join(" · "), undefined, compactFocus ? 1 : 2);
@@ -258,51 +370,84 @@ export function richFrame(view, composer, cursor, { columns = 80, rows = 24, col
     const name = Math.min(16, Math.max(...view.palette.map(row => row.name.length + 1)));
     view.palette.slice(offset, offset + count).forEach((row, i) => {
       const current = i + offset === selected, label = pad(`/${row.name}`, name);
-      lines.push(wrap(`${current ? style("›", ACCENT, color) : " "} ${current ? style(label, ACCENT, color) : label}  ${style(terminalText(row.disabled || row.description), DIM, color)}`, width)[0]);
+      lines.push(wrap(`${current ? paint("›", "accent", theme) : " "} ${current ? paint(label, "accent", theme) : label}  ${paint(terminalText(row.disabled || row.description), "secondary", theme)}`, width)[0]);
     });
   }
   const compactAttachments = rows < 24 && view.attachments?.length;
-  if (view.attachments?.length && !compactAttachments) line(`${view.attachments.length} file(s) selected · uploaded only on send`, DIM, 1);
-  if (view.issue && !prompt) line(view.issue.text + (view.issue.count > 1 ? ` (${view.issue.count} attempts)` : ""), ATTENTION, Math.max(1, Math.min(3, room())));
-  if (!active && !view.issue && !prompt && !view.login && !view.palette?.length) line(view.status, DIM, 1);
+  if (view.attachments?.length && !compactAttachments) line(`${view.attachments.length} file(s) selected · uploaded only on send`, "secondary", 1);
+  if (view.issue && !prompt) line(view.issue.text + (view.issue.count > 1 ? ` (${view.issue.count} attempts)` : ""), "attention", Math.max(1, Math.min(3, room())));
+  // First use: signed in, idle, an unbound folder, an empty transcript and an empty draft.
+  const firstUse = view.header && view.firstUse && !active && !composer && !prompt
+    && !view.login && !view.issue && !view.palette?.length && !view.attachments?.length;
+  const idle = !active && !view.issue && !prompt && !view.login && !view.palette?.length;
+  // "Ready" is what the idle hint already says; every other state keeps its line.
+  if (idle && !firstUse && view.status !== "Ready") line(view.status, "secondary", 1);
   const maxDraft = Math.max(1, Math.min(6, budget - lines.length - footer.length - 2));
-  const draft = composerViewport(composer, cursor, width - 6, maxDraft);
+  const draft = composerViewport(composer, cursor, width - 4, maxDraft, theme);
   const selection = compactAttachments ? `${view.attachments.length} file(s) · upload on send` : "";
   const placeholder = prompt ? (prompt.typed ? "Type your answer…" : "Filter or type a choice number…")
     : readOnly ? "Read-only Project — draft here…" : view.offline ? "Draft offline…"
       : !view.account ? "Sign in to send — draft here…"
         : active ? "Draft your next question…" : "Ask Laplace…";
-  lines.push(...box(draft.lines.map((value, index) => `${index ? "  " : style("›", ACCENT, color) + " "}${composer ? value : style("▌" + placeholder, DIM, color)}`),
-    width, color, { top: selection, bottom: draft.scrolling ? draft.position : "" }));
+  lines.push(...composerBand(draft.lines.map((value, index) => ` ${index ? " " : paint("›", "accent", theme)} ${composer ? value
+    : paint("▌", "accent", theme) + paint(placeholder, "secondary", theme)}`), width, theme,
+  { top: selection, bottom: draft.scrolling ? draft.position : "" }));
   lines.push(...footer);
-  return lines.slice(-budget).join("\n");
+  const bottom = lines.slice(-budget);
+
+  // Above the gap: identity while the transcript is empty, then the first-use note if it fits.
+  const space = rows - 1 - bottom.length;
+  const top = [];
+  if (view.header) {
+    const header = richHeader(view, columns, theme);
+    // No room for the identity: the footer owns the route and origin, as after the commit.
+    if (header.length > space) return richLayout({ ...view, header: false }, composer, cursor, options);
+    top.push(...header);
+  }
+  if (firstUse) {
+    const note = "New folder · A project will be created on your first message. /link existing";
+    const intro = [paint("What are we working on?", "strong", theme), paint("Ask Laplace about your mission, or start from a file.", "secondary", theme)];
+    const suggestions = ONBOARDING.map(text => `${paint("›", "accent", theme)} ${paint(text, "secondary", theme)}`);
+    const quiet = wrap(note, width).map(row => paint(row, "quiet", theme));
+    const body = [[...intro, "", ...suggestions, "", ...quiet], [...intro, "", ...quiet], quiet]
+      .map(rows => rows.map(row => measure(row) > width ? wrap(row, width)[0] : row))
+      .find(rows => top.length + 1 + rows.length + 1 <= space);
+    if (body) top.push("", ...body);
+  }
+  return { top, bottom };
+}
+
+/** Bottom-anchored live area as one string: identity, gap, activity, focus, composer, footer. */
+export function richFrame(view, composer, cursor, options = {}) {
+  const { top, bottom } = richLayout(view, composer, cursor, options);
+  return [...top, ...bottom].join("\n");
 }
 
 const indent = (text, first, rest = "  ") => text.split("\n").map((line, i) => (i ? (line ? rest : "") : first) + line).join("\n");
 
 /** One scrollback block per message: the ask, the answer with its record, or a quiet notice. */
 export function richMessage(message, columns, color, { stepsShown = false } = {}) {
-  const width = Math.max(20, columns - 1);
+  const theme = themeOf(color), width = Math.max(20, columns - 1);
   if (message.kind === "user") {
-    return "\n" + indent(wrap(terminalText(message.text), width - 2).join("\n"), style("›", ACCENT, color) + " ") + "\n";
+    return "\n" + indent(wrap(terminalText(message.text), width - 2).join("\n"), paint("›", "accent", theme) + " ") + "\n";
   }
-  if (message.kind === "step") return style(trimEnd(`  ⎿ ${message.text}`, width), DIM, color);
+  if (message.kind === "step") return paint(trimEnd(`  ⎿ ${message.text}`, width), "secondary", theme);
   if (message.kind === "cost") {
     const display = message.value?.display ?? {};
     const parts = [["Used", display.used], ["Limit", display.limit], ["Remaining", display.remaining]].filter(([, v]) => v !== null && v !== undefined);
-    return style(trimEnd(`  Usage this UTC month · ${parts.length ? parts.map(([k, v]) => `${k} ${v}`).join(" · ") : "no exact amount available"} · /usage`, width), DIM, color);
+    return paint(trimEnd(`  Usage this UTC month · ${parts.length ? parts.map(([k, v]) => `${k} ${v}`).join(" · ") : "no exact amount available"} · /usage`, width), "quiet", theme);
   }
   if (message.kind !== "answer") return wrap(terminalText(message.text), width - 2).map(line => "  " + line).join("\n");
   const run = message.sections;
-  if (!run) return "\n" + indent(markdownView(message.text, width - 2, color), style("●", ACCENT, color) + " ") + "\n";
+  if (!run) return "\n" + indent(markdownView(message.text, width - 2, theme), paint("●", "accent", theme) + " ") + "\n";
   const out = [];
-  out.push(run.answer !== undefined ? indent(markdownView(run.answer, width - 2, color), style("●", ACCENT, color) + " ")
-    : style("●", ATTENTION, color) + " No answer was published for this Run.");
-  const section = (title, rows) => { if (rows.length) out.push("", "  " + style(title, DIM, color), ...rows); };
+  out.push(run.answer !== undefined ? indent(markdownView(run.answer, width - 2, theme), paint("●", "accent", theme) + " ")
+    : paint("●", "attention", theme) + " No answer was published for this Run.");
+  const section = (title, rows) => { if (rows.length) out.push("", "  " + paint(title, "strong", theme), ...rows); };
   const one = text => text.split("\n").map(part => part.trim()).filter(Boolean).join(" · ");
-  section("Steps", run.tasks.slice(stepsShown).map(task => style(trimEnd(`  ⎿ ${one(task.replace(/^\s*[▸·]\s*/, ""))}`, width), DIM, color)));
+  section("Steps", run.tasks.slice(stepsShown).map(task => paint(trimEnd(`  ⎿ ${one(task.replace(/^\s*[▸·]\s*/, ""))}`, width), "secondary", theme)));
   // Evidence rows are never truncated: quantity, unit and origin wrap with a hanging indent.
-  const full = (row, code = DIM) => prose(terminalText(row.trim()), width - 4).map((part, i) => (i ? "    " : "  ") + style(part, code, color));
+  const full = (row, role = "secondary") => prose(terminalText(row.trim()), width - 4).map((part, i) => (i ? "    " : "  ") + paint(part, role, theme));
   section("Inputs and origins", run.origins.flatMap(row => full(row)));
   section("Assumptions", run.assumptions.flatMap(row => full(row)));
   section("Transfer tables", run.tables.flatMap(rows => rows.flatMap(row => full(row))));
@@ -311,9 +456,9 @@ export function richMessage(message, columns, color, { stepsShown = false } = {}
   const digest = row => /^[0-9a-f]{32,}\./.test(row.artifact.filename);
   const shown = [...numbered.filter(row => !digest(row)), ...numbered.filter(digest)].slice(0, 3);
   const more = run.artifacts.length - shown.length;
-  section("Files", shown.flatMap(({ artifact, number }) => prose(`${terminalText(artifact.filename)} ${style(`· ${artifact.kind} · /download ${number}`, DIM, color)}`, width - 4)
-    .map((part, i) => `  ${i ? " " : style("↓", ACCENT, color)} ${part}`))
-    .concat(more > 0 ? [style(`  … ${more} more · /files`, DIM, color)] : []));
-  out.push("", ...full(run.tail.map(terminalText).join(" · "), run.state === "ok" ? DIM : ATTENTION));
+  section("Files", shown.flatMap(({ artifact, number }) => prose(`${terminalText(artifact.filename)} ${paint(`· ${artifact.kind} · /download ${number}`, "quiet", theme)}`, width - 4)
+    .map((part, i) => `  ${i ? " " : paint("↓", "accent", theme)} ${part}`))
+    .concat(more > 0 ? [paint(`  … ${more} more · /files`, "quiet", theme)] : []));
+  out.push("", ...full(run.tail.map(terminalText).join(" · "), run.state === "ok" ? "quiet" : "attention"));
   return "\n" + out.join("\n") + "\n";
 }