ucode-agent 1.10.0 → 1.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ucode-agent",
-  "version": "1.10.0",
+  "version": "1.12.0",
   "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

@@ -65,6 +65,32 @@ const MAX_ARG_RETRIES = 2;
 const MAX_CONTINUATIONS = 3;
 
 /** Read-only tools whose result line adds nothing — the user saw the output. */
+/**
+ * How many rows a diff adds and removes.
+ *
+ * The rows come through as "+12| text" and "-12| text", with a "~" heading
+ * for each file in a multi-file write and an undecorated note counting what
+ * was elided. Only the signs are counted.
+ */
+export function countDiff(rows = []) {
+  let added = 0;
+  let removed = 0;
+  for (const row of rows) {
+    const line = String(row ?? '');
+    if (line.startsWith('~')) continue;
+    // "… 218 more removed" / "… 508 more added" stand for rows not shown.
+    const more = /^\s*[….]+\s*(\d+)\s+more\s+(added|removed)/.exec(line);
+    if (more) {
+      if (more[2] === 'added') added += Number(more[1]);
+      else removed += Number(more[1]);
+      continue;
+    }
+    if (line.startsWith('+')) added++;
+    else if (line.startsWith('-')) removed++;
+  }
+  return { added, removed };
+}
+
 const QUIET = new Set(['read_file', 'read_files', 'list_dir', 'glob', 'grep', 'web_search', 'update_plan']);
 
 /** Tools that draw their own line, so they get no "● Doing X" line of their own. */
@@ -897,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 });
     }
   }
 
@@ -1266,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);
@@ -1320,8 +1356,10 @@ export class Agent {
       this.sinceCheck?.clear();
     }
     if (!QUIET.has(call.name)) this.ui.toolResult(out.summary);
-    if (out.diff?.length) this.ui.diff(out.diff);
-    if (out.output?.length) this.ui.commandOutput(out.output);
+    // The change as its two numbers, not as a copy of the file. The diff rows
+    // are still built by the tool — the model reads them in the result — they
+    // simply do not go on screen.
+    if (out.diff?.length) this.ui.diffStat?.(countDiff(out.diff));
     this.push({ role: 'tool', toolCallId: call.id, name: call.name, content: out.content + this.stuckNote(call, { out }) });
   }
 

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

@@ -39,7 +39,7 @@ import chalk from 'chalk';
 import {
   theme, blue, sky, deep, dim, edge, ADDED, REMOVED, BANNER, BANNER_WIDTH, SPINNER,
   boxTop, boxBottom, boxRow, visLen, padVis, clip, wrapAnsi,
-  shortenPath, asLabel, ensureColour, planLine, bare, narration, narrationMark, groupKind, groupLabel } from './theme.js';
+  shortenPath, asLabel, ensureColour, planLine, bare, narration, narrationMark, groupKind, groupLabel, groupTarget, runLine } from './theme.js';
 import { FRAME_MS, fitActivity, shimmer, spinnerGlyph, formatDuration, doneLine, stepPaint } from './activity.js';
 import { renderer, render, polish } from './markdown.js';
 import { VERSION } from '../core/version.js';
@@ -84,6 +84,8 @@ const TRACK = process.platform === 'win32'
 const UNTRACK = process.platform === 'win32'
   ? '' : `${ESC}[?1006l${ESC}[?1015l${ESC}[?1002l${ESC}[?1000l`;
 
+const PASTE_ON = `${ESC}[?2004h`;
+const PASTE_OFF = `${ESC}[?2004l`;
 const MOUSE_ON = `${ESC}[?1007h${TRACK}`;
 const MOUSE_OFF = `${UNTRACK}${ESC}[?1007l`;
 const HIDE = `${ESC}[?25l`;
@@ -149,7 +151,7 @@ export class Screen {
 
   async start() {
     ensureColour(this.output);
-    this.output.write(ALT_ON + MOUSE_ON + HIDE + title(`ucode — ${path.basename(this.cwd)}`));
+    this.output.write(ALT_ON + MOUSE_ON + PASTE_ON + HIDE + title(`ucode — ${path.basename(this.cwd)}`));
     this.input.setRawMode?.(true);
     this.input.resume();
     this.input.setEncoding('utf8');
@@ -173,7 +175,7 @@ export class Screen {
     this.output.off?.('resize', this.onResize);
     this.input.setRawMode?.(false);
     this.input.pause();
-    this.output.write(MOUSE_OFF + ALT_OFF + SHOW);
+    this.output.write(PASTE_OFF + MOUSE_OFF + ALT_OFF + SHOW);
   }
 
   close() {
@@ -305,11 +307,14 @@ export class Screen {
       if (gap === 1) this.lines.pop();   // its single result line, now counted
       run.count++;
       run.label = label;
-      this.lines[run.at] = `${narrationMark()} ${narration(asLabel(groupLabel(label, run.count)))}`;
-      this.render();
+      run.targets.push(groupTarget(label));
+      this.paintRun();
     } else {
       this.push(`${narrationMark()} ${narration(asLabel(label))}`);
-      this.run = { kind, count: 1, at: this.lines.length - 1, label };
+      this.run = {
+        kind, count: 1, at: this.lines.length - 1, label,
+        targets: [groupTarget(label)], added: 0, removed: 0,
+      };
     }
     this.updateSpinner(label);
   }
@@ -317,18 +322,42 @@ export class Screen {
   /** Anything that is not another step of the same kind ends the run. */
   endRun() { this.run = null; }
 
+  /** Redraw the run's single line from what it has accumulated. */
+  paintRun() {
+    if (!this.run) return;
+    this.lines[this.run.at] = `${narrationMark()} ${narration(asLabel(runLine(this.run)))}`;
+    this.render();
+  }
+
+  /**
+   * A change, as its two numbers.
+   *
+   * The diff itself used to go into the transcript. A 539-line file printed
+   * there buries the answer under a copy of something already on disk, so
+   * what is kept is the shape of the change: how much arrived, how much left.
+   */
+  diffStat({ added = 0, removed = 0 } = {}) {
+    if (!this.run) return;
+    this.run.added += added;
+    this.run.removed += removed;
+    this.paintRun();
+  }
+
   /** The checklist, when the model updates it. One line, wrapped if it must. */
   plan(items) {
     const line = planLine(items);
     if (line) this.push(line);
   }
 
-  toolResult(summary) {
-    // Inside a run, the count on the line above already says what happened;
-    // a result line per step is the noise this is meant to remove.
-    if (this.run && this.run.count > 1) return;
-    this.push(dim(`  └ ${summary}`));
-  }
+  /**
+   * What came of a step.
+   *
+   * Nothing goes underneath the bullet any more: a line of its own for every
+   * result doubles the height of the transcript to say "ok". The bullet
+   * already names the step, and a change adds its numbers to that same line.
+   * Only a failure earns a line of its own.
+   */
+  toolResult() {}
 
   toolFailed(summary) {
     // A failure is never folded away.
@@ -953,7 +982,55 @@ export class Screen {
     this.render();
   }
 
+  /**
+   * Text arriving as a paste rather than as typing.
+   *
+   * A terminal in bracketed-paste mode wraps pasted text in markers, which is
+   * the only way to tell forty lines pasted at once from forty lines typed
+   * very fast. Without it every newline in the paste reads as Enter, so a
+   * pasted block submits itself a line at a time and arrives as forty
+   * messages. Inside the markers a newline is just a character.
+   */
+  onPaste(text) {
+    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();
+  }
+
   onData(chunk) {
+    // Pasted text first: it is wrapped in markers and must not be read as
+    // keys, or its newlines submit it in pieces.
+    const paste = /\[200~([\s\S]*?)\[201~/g;
+    if (paste.test(chunk)) {
+      paste.lastIndex = 0;
+      let at = 0;
+      let m;
+      while ((m = paste.exec(chunk))) {
+        if (m.index > at) this.onData(chunk.slice(at, m.index));
+        this.onPaste(m[1]);
+        at = m.index + m[0].length;
+      }
+      if (at < chunk.length) this.onData(chunk.slice(at));
+      return;
+    }
+    // An unterminated paste: hold what has arrived and wait for the rest.
+    const open = chunk.indexOf('[200~');
+    if (open !== -1) {
+      if (open > 0) this.onData(chunk.slice(0, open));
+      this.pasting = chunk.slice(open + 6);
+      return;
+    }
+    if (this.pasting !== undefined && this.pasting !== null) {
+      const close = chunk.indexOf('[201~');
+      if (close === -1) { this.pasting += chunk; return; }
+      this.onPaste(this.pasting + chunk.slice(0, close));
+      this.pasting = null;
+      const after = chunk.slice(close + 6);
+      if (after) this.onData(after);
+      return;
+    }
+
     // UCODE_DEBUG_KEYS=1 logs every byte the terminal sends to
     // ~/.ucode/keys.log. Whether mouse reporting works at all depends on the
     // terminal forwarding it; this is how to find out.
@@ -987,6 +1064,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);
   }
 
@@ -1256,6 +1340,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/src/ui/theme.js

@@ -291,40 +291,65 @@ export const narration = (text) => chalk.dim(text);
 
 /** The bullet beside a narration line: present, not loud. */
 export const narrationMark = () => chalk.dim(deep('●'));
-
-/**
- * How a run of the same kind of step reads once it is over.
- *
- * While it happens, "Running npm test" is the useful thing to show. Once
- * three of them have happened, three near-identical lines are just noise
- * between the reader and the answer, so they fold into one: "Ran 3 commands".
- * The present tense belongs to the thing happening now; the past tense to the
- * summary of what did.
- */
-const GROUPS = {
-  Running: ['Ran', 'command', 'commands'],
-  Reading: ['Read', 'file', 'files'],
-  Searching: ['Searched', 'time', 'times'],
-  Finding: ['Found', 'pattern', 'patterns'],
-  Listing: ['Listed', 'directory', 'directories'],
-  Writing: ['Wrote', 'file', 'files'],
-  Editing: ['Edited', 'file', 'files'],
-  Checking: ['Checked', 'thing', 'things'],
-  Looking: ['Looked up', 'name', 'names'],
-  Asking: ['Asked about', 'name', 'names'],
-  Mapping: ['Mapped', 'folder', 'folders'],
-  Adding: ['Added', 'block', 'blocks'],
-  Renaming: ['Renamed', 'name', 'names'],
-};
-
-/** The first word of a label, which is what decides whether two steps match. */
-export const groupKind = (label) => String(label ?? '').trim().split(/\s+/)[0] ?? '';
-
-/** One line standing in for `count` steps that all began with the same word. */
-export function groupLabel(label, count) {
-  if (count <= 1) return String(label ?? '');
-  const g = GROUPS[groupKind(label)];
-  if (!g) return `${label} (+${count - 1} more)`;
-  const [past, one, many] = g;
-  return `${past} ${count} ${count === 1 ? one : many}`;
-}
+
+/**
+ * How a run of the same kind of step reads once it is over.
+ *
+ * While it happens, "Running npm test" is the useful thing to show. Once
+ * three of them have happened, three near-identical lines are just noise
+ * between the reader and the answer, so they fold into one: "Ran 3 commands".
+ * The present tense belongs to the thing happening now; the past tense to the
+ * summary of what did.
+ */
+const GROUPS = {
+  Running: ['Ran', 'command', 'commands'],
+  Reading: ['Read', 'file', 'files'],
+  Searching: ['Searched', 'time', 'times'],
+  Finding: ['Found', 'pattern', 'patterns'],
+  Listing: ['Listed', 'directory', 'directories'],
+  Writing: ['Wrote', 'file', 'files'],
+  Editing: ['Edited', 'file', 'files'],
+  Checking: ['Checked', 'thing', 'things'],
+  Looking: ['Looked up', 'name', 'names'],
+  Asking: ['Asked about', 'name', 'names'],
+  Mapping: ['Mapped', 'folder', 'folders'],
+  Adding: ['Added', 'block', 'blocks'],
+  Renaming: ['Renamed', 'name', 'names'],
+};
+
+/** The first word of a label, which is what decides whether two steps match. */
+export const groupKind = (label) => String(label ?? '').trim().split(/\s+/)[0] ?? '';
+
+/** One line standing in for `count` steps that all began with the same word. */
+export function groupLabel(label, count) {
+  if (count <= 1) return String(label ?? '');
+  const g = GROUPS[groupKind(label)];
+  if (!g) return `${label} (+${count - 1} more)`;
+  const [past, one, many] = g;
+  return `${past} ${count} ${count === 1 ? one : many}`;
+}
+
+/** The part of a label after its opening word: the file or command it is about. */
+export const groupTarget = (label) => String(label ?? '').trim().split(/\s+/).slice(1).join(' ');
+
+/**
+ * One narration line, standing for everything that happened under it.
+ *
+ * The transcript is a record of what was done, not a copy of what was
+ * written. A 539-line file printed into it buries the answer and tells the
+ * reader nothing they could not get from the file itself, so a change is its
+ * two numbers. Several steps on one file stay one line naming that file;
+ * several files become a count.
+ */
+export function runLine({ label, count = 1, targets = [], added = 0, removed = 0 }) {
+  const counts = added || removed
+    ? ` ${chalk.hex('#3fb950')(`+${added}`)} ${chalk.hex('#f2939c')(`-${removed}`)}`
+    : '';
+  if (count <= 1) return `${label}${counts}`;
+
+  const g = GROUPS[groupKind(label)];
+  const unique = [...new Set(targets.filter(Boolean))];
+  if (g && unique.length === 1) return `${g[0]} ${unique[0]}${counts}`;
+  if (!g) return `${label} (+${count - 1} more)${counts}`;
+  return `${g[0]} ${count} ${count === 1 ? g[1] : g[2]}${counts}`;
+}

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; }
+}