makersclaw 0.4.0 → 0.5.2

package/registry/blocks/record-notes/record-notes.jsx

@@ -14,7 +14,7 @@
 // browser: the server draws the notes as one list, and the day headings
 // appear once mounted — never a mismatch between the two renders.
 import { useEffect, useRef, useState } from "react";
-import { Avatar, Badge, Card, Confirm, Menu, cx } from "../../ui";
+import { Avatar, Badge, Card, Confirm, Menu, cx, toLocalDate } from "../../ui";
 import { CommentBody, CommentComposer, CommentTime } from "../comment-box";
 import { docToText } from "../doc-editor";
 
@@ -22,10 +22,9 @@ const nameOf = (author) => (typeof author === "string" ? author : author?.name)
 const srcOf = (author) => (typeof author === "object" && author ? author.src : undefined);
 const idOf = (author) => (typeof author === "object" && author ? author.id : undefined);
 
-const toMs = (v) => {
-  if (v === undefined || v === null || v === "") return NaN;
-  return (v instanceof Date ? v : new Date(v)).getTime();
-};
+// A note dated with a day alone ("2026-09-28", a `date` column) files
+// under that day wherever the reader is: local midnight, never UTC's.
+const toMs = (v) => toLocalDate(v)?.getTime() ?? NaN;
 
 function useMounted() {
   const [on, setOn] = useState(false);

package/registry/blocks/sidebar/sidebar-panel.jsx

@@ -69,9 +69,9 @@ export function PanelBody({ panel, onChoose, sheet = false }) {
     );
   } else if (panel.loading) {
     body = (
-      <ul aria-busy="true" aria-label={`Loading ${panel.title ?? "list"}`} className="grid">
+      <ul aria-busy="true" aria-label={`Loading ${panel.title ?? "list"}`} className="grid grid-cols-1">
         {[0, 1, 2, 3, 4].map((i) => (
-          <li key={i} className="grid gap-2 border-b border-border px-4 py-3">
+          <li key={i} className="grid grid-cols-1 gap-2 border-b border-border px-4 py-3">
             <Skeleton className="w-1/2" />
             <Skeleton className="w-3/4" />
             <Skeleton className="w-full" />
@@ -90,7 +90,7 @@ export function PanelBody({ panel, onChoose, sheet = false }) {
     );
   } else {
     body = (
-      <ul aria-label={panel.title ?? "List"} className="grid">
+      <ul aria-label={panel.title ?? "List"} className="grid grid-cols-1">
         {shown.map((it, i) => (
           <li key={it.key ?? it.href ?? `${it.title}-${i}`} className="border-b border-border">
             <Item
@@ -120,7 +120,7 @@ export function PanelBody({ panel, onChoose, sheet = false }) {
   return (
     <div className="flex min-h-0 flex-1 flex-col">
       {panel.title || panel.actions || searchOn ? (
-        <div className="grid shrink-0 gap-3 border-b border-border p-3">
+        <div className="grid grid-cols-1 shrink-0 gap-3 border-b border-border p-3">
           {panel.title || panel.actions ? (
             <div className="flex min-h-9 items-center gap-2">
               {panel.title ? <h2 className="min-w-0 flex-1 truncate text-base font-semibold">{panel.title}</h2> : null}

package/registry/blocks/sidebar/sidebar.jsx

@@ -354,7 +354,7 @@ export function Sidebar({
           <Icon name={item.icon} className="shrink-0" />
         ) : null}
         {item.description ? (
-          <span className="grid min-w-0 flex-1 text-left leading-tight">
+          <span className="grid grid-cols-1 min-w-0 flex-1 text-left leading-tight">
             <span className="truncate">{item.label}</span>
             <span className="truncate text-xs text-muted-foreground">{item.description}</span>
           </span>
@@ -420,7 +420,7 @@ export function Sidebar({
             opts.sheet ? "[&>summary]:px-4" : "[&>summary]:min-h-9 [&>summary]:px-3 [&>summary]:py-1",
           )}
         >
-          <ul className="ml-5 grid gap-0.5 border-l border-border pl-2">
+          <ul className="ml-5 grid grid-cols-1 gap-0.5 border-l border-border pl-2">
             {item.items.map((child) => (
               <li key={keyOf(child)}>{leaf(child, opts)}</li>
             ))}
@@ -469,7 +469,7 @@ export function Sidebar({
   function replaced(item, { sheet, where }) {
     const headingId = `${uid}-${where}-drill`;
     return (
-      <div className="grid gap-0.5">
+      <div className="grid grid-cols-1 gap-0.5">
         <Button id={`${uid}-${where}-back`} variant="nav" size={sheet ? "md" : "sm"} onClick={() => closeDrill(where)}>
           <Icon name="arrow-left" className="shrink-0" />
           <span className="min-w-0 flex-1 truncate text-left">Back</span>
@@ -477,7 +477,7 @@ export function Sidebar({
         <h2 id={headingId} className="flex h-8 items-center px-3 text-xs font-medium text-muted-foreground">
           {item.label}
         </h2>
-        <ul aria-labelledby={headingId} className="grid gap-0.5">
+        <ul aria-labelledby={headingId} className="grid grid-cols-1 gap-0.5">
           {item.items.map((child) => (
             <li key={keyOf(child)}>{leaf(child, { sheet })}</li>
           ))}
@@ -513,7 +513,7 @@ export function Sidebar({
     // children stand in for the list.
     const drilledHere = drillItem && !icons && (drillMode === "replace" || (sheet && drillMode === "panel"));
     return (
-      <nav aria-label={label} className={cx("grid gap-3", icons ? "justify-items-center py-2" : "px-2 py-2")}>
+      <nav aria-label={label} className={cx("grid grid-cols-1 gap-3", icons ? "justify-items-center py-2" : "px-2 py-2")}>
         {primaryAction && !drilledHere ? primary({ icons, sheet }) : null}
         {drilledHere
           ? replaced(drillItem, { sheet, where })
@@ -524,7 +524,7 @@ export function Sidebar({
                 <ul
                   aria-labelledby={group.label && !icons && !group.collapsible ? headingId : undefined}
                   aria-label={group.label && !icons && group.collapsible ? group.label : undefined}
-                  className={cx("grid gap-0.5", icons && "justify-items-center")}
+                  className={cx("grid grid-cols-1 gap-0.5", icons && "justify-items-center")}
                 >
                   {group.items.map((item) => (
                     <li key={keyOf(item)}>{icons ? iconItem(item) : wideItem(item, { sheet, where })}</li>
@@ -546,7 +546,7 @@ export function Sidebar({
                 );
               }
               return (
-                <div key={group.key ?? group.label ?? gi} className="grid gap-0.5">
+                <div key={group.key ?? group.label ?? gi} className="grid grid-cols-1 gap-0.5">
                   {group.label && !icons ? (
                     <h2 id={headingId} className="flex h-8 items-center px-3 text-xs font-medium text-muted-foreground">
                       {group.label}
@@ -565,7 +565,7 @@ export function Sidebar({
 
   function brand({ icons, side = "bottom" }) {
     const words = (
-      <span className="grid min-w-0 flex-1 text-left leading-tight">
+      <span className="grid grid-cols-1 min-w-0 flex-1 text-left leading-tight">
         <span className="truncate text-sm font-semibold">{title}</span>
         {subtitle ? <span className="truncate text-xs font-normal text-muted-foreground">{subtitle}</span> : null}
       </span>
@@ -667,7 +667,7 @@ export function Sidebar({
     if (!user) return null;
     const face = <Avatar name={user.name} src={user.src} size="sm" />;
     const words = (
-      <span className="grid min-w-0 flex-1 text-left leading-tight">
+      <span className="grid grid-cols-1 min-w-0 flex-1 text-left leading-tight">
         <span className="truncate text-sm font-medium">{user.name}</span>
         {user.email ? <span className="truncate text-xs font-normal text-muted-foreground">{user.email}</span> : null}
       </span>
@@ -711,7 +711,7 @@ export function Sidebar({
     ) : null;
     if (!user && !plus && !footSwitch) return null;
     return (
-      <div className="grid gap-1">
+      <div className="grid grid-cols-1 gap-1">
         {footSwitch ? brand({ icons, side: "top" }) : null}
         {user || plus ? (
           <div className={cx("flex items-center gap-1", icons && "flex-col")}>
@@ -745,7 +745,7 @@ export function Sidebar({
             <IconButton icon="x" label={`Close ${drillItem.label}`} size="sm" onClick={() => closeDrill("r")} />
           </div>
           <ScrollArea label={drillItem.label} className="min-h-0 flex-1" fade>
-            <ul aria-labelledby={headingId} className="grid gap-0.5 p-2">
+            <ul aria-labelledby={headingId} className="grid grid-cols-1 gap-0.5 p-2">
               {drillItem.items.map((child, i) => (
                 <li key={keyOf(child)}>{leaf(child, { sheet: false, id: i === 0 ? `${uid}-drill-first` : undefined })}</li>
               ))}
@@ -813,7 +813,7 @@ export function Sidebar({
         >
           {ctx.mobileOpen ? (
             sheetPanel && panel ? (
-              <div className="-mx-2 -my-2 grid gap-2">
+              <div className="-mx-2 -my-2 grid grid-cols-1 gap-2">
                 <div className="px-2 pt-2">
                   <Button variant="nav" size="md" onClick={() => setSheetPanel(false)}>
                     <Icon name="arrow-left" className="shrink-0" />
@@ -823,7 +823,7 @@ export function Sidebar({
                 {panelIsNode ? panel : <PanelBody panel={panel} sheet onChoose={() => ctx.setMobileOpen(false)} />}
               </div>
             ) : (
-              <div className="-mx-2 -my-2 grid gap-2">
+              <div className="-mx-2 -my-2 grid grid-cols-1 gap-2">
                 {headerActions ? <div className="flex flex-wrap items-center gap-1 px-2">{headerActions}</div> : null}
                 {searchOpts ? <div className="px-2">{searchRow({ icons: false, sheet: true })}</div> : null}
                 {switcher?.length ? (

package/registry/blocks/signature-pad/signature.js

@@ -60,9 +60,16 @@ export function signatureRecord({ png, name, mode, signedAt }) {
   return { png, name: String(name ?? "").trim(), mode, signedAt: signedAt ?? new Date().toISOString() };
 }
 
+// A day alone ("2026-09-28", from a `date` column) is that day's local
+// midnight: new Date() would read it as UTC's, the day before west of
+// Greenwich. Written out here, not the kit's toLocalDate: these helpers
+// import nothing, so they run anywhere.
+const DAY = /^(\d{4})-(\d{2})-(\d{2})$/;
+
 /** "Sep 23, 2026, 2:04 PM" in the reader's own locale. */
 export function formatSignedAt(iso, locale) {
-  const d = new Date(iso);
+  const day = typeof iso === "string" ? DAY.exec(iso) : null;
+  const d = day ? new Date(+day[1], +day[2] - 1, +day[3]) : new Date(iso);
   if (Number.isNaN(d.getTime())) return "";
   return d.toLocaleString(locale, { month: "short", day: "numeric", year: "numeric", hour: "numeric", minute: "2-digit" });
 }

package/registry/blocks/spreadsheet/cells.jsx

@@ -5,7 +5,7 @@
 // type's `editor` name. A custom type (the `types` prop) may bring its own
 // `render(value, column, ctx)` and `Editor` component.
 import { useEffect, useLayoutEffect, useRef, useState } from "react";
-import { Avatar, AvatarGroup, Badge, Calendar, Command, Icon, Rating, cx, panelClass, usePopoverPosition } from "../../ui";
+import { Avatar, AvatarGroup, Badge, Calendar, Command, Icon, Rating, cx, panelClass, todayString, usePopoverPosition } from "../../ui";
 import { optionOf, optionValue } from "./types";
 
 const asList = (v) => (Array.isArray(v) ? v : v == null || v === "" ? [] : [v]);
@@ -303,7 +303,7 @@ function DateEditor({ value, column, type, ctx, initial, today, onCommit, onCanc
             <button
               type="button"
               className="rounded-sm px-1.5 py-1 text-xs text-muted-foreground outline-none hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring"
-              onClick={() => onCommit(today ?? new Date().toISOString().slice(0, 10), null)}
+              onClick={() => onCommit(today ?? todayString(), null)}
             >
               Today
             </button>

package/templates/next/files/README.md

@@ -56,6 +56,7 @@ app/DESIGN.md          the design, written before the code (§3)
 surfaces/<key>.jsx     one file per domain surface
 surfaces.js            the manifest entries (import + component when built)
 components/*.jsx       anything shared between surfaces
+components/*-actions.js your own server actions, for a write lib/actions.js cannot make (§5)
 components/depictions/ pictures of things that exist elsewhere, in their own colours (§3c)
 ```
 
@@ -67,7 +68,7 @@ app/globals.css        the workspace theme's tokens (§1) — no palette of your
 app/page.jsx           / → the home surface (or "No surfaces yet" while the manifest is empty)
 app/s/[key]/page.jsx   renders the surface with that key; planned ones say so
 app/error.jsx, app/global-error.jsx, app/not-found.jsx, app/error-relay.jsx, app/auto-refresh.jsx,
-app/escape-relay.jsx, app/frame.js, app/claw-alive/route.js   the app inside its window: refresh while shown, Escape from the desk
+app/escape-relay.jsx, app/frame.js, app/claw-alive/route.js   the app inside its window: refresh while shown (a surface opts out, §7), Escape from the desk
 components/ui/         the kit: Button, Field, Input, Select, Sheet, Tabs, Menu, Notice, Icon, Depiction… (§3b, §3c)
 components/parts/      the parts: RecordSwitcher, LiveEmpty + LiveWork, useFixture + FixtureNotice (§3a, §3b)
 check/pins.json        the fixed files by hash; `npm run check` refuses one that differs
@@ -194,7 +195,7 @@ import { Button, IconButton, ButtonGroup, ButtonGroupSeparator, Toggle, ToggleGr
          Field, Input, TimeInput, Textarea, Select, Switch, Checkbox, RadioGroup, Radio, Rating,
          InputGroup, PasswordInput, InputOTP, Slider, Image, FileInput, FileDrop, fileMatches, Combobox, Command, CommandDialog, Calendar, DatePicker, DateInput, DATE_PRESETS,
          parseDate, isDateString, toDateString, todayString, addDays, addMonths,
-         startOfMonth, endOfMonth, dayOfWeek, formatDate, firstDayOfWeek,
+         startOfMonth, endOfMonth, dayOfWeek, formatDate, toLocalDate, firstDayOfWeek,
          Card, Notice, Badge, Kicker, Empty, Item, ItemGroup, Avatar, AvatarGroup,
          Sheet, Confirm, Tabs, TabPanel, Menu, ContextMenu, Popover, Tooltip, HoverCard,
          Breadcrumb, Pagination, Collapsible, Accordion, Carousel, ScrollArea,
@@ -218,8 +219,10 @@ import { RecordSwitcher, LiveEmpty, LiveWork, liveWords, useFixture, FixtureNoti
   `IconButton` for an icon alone (`label` required). `loading` while its
   action runs: a spinner, the same width, `aria-busy`, disabled.
 - `Field` wraps `Input`, `Textarea`, `Select`, `Switch`, `Checkbox` with
-  its label, hint and error. `Select` with empty `options` renders a
-  muted line, never a disabled dropdown. `TimeInput` — a time of day
+  its label, hint and error. An `Input` is as wide as its column; a width
+  in its `className` (`w-24`, `w-auto`) sets its own. `Select` with
+  empty `options` renders a muted line, never a disabled dropdown.
+  `TimeInput` — a time of day
   ("HH:MM"; `min max step`), the kit's clock in place of the browser's.
 - `Rating` — stars: read-only `value` of `max` (halves drawn, "4.5 out
   of 5" to a reader), or with `onChange` a radio-group input; `size`, `label`.
@@ -246,8 +249,10 @@ import { RecordSwitcher, LiveEmpty, LiveWork, liveWords, useFixture, FixtureNoti
 - `Sheet` — the one overlay, a rail beside the work (`side="end"`), a
   navigation drawer (`start`), a dialog (`center`) or a bottom sheet; on a narrow window every side
   becomes a bottom sheet; `bare` + `label` for a panel that draws its own
-  top (no header, flush body). `Confirm` is the "delete this?" case;
-  `consequences`, `requireText` and `acknowledge` hold it until met.
+  top (no header, flush body). A field inside with `autoFocus` takes the
+  focus once it opens (since 0.5.0; before, Close had it). `Confirm` is
+  the "delete this?" case; `consequences`, `requireText` and
+  `acknowledge` hold it until met.
 - `Image src alt ratio fit rounded` — a picture of a thing (thumbnail,
   cover): Skeleton while it loads, a glyph when it fails, lazy, `alt`
   required. Never a raw `<img>`; a face is an `Avatar`.
@@ -280,7 +285,13 @@ import { RecordSwitcher, LiveEmpty, LiveWork, liveWords, useFixture, FixtureNoti
   `DateInput` (a typed date with the Calendar a button away;
   `clearable` for an ×). Dates are
   `"YYYY-MM-DD"` strings in and out — never a Date — and `addDays`,
-  `addMonths`, `formatDate`… do the arithmetic.
+  `addMonths`, `formatDate`… do the arithmetic. A `date` column reads
+  as that same string (§4), so a row's day goes into a `DatePicker` and
+  back unchanged. Never `new Date("2026-09-28")`: that is UTC's
+  midnight, the 27th west of Greenwich, and a form that saves what it
+  shows moves the day back. Showing a day beside times (a due date by
+  a sent-at), `toLocalDate(value)` gives a Date at that day's LOCAL
+  midnight (a timestamp or a Date passes through).
 - `RadioGroup` (`options` or `<Radio>` children, each with a
   `description`; `variant` list · card; `orientation`; in a `Field` with
   the same `id`), `Toggle` (`pressed` + `onPressedChange`, aria-pressed),
@@ -506,7 +517,14 @@ surfaces.js                  server files only (entries import components)
 ```
 
 Pass plain data across the boundary — strings, numbers, arrays, objects.
-`plain(row)` already turns dates into ISO strings. A client component can
+`plain(row)` already turns a timestamp into its ISO string. A `date`
+column is its day, `"2026-09-28"`: text, the same day for every reader,
+from `loadRows` and from `query()` alike (`lib/db.js` reads it so). Up to
+0.4.x `query()` gave a Date at the server's midnight and the reads an ISO
+timestamp of it, a day off on either side of UTC. A server file that
+called a Date method on a `date` value now holds the day's string:
+compare days as strings (`"2026-09-28" < "2026-10-01"`), and build a
+Date only where a sum needs one. A client component can
 receive a server action as a prop, and nothing else that is a function.
 
 A surface file that uses hooks or event handlers starts with `"use
@@ -636,7 +654,8 @@ const { counts } = await countBy({ source: "public.investors", column: "stage" }
 const { rows: log } = await loadActivity({ surface: "drafts", limit: 50 });
 ```
 
-Helpers: `plain(row)` (dates → ISO, buffers → base64), `orderClause(orderBy,
+Helpers: `plain(row)` (timestamps → ISO, buffers → base64; a `date` is
+already its `"YYYY-MM-DD"`), `orderClause(orderBy,
 fallback)` (validated `ORDER BY` text), `markSample(sample, idColumn)`
 (stable ids + `_sample: true`), `currentSurface(explicit)` (the surface
 key of the request, from `x-claw-surface`, unless one is passed).
@@ -661,6 +680,13 @@ saveSetting({ mode = "table" | "json", source, keyColumn = "key", valueColumn =
 when missing — a plain `key text, value text` table is enough. JSON mode
 sets `key` inside the jsonb `column` of row `id`.
 
+Every update (`updateRow`, `moveRow`, `saveSetting`) sets `updated_at =
+now()` when the table has an `updated_at` timestamp it can write (since
+0.5.0; before, only a trigger of the app's own kept it). A patch that
+sets `updated_at` itself wins, and a column of that name that is text, a
+number or a view's computed value is left alone. An insert leaves it to
+the column's default: `updated_at timestamptz not null default now()`.
+
 ```js
 "use client";
 import { moveRow } from "../lib/actions";
@@ -668,8 +694,15 @@ const r = await moveRow({ source: "public.investors", id, stateColumn: "stage",
 if (!r.ok) setError(r.error);
 ```
 
-Never write raw SQL from a surface. A write that needs more than these
-is a new function in `lib/actions.js` that also calls `logActivity`.
+Never write raw SQL from a surface. `lib/*.js` is fixed (`npm run check`
+refuses an edit, and `makersclaw update` lays the file again), so a write
+these cannot make goes in a server-action file of the app's own:
+`"use server"` on its first line, beside the components that call it
+(`components/deal-actions.js`). There it composes the actions above, or
+runs its UPDATE or DELETE through `query()` from `lib/db.js`, records it
+with `logActivity()` and ends with `revalidatePath("/", "layout")`, as
+`lib/actions.js` does. A new row still goes through `insertRow`: the
+check refuses a raw `INSERT INTO` anywhere outside `lib/`.
 
 ### Platform — `lib/platform.js` (browser)
 
@@ -824,7 +857,11 @@ error, code }` — `needs_answer` while the thread waits on an answer in
 the column, `queue_full`, `unknown_job`, `no_credits`, …; the panel
 shows the error). The hook then follows the request — every 2.5 s while
 the App tab is on screen — until it ends. On the 0.3.x path it resolves
-when the job ends, as it always did.
+when the job ends, as it always did. React's development double mount
+(and a fast refresh) cleans the hook up and mounts it again: it follows
+a live request on from there, and an ask it cut off before an answer
+came closes the panel — neither done nor failed. A job started from an
+effect runs twice there; start it from a press.
 
 What it holds, for the panel:
 
@@ -993,7 +1030,8 @@ surface; `--static` skips the build and the smoke. Then, by eye:
 - Error state shows the text from `{ error }`.
 - Keyboard focus visible on every control.
 - Numbers tabular (`data-nums`).
-- Every write goes through `lib/actions.js`; no raw SQL from a surface.
+- Every write is a server action — `lib/actions.js`, or the app's own
+  `"use server"` file (§5) — never raw SQL in a surface.
 - Every surface reachable from the nav.
 
 ## 7. Run
@@ -1018,9 +1056,29 @@ state; a 5xx carries the log tail. Fix it before moving on — the founder
 is watching the preview.
 
 Every page is `dynamic = "force-dynamic"`: nothing is prerendered, so a
-build never needs the database. `app/auto-refresh.jsx` re-renders from
-the server every 5 s while the App tab is on screen and nobody is typing
-(never while a sheet is open, a field they typed in holds focus, or
-within 10 s of a keystroke) and the app answers `/claw-alive` (a fixed
-route) with a 204, so the agent's writes appear. The founder reads "artifact", "app", "agent", "automation" —
-nothing else.
+build never needs the database. `app/auto-refresh.jsx` re-renders the
+page from the server while it is shown, so the agent's writes appear:
+one refresh at a time, 5 s after the last one landed plus what that one
+took (a minute at most), and only while the App tab is on screen in a
+visible browser tab (hidden, it asks nothing; back, it refreshes at
+once), nobody is typing (never while a sheet is open, a field they typed
+in holds focus, or within 10 s of a keystroke), and the app answers
+`/claw-alive` (a fixed route) with a 204.
+
+**A surface that must not be refreshed opts out with
+`data-claw-refresh="off"` on its root element**: one whose rows only its
+own writes change, or a table too big to send every few seconds. While
+any element on the page carries it, nothing is refreshed and nothing is
+probed; the surface's own writes still re-render it (`lib/actions.js`
+revalidates), and so does every navigation. Set it from state to pause
+only while it matters: `data-claw-refresh={importing ? "off" : undefined}`.
+
+**A page left open stops refreshing after 30 minutes with no sign of
+anyone** in the app — a key, the pointer, a touch, a wheel, focus. The
+platform stops an app nobody used for 30 minutes, and every refresh is a
+use, so an open tab nobody looked at kept its app running all night. The
+next sign of someone refreshes at once and the refresh goes on; so does
+coming back to the tab. Nothing on the page says so: the first touch
+brings it up to date.
+
+The founder reads "artifact", "app", "agent", "automation" — nothing else.

package/templates/next/files/app/auto-refresh.jsx

@@ -1,88 +1,53 @@
 "use client";
 
-import { useEffect } from "react";
+import { useEffect, useRef, useTransition } from "react";
 import { useRouter } from "next/navigation";
-import { REFRESH_MS, answering, isEditing, probeUrl, shouldRefresh } from "./frame";
+import { refreshLoop } from "./frame";
 
 // Rows change under this page from outside it — the agent writes them
-// while the founder watches. Re-render from the server every 5 s;
-// router.refresh() keeps form state and scroll, a reload would not.
+// while the founder watches. Re-render from the server while the page is
+// shown; router.refresh() keeps form state and scroll, a reload would not.
 //
-// Until 0.3.3 the only gate was document.visibilityState, and in the
-// desk it is always "visible": the window keeps the App tab mounted,
-// hidden, behind its other tabs, so an app refreshed every 5 s behind
-// Runs and Settings, and refreshed under the founder's hands mid-word.
-// One 502 on such a refresh (the app restarting) made Next load the
-// whole frame again and the half-typed field was gone (landing-page-
-// reviewer, okr-tracker, 2026-09-24). Now a tick refreshes only when:
+// The rules are app/frame.js's (refreshLoop, and the reasons with each):
 //
-//   - the tab is visible AND the App tab is on screen (an
-//     IntersectionObserver on the root: app/frame.js says why nothing
-//     else sees a hidden tab);
-//   - the founder is not typing: nothing typed in the last 10 s, no
-//     half-typed field holding focus, no dialog open (app/frame.js,
-//     isEditing, says what counts and what does not);
-//   - the app answers app/claw-alive/route.js with a 204 within 4 s:
-//     while it is down, restarting or unreachable the page stays as it
-//     is, never reloaded.
-//
-// The first two are asked again when the answer comes back: typing may
-// have started, or the founder may have switched tabs, while it was on
-// its way. Coming back on screen refreshes at once, so the rows are
-// current.
+//   - only while the tab is visible AND the App tab is on screen: no timer
+//     at all otherwise, and coming back refreshes at once;
+//   - only while someone is there: after 30 minutes with no key, pointer,
+//     touch, wheel or focus in the app it stops, so the platform's idle
+//     sweep can stop an app left open; the next sign refreshes at once;
+//   - only while the founder is not typing and no dialog is open
+//     (isEditing), and never while a surface has opted out with
+//     data-claw-refresh="off" on its root;
+//   - only after app/claw-alive/route.js answers 204 within 4 s: while
+//     the app is down, restarting or unreachable the page stays as it is,
+//     never reloaded;
+//   - one refresh at a time. It runs in a transition, and the next tick is
+//     timed only once `isPending` is false again: the interval plus what
+//     the last one took, so a slow render is never cut off by the next and
+//     a busy stack is asked less often. Until 0.5.0 a refresh fired every
+//     5 s whatever was in flight.
 export default function AutoRefresh() {
   const router = useRouter();
-  useEffect(() => {
-    let onScreen = true;
-    let lastInput = -Infinity;
-    let typed = null; // the field the last `input` event came from
-    let asking = false;
-    let stopped = false;
-
-    const ready = () =>
-      shouldRefresh({
-        visible: document.visibilityState === "visible",
-        onScreen,
-        editing: isEditing(document, typed),
-        quietFor: Date.now() - lastInput,
-      });
-
-    const tick = async () => {
-      if (asking || !ready()) return;
-      asking = true;
-      const up = await answering(probeUrl(document));
-      asking = false;
-      if (up && !stopped && ready()) router.refresh();
-    };
+  const [pending, startTransition] = useTransition();
+  const landed = useRef([]); // the loop's waits for the refresh in flight
 
-    const onInput = (event) => {
-      lastInput = Date.now();
-      typed = event.target;
-    };
-    const onVisible = () => {
-      if (document.visibilityState === "visible") tick();
-    };
-
-    let observer = null;
-    if (typeof IntersectionObserver === "function") {
-      observer = new IntersectionObserver((entries) => {
-        const was = onScreen;
-        onScreen = entries[entries.length - 1].isIntersecting;
-        if (onScreen && !was) tick();
-      });
-      observer.observe(document.documentElement);
-    }
+  // isPending turns false when the refresh's new tree has rendered: that
+  // is the refresh landed.
+  useEffect(() => {
+    if (pending) return;
+    for (const done of landed.current.splice(0)) done();
+  }, [pending]);
 
-    const id = setInterval(tick, REFRESH_MS);
-    document.addEventListener("visibilitychange", onVisible);
-    document.addEventListener("input", onInput, true);
-    return () => {
-      stopped = true;
-      clearInterval(id);
-      observer?.disconnect();
-      document.removeEventListener("visibilitychange", onVisible);
-      document.removeEventListener("input", onInput, true);
-    };
+  useEffect(() => {
+    const loop = refreshLoop({
+      doc: document,
+      refresh: () =>
+        new Promise((done) => {
+          landed.current.push(done);
+          startTransition(() => router.refresh());
+        }),
+    });
+    return () => loop.stop();
   }, [router]);
   return null;
 }