ucode-agent 1.11.0 → 1.12.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ucode-agent",
-  "version": "1.11.0",
+  "version": "1.12.1",
   "description": "ucode - a terminal coding agent that reads, edits and runs your code, on NVIDIA and Cohere models.",
   "type": "module",
   "main": "ucode.js",

package/src/core/loop.js

@@ -923,10 +923,12 @@ export class Agent {
       this.ui.stopSpinner();
       this.ui.stopTimer?.();
       this.activity = null;
-      this.ui.turnEnd?.({ ok: finished });
       await this.persist();
       if (this.full) this.showHeader({ clear: false });
       if (finished) this.openWhenReady(turnStarted);
+      // Last, so "Done" is the last thing that happens rather than the last
+      // thing said before several more things happen.
+      this.ui.turnEnd?.({ ok: finished });
     }
   }
 
@@ -1292,8 +1294,16 @@ export class Agent {
   }
 
   /** A dev server came up during this turn: open it in the browser, once. */
+  /**
+   * Open the running app in a browser — only when asked.
+   *
+   * This used to happen on its own whenever a dev server came up. Something
+   * seizing the screen mid-thought is startling at the best of times, and
+   * during a demo it is worse. UCODE_OPEN=1 brings the old behaviour back for
+   * anyone who liked it; otherwise the URL is on screen to click.
+   */
   openWhenReady(since) {
-    if (!this.full || process.env.UCODE_OPEN === '0') return;
+    if (!this.full || process.env.UCODE_OPEN !== '1') return;
     const server = serversReadySince(since).at(-1);
     if (!server || (this.opened ??= new Set()).has(server.url)) return;
     this.opened.add(server.url);

package/src/tools/index.js

@@ -13,7 +13,7 @@ import { typeOf } from './types.js';
 import { runCommand, runCommands } from './shell.js';
 import { webSearch } from './web.js';
 import { lookAtApp } from './browser.js';
-import { createApp } from './scaffold.js';
+import { createApp, TEMPLATE_NAMES, TEMPLATE_NOTES } from './scaffold.js';
 import { deploy } from './deploy.js';
 import { clip, READ_LINES } from './shared.js';
 
@@ -27,18 +27,28 @@ export const tools = [
   {
     name: 'create_app',
     description:
-      'Start a new Next.js + shadcn/ui app from the ready-made ucode starter. This is how every ' +
-      'Next.js app begins - never run create-next-app or shadcn init. It copies a project that ' +
-      'is already known to build (Next.js 16, TypeScript, Tailwind 4, shadcn with 33 common ' +
-      'components, light/dark mode, toasts, a design preset of colours and fonts) into a new empty folder, and ' +
-      'starts installing its packages in the background so you can write components at once. ' +
-      'The result lists everything included.',
+      'Start a new app from a starter that already works. Two to choose between, and the ' +
+      'choice matters. "plain-html": one index.html, one stylesheet, one ES module — nothing ' +
+      'to install, nothing to build, opens straight in a browser. Use it whenever the user ' +
+      'asks for plain HTML/CSS/JS, or for a single page, a toy, a game or a visualisation. ' +
+      '"next-shadcn": Next.js 16, TypeScript, Tailwind 4 and shadcn with 33 components, light ' +
+      'and dark, toasts, and a design preset — for anything with routes, data or many screens; ' +
+      'its packages install in the background so you can write components at once. This is how ' +
+      'every Next.js app begins - never run create-next-app or shadcn init. Do not reach for ' +
+      'Next.js when a single HTML file is what was asked for.',
     parameters: {
       type: 'object',
       properties: {
         folder: str('A new, empty folder for the app, relative to the project root, e.g. "stride".'),
         name: str('The display name of the app, e.g. "Stride".'),
         description: str('One line about the app, used in the page metadata.'),
+        template: {
+          type: 'string',
+          enum: ['next-shadcn', 'plain-html'],
+          description:
+            'Which starter. "plain-html" for plain HTML/CSS/JS, a single page, a toy or a game: ' +
+            'no install, no build. "next-shadcn" (the default) for routes, data or many screens.',
+        },
         design: {
           type: 'string',
           enum: ['ocean', 'grove', 'sunset', 'graphite', 'violet', 'citrus'],

package/src/tools/scaffold.js

@@ -1,209 +1,221 @@
-/**
- * scaffold.js — starting an app from a starter that is known to work.
- *
- * Setting up a Next.js + shadcn project from nothing is four minutes of
- * create-next-app and shadcn CLI runs — measured at 116s and 130s — plus a
- * dozen model round trips to drive them and then theme the result. Every app
- * starts from the same place anyway, so ucode ships that place: a project
- * that has already been built and type-checked, copied in one step, with its
- * install starting in the background while the model writes the first
- * component.
- */
-
-import { promises as fs } from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { ToolFailure } from '../core/failure.js';
-import { resolveIn, guard, result } from './shared.js';
-import { packageJsonWritten, installIn } from './shell.js';
-import { restore, populate } from './cache.js';
-
-const TEMPLATES = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'templates');
-
-/** npm silently drops these two names from published packages, so they ship renamed. */
-const RENAME = { _gitignore: '.gitignore', '_package-lock.json': 'package-lock.json' };
-
-/** Files the placeholders are filled into. Everything else is copied byte for byte. */
-const TEXT = /\.(?:json|md|mjs|css|tsx?)$/i;
-
-export const TEMPLATE_NAMES = ['next-shadcn'];
-
-function slug(name) {
-  return String(name).toLowerCase().trim().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'app';
-}
-
-/** Text that is safe inside a JS string and a JSON string. */
-const plain = (s) => String(s ?? '').replace(/["'`\\<>]/g, '').replace(/\s+/g, ' ').trim();
-
-async function copyTree(from, to, fill) {
-  await fs.mkdir(to, { recursive: true });
-  const copied = [];
-  for (const entry of await fs.readdir(from, { withFileTypes: true })) {
-    const name = RENAME[entry.name] ?? entry.name;
-    const src = path.join(from, entry.name);
-    const dest = path.join(to, name);
-    if (entry.isDirectory()) {
-      copied.push(...(await copyTree(src, dest, fill)).map((f) => `${name}/${f}`));
-    } else if (TEXT.test(entry.name) || entry.name in RENAME) {
-      let text = await fs.readFile(src, 'utf8');
-      for (const [token, value] of Object.entries(fill)) text = text.split(token).join(value);
-      await fs.writeFile(dest, text, 'utf8');
-      copied.push(name);
-    } else {
-      await fs.copyFile(src, dest);
-      copied.push(name);
-    }
-  }
-  return copied;
-}
-
-/**
- * @param {object} o
- * @param {string} o.folder       new, empty folder for the app
- * @param {string} o.name         display name, e.g. "Stride"
- * @param {string} [o.description]
- * @param {string} [o.template]
- * @param {boolean} [o.install]   start the background install (tests turn it off)
- */
-/**
- * Give the new app its look: one of the hand-picked presets in the starter's
- * presets/ folder — a full light and dark palette and a font — written into
- * globals.css and layout.tsx. Apps stop looking like the same default blue.
- * Returns the preset used, or null when the starter has none.
- */
-export async function applyDesign(appDir, design) {
-  const dir = path.join(appDir, 'presets');
-  const names = (await fs.readdir(dir).catch(() => [])).filter((f) => f.endsWith('.json'));
-  if (!names.length) return null;
-  const presets = await Promise.all(names.map(async (f) => JSON.parse(await fs.readFile(path.join(dir, f), 'utf8'))));
-  await fs.rm(dir, { recursive: true, force: true }); // the app needs the result, not the catalogue
-  const preset = presets.find((p) => p.name === design) ?? presets.find((p) => p.default) ?? presets[0];
-
-  const cssFile = path.join(appDir, 'src', 'app', 'globals.css');
-  let css = await fs.readFile(cssFile, 'utf8').catch(() => null);
-  if (css !== null) {
-    const retint = (selector, tokens) => {
-      const block = new RegExp(`(${selector}\\s*\\{)([\\s\\S]*?)(\\n\\})`);
-      css = css.replace(block, (all, open, body, close) => {
-        const seen = new Set();
-        let next = body.replace(/(\n\s*)--([\w-]+):\s*[^;]+;/g, (line, lead, key) => {
-          if (!(key in tokens)) return line;
-          seen.add(key);
-          return `${lead}--${key}: ${tokens[key]};`;
-        });
-        for (const [key, value] of Object.entries(tokens)) if (!seen.has(key)) next += `\n  --${key}: ${value};`;
-        return open + next + close;
-      });
-    };
-    retint(':root', { radius: preset.radius, ...preset.light });
-    retint('\\.dark', preset.dark);
-    await fs.writeFile(cssFile, css);
-  }
-
-  const sans = preset.fonts?.sans;
-  const layoutFile = path.join(appDir, 'src', 'app', 'layout.tsx');
-  if (sans && sans !== 'Geist') {
-    const id = sans.replace(/\s+/g, '_');
-    const layout = await fs.readFile(layoutFile, 'utf8').catch(() => null);
-    if (layout !== null) {
-      await fs.writeFile(layoutFile, layout
-        .replace('import { Geist, Geist_Mono } from "next/font/google";', `import { ${id}, Geist_Mono } from "next/font/google";`)
-        .replace('const sans = Geist({', `const sans = ${id}({`));
-    }
-  }
-
-  const guide = path.join(appDir, 'TEMPLATE.md');
-  const text = await fs.readFile(guide, 'utf8').catch(() => null);
-  if (text !== null) {
-    await fs.writeFile(guide, `${text.trimEnd()}\n\n## Design\n\nThis app uses the **${preset.name}** preset — ` +
-      `${preset.summary}. Font: ${sans ?? 'Geist'}. The palette lives in globals.css (light and dark): ` +
-      'build with the tokens (bg-primary, text-muted-foreground, border, ...) rather than raw colours, ' +
-      'so every screen stays in one look.\n');
-  }
-  return preset;
-}
-
-export async function createApp({ folder, name, description, template = 'next-shadcn', design, install = true }) {
-  if (!TEMPLATE_NAMES.includes(template)) {
-    throw new ToolFailure({
-      kind: 'bad_args',
-      attempted: 'creating an app',
-      failed: `There is no starter called "${template}".`,
-      fix: `Use one of: ${TEMPLATE_NAMES.join(', ')}.`,
-    });
-  }
-
-  const target = resolveIn(folder, 'create_app', 'folder');
-  const attempted = `creating an app in ${target.show}`;
-  if (target.show === '.') {
-    throw new ToolFailure({
-      kind: 'bad_args',
-      attempted,
-      failed: 'The app needs its own folder, not the project root.',
-      fix: 'Pass a new folder name, e.g. "stride".',
-    });
-  }
-  await guard(target, `create an app in ${target.abs}`);
-
-  let existing = [];
-  try {
-    existing = await fs.readdir(target.abs);
-  } catch {
-    existing = [];
-  }
-  if (existing.length) {
-    throw new ToolFailure({
-      kind: 'not_empty',
-      attempted,
-      failed: `${target.show} already has ${existing.length} item(s) in it: ${existing.slice(0, 5).join(', ')}.`,
-      fix: 'Pick a new folder name. If this folder is the app from an earlier attempt, work in it instead of creating it again.',
-    });
-  }
-
-  const display = plain(name) || path.basename(target.abs);
-  const fill = {
-    __APP_NAME__: display,
-    __APP_SLUG__: slug(display),
-    __APP_DESCRIPTION__: plain(description) || display,
-  };
-
-  const files = await copyTree(path.join(TEMPLATES, template), target.abs, fill);
-  await fs.mkdir(path.join(target.abs, 'public'), { recursive: true });
-  const look = await applyDesign(target.abs, design);
-
-  // The starter has been installed on this machine before: hard-link that
-  // tree in, which is seconds where npm is a minute. Otherwise install as
-  // usual, and keep the result so the next app is instant.
-  let linked = 0;
-  if (install) {
-    // Keyed on the starter's lockfile, which is the same for every app made
-    // from it — the app's own is rewritten by npm as it installs.
-    const lockText = await fs
-      .readFile(path.join(TEMPLATES, template, '_package-lock.json'), 'utf8')
-      .catch(() => null);
-    linked = await restore(target.abs, template, lockText);
-    if (!linked) {
-      const pkg = path.join(target.abs, 'package.json');
-      packageJsonWritten(pkg, await fs.readFile(pkg, 'utf8'));
-      installIn(target.abs)?.then((done) => {
-        if (done?.code === 0) populate(target.abs, template, lockText);
-      });
-    }
-  }
-
-  const guide = await fs.readFile(path.join(target.abs, 'TEMPLATE.md'), 'utf8').catch(() => '');
-
-  return result(
-    `Created ${target.show} from the ${template} starter — ${files.length} files, already known to build.\n` +
-      (look ? `Design: the ${look.name} preset (${look.summary}), font ${look.fonts?.sans ?? 'Geist'}.\n` : '') +
-      (linked
-        ? `Its packages are already in place (${linked.toLocaleString()} files, linked from the starter cache) — ` +
-          'nothing to install: build and run straight away.\n'
-        : install
-        ? `Its packages are installing in the background right now. Keep writing: any command you run in ` +
-          `${target.show} waits for that install first, so there is no need to run npm install.\n`
-        : '') +
-      `Run this app's commands with cwd: "${target.show}" (npm run build, npm run dev).\n\n${guide}`,
-    `${files.length} files${linked ? ' · packages ready' : install ? ' · installing in the background' : ''}`
-  );
-}
+/**
+ * scaffold.js — starting an app from a starter that is known to work.
+ *
+ * Setting up a Next.js + shadcn project from nothing is four minutes of
+ * create-next-app and shadcn CLI runs — measured at 116s and 130s — plus a
+ * dozen model round trips to drive them and then theme the result. Every app
+ * starts from the same place anyway, so ucode ships that place: a project
+ * that has already been built and type-checked, copied in one step, with its
+ * install starting in the background while the model writes the first
+ * component.
+ */
+
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ToolFailure } from '../core/failure.js';
+import { resolveIn, guard, result } from './shared.js';
+import { packageJsonWritten, installIn } from './shell.js';
+import { restore, populate } from './cache.js';
+
+const TEMPLATES = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'templates');
+
+/** npm silently drops these two names from published packages, so they ship renamed. */
+const RENAME = { _gitignore: '.gitignore', '_package-lock.json': 'package-lock.json' };
+
+/** Files the placeholders are filled into. Everything else is copied byte for byte. */
+const TEXT = /\.(?:json|md|mjs|css|html|jsx?|tsx?)$/i;
+
+export const TEMPLATE_NAMES = ['next-shadcn', 'plain-html'];
+
+/** What each starter is for, so the choice is made on purpose. */
+export const TEMPLATE_NOTES = {
+  'next-shadcn': 'Next.js, TypeScript, Tailwind and shadcn/ui. For anything with routes, data or many components.',
+  'plain-html': 'One index.html, one stylesheet, one module. No install, no build, opens straight in a browser.',
+};
+
+function slug(name) {
+  return String(name).toLowerCase().trim().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'app';
+}
+
+/** Text that is safe inside a JS string and a JSON string. */
+const plain = (s) => String(s ?? '').replace(/["'`\\<>]/g, '').replace(/\s+/g, ' ').trim();
+
+async function copyTree(from, to, fill) {
+  await fs.mkdir(to, { recursive: true });
+  const copied = [];
+  for (const entry of await fs.readdir(from, { withFileTypes: true })) {
+    const name = RENAME[entry.name] ?? entry.name;
+    const src = path.join(from, entry.name);
+    const dest = path.join(to, name);
+    if (entry.isDirectory()) {
+      copied.push(...(await copyTree(src, dest, fill)).map((f) => `${name}/${f}`));
+    } else if (TEXT.test(entry.name) || entry.name in RENAME) {
+      let text = await fs.readFile(src, 'utf8');
+      for (const [token, value] of Object.entries(fill)) text = text.split(token).join(value);
+      await fs.writeFile(dest, text, 'utf8');
+      copied.push(name);
+    } else {
+      await fs.copyFile(src, dest);
+      copied.push(name);
+    }
+  }
+  return copied;
+}
+
+/**
+ * @param {object} o
+ * @param {string} o.folder       new, empty folder for the app
+ * @param {string} o.name         display name, e.g. "Stride"
+ * @param {string} [o.description]
+ * @param {string} [o.template]
+ * @param {boolean} [o.install]   start the background install (tests turn it off)
+ */
+/**
+ * Give the new app its look: one of the hand-picked presets in the starter's
+ * presets/ folder — a full light and dark palette and a font — written into
+ * globals.css and layout.tsx. Apps stop looking like the same default blue.
+ * Returns the preset used, or null when the starter has none.
+ */
+export async function applyDesign(appDir, design) {
+  const dir = path.join(appDir, 'presets');
+  const names = (await fs.readdir(dir).catch(() => [])).filter((f) => f.endsWith('.json'));
+  if (!names.length) return null;
+  const presets = await Promise.all(names.map(async (f) => JSON.parse(await fs.readFile(path.join(dir, f), 'utf8'))));
+  await fs.rm(dir, { recursive: true, force: true }); // the app needs the result, not the catalogue
+  const preset = presets.find((p) => p.name === design) ?? presets.find((p) => p.default) ?? presets[0];
+
+  const cssFile = path.join(appDir, 'src', 'app', 'globals.css');
+  let css = await fs.readFile(cssFile, 'utf8').catch(() => null);
+  if (css !== null) {
+    const retint = (selector, tokens) => {
+      const block = new RegExp(`(${selector}\\s*\\{)([\\s\\S]*?)(\\n\\})`);
+      css = css.replace(block, (all, open, body, close) => {
+        const seen = new Set();
+        let next = body.replace(/(\n\s*)--([\w-]+):\s*[^;]+;/g, (line, lead, key) => {
+          if (!(key in tokens)) return line;
+          seen.add(key);
+          return `${lead}--${key}: ${tokens[key]};`;
+        });
+        for (const [key, value] of Object.entries(tokens)) if (!seen.has(key)) next += `\n  --${key}: ${value};`;
+        return open + next + close;
+      });
+    };
+    retint(':root', { radius: preset.radius, ...preset.light });
+    retint('\\.dark', preset.dark);
+    await fs.writeFile(cssFile, css);
+  }
+
+  const sans = preset.fonts?.sans;
+  const layoutFile = path.join(appDir, 'src', 'app', 'layout.tsx');
+  if (sans && sans !== 'Geist') {
+    const id = sans.replace(/\s+/g, '_');
+    const layout = await fs.readFile(layoutFile, 'utf8').catch(() => null);
+    if (layout !== null) {
+      await fs.writeFile(layoutFile, layout
+        .replace('import { Geist, Geist_Mono } from "next/font/google";', `import { ${id}, Geist_Mono } from "next/font/google";`)
+        .replace('const sans = Geist({', `const sans = ${id}({`));
+    }
+  }
+
+  const guide = path.join(appDir, 'TEMPLATE.md');
+  const text = await fs.readFile(guide, 'utf8').catch(() => null);
+  if (text !== null) {
+    await fs.writeFile(guide, `${text.trimEnd()}\n\n## Design\n\nThis app uses the **${preset.name}** preset — ` +
+      `${preset.summary}. Font: ${sans ?? 'Geist'}. The palette lives in globals.css (light and dark): ` +
+      'build with the tokens (bg-primary, text-muted-foreground, border, ...) rather than raw colours, ' +
+      'so every screen stays in one look.\n');
+  }
+  return preset;
+}
+
+export async function createApp({ folder, name, description, template = 'next-shadcn', design, install = true }) {
+  if (!TEMPLATE_NAMES.includes(template)) {
+    throw new ToolFailure({
+      kind: 'bad_args',
+      attempted: 'creating an app',
+      failed: `There is no starter called "${template}".`,
+      fix: `Use one of: ${TEMPLATE_NAMES.join(', ')}.`,
+    });
+  }
+
+  const target = resolveIn(folder, 'create_app', 'folder');
+  const attempted = `creating an app in ${target.show}`;
+  if (target.show === '.') {
+    throw new ToolFailure({
+      kind: 'bad_args',
+      attempted,
+      failed: 'The app needs its own folder, not the project root.',
+      fix: 'Pass a new folder name, e.g. "stride".',
+    });
+  }
+  await guard(target, `create an app in ${target.abs}`);
+
+  let existing = [];
+  try {
+    existing = await fs.readdir(target.abs);
+  } catch {
+    existing = [];
+  }
+  if (existing.length) {
+    throw new ToolFailure({
+      kind: 'not_empty',
+      attempted,
+      failed: `${target.show} already has ${existing.length} item(s) in it: ${existing.slice(0, 5).join(', ')}.`,
+      fix: 'Pick a new folder name. If this folder is the app from an earlier attempt, work in it instead of creating it again.',
+    });
+  }
+
+  const display = plain(name) || path.basename(target.abs);
+  const fill = {
+    __APP_NAME__: display,
+    __APP_SLUG__: slug(display),
+    __APP_DESCRIPTION__: plain(description) || display,
+  };
+
+  const files = await copyTree(path.join(TEMPLATES, template), target.abs, fill);
+  // Next.js serves static files from public/; a plain page has no such place
+  // and an empty folder in a three-file app is clutter.
+  if (template !== 'plain-html') await fs.mkdir(path.join(target.abs, 'public'), { recursive: true });
+  const look = await applyDesign(target.abs, design);
+
+  // The starter has been installed on this machine before: hard-link that
+  // tree in, which is seconds where npm is a minute. Otherwise install as
+  // usual, and keep the result so the next app is instant.
+  let linked = 0;
+  const needsInstall = template !== 'plain-html';
+  if (install && needsInstall) {
+    // Keyed on the starter's lockfile, which is the same for every app made
+    // from it — the app's own is rewritten by npm as it installs.
+    const lockText = await fs
+      .readFile(path.join(TEMPLATES, template, '_package-lock.json'), 'utf8')
+      .catch(() => null);
+    linked = await restore(target.abs, template, lockText);
+    if (!linked) {
+      const pkg = path.join(target.abs, 'package.json');
+      packageJsonWritten(pkg, await fs.readFile(pkg, 'utf8'));
+      installIn(target.abs)?.then((done) => {
+        if (done?.code === 0) populate(target.abs, template, lockText);
+      });
+    }
+  }
+
+  const guide = await fs.readFile(path.join(target.abs, 'TEMPLATE.md'), 'utf8').catch(() => '');
+
+  return result(
+    `Created ${target.show} from the ${template} starter — ${files.length} files, already known to build.\n` +
+      (look ? `Design: the ${look.name} preset (${look.summary}), font ${look.fonts?.sans ?? 'Geist'}.\n` : '') +
+      (linked
+        ? `Its packages are already in place (${linked.toLocaleString()} files, linked from the starter cache) — ` +
+          'nothing to install: build and run straight away.\n'
+        : install && needsInstall
+        ? `Its packages are installing in the background right now. Keep writing: any command you run in ` +
+          `${target.show} waits for that install first, so there is no need to run npm install.\n`
+        : '') +
+      (needsInstall
+        ? `Run this app's commands with cwd: "${target.show}" (npm run build, npm run dev).\n\n${guide}`
+        : `Nothing to install and nothing to build: open ${target.show}/index.html directly, or serve the ` +
+          `folder with "python -m http.server 8000" if it fetches anything.\n\n${guide}`),
+    `${files.length} files${linked ? ' · packages ready' : install && needsInstall ? ' · installing in the background' : ''}`
+  );
+}

package/src/ui/screen.js

@@ -92,6 +92,8 @@ const HIDE = `${ESC}[?25l`;
 const SHOW = `${ESC}[?25h`;
 const HOME = `${ESC}[H`;
 const CLEAR_LINE = `${ESC}[K`;
+/** Written out rather than inline, so no edit can turn it into a real break. */
+const NEWLINE = String.fromCharCode(10);
 const at = (row, col) => `${ESC}[${row};${col}H`;
 const title = (t) => `${ESC}]0;${t}\x07`;
 
@@ -603,15 +605,47 @@ export class Screen {
   // -- input box -----------------------------------------------------------
 
   /** The typed line, wrapped to the inside of a box `width` characters across. */
+  /**
+   * The typed text, laid out as rows inside the box.
+   *
+   * A line break in the buffer is a row of its own before any wrapping is
+   * considered. Slicing the text into fixed widths without looking for one
+   * put the newline into the frame instead, and the terminal obeyed it — the
+   * pasted text walked out of the box and over the transcript beside it.
+   *
+   * `starts` records where each row begins in the text, so the caret can be
+   * placed by looking up rather than by counting characters a second way and
+   * hoping the two agree.
+   */
   inputLines(width = this.inner()) {
     const prefix = this.pendingPrompt ? `${this.pendingPrompt} ` : '› ';
     const full = prefix + this.buffer;
 
     const rows = [];
-    for (let i = 0; i < full.length; i += width) rows.push(full.slice(i, i + width));
-    if (rows.length === 0) rows.push(prefix);
+    const starts = [];
+    let at = 0;
+
+    for (const para of full.split(NEWLINE)) {
+      let i = 0;
+      do {
+        rows.push(para.slice(i, i + width));
+        starts.push(at + i);
+        i += width;
+      } while (i < para.length);
+      at += para.length + 1; // the newline itself
+    }
+
+    if (rows.length === 0) { rows.push(prefix); starts.push(0); }
+    return { rows, prefix, width, starts };
+  }
 
-    return { rows, prefix, width };
+  /** Which row the caret sits on, and how far along it. */
+  caretAt(width) {
+    const { rows, prefix, starts } = this.inputLines(width);
+    const index = prefix.length + this.cursor;
+    let row = 0;
+    while (row + 1 < starts.length && starts[row + 1] <= index) row++;
+    return { row, col: Math.min(index - starts[row], rows[row].length), rows };
   }
 
   viewportHeight() {
@@ -992,7 +1026,7 @@ export class Screen {
    * messages. Inside the markers a newline is just a character.
    */
   onPaste(text) {
-    const clean = String(text).replace(/\r\n?/g, '\n');
+    const clean = String(text).replace(/\r\n?/g, '\n');
     this.buffer = this.buffer.slice(0, this.cursor) + clean + this.buffer.slice(this.cursor);
     this.cursor += clean.length;
     this.render();
@@ -1064,6 +1098,13 @@ export class Screen {
     }
     rest += chunk.slice(index);
 
+    // A chunk carrying a line break *and* other text did not come from a
+    // keyboard: nobody types a newline in the middle of a burst. Many
+    // terminals, Windows ones especially, send a paste with no markers at
+    // all, so without this every newline in it reads as Enter and the paste
+    // submits itself a line at a time.
+    if (looksPasted(rest)) { this.onPaste(rest); return; }
+
     for (const key of splitKeys(rest)) this.onKey(key);
   }
 
@@ -1248,17 +1289,13 @@ export class Screen {
   caret() {
     if (this.welcoming()) {
       const g = this.welcomeGeometry();
-      const { rows, prefix, width } = this.inputLines(g.boxWidth - 4);
-      const index = prefix.length + this.cursor;
-      const row = Math.min(Math.floor(index / width), rows.length - 1);
+      const { row, col } = this.caretAt(g.boxWidth - 4);
       // g.boxTop is 0-based and the typed lines start one below the border.
-      return [g.boxTop + 2 + row, g.left + 3 + (index % width)];
+      return [g.boxTop + 2 + row, g.left + 3 + col];
     }
 
-    const { rows, prefix, width } = this.inputLines();
-    const index = prefix.length + this.cursor;
-    const row = Math.min(Math.floor(index / width), rows.length - 1);
-    const col = 3 + (index % width);
+    const { row, col: at, rows } = this.caretAt();
+    const col = 3 + at;
     // Counting up from the bottom: the box border is the last row, the status
     // row is above it, then the blank row, then the typed lines.
     const firstRow = this.rows - 2 - rows.length;
@@ -1333,6 +1370,27 @@ export class Screen {
  * up arrow rather than ESC [ A. Both are normalised to the bracket form here
  * so the key handler only ever sees one of them.
  */
+/**
+ * Did this arrive as a paste, judged by shape rather than by markers?
+ *
+ * Someone pressing Enter sends one carriage return on its own. A paste sends
+ * a line break with text around it, in a single read. That difference is all
+ * there is to go on when a terminal does not implement bracketed paste, and
+ * it is enough.
+ *
+ * Anything carrying an escape sequence is left alone: that is a key or a
+ * mouse report, and reading one as text would put gibberish in the input.
+ */
+export function looksPasted(chunk) {
+  const text = String(chunk ?? '');
+  if (text.length < 2 || text.includes(ESC)) return false;
+  const breaks = (text.match(/[\r\n]/g) ?? []).length;
+  if (breaks === 0) return false;
+  // One trailing break is someone finishing a line, not pasting one.
+  if (breaks === 1 && /[\r\n]$/.test(text)) return false;
+  return true;
+}
+
 export function splitKeys(chunk) {
   const keys = [];
   let i = 0;

package/templates/plain-html/TEMPLATE.md

@@ -0,0 +1,25 @@
+# __APP_NAME__
+
+A plain HTML, CSS and JavaScript app. No framework, no build step, no install:
+`index.html` is the whole program's front door.
+
+## The files
+
+- `index.html` — the markup, and the only place scripts and styles are linked
+- `styles.css` — the design tokens at the top, then the components
+- `app.js` — an ES module; `state` holds everything, `render()` draws it
+
+## Working in it
+
+Open `index.html` in a browser, or serve the folder if the app fetches
+anything: `python -m http.server 8000`. There is nothing to install and
+nothing to compile, so a change is visible on refresh.
+
+## Conventions worth keeping
+
+- **One state object, one render.** Patching the DOM from several places is
+  where these apps become impossible to reason about.
+- **Tokens in `:root`.** Colour, spacing and timing are defined once, so the
+  look can be changed without touching components.
+- **Reduced motion is honoured** at the bottom of the stylesheet. Leave it in.
+- Keep it to these three files until there is a real reason not to.

package/templates/plain-html/_gitignore

@@ -0,0 +1,2 @@
+.DS_Store
+node_modules/

package/templates/plain-html/app.js

@@ -0,0 +1,43 @@
+/**
+ * __APP_NAME__
+ *
+ * Plain modules, no build step: this file is what the browser runs. Keep the
+ * state in one place and render from it, so there is one answer to "what is
+ * on screen" rather than a DOM that has been patched in six directions.
+ */
+
+const app = document.querySelector('#app');
+
+/** Everything the page knows. Change this, then call render(). */
+const state = {
+  items: load(),
+};
+
+function load() {
+  try {
+    return JSON.parse(localStorage.getItem('__APP_SLUG__') ?? '[]');
+  } catch {
+    return []; // a corrupt store is an empty one, not a broken page
+  }
+}
+
+function save() {
+  try {
+    localStorage.setItem('__APP_SLUG__', JSON.stringify(state.items));
+  } catch {
+    // Private mode, or the quota is full. Losing the save is survivable;
+    // throwing here would take the whole page down with it.
+  }
+}
+
+function render() {
+  app.innerHTML = '';
+  app.append(
+    Object.assign(document.createElement('div'), {
+      className: 'card',
+      textContent: 'Edit app.js to build __APP_NAME__.',
+    })
+  );
+}
+
+render();

package/templates/plain-html/index.html

@@ -0,0 +1,22 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>__APP_NAME__</title>
+    <meta name="description" content="__APP_DESCRIPTION__" />
+    <link rel="stylesheet" href="styles.css" />
+  </head>
+  <body>
+    <main class="shell">
+      <header class="head">
+        <h1>__APP_NAME__</h1>
+        <p class="sub">__APP_DESCRIPTION__</p>
+      </header>
+
+      <section id="app"></section>
+    </main>
+
+    <script type="module" src="app.js"></script>
+  </body>
+</html>

package/templates/plain-html/styles.css

@@ -0,0 +1,100 @@
+:root {
+  /* One accent, a handful of greys, and a scale. Everything else is composed
+     from these, so the whole look changes by editing this block. */
+  --bg: #0b0d10;
+  --surface: #14171c;
+  --line: #232830;
+  --text: #e7eaf0;
+  --muted: #8b93a3;
+  --accent: #2dd4bf;
+
+  --r: 16px;
+  --s1: 8px;
+  --s2: 12px;
+  --s3: 16px;
+  --s4: 24px;
+  --s5: 40px;
+
+  --fast: 160ms cubic-bezier(0.2, 0, 0.2, 1);
+  --slow: 260ms cubic-bezier(0.2, 0, 0.2, 1);
+}
+
+* { box-sizing: border-box; }
+
+html, body { height: 100%; }
+
+body {
+  margin: 0;
+  background: var(--bg);
+  color: var(--text);
+  font: 15px/1.6 ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+  -webkit-font-smoothing: antialiased;
+}
+
+.shell {
+  max-width: 720px;
+  margin: 0 auto;
+  padding: var(--s5) var(--s4) var(--s5);
+}
+
+.head { margin-bottom: var(--s4); }
+
+h1 {
+  margin: 0;
+  font-size: 28px;
+  font-weight: 600;
+  letter-spacing: -0.02em;
+}
+
+.sub {
+  margin: var(--s1) 0 0;
+  color: var(--muted);
+}
+
+.card {
+  background: var(--surface);
+  border: 1px solid var(--line);
+  border-radius: var(--r);
+  padding: var(--s3);
+  box-shadow: 0 1px 2px rgb(0 0 0 / 0.3), 0 8px 24px rgb(0 0 0 / 0.2);
+}
+
+button {
+  font: inherit;
+  color: var(--bg);
+  background: var(--accent);
+  border: 0;
+  border-radius: 10px;
+  padding: 10px var(--s3);
+  cursor: pointer;
+  transition: transform var(--fast), filter var(--fast);
+}
+
+button:hover { filter: brightness(1.08); }
+button:active { transform: translateY(1px); }
+
+input, textarea {
+  font: inherit;
+  color: var(--text);
+  background: transparent;
+  border: 1px solid var(--line);
+  border-radius: 10px;
+  padding: 10px var(--s2);
+  width: 100%;
+  transition: border-color var(--fast);
+}
+
+input:focus, textarea:focus {
+  outline: none;
+  border-color: var(--accent);
+}
+
+/* Anyone who has asked their system not to animate things means it. */
+@media (prefers-reduced-motion: reduce) {
+  * { animation: none !important; transition: none !important; }
+}
+
+@media (max-width: 480px) {
+  .shell { padding: var(--s4) var(--s3); }
+  h1 { font-size: 24px; }
+}