makersclaw 0.3.2 → 0.5.1

package/templates/next/files/check/run.mjs

@@ -48,7 +48,7 @@ const STATIC_ONLY = process.argv.includes("--static");
 // update` lays both folders again.
 // Exact names AND extensions: Next resolves .js before .jsx, so a
 // components/ui/depiction.js beside depiction.jsx would win unseen.
-const KIT = /^components\/(?:ui\/(?:cx|index)\.js|ui\/(?:radio|toggle|button-group|avatar|breadcrumb|pagination|button|collapsible|item|table|depiction|feedback|stat|distribution|swatch|steps|separator|scroll-area|field|icon|menu|context-menu|popover|calendar|date-picker|tooltip|notice|sheet|tabs|slider|input-group|image|file-input|input-otp|command|combobox|rating|toast|carousel|resizable)\.jsx|parts\/(?:index|sample)\.js|parts\/(?:fixture|record-switcher)\.jsx)$/;
+const KIT = /^components\/(?:ui\/(?:cx|index)\.js|ui\/(?:radio|toggle|button-group|avatar|breadcrumb|pagination|button|collapsible|item|table|depiction|feedback|stat|distribution|swatch|steps|separator|scroll-area|field|icon|menu|context-menu|popover|calendar|date-picker|tooltip|notice|sheet|tabs|slider|input-group|image|file-input|input-otp|command|combobox|rating|toast|carousel|resizable)\.jsx|parts\/(?:index|sample)\.js|parts\/(?:fixture|record-switcher|live-work)\.jsx)$/;
 
 // The pins: sha256 of every fixed file, written by `makersclaw init` and
 // `makersclaw add` (check/pins.json). Read first, because a BLOCK is
@@ -73,17 +73,35 @@ const DEPICTION = /^components\/depictions\//;
  *  preview can follow typing). Never the shell, the kit or lib/. */
 const FRAME_HOST = /^(?:surfaces\/[^/]+\.jsx|components\/[^/]+\.jsx)$/;
 
+// Folders a build, an install or a tool leaves in the app, never its
+// source: ONE list for every walk here — the rules, the smoke build's
+// freshness, its copy in the sandbox. Until 0.5.0 each walk named its own
+// two or three, and the rules read a temporary .next-stub a build had
+// left (phase-planner, 2026-09-23; CLAW-FIXES #36). A name ending in *
+// is a prefix (.next, .next-check, .next-stub…). node_modules and .git
+// are skipped wherever they are; the rest at the app's root only, where
+// the build puts them: a folder of the app's own may be called out/.
+const BUILD_DIRS = ["node_modules", ".git", ".next*", "out", ".turbo", ".cache"];
+const ANY_DEPTH = new Set(["node_modules", ".git"]);
+const isBuildDir = (name) => BUILD_DIRS.some((d) => (d.endsWith("*") ? name.startsWith(d.slice(0, -1)) : name === d));
+/** Is this path, relative to the app, inside a folder that is not source? */
+function notSource(rel) {
+  const parts = rel.split("/");
+  return isBuildDir(parts[0]) || parts.some((part) => ANY_DEPTH.has(part));
+}
+
 // Files the rules skip: the kit (it owns the native elements and the
-// fallback colours), the fixed template files, machine folders. Depiction
-// files are NOT skipped — the `depictions` rule reads them.
+// fallback colours), the fixed template files, the check itself. Build
+// folders never reach this list (walk, below). Depiction files are NOT
+// skipped — the `depictions` rule reads them.
 const SKIP = [
-  /^node_modules\//,
-  /^\.next(-check)?\//,
   /^check\//,
   KIT,
   /^app\/globals\.css$/,
   /^lib\/(db|data|actions|claw|platform|hooks|sample)\.js$/,
-  /^app\/(layout|page|error|global-error|not-found|error-relay|auto-refresh)\.jsx$/,
+  /^app\/(layout|page|error|global-error|not-found|error-relay|auto-refresh|escape-relay)\.jsx$/,
+  /^app\/frame\.js$/,
+  /^app\/claw-alive\/route\.js$/,
   /^app\/s\/\[key\]\/page\.jsx$/,
   /^middleware\.js$/,
   /^next\.config\.mjs$/,
@@ -92,12 +110,12 @@ const SKIP = [
   /\.(md|sql|json|lock)$/,
 ];
 
-// Only the build's own folders are skipped: a dot-named module
+// Only build folders are skipped (BUILD_DIRS): a dot-named module
 // (components/.pictures.js) is a module Next bundles all the same.
 function walk(dir, out = []) {
   for (const name of readdirSync(dir)) {
-    if (name === "node_modules" || name === ".git" || name === ".next" || name === ".next-check") continue;
     const full = join(dir, name);
+    if (notSource(relative(ROOT, full))) continue;
     if (statSync(full).isDirectory()) walk(full, out);
     else out.push(full);
   }
@@ -223,7 +241,10 @@ const ATTRS = String.raw`(?:"[^"]*"|'[^']*'|\{(?:[^{}]|\{[^{}]*\})*\}|[^>"'{])*`
   if (!L.count) ok("controls", "every control is a kit part");
 }
 
-// 3. The example is a fixture in code — never a row in the shared database.
+// 3. The example is a fixture in code — never a row in the shared database
+//    — and since 0.4.0 it shows only outside a workspace: useFixture reads
+//    the layout's <Examples allowed>, off in every workspace app, where an
+//    empty table shows its live work (LiveEmpty) instead.
 {
   const L = limiter("examples");
   scan(/\bINSERT\s+INTO\b/i, (f, m, line) => L.hit(`${f.path}:${line}`, "insert", "SQL INSERT outside lib/actions.js; insertRow() is the write door, and a fixture is never inserted"), files);
@@ -234,11 +255,14 @@ const ATTRS = String.raw`(?:"[^"]*"|'[^']*'|\{(?:[^{}]|\{[^{}]*\})*\}|[^>"'{])*`
     // them is the one that must run them through useFixture(). A depiction
     // never holds one: its rows arrive as props from the surface.
     const renders = /<\/|\/>/.test(f.code);
-    const uses = /\buseFixture\(|\bmarkSample\(/.test(f.code);
+    // Only useFixture reads the layout's <Examples allowed>: markSample
+    // gives rows their ids and nothing else, so a surface that marks its
+    // own fixture would show it inside a workspace too.
+    const uses = /\buseFixture\(/.test(f.code);
     const server = /from\s*["']\.\.?\/lib\/data["']/.test(f.code);
-    if (renders && !uses) L.hit(`${f.path}:${lineOf(f.code, decl.index)}`, "fixture", `${decl[1]} is rendered without useFixture() — the example shows only while the table is empty, and is never saved${DEPICTION.test(f.path) ? " (a depiction takes its rows as props; the surface holds the fixture)" : server ? " (a server surface cannot call it: pass the rows down and let the client component run useFixture)" : ""}`);
+    if (renders && !uses) L.hit(`${f.path}:${lineOf(f.code, decl.index)}`, "fixture", `${decl[1]} is rendered without useFixture() — examples show only outside a workspace (useFixture); a workspace app opens empty${DEPICTION.test(f.path) ? " (a depiction takes its rows as props; the surface holds the fixture)" : server ? " (a server surface cannot call it: pass the rows down and let the client component run useFixture)" : ""}`);
   }
-  if (!L.count) ok("examples", "fixtures stay in code (useFixture), nothing INSERTs one");
+  if (!L.count) ok("examples", "examples show only outside a workspace (useFixture); a workspace app opens empty");
 }
 
 // 4. The manifest names surfaces that exist, once each, under keys that are free.
@@ -270,7 +294,10 @@ const surfaceKeys = [];
 }
 
 // 5. Every icon named exists in the sprite (a depiction's own glyphs are
-//    not sprite names).
+//    not sprite names). The sprite is a kit file, fixed like the rest (the
+//    next rule refuses an edit to it), so the way out is another name —
+//    until 0.3.3 this line said "Add the glyph there", a door the next
+//    rule shuts.
 {
   const sprite = readFileSync(join(ROOT, "components/ui/icon.jsx"), "utf8");
   const names = new Set([...sprite.matchAll(/^\s+"?([a-z][a-z0-9-]*)"?:\s*"/gm)].map((m) => m[1]));
@@ -282,7 +309,7 @@ const surfaceKeys = [];
   scan(/\bicon(?:=|:\s*)["']([a-z][a-z0-9-]*)["']/, (f, m, line) => check(f, m[1], line));
   if (missing.size) {
     const where = [...missing].map(([n, at]) => `"${n}" (${at})`).join(", ");
-    fail("icons", "sprite", `not in components/ui/icon.jsx: ${where}. Add the glyph there, or pick one of: ${[...names].join(" ")}`);
+    fail("icons", "sprite", `not in components/ui/icon.jsx: ${where}. The kit is fixed, so pick one of: ${[...names].join(" ")}`);
   } else ok("icons", "every icon name exists");
 }
 
@@ -531,12 +558,12 @@ const surfaceKeys = [];
 
 // 6. Smoke: the app, built and started, answers every surface.
 
-/** Newest mtime among the app's own sources (what a build reads). */
+/** Newest mtime among the app's own sources (what a build reads): walk
+ *  leaves the build folders out, and check/ is not built. */
 function newestSource() {
   let newest = 0;
   for (const f of walk(ROOT)) {
-    const rel = relative(ROOT, f);
-    if (/^(node_modules|\.next|\.next-check|check)\//.test(rel)) continue;
+    if (/^check\//.test(relative(ROOT, f))) continue;
     newest = Math.max(newest, statSync(f).mtimeMs);
   }
   return newest;
@@ -571,7 +598,7 @@ function copySources(dir) {
     dereference: false,
     filter: (src) => {
       const rel = relative(ROOT, src);
-      return !/^(node_modules|\.next|\.next-check|check)(\/|$)/.test(rel);
+      return !notSource(rel) && !/^check(\/|$)/.test(rel);
     },
   });
   const link = join(dir, "node_modules");
@@ -625,6 +652,12 @@ async function smoke() {
     const home = await fetch(`${origin}/`, { redirect: "manual" });
     results.push(`/ → ${home.status}`);
     if (!(home.status === 200 || (home.status >= 300 && home.status < 400))) fail("smoke", "/", `answered ${home.status}`);
+    // The route app/auto-refresh.jsx asks before every refresh. Anything
+    // but its 204 and the app never refreshes again: its rows go stale
+    // while the agent writes them, and nothing on the page says so.
+    const alive = await fetch(`${origin}/claw-alive`, { redirect: "manual" });
+    results.push(`/claw-alive → ${alive.status}`);
+    if (alive.status !== 204) fail("smoke", "/claw-alive", `answered ${alive.status}, not 204: app/auto-refresh.jsx will never refresh this app. \`makersclaw update\` restores app/claw-alive/route.js`);
     for (const key of surfaceKeys) {
       const res = await fetch(`${origin}/s/${encodeURIComponent(key)}`);
       const body = await res.text();

package/templates/next/files/components/parts/fixture.jsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { useMemo, useState } from "react";
+import { createContext, useContext, useMemo, useState } from "react";
 import { markSample } from "./sample";
 import { Button, Notice } from "../ui";
 
@@ -20,18 +20,43 @@ import { Button, Notice } from "../ui";
 //
 // `rows` keeps its identity between renders (an effect may depend on it);
 // declare SAMPLE at module level, not inside the component, so it does too.
+//
+// Examples show only OUTSIDE a Makersclaw workspace: the store's authoring
+// loop, a shadcn project. Inside one, an app never shows example data (up
+// to 0.3.x it did, until its table had a row): an empty table stays empty
+// and the screen shows what its agent is doing instead. app/layout.jsx
+// decides it per request and says so through <Examples allowed>; with no
+// provider at all — a shadcn project — the answer is yes. The provider
+// lives here, not in lib/, so the parts still travel as one folder.
 
 const NONE = [];
+const nothing = () => {};
+
+const ExamplesContext = createContext(true);
+
+/** Whether the parts below may show an example. The layout wraps the app
+ *  in it; `allowed` is false inside a workspace. */
+export function Examples({ allowed, children }) {
+  return <ExamplesContext.Provider value={Boolean(allowed)}>{children}</ExamplesContext.Provider>;
+}
+
+/** true unless an <Examples allowed={false}> is above. */
+export function useExamples() {
+  return useContext(ExamplesContext);
+}
 
 export function useFixture(rows, sample, { idColumn = "id" } = {}) {
+  const allowed = useExamples();
   const [cleared, setCleared] = useState(false);
-  const isFixture = !cleared && (!rows || rows.length === 0) && Array.isArray(sample) && sample.length > 0;
+  const isFixture = allowed && !cleared && (!rows || rows.length === 0) && Array.isArray(sample) && sample.length > 0;
   const fixtureRows = useMemo(() => markSample(sample, idColumn), [sample, idColumn]);
+  // With examples off there is no example to clear or bring back: the
+  // real rows, however few, are all a surface gets.
   return {
     rows: isFixture ? fixtureRows : rows ?? NONE,
     isFixture,
-    clear: () => setCleared(true),
-    restore: () => setCleared(false),
+    clear: allowed ? () => setCleared(true) : nothing,
+    restore: allowed ? () => setCleared(false) : nothing,
   };
 }
 

package/templates/next/files/components/parts/index.js

@@ -1,5 +1,6 @@
 // Parts: the kit's pieces bound to this template's data layer. Each
 // exists because an app got it wrong once; each carries the behaviour
 // that makes it right. README §3b.
-export { useFixture, isSample, FixtureNotice } from "./fixture";
+export { Examples, useExamples, useFixture, isSample, FixtureNotice } from "./fixture";
+export { LiveWork, LiveEmpty, liveWords } from "./live-work";
 export { RecordSwitcher } from "./record-switcher";

package/templates/next/files/components/parts/live-work.jsx

@@ -0,0 +1,235 @@
+"use client";
+
+import { isValidElement, useState } from "react";
+import { Button, Icon, StatusDot, cx } from "../ui";
+
+// The empty state that shows the work coming, never an example. Inside a
+// Makersclaw workspace a table opens empty (fixture.jsx: examples show
+// only outside one), and a table is usually empty because its agent has
+// not got to it yet — or is on it right now. So the empty block says
+// which: the ask in flight on this surface (its line, whose ask it is,
+// what it waits behind, the one press it needs), or, with nothing in
+// flight, what would appear here and the one way to make it. Up to 0.3.x
+// an example filled that gap; since 0.4.0 no app shows example data in a
+// workspace (claw's docs/JARVIS-PLATFORM.md §9.6 and §12, promise 6).
+//
+//   const work = useRequests({ surface: "deals" });           // lib/hooks.js
+//   if (!rows.length) {
+//     return <LiveEmpty work={work} surface="deals" icon="inbox" title="No deals yet"
+//                       line="Ask the agent to find some, or add one." action={{ label: "Add a deal", onClick: add }} />;
+//   }
+//
+// Props in, callbacks out: `work` is useRequests()'s answer as it stands,
+// and the row calls back through it — work.open(request) opens the
+// conversation in the desk's agent column (where a need is answered),
+// work.stop(id) stops an ask. The part imports nothing from lib/, so the
+// parts still travel as one folder; in a shadcn project, with no `work`,
+// it is the plain empty block.
+
+// A request's status is one of eleven (claw's shared/src/requests.ts;
+// lib/hooks.js keeps the same list — this folder may not import it).
+// Every step before the agent is on it reads as Working: the member asked
+// for the result, not for its plumbing.
+const WORDS = new Map([
+  ["routing", "Working"],
+  ["queued", "Working"],
+  ["installing", "Working"],
+  ["setting_up", "Working"],
+  ["building", "Working"],
+  ["working", "Working"],
+  ["needs_you", "Needs you"],
+  ["answered", "Answered"],
+  ["done", "Done"],
+  ["stopped", "Stopped"],
+  ["didnt_finish", "Didn't finish"],
+]);
+
+/** The seven statuses in which the work still goes. `answered` is open
+ *  but not live: the agent answered and waits, and no row is coming. */
+const LIVE = new Set(["routing", "queued", "installing", "setting_up", "building", "working", "needs_you"]);
+
+/** A scheduled run's statuses while it goes (a brief's, not a request's:
+ *  _claw/requests returns the run only in one of these). */
+const RUN_LIVE = new Set(["queued", "planning", "awaiting_approval", "in_progress"]);
+
+/** The status word for a request or a bare status: "Working", "Needs
+ *  you", "Answered", "Done", "Stopped", "Didn't finish". An unknown
+ *  status is "" — a word the platform has not taught this part yet is
+ *  better unsaid than guessed. */
+export function liveWords(requestOrStatus) {
+  const status = typeof requestOrStatus === "string" ? requestOrStatus : requestOrStatus?.status;
+  return WORDS.get(status) ?? "";
+}
+
+function runGoing(run) {
+  return Boolean(run && typeof run === "object" && (run.status == null || RUN_LIVE.has(run.status)));
+}
+
+/**
+ * One piece of work in flight, as a row: a pulsing dot, the request's
+ * line, whose request it is when it is not yours, what it waits behind.
+ * A need gets the warning tone and Answer (it is answered in the desk's
+ * column, where the conversation lives); your own ask gets Stop. With no
+ * request, a scheduled run that is going shows its title.
+ *
+ *   request   one of useRequests().live (lib/hooks.js)
+ *   run       useRequests().run, shown when there is no request
+ *   onOpen    (request) → open its conversation; Answer needs it
+ *   onStop    (id) → stop it; Stop needs it, and shows only to the asker
+ */
+export function LiveWork({ request, run, onOpen, onStop, className }) {
+  const [stopping, setStopping] = useState(false);
+
+  if (request && typeof request === "object") {
+    const status = request.status;
+    const word = liveWords(request);
+    const needs = status === "needs_you";
+    const queued = status === "queued";
+    const theirs = request.mine === false;
+    const main = request.line || word || request.title || "";
+    const meta = [];
+    if (theirs) meta.push(`from ${request.asker_name || "a teammate"}'s request`);
+    // claw's line for a queued request already says "Queued · after …"
+    // (lineOf, shared/src/requests.ts); say it once, under a line that
+    // does not.
+    if (queued && !/^Queued\b/.test(main)) meta.push(`Queued · after ${request.queued?.after_title || "the job before it"}`);
+    // Only the asker answers: a teammate's need opens on "Waiting on …"
+    // in the desk, so it is shown, not offered.
+    const answer = needs && !theirs && onOpen;
+    const going = LIVE.has(status);
+    const stop = !needs && going && request.mine === true && onStop;
+    const onStopClick = async () => {
+      setStopping(true);
+      try {
+        await onStop(request.id);
+      } finally {
+        setStopping(false);
+      }
+    };
+    return (
+      <Row
+        tone={needs ? "warning" : going && !queued ? "primary" : "neutral"}
+        pulse={going && !queued}
+        word={word}
+        warn={needs}
+        main={main}
+        meta={meta}
+        className={className}
+      >
+        {answer ? (
+          <Button size="sm" variant="primary" onClick={() => onOpen(request)}>
+            Answer
+          </Button>
+        ) : stop ? (
+          <Button size="sm" variant="quiet" loading={stopping} onClick={onStopClick}>
+            Stop
+          </Button>
+        ) : null}
+      </Row>
+    );
+  }
+
+  if (runGoing(run)) {
+    return (
+      <Row tone="primary" pulse word="Working" main={run.title || "Working"} meta={run.title ? ["Working"] : []} className={className} />
+    );
+  }
+  return null;
+}
+
+function Row({ tone, pulse, word, warn, main, meta, className, children }) {
+  return (
+    <div
+      className={cx(
+        "flex items-center gap-3 rounded-lg border bg-card px-3 py-2.5 text-left text-sm text-card-foreground",
+        warn ? "border-warning/50" : "border-border",
+        className,
+      )}
+    >
+      <StatusDot tone={tone} pulse={pulse} label={word || "Working"} hideLabel />
+      <div aria-live="polite" className="min-w-0 flex-1">
+        <p className="truncate font-medium">{main}</p>
+        {meta.length ? <p className="truncate text-xs text-muted-foreground">{meta.join(" · ")}</p> : null}
+      </div>
+      {children ? <div className="flex shrink-0 items-center gap-2">{children}</div> : null}
+    </div>
+  );
+}
+
+/** Does a request belong to this empty state? Each filter given is a way
+ *  in (lib/hooks.js reads it the same way): an ask made on this surface,
+ *  or work on this job wherever it was asked for. No filter: any. */
+function belongs(request, surface, job) {
+  if (!surface && !job) return true;
+  return Boolean((surface && request.surface === surface) || (job && request.job_key === job));
+}
+
+// The one to show when several are in flight: what needs an answer, then
+// what is working, then what waits in the queue; yours before a
+// teammate's; the newest first.
+const rank = (r) => (r.status === "needs_you" ? 0 : r.status === "queued" ? 2 : 1);
+
+function pickRequest(live, surface, job) {
+  const list = (Array.isArray(live) ? live : [])
+    .map((r, i) => ({ r, i }))
+    .filter(({ r }) => r && typeof r === "object" && LIVE.has(r.status) && belongs(r, surface, job));
+  list.sort(
+    (a, b) =>
+      rank(a.r) - rank(b.r) ||
+      Number(b.r.mine === true) - Number(a.r.mine === true) ||
+      String(b.r.created_at ?? "").localeCompare(String(a.r.created_at ?? "")) ||
+      a.i - b.i,
+  );
+  return list[0]?.r ?? null;
+}
+
+const FRAME = "grid place-items-center rounded-lg border border-dashed border-border px-6 py-10 text-center";
+
+/**
+ * What an empty collection shows in a workspace. With work in flight for
+ * this surface or job — or the app's scheduled run going — the work, as
+ * a LiveWork row, and "Rows appear here as they land". With none, the
+ * empty block: icon, title, line and the one action that fills it.
+ *
+ *   work      useRequests()'s answer ({ live, run, open, stop }); absent
+ *             in a shadcn project, where only the empty block shows
+ *   surface   the surface key its asks carry; job — the job key whose
+ *             work lands here. Either is a way in; neither: any live work
+ *   icon      the empty block's glyph (inbox)
+ *   title     what would be here: "No deals yet"
+ *   line      how it gets here: "Ask the agent to find some, or add one."
+ *   action    { label, onClick, href, icon, variant } for a Button, or an
+ *             element as it is
+ *   children  anything the surface adds under either state
+ */
+export function LiveEmpty({ work, surface, job, icon = "inbox", title, line, action, children, className }) {
+  const request = pickRequest(work?.live, surface, job);
+  const run = !request && runGoing(work?.run) ? work.run : null;
+
+  if (request || run) {
+    return (
+      <div className={cx(FRAME, "gap-3", className)}>
+        <LiveWork request={request} run={run} onOpen={work.open} onStop={work.stop} className="w-full max-w-md" />
+        <p className="text-sm text-muted-foreground">Rows appear here as they land</p>
+        {children}
+      </div>
+    );
+  }
+
+  const button = isValidElement(action) ? (
+    action
+  ) : action && typeof action === "object" && action.label ? (
+    <Button variant={action.variant ?? "secondary"} icon={action.icon} href={action.href} onClick={action.onClick}>
+      {action.label}
+    </Button>
+  ) : null;
+  return (
+    <div className={cx(FRAME, "gap-2", className)}>
+      <Icon name={icon} size={22} className="text-muted-foreground" />
+      {title ? <p className="text-sm font-medium">{title}</p> : null}
+      {line ? <p className="max-w-prose text-sm text-muted-foreground">{line}</p> : null}
+      {button ? <div className="mt-2">{button}</div> : null}
+      {children}
+    </div>
+  );
+}

package/templates/next/files/components/ui/button.jsx

@@ -9,7 +9,12 @@ import { Spinner } from "./feedback";
 // by hand in a surface: the look is the workspace's, the behaviour is
 // the browser's, and this is the only place both meet.
 //
-//   variant   primary (the one main action per surface) · secondary ·
+//   variant   primary (the one main action per surface, filled with
+//             --primary, the app's accent) · secondary (the default, the
+//             workspace's neutral --secondary: a Button that does not say
+//             primary is never the accent — a surface's "Add guest"
+//             written without variant="primary" came out dark grey on a
+//             coral app, 2026-09-25) ·
 //             quiet (no fill) · danger (destructive, red text) ·
 //             link (text only: inline, no box, padding or min-height — it
 //             wraps and truncates with the sentence it sits in) · nav (a navigation row: quiet, full

package/templates/next/files/components/ui/calendar.jsx

@@ -139,6 +139,30 @@ export function formatDate(s, options = { dateStyle: "medium" }, locale) {
   return d ? plainSpaces(new Intl.DateTimeFormat(locale, { ...options, timeZone: "UTC" }).format(d)) : "";
 }
 
+/** Any date a row holds → a Date to show in the reader's own time; null
+ *  when it is none. A day ("2026-09-28", what a `date` column reads as)
+ *  is that day's LOCAL midnight: new Date("2026-09-28") is UTC's
+ *  midnight, the 27th everywhere west of Greenwich, and a screen that
+ *  shows it, then saves what it shows, moves the day back by one. A Date
+ *  stays as it is; an ISO timestamp or epoch milliseconds go through
+ *  new Date(). For a day alone, formatDate and the helpers above need no
+ *  Date at all; this is for code that mixes days with instants (a
+ *  comment's time, "due" beside "sent at"). */
+export function toLocalDate(value) {
+  if (value === null || value === undefined || value === "") return null;
+  if (value instanceof Date) return Number.isNaN(value.getTime()) ? null : value;
+  const day = typeof value === "string" ? parseDate(value) : null;
+  if (day) {
+    // setFullYear, not new Date(y, m, d): that one reads years 0–99 as 19xx.
+    const local = new Date(0);
+    local.setFullYear(day.getUTCFullYear(), day.getUTCMonth(), day.getUTCDate());
+    local.setHours(0, 0, 0, 0);
+    return local;
+  }
+  const d = new Date(value);
+  return Number.isNaN(d.getTime()) ? null : d;
+}
+
 // The week's first day for a locale: Intl's own answer where the browser
 // has it (getWeekInfo), else CLDR's regions that start on Sunday or
 // Saturday; everyone else starts on Monday.

package/templates/next/files/components/ui/date-picker.jsx

@@ -275,6 +275,15 @@ export function DatePicker({
  *   value, onChange(date | null), defaultValue, min, max, disabled
  *   (true, or a function for the Calendar's days), name, invalid, size,
  *   locale (the Calendar's; the field itself follows the browser), today
+ *   clearable  an × beside the calendar button once the field holds a
+ *              date (false — DatePicker's is true)
+ *
+ * Every other prop goes onto the <input>, so a prop this part names must
+ * be taken out here: until 0.3.3 `clearable` was DatePicker's alone, and
+ * a surface that wrote <DateInput clearable> put it on the <input> ("Received
+ * `true` for a non-boolean attribute clearable", a podcast guest sheet,
+ * 2026-09-25). It is DateInput's now too, off unless asked, so a field
+ * that did not ask keeps its width.
  */
 export function DateInput({
   id,
@@ -290,6 +299,7 @@ export function DateInput({
   locale,
   today,
   weekStartsOn,
+  clearable = false,
   className,
   ...rest
 }) {
@@ -299,6 +309,7 @@ export function DateInput({
   const [month, setMonth] = useState(null);
   const off = disabled === true;
   const out = !!value && ((min && value < min) || (max && value > max));
+  const showClear = clearable && !off && !!value;
 
   function set(v) {
     if (valueProp === undefined) setOwn(v);
@@ -318,12 +329,14 @@ export function DateInput({
         invalid={invalid || out}
         onChange={(e) => set(e.target.value || null)}
         className={cx(
-          "pr-12 [&::-webkit-calendar-picker-indicator]:hidden tabular-nums",
+          showClear ? "pr-20" : "pr-12",
+          "[&::-webkit-calendar-picker-indicator]:hidden tabular-nums",
           size === "sm" && "min-h-9",
         )}
         {...rest}
       />
-      <span className={cx("absolute right-1", size === "sm" ? "top-0" : "top-1")}>
+      <span className={cx("absolute right-1 flex", size === "sm" ? "top-0" : "top-1")}>
+        {showClear ? <IconButton icon="x" label="Clear date" size="sm" onClick={() => set(null)} /> : null}
         <Popover
           open={open}
           onOpenChange={(next) => {

package/templates/next/files/components/ui/field.jsx

@@ -8,10 +8,19 @@ import { cx } from "./cx";
 // validation, autofill). Wrap one in <Field> for its label, hint and
 // error — never a bare <input> with a <div> label beside it.
 
-const CONTROL =
-  "w-full min-h-11 rounded-md border border-input bg-background px-3 text-sm text-foreground " +
+const BOX =
+  "min-h-11 rounded-md border border-input bg-background px-3 text-sm text-foreground " +
   "placeholder:text-muted-foreground outline-none focus-visible:ring-2 focus-visible:ring-ring " +
   "disabled:cursor-not-allowed disabled:opacity-50 aria-[invalid=true]:border-destructive";
+const CONTROL = `w-full ${BOX}`;
+
+// An Input is as wide as its column unless the caller's className gives
+// it a width (w-24, w-auto, w-[12rem], size-10), which then stands in
+// for w-full. cx does not merge classes: with both, the rule later in the
+// stylesheet wins, and Tailwind writes w-full after w-24, w-auto, w-fit
+// and w-[…] — until 0.5.1 those did nothing on an Input. A width under a
+// breakpoint (sm:w-40) keeps w-full below it.
+const ownWidth = (className) => /(?:^|\s)!?(?:w|size)-/.test(className ?? "");
 
 /** Label, control, hint and error in one stack. Pass `id`; the label
  *  points at it. `error` (a string) marks the control invalid. */
@@ -39,7 +48,7 @@ export function Field({ id, label, hint, error, required, className, children })
 }
 
 export function Input({ className, invalid, ...rest }) {
-  return <input className={cx(CONTROL, className)} aria-invalid={invalid ? true : undefined} {...rest} />;
+  return <input className={cx(!ownWidth(className) && "w-full", BOX, className)} aria-invalid={invalid ? true : undefined} {...rest} />;
 }
 
 /**

package/templates/next/files/components/ui/icon.jsx

@@ -3,6 +3,18 @@
 // one here, never an <svg> in a surface. `name` is a key below; unknown
 // names render nothing (and `npm run check` names them).
 //
+// `size` is pixels (16, the default) or one of the kit's size names:
+// xs 12 · sm 14 · md 16 · lg 20 · xl 24. Every other part of the kit
+// takes size="sm", so a surface writes it here too — and until 0.3.3 a
+// name went onto the <svg> as width="sm", which is not a length: the
+// browser logged "Expected length, 'sm'" and drew the glyph at its
+// 300×150 default, a calendar as big as the card around it (a podcast
+// guest board, 2026-09-25).
+//
+// A glyph added for a build takes lucide's name when lucide has one
+// (calendar-check, trash-2), because that is the name a build reaches for
+// first; the path is our own, drawn to the same 24 box, never copied.
+//
 // BRANDS holds the brand marks: google, github, apple, microsoft,
 // x-logo (the X / Twitter mark; `x` is the close glyph), linkedin,
 // instagram, youtube, facebook. Unlike PATHS they are FILLED shapes
@@ -167,6 +179,13 @@ const PATHS = {
   kanban: "M4 4h4v14H4zM10 4h4v9h-4zM16 4h4v16h-4z",
   table: "M3 4h18v16H3zM3 10h18M3 15h18M9 10v10",
   gantt: "M4 4v16h16M8 8h6M11 12h7M9 16h5",
+  // Names builds reached for that the sprite lacked, so `npm run check`
+  // refused the ship and the build spent a round renaming them (the
+  // launch build test, 2026-09-25, and the local build logs before it):
+  // a day that is booked, the bin with its slats, a small tree of nodes.
+  "calendar-check": "M3 5h18v16H3zM16 3v4M8 3v4M3 10h18M9 15.5l2 2 4-4",
+  "trash-2": "M3 6h18M8 6V4h8v2m-9 0 1 14h8l1-14M10 11v6M14 11v6",
+  network: "M9 2h6v6H9zM2 16h6v6H2zM16 16h6v6h-6zM12 8v4M5 16v-4h14v4",
 };
 
 const BRANDS = {
@@ -183,14 +202,30 @@ const BRANDS = {
 
 export const ICON_NAMES = [...Object.keys(PATHS), ...Object.keys(BRANDS)];
 
+// The kit's size names in pixels. A number, or a length the <svg> can
+// read ("18", "1.25em"), is kept as it was; anything else is the default,
+// never an attribute the browser cannot read.
+const SIZES = { xs: 12, sm: 14, md: 16, lg: 20, xl: 24 };
+const LENGTH = /^(\d+\.?\d*|\.\d+)(px|em|rem|%)?$/;
+
+function pixels(size) {
+  if (typeof size === "number" && size > 0) return size;
+  if (typeof size === "string") {
+    if (SIZES[size]) return SIZES[size];
+    if (LENGTH.test(size)) return size;
+  }
+  return SIZES.md;
+}
+
 export function Icon({ name, size = 16, className, label }) {
   const brand = BRANDS[name];
   const d = PATHS[name] || brand;
   if (!d) return null;
+  const px = pixels(size);
   return (
     <svg
-      width={size}
-      height={size}
+      width={px}
+      height={px}
       viewBox="0 0 24 24"
       fill={brand ? "currentColor" : "none"}
       fillRule={brand ? "evenodd" : undefined}

package/templates/next/files/components/ui/index.js

@@ -23,6 +23,7 @@ export {
   endOfMonth,
   dayOfWeek,
   formatDate,
+  toLocalDate,
   firstDayOfWeek,
 } from "./calendar";
 export { DatePicker, DateInput, DATE_PRESETS } from "./date-picker";