makersclaw 0.5.2 → 0.7.0

package/templates/next/files/app/claw-alive/route.js

@@ -4,8 +4,8 @@
 // before every refresh: only a 2xx from here means the refresh will get
 // its payload and not reload the frame (app/frame.js, answering, has the
 // story). It renders nothing and reads nothing, so the question costs the
-// app almost nothing; the middleware's token check still runs first, as
-// on every request.
+// app almost nothing; proxy.js's token check still runs first, as on
+// every request.
 //
 // A 204 and not the 404 of a path nobody serves: the browser logs every
 // 404 fetch as a console error, and an app that logs one every 5 s reads

package/templates/next/files/app/frame.js

@@ -63,7 +63,8 @@ export const PRESENCE_EVENTS = ["pointerdown", "pointermove", "keydown", "wheel"
  *  and no probe, while any element on the page carries it. For a surface
  *  whose rows only its own writes change, or one too big to send every
  *  few seconds (a base of 4,812 records was about 2 MB a refresh). Its
- *  writes still re-render it (lib/actions.js revalidates), and so does
+ *  writes still re-render it (a server app's lib/actions.js revalidates;
+ *  a browser app's writes call lib/door.js dataChanged()), and so does
  *  every navigation. */
 export const REFRESH_OFF = '[data-claw-refresh="off"]';
 
@@ -142,9 +143,9 @@ export function nextRefreshIn(lastCostMs = 0) {
 }
 
 /** What to ask before a refresh: app/claw-alive/route.js, a fixed route
- *  that answers 204 with no body — no render, no database. The middleware
- *  checks the proxy's token first, as on every request, so a 204 says the
- *  page's own request would be answered too.
+ *  that answers 204 with no body — no render, no database. proxy.js
+ *  checks the product proxy's token first, as on every request, so a 204
+ *  says the page's own request would be answered too.
  *
  *  Not a path the app merely 404s. The first draft of 0.3.3 asked for a
  *  file under _next/static/ that no build writes and read the 404 as
@@ -172,8 +173,9 @@ export function probeUrl(doc) {
  *
  *  Why ask first: router.refresh() treats any answer that is not its own
  *  payload as "this is not my app any more" and loads the whole page
- *  again (Next 15, fetch-server-response.js: a non-OK or non-RSC response
- *  becomes a browser navigation). In the frame that reload wipes a
+ *  again (fetch-server-response.js: a non-OK or non-RSC response becomes
+ *  a browser navigation; Next 16's refresh reaches it through
+ *  ppr-navigations.js and still does). In the frame that reload wipes a
  *  half-typed field, and one 502 was enough (landing-page-reviewer,
  *  okr-tracker, 2026-09-24). So the probe says yes exactly where the
  *  refresh would not turn into a reload. Asking first leaves only the
@@ -194,6 +196,123 @@ export async function answering(url, fetchImpl = globalThis.fetch, timeoutMs = P
   }
 }
 
+// ---------------------------------------------------------------------------
+// Auto-refresh in a browser app
+
+// A browser app (makersclaw.json "mode": "browser") has no server to ask
+// and nothing to re-render from: its pages are files, prerendered once,
+// and its rows come from the platform's data door through lib/door.js's
+// hooks. So its refresh is not router.refresh(): under an export that
+// fetches the same prebuilt payload and shows nothing new. It is the
+// hooks reading again (lib/door.js dataChanged(), then whenLanded()),
+// and only when something changed: a question the door answers in one
+// small request, where the server app's refresh re-rendered every
+// surface every 5 s whether anything had changed or not (claw's
+// STATIC-SPEC §3, a browser app's auto-refresh).
+//
+// The question is the door's change feed, GET _claw/data/changes (claw's
+// CONTRACTS §8), which answers two things:
+//   - `changes`: the company brain's changes in the app's kinds and the
+//     member's areas since the cursor, and `next`, the cursor after them;
+//   - `tables`: a stamp of the app's own tables (Postgres's counters:
+//     rows written, then rows live). It moves with any write to them, the
+//     agent's, a job's, another member's. The platform's counters lag:
+//     a write shows in the stamp within about 11 s, two or three ticks.
+// The first answer only sets the cursor and the stamp: the hooks read
+// the rows on their own as the page opened. After it, "something
+// changed" is a brain change, a cursor that moved (a brain that
+// appeared, or an app whose grant went away), or a different stamp, up
+// or down. A stamp that moved for nothing (autovacuum re-counting, a
+// rolled-back write, a restart that zeroed the counters) costs one read
+// too many, never one too few; so does the page's own write, which
+// reads again at once and then shows in the stamp too.
+
+/** The feed's path under _claw/: the changes after `since`, the last
+ *  answer's `next`. None yet: the door answers where the feed is now. */
+export function changesPath(since) {
+  return since === undefined || since === null || since === "" ? "data/changes" : `data/changes?since=${encodeURIComponent(String(since))}`;
+}
+
+/** An abort signal that fires at the deadline or on `stop`, whichever is
+ *  first. A browser without AbortSignal.any keeps the deadline: a held
+ *  request must not stall every tick after it. */
+function askSignal(timeoutMs, stop) {
+  const timeout = typeof AbortSignal !== "undefined" && typeof AbortSignal.timeout === "function" ? AbortSignal.timeout(timeoutMs) : undefined;
+  if (!timeout || !stop) return timeout ?? stop;
+  return typeof AbortSignal.any === "function" ? AbortSignal.any([timeout, stop]) : timeout;
+}
+
+/**
+ * The browser app's probe: has anything changed since the last refresh?
+ * `ask(path, signal)` sends GET _claw/<path> and resolves to lib/claw.js
+ * claw()'s answer ({ ok, status, data, unavailable }); it may throw, and
+ * a throw is no answer. → { probe, covered, stop }
+ *
+ *   - probe() resolves true when a change was seen that no refresh has
+ *     covered yet. It asks the door every time (one ask at a time: a
+ *     second probe while one is out shares its answer), within
+ *     PROBE_TIMEOUT_MS.
+ *   - covered(): a refresh has started, so what was seen is on its way.
+ *     A change stays owed until then: a tick that saw one and found the
+ *     founder typing refreshes on a later tick, not never.
+ *   - A failed answer changes nothing: the cursor and the stamp stay, and
+ *     the next tick asks again. A 5xx, a 401 (a grant gone stale), no
+ *     network, no answer in time. A refresh would read nothing new.
+ *   - A 404 that names no code is no door at all (a Makersclaw from
+ *     before it, a `next dev` with nothing in front of it): the feed
+ *     stops asking for the page's life, so the console does not log a
+ *     failed request every five seconds.
+ *   - stop() aborts an ask in flight; every probe after it is false.
+ */
+export function changeFeed(ask, { timeoutMs = PROBE_TIMEOUT_MS } = {}) {
+  let first = true; // no answer yet: the next one only sets where we are
+  let cursor = null; // the feed's `next`: where the next ask starts
+  let stamp = null; // the own tables' stamp, as last answered
+  let owed = false; // a change seen and not yet covered by a refresh
+  let gone = false; // no door answers here
+  let stopped = false;
+  let asking = null; // the ask in flight
+  const halt = typeof AbortController === "function" ? new AbortController() : null;
+
+  async function askOnce() {
+    let answer;
+    try {
+      answer = await ask(changesPath(cursor), askSignal(timeoutMs, halt?.signal));
+    } catch {
+      return; // no answer
+    }
+    if (stopped || !answer) return;
+    if (!answer.ok) {
+      if (answer.status === 404 && answer.unavailable) gone = true;
+      return;
+    }
+    const data = answer.data;
+    if (!data || typeof data !== "object" || Array.isArray(data) || data.ok === false) return;
+    const next = data.next === undefined || data.next === null ? null : String(data.next);
+    const tables = data.tables === undefined || data.tables === null ? null : String(data.tables);
+    const changed = (Array.isArray(data.changes) && data.changes.length > 0) || next !== cursor || tables !== stamp;
+    if (!first && changed) owed = true;
+    first = false;
+    cursor = next;
+    stamp = tables;
+  }
+
+  return {
+    probe() {
+      if (stopped || gone) return Promise.resolve(false);
+      if (!asking) asking = askOnce().finally(() => (asking = null));
+      return asking.then(() => owed && !stopped);
+    },
+    covered() {
+      owed = false;
+    },
+    stop() {
+      stopped = true;
+      halt?.abort();
+    },
+  };
+}
+
 /** `promise`, or undefined once `ms` have passed, whichever comes first. */
 function within(promise, ms, timers) {
   let timer = null;
@@ -204,8 +323,14 @@ function within(promise, ms, timers) {
 /**
  * The refresh loop app/auto-refresh.jsx runs, as plain code over a
  * document so `npm test` can drive it. `refresh()` starts one refresh and
- * resolves when it has landed (the component's transition settling);
- * `probe()` is the question above, asked first. → { stop() }
+ * resolves when it has landed; `probe()` is asked first, and a tick
+ * refreshes only on its yes. → { stop() }
+ *
+ * The two modes differ only in those two. A server app's refresh is
+ * router.refresh() in a transition, landed when the transition settles,
+ * and its probe is `answering` (the default here): will the app answer?
+ * A browser app's refresh is lib/door.js dataChanged() then whenLanded(),
+ * and its probe is a changeFeed's: has anything changed?
  *
  * Until 0.5.0 a timer fired every REFRESH_MS whatever was in flight: the
  * probe was guarded, the refresh was not, so a render slower than the
@@ -222,7 +347,7 @@ function within(promise, ms, timers) {
  *     (PRESENCE_EVENTS, in the frame): the next sign refreshes at once
  *     and the loop goes on. Coming back from hidden is such a sign;
  *   - a tick refreshes only when shouldRefresh says so, with the probe's
- *     2xx, and never while a surface has opted out (REFRESH_OFF).
+ *     yes, and never while a surface has opted out (REFRESH_OFF).
  *
  * The rules are asked again after the probe: typing may have started, or
  * the tab changed, while it was on its way.

package/templates/next/files/app/layout.jsx

@@ -20,8 +20,8 @@ export const metadata = { title: process.env.CLAW_PRODUCT || "Artifact" };
 // lib/claw.js, the product name, and data-theme. The theme follows the
 // desk: the OS window opens the app with ?theme=light|dark and the
 // product proxy repeats it as the x-claw-theme header on every request
-// (middleware.js explains); the claw_theme cookie covers a run without
-// the proxy. Dark when neither says — the desk is dark.
+// (proxy.js explains); the claw_theme cookie covers a run without
+// the product proxy. Dark when neither says — the desk is dark.
 //
 // The palette follows the WORKSPACE: <head> links `_claw/theme.css`, the
 // preset picked in System Settings → Appearance, served by the product