ucode-agent 1.5.0 → 1.6.0

package/src/tools/shell.js

@@ -175,6 +175,14 @@ function stopHint(pid) {
  * is ready, it exits, or the wait runs out. Whichever comes first is reported
  * with the URL it is actually listening on.
  */
+/** Dev servers that said they were ready, newest last — for opening the app when a turn ends. */
+const readyServers = [];
+
+/** Servers that became ready at or after `since` (epoch ms). */
+export function serversReadySince(since = 0) {
+  return readyServers.filter((s) => s.at >= since);
+}
+
 function startServer(command, workdir, { env } = {}) {
   return new Promise((resolve, reject) => {
     let log;
@@ -292,6 +300,7 @@ function startServer(command, workdir, { env } = {}) {
       if ((ready && url) || graceOver || (ready && Date.now() - started > 1500)) {
         finish(() => {
           const where = url ? tidyUrl(url) : null;
+          if (where) readyServers.push({ url: where, pid: child.pid, at: Date.now() });
           return result(
             describeRun([
               `Running in the background as PID ${child.pid}, ready after ${seconds}s.`,
@@ -460,6 +469,78 @@ async function awaitInstall(command, workdir, onOutput) {
   return out;
 }
 
+// ---------------------------------------------------------------------------
+// What a failed build is really asking for
+// ---------------------------------------------------------------------------
+
+/**
+ * Plain next steps for the build failures that send a model down a hole.
+ *
+ * Measured: a missing shadcn component failed the build, and instead of
+ * adding it the model spent a dozen steps listing node_modules, then deleted
+ * the app and started over. The error names exactly what is missing; this
+ * turns that into the one command that fixes it.
+ */
+export function buildHints(output, dir = null) {
+  const hints = [];
+  const seen = new Set();
+  const add = (key, text) => {
+    if (seen.has(key)) return;
+    seen.add(key);
+    hints.push(text);
+  };
+
+  const UI = /(?:Can't resolve|Cannot find module) '@\/components\/ui\/([\w-]+)'/g;
+  for (const m of output.matchAll(UI)) {
+    add(`ui:${m[1]}`, `The shadcn component "${m[1]}" is not in this project. Add it with ` +
+      `\`npx shadcn@latest add ${m[1]} -y\` (cwd: the app folder), then build again. ` +
+      'Do not look inside node_modules.');
+  }
+
+  const PKG = /(?:Can't resolve|Cannot find module) '((?:@[\w.-]+\/)?[\w.-]+)(\/[^']*)?'/g;
+  for (const m of output.matchAll(PKG)) {
+    const [, pkg, subpath] = m;
+    if (pkg.startsWith('.')) continue;
+    if (subpath && dir && installed(dir, pkg)) {
+      // Installed, but that path inside it does not exist: an import copied
+      // from an older version. Installing it again changes nothing.
+      add(`sub:${pkg}${subpath}`, `"${pkg}" is installed, but "${pkg}${subpath}" does not exist — ` +
+        `that path is from an older version. Import from "${pkg}" itself` +
+        (pkg === 'next-themes'
+          ? '; for the provider\'s props use `React.ComponentProps<typeof NextThemesProvider>`.'
+          : ', or check its package.json "exports" for the right path.') +
+        ' Do not reinstall it.');
+      continue;
+    }
+    add(`pkg:${pkg}`, `The package "${pkg}" is not installed. Install it with ` +
+      `\`npm install ${pkg}\` (cwd: the app folder), then build again.`);
+  }
+
+  if (/Parsing ecmascript source code failed|Expression expected|Unexpected token/.test(output)) {
+    add('syntax', 'A file does not parse. Open the file and line the error names, fix that ' +
+      'syntax, then build again.');
+  }
+
+  return hints;
+}
+
+/** Is this package installed for the project at dir (or a folder above it)? */
+function installed(dir, pkg) {
+  for (let at = path.resolve(dir); ; at = path.dirname(at)) {
+    try {
+      statSync(path.join(at, 'node_modules', pkg, 'package.json'));
+      return true;
+    } catch { /* not here */ }
+    if (path.dirname(at) === at) return false;
+  }
+}
+
+/** The folder a command really runs in: its cwd, moved by a leading `cd x &&`. */
+function effectiveDir(command, workdir) {
+  const cd = /^\s*cd\s+(?:\/d\s+)?("?)([^"&|;]+?)\1\s*(?:&&|;)\s*/i.exec(command);
+  return cd ? path.resolve(workdir.abs, cd[2].trim()) : path.resolve(workdir.abs);
+}
+
 // ---------------------------------------------------------------------------
 // run_command
 // ---------------------------------------------------------------------------
@@ -474,6 +555,11 @@ export async function runCommand({ command, cwd, timeout_ms, background }, { onO
     });
   }
 
+  // `sleep 3 && curl localhost:3000` after the server already reported ready
+  // is a wait for nothing. Measured on a real build; the sleep is dropped.
+  const napping = /^\s*(?:sleep\s+\d+(?:\.\d+)?|timeout\s+\/t\s+\d+(?:\s+\/nobreak)?)\s*(?:&&|;)\s*/i.exec(command);
+  if (napping && readyServers.length) command = command.slice(napping[0].length);
+
   if (KILLS_EVERYTHING.test(command)) {
     throw new ToolFailure({
       kind: 'suicidal_command',
@@ -618,8 +704,10 @@ export async function runCommand({ command, cwd, timeout_ms, background }, { onO
       }
 
       const count = captured.trim() ? captured.trim().split(/\r?\n/).length : 0;
+      const hints = code !== 0 ? buildHints(captured, effectiveDir(command, workdir)) : [];
+      const advice = hints.length ? `\n\nWhat to do:\n${hints.map((h) => `- ${h}`).join('\n')}` : '';
       const out = result(
-        `exit code: ${code}\n\n${body}`,
+        `exit code: ${code}\n\n${body}${advice}`,
         `exit ${code} · ${count} line${count === 1 ? '' : 's'}`
       );
       out.exitCode = code;

package/src/ui/activity.js

@@ -0,0 +1,203 @@
+/**
+ * activity.js — what the status row shows while ucode is working.
+ *
+ * A long turn is minutes of the agent doing things the user did not type and
+ * cannot see coming. The status row is the one place that says it is still
+ * going, so it has to look alive at a glance without asking to be read: a
+ * spinner that turns, a soft band of light passing across the label, the
+ * step count ticking up, and the time the turn has taken so far.
+ *
+ * Everything here is a pure function of the text and the clock, so it can be
+ * tested without a terminal and painted at any frame rate.
+ */
+
+import chalk, { Chalk } from 'chalk';
+import { dim, sky, theme, clip, SPINNER } from './theme.js';
+
+/** One painter per colour level, so a test can ask for truecolour on a pipe. */
+const painters = new Map();
+const painter = (level) => {
+  if (!painters.has(level)) painters.set(level, new Chalk({ level }));
+  return painters.get(level);
+};
+
+/** One frame every 85ms — just under twelve a second, smooth without being busy. */
+export const FRAME_MS = 85;
+
+/**
+ * A duration as a person says it: 0.4s, 14s, 2m 04s, 1h 07m.
+ *
+ * Seconds are zero-padded once there are minutes, so the text after the timer
+ * does not shift sideways every time the seconds roll from 9 to 10.
+ */
+export function formatDuration(ms) {
+  const value = Math.max(0, Number(ms) || 0);
+  if (value < 1000) return `${(value / 1000).toFixed(1)}s`;
+  const total = Math.floor(value / 1000);
+  if (total < 60) return `${total}s`;
+  const minutes = Math.floor(total / 60);
+  if (minutes < 60) return `${minutes}m ${String(total % 60).padStart(2, '0')}s`;
+  return `${Math.floor(minutes / 60)}h ${String(minutes % 60).padStart(2, '0')}m`;
+}
+
+// ---------------------------------------------------------------------------
+// The shimmer
+// ---------------------------------------------------------------------------
+
+/**
+ * The two ends of the shimmer, both blue. The resting colour is muted enough
+ * to read as secondary text beside the model name; the peak is almost white,
+ * so the band reads as light passing over the words rather than a second
+ * colour arriving.
+ */
+const REST_RGB = [0x7a, 0x96, 0xc8];
+const PEAK_RGB = [0xe6, 0xf0, 0xff];
+
+/** Half the width of the band of light, in characters. */
+const BAND = 3;
+
+/** How fast the band travels, in characters a second. */
+const SPEED = 24;
+
+/** Characters' worth of dark between one pass and the next. */
+const PAUSE = 18;
+
+/** Brightness steps. Neighbouring letters that land on the same step share one escape code. */
+const STEPS = 8;
+
+const mix = (a, b, k) => a.map((v, i) => Math.round(v + (b[i] - v) * k));
+
+/**
+ * The text with a soft band of light passing across it, left to right, then a
+ * short rest, then again.
+ *
+ * `t` is milliseconds on any clock; the band's position is a function of it,
+ * so a slow frame skips ahead rather than slowing the sweep down.
+ *
+ * Needs 256 colours or more. With 16 there are no in-between blues to fade
+ * through, and a band that jumps between two colours reads as flicker rather
+ * than light — so below that the label is simply dim, and never moves.
+ */
+export function shimmer(text, t, { level = chalk.level } = {}) {
+  const s = String(text ?? '');
+  if (!s || level < 2) return dim(s);
+
+  const cycle = s.length + BAND * 2 + PAUSE;
+  const centre = ((Math.max(0, t) / 1000) * SPEED) % cycle - BAND;
+
+  let out = '';
+  let run = '';
+  let runStep = -1;
+  const flush = () => {
+    if (!run) return;
+    const [r, g, b] = mix(REST_RGB, PEAK_RGB, runStep / STEPS);
+    out += painter(level).rgb(r, g, b)(run);
+    run = '';
+  };
+
+  for (let i = 0; i < s.length; i++) {
+    const distance = Math.abs(i - centre);
+    // A cosine falloff: brightest at the centre, fading smoothly to nothing
+    // at the edge of the band, so the light has no hard edge to it.
+    const k = distance < BAND ? (Math.cos((Math.PI * distance) / BAND) + 1) / 2 : 0;
+    const step = Math.round(k * STEPS);
+    if (step !== runStep) { flush(); runStep = step; }
+    run += s[i];
+  }
+  flush();
+  return out;
+}
+
+/**
+ * The spinner glyph for a frame, breathing slowly between two blues.
+ *
+ * The pulse is slow — a little over a second a breath — so it reads as the
+ * glyph being alive rather than as a blink.
+ */
+export function spinnerGlyph(frame, t, { level = chalk.level } = {}) {
+  const glyph = SPINNER[((frame % SPINNER.length) + SPINNER.length) % SPINNER.length];
+  if (level < 2) return theme.blue(glyph);
+  const k = (Math.sin((Math.max(0, t) / 1300) * Math.PI * 2) + 1) / 2;
+  const [r, g, b] = mix([0x4d, 0x8d, 0xff], [0x9f, 0xc6, 0xff], k);
+  return painter(level).rgb(r, g, b)(glyph);
+}
+
+// ---------------------------------------------------------------------------
+// Fitting it into the room there is
+// ---------------------------------------------------------------------------
+
+/** Shorter than this, a label is a stub that says nothing, so it goes entirely. */
+const MIN_LABEL = 10;
+
+/**
+ * The middle of the status row, fitted to `room` columns.
+ *
+ * Parts, in the order they are given up when the terminal is too narrow for
+ * all of them:
+ *
+ *   1. the "esc to stop" hint     — useful once, known after that
+ *   2. the end of the label        — clipped with an ellipsis, down to a stub
+ *   3. the step count
+ *   4. the label itself
+ *   5. the elapsed time
+ *
+ * The spinner is the last thing standing: even with a single column left the
+ * row still shows that something is happening.
+ *
+ * `meta` is a list of { text, paint, keep } — keep marks the one that survives
+ * the longest (the timer). `paint` colours the label, which is where the
+ * shimmer comes in.
+ */
+export function fitActivity({ glyph, label = '', meta = [], hint = '', paint = dim }, room) {
+  if (room < 1) return '';
+  const items = meta.filter((m) => m && m.text);
+  const kept = items.filter((m) => m.keep);
+  const text = String(label ?? '');
+
+  const width = (labelLen, list, withHint) =>
+    1 +
+    (labelLen ? 1 + labelLen : 0) +
+    (list.length ? (labelLen ? 3 : 1) + list.map((m) => m.text).join(' · ').length : 0) +
+    (withHint && hint ? 2 + hint.length : 0);
+
+  const build = (labelText, list, withHint) => {
+    let out = glyph;
+    if (labelText) out += ` ${paint(labelText)}`;
+    if (list.length) {
+      out += labelText ? dim(' · ') : ' ';
+      out += list.map((m) => (m.paint ?? dim)(m.text)).join(dim(' · '));
+    }
+    if (withHint && hint) out += `  ${dim(hint)}`;
+    return out;
+  };
+
+  if (text) {
+    if (width(text.length, items, true) <= room) return build(text, items, true);
+    if (width(text.length, items, false) <= room) return build(text, items, false);
+    for (const list of [items, kept]) {
+      const labelRoom = room - width(0, list, false) - 1 - (list.length ? 2 : 0);
+      if (labelRoom >= MIN_LABEL) return build(clip(text, labelRoom), list, false);
+    }
+  }
+  for (const list of [items, kept, []]) {
+    if (width(0, list, false) <= room) return build('', list, false);
+  }
+  return glyph;
+}
+
+/**
+ * The line a finished turn leaves in the transcript: "✓ Done in 6m 12s · 25 steps".
+ *
+ * Green for the tick, because green means done and nothing else in this
+ * theme; the rest dim, because it is a footnote to the answer above it rather
+ * than something to read first.
+ */
+export function doneLine(ms, steps) {
+  const count = steps > 0 ? ` · ${steps} step${steps === 1 ? '' : 's'}` : '';
+  return `${theme.ok('✓')} ${dim(`Done in ${formatDuration(ms)}${count}`)}`;
+}
+
+/** The step count, brighter for a moment right after it goes up. */
+export function stepPaint(justMoved) {
+  return justMoved ? sky : dim;
+}

package/src/ui/plain.js

@@ -15,6 +15,7 @@ import {
   theme, blue, sky, dim, boxTop, boxBottom, boxRow,
   BANNER, BANNER_WIDTH, SPINNER, clip, shortenPath, asLabel, padVis, visLen, planLine,
 } from './theme.js';
+import { formatDuration, doneLine } from './activity.js';
 import { renderer, render } from './markdown.js';
 
 const COMMANDS = [
@@ -227,9 +228,11 @@ export class Plain {
   }
 
   paintSpinner() {
-    const secs = Math.round((Date.now() - this.since) / 1000);
-    const line = `  ${blue(SPINNER[this.frame])} ${dim(this.spinnerText)}` +
-      (secs >= 2 ? dim(` ${secs}s`) : '');
+    const since = this.turn?.start ?? this.since;
+    const secs = Math.round((Date.now() - since) / 1000);
+    const meta = [this.turn?.steps ? `step ${this.turn.steps}` : '', secs >= 2 ? formatDuration(secs * 1000) : '']
+      .filter(Boolean).join(' · ');
+    const line = `  ${blue(SPINNER[this.frame])} ${dim(this.spinnerText)}` + (meta ? dim(` · ${meta}`) : '');
     this.output.write(`\r\x1b[K${padVis(line, this.width() - 1)}`);
   }
 
@@ -246,6 +249,22 @@ export class Plain {
     this.output.write('\r\x1b[K');
   }
 
+  // -- the turn in flight ----------------------------------------------------
+
+  turnStart() {
+    this.turn = { start: Date.now(), steps: 0 };
+  }
+
+  step() {
+    if (this.turn) this.turn.steps++;
+  }
+
+  turnEnd({ ok = true } = {}) {
+    const t = this.turn;
+    this.turn = null;
+    if (t && ok && Date.now() - t.start >= 2000) this.write(`  ${doneLine(Date.now() - t.start, t.steps)}`);
+  }
+
   // -- input ---------------------------------------------------------------
 
   nextLine() {

package/src/ui/screen.js

@@ -41,6 +41,7 @@ import {
   boxTop, boxBottom, boxRow, visLen, padVis, clip, wrapAnsi,
   shortenPath, asLabel, ensureColour, planLine, bare,
 } 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';
 
@@ -58,6 +59,7 @@ export function isLabel(text) {
 export const COMMANDS = [
   '/help', '/model', '/models', '/session', '/sessions', '/resume',
   '/new', '/remember', '/skills', '/clear', '/search', '/copy', '/exit',
+  '/stats', '/doctor', '/deploy',
 ];
 
 // ANSI ----------------------------------------------------------------------
@@ -135,6 +137,8 @@ export class Screen {
     this.onInterrupt = null;
     this.onModeChange = null;
     this.spinTimer = null;
+    this.activity = null; // the turn in flight: when it began, how many steps
+    this.tick = 0;        // animation frames painted, for the spinner
     this.pendingPrompt = null;
 
     this.cols = output.columns || 80;
@@ -164,7 +168,9 @@ export class Screen {
   }
 
   stop() {
+    this.activity = null;
     this.stopSpinner();
+    this.stopTimer();
     this.output.off?.('resize', this.onResize);
     this.input.setRawMode?.(false);
     this.input.pause();
@@ -633,14 +639,23 @@ export class Screen {
     let middle = '';
     if (this.flashText) {
       middle = dim(clip(this.flashText, between - 2));
-    } else if (this.status.busy) {
-      const frame = blue(SPINNER[this.status.frame]);
-      const secs = Math.round((Date.now() - (this.status.since || Date.now())) / 1000);
-      const elapsed = secs >= 2 ? dim(` ${secs}s`) : '';
-      const room = between - 20;
-      middle = room > 8
-        ? `${frame} ${dim(clip(this.status.text, room))}${elapsed}  ${dim('esc to stop')}`
-        : `${frame}${elapsed}`;
+    } else if (this.status.busy || this.activity) {
+      // The whole turn, not just the current tool: the timer and step count
+      // keep going through the gaps between calls, so a long build never
+      // looks like it has stopped.
+      const now = Date.now();
+      const a = this.activity;
+      const since = a?.start ?? this.status.since ?? now;
+      const meta = [];
+      if (a?.steps) meta.push({ text: `step ${a.steps}`, paint: stepPaint(now - a.movedAt < 900) });
+      if (now - since >= 1000) meta.push({ text: formatDuration(now - since), keep: true });
+      middle = fitActivity({
+        glyph: spinnerGlyph(this.tick, now),
+        label: this.status.busy ? this.status.text : 'working',
+        meta,
+        hint: 'esc to stop',
+        paint: (s) => shimmer(s, now),
+      }, between - 3);
     }
 
     // The percentage is pinned to the right border whatever is in the middle,
@@ -700,13 +715,7 @@ export class Screen {
     // `since` is what makes a long think legible: the label may not change for
     // a minute, so the seconds beside it are the proof it is still alive.
     this.status = { busy: true, text: asLabel(text), frame: 0, since: Date.now() };
-    if (!this.spinTimer) {
-      this.spinTimer = setInterval(() => {
-        this.status.frame = (this.status.frame + 1) % SPINNER.length;
-        this.paintStatus();
-      }, 80);
-      this.spinTimer.unref?.();
-    }
+    this.startTimer();
     this.paintStatus();
   }
 
@@ -717,16 +726,53 @@ export class Screen {
   }
 
   stopSpinner() {
-    if (this.spinTimer) {
-      clearInterval(this.spinTimer);
-      this.spinTimer = null;
-    }
+    if (!this.activity) this.stopTimer();
     if (this.status.busy) {
       this.status = { busy: false, text: '', frame: 0, since: 0 };
       this.paintStatus();
     }
   }
 
+  // -- the turn in flight ----------------------------------------------------
+
+  /** A turn begins: the timer and step count run until turnEnd(). */
+  turnStart() {
+    this.activity = { start: Date.now(), steps: 0, movedAt: 0 };
+    this.startTimer();
+  }
+
+  /** One more model step in this turn. */
+  step() {
+    if (!this.activity) return;
+    this.activity.steps++;
+    this.activity.movedAt = Date.now();
+  }
+
+  /** The turn is over: leave "✓ Done in 6m 12s · 25 steps" under the answer. */
+  turnEnd({ ok = true } = {}) {
+    const a = this.activity;
+    this.activity = null;
+    if (!this.status.busy) this.stopTimer();
+    if (a && ok && Date.now() - a.start >= 2000) this.push(`  ${doneLine(Date.now() - a.start, a.steps)}`);
+    this.paintStatus();
+  }
+
+  /** The animation clock: only the status row repaints, about twelve times a second. */
+  startTimer() {
+    if (this.spinTimer) return;
+    this.spinTimer = setInterval(() => {
+      this.tick++;
+      this.paintStatus();
+    }, FRAME_MS);
+    this.spinTimer.unref?.();
+  }
+
+  stopTimer() {
+    if (!this.spinTimer) return;
+    clearInterval(this.spinTimer);
+    this.spinTimer = null;
+  }
+
   // -- input ---------------------------------------------------------------
 
   nextLine() {

package/templates/next-shadcn/TEMPLATE.md

@@ -6,16 +6,16 @@ Do not re-run create-next-app or `shadcn init` — everything below is in place.
 ## Stack
 
 - Next.js 16 (App Router), React 19, TypeScript, Tailwind CSS 4
-- shadcn/ui ("base-nova" style, built on `@base-ui/react`), lucide-react icons
-- next-themes (light / dark / system), sonner toasts, date-fns
+- shadcn/ui on Radix (the standard shadcn you know — `asChild` works), lucide-react icons
+- next-themes (light / dark / system), sonner toasts, date-fns, react-day-picker
 
-Next 16 changed APIs. `AGENTS.md` explains, and `node_modules/next/dist/docs/`
+Next 16 changed some APIs. `AGENTS.md` explains, and `node_modules/next/dist/docs/`
 has the guides — check them before using an API you are unsure of.
 
 ## Already wired
 
 - `src/app/layout.tsx` — font (Geist, registered as `--font-sans`), `ThemeProvider`,
-  `TooltipProvider`, and `<Toaster />`. Call `toast()` from `sonner` anywhere.
+  `TooltipProvider`, and `<Toaster />`.
 - `src/components/theme-toggle.tsx` — a light/dark button, ready to place.
 - `src/app/globals.css` — the design tokens. The palette is a starting point:
   re-tint `--primary`, `--accent` and the neutrals for this app's direction.
@@ -23,17 +23,61 @@ has the guides — check them before using an API you are unsure of.
   (`bg-success`, `text-warning`, ...).
 - `src/app/page.tsx` — a placeholder. Replace it.
 
+`layout.tsx`, `theme-provider.tsx`, `theme-toggle.tsx`, `src/lib/utils.ts` and
+everything in `src/components/ui/` are finished and build. Use them; do not
+rewrite them — a rewrite from memory brings back APIs that no longer exist.
+
 ## Components in `src/components/ui/`
 
-alert-dialog, avatar, badge, button, calendar, card, checkbox, command, dialog,
-dropdown-menu, input, input-group, label, popover, progress, scroll-area, select,
-separator, sheet, skeleton, sonner, switch, tabs, textarea, tooltip
+accordion, alert-dialog, avatar, badge, button, calendar, card, checkbox, collapsible, command, dialog, dropdown-menu, hover-card, input-group, input, label, popover, progress, radio-group, scroll-area, select, separator, sheet, skeleton, slider, sonner, switch, table, tabs, textarea, toggle-group, toggle, tooltip
+
+Anything else: `npx shadcn@latest add <name> -y` with cwd set to this folder.
+
+## APIs that are easy to get wrong
+
+```tsx
+// Toasts — sonner. A message first, options second. There is no toast({ title }).
+import { toast } from "sonner";
+toast.success("Saved");
+toast("Task deleted", { description: "Buy milk", action: { label: "Undo", onClick: () => restore() } });
+
+// Slider — value is an ARRAY, even for one thumb.
+<Slider value={[tip]} onValueChange={([v]) => setTip(v)} min={0} max={30} step={1} />
+
+// Select — value is a string.
+<Select value={list} onValueChange={(v: string) => setList(v)}>
+  <SelectTrigger><SelectValue placeholder="Pick a list" /></SelectTrigger>
+  <SelectContent><SelectItem value="inbox">Inbox</SelectItem></SelectContent>
+</Select>
+
+// Date picker — Calendar inside a Popover.
+<Popover>
+  <PopoverTrigger asChild><Button variant="outline">{date ? format(date, "PPP") : "Pick a date"}</Button></PopoverTrigger>
+  <PopoverContent className="w-auto p-0"><Calendar mode="single" selected={date} onSelect={setDate} /></PopoverContent>
+</Popover>
+
+// Toggle group — value is a string for type="single".
+<ToggleGroup type="single" value={preset} onValueChange={(v) => v && setPreset(v)}>
+  <ToggleGroupItem value="15">15%</ToggleGroupItem>
+</ToggleGroup>
+
+// Anything using useState, events, localStorage or browser APIs needs "use client"
+// as the first line of its file.
+
+// localStorage — read it in useEffect, never in render or a useState initializer:
+// the page is also rendered on the server, where localStorage does not exist.
+const [bill, setBill] = useState("");
+useEffect(() => { setBill(localStorage.getItem("bill") ?? ""); }, []);
+useEffect(() => { localStorage.setItem("bill", bill); }, [bill]);
 
-Anything else: `npx shadcn@latest add <name> -y`.
+// next-themes — there is no "next-themes/dist/types". Import from "next-themes".
+```
 
 ## Conventions
 
+- Components are named exports — `export function BillInput()` — imported with
+  braces: `import { BillInput } from "@/components/calculator/bill-input"`.
+  Only `page.tsx` and `layout.tsx` use `export default`.
 - One component per file, grouped by feature: `src/components/<feature>/`.
 - Shared types in `src/lib/types.ts`, helpers in `src/lib/`.
-- `"use client"` only on components that need state or events.
 - `cn()` from `@/lib/utils` to merge class names.