makersclaw 0.3.2 → 0.4.0

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

@@ -2,24 +2,86 @@
 
 import { useEffect } from "react";
 import { useRouter } from "next/navigation";
+import { REFRESH_MS, answering, isEditing, probeUrl, shouldRefresh } 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 while the
-// tab is visible; router.refresh() keeps form state and scroll, a reload
-// would not. Nothing runs while the tab is hidden.
-const EVERY_MS = 5000;
-
+// while the founder watches. Re-render from the server every 5 s;
+// 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 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.
 export default function AutoRefresh() {
   const router = useRouter();
   useEffect(() => {
-    const tick = () => {
-      if (document.visibilityState === "visible") router.refresh();
+    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 onInput = (event) => {
+      lastInput = Date.now();
+      typed = event.target;
+    };
+    const onVisible = () => {
+      if (document.visibilityState === "visible") tick();
     };
-    const id = setInterval(tick, EVERY_MS);
-    document.addEventListener("visibilitychange", 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);
+    }
+
+    const id = setInterval(tick, REFRESH_MS);
+    document.addEventListener("visibilitychange", onVisible);
+    document.addEventListener("input", onInput, true);
     return () => {
+      stopped = true;
       clearInterval(id);
-      document.removeEventListener("visibilitychange", tick);
+      observer?.disconnect();
+      document.removeEventListener("visibilitychange", onVisible);
+      document.removeEventListener("input", onInput, true);
     };
   }, [router]);
   return null;

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

@@ -0,0 +1,17 @@
+// FIXED — the platform agent does not edit this file.
+//
+// GET <base>/claw-alive → 204, no body. app/auto-refresh.jsx asks it
+// 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.
+//
+// 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
+// as broken to anyone checking its console (2026-09-25).
+export const dynamic = "force-dynamic";
+
+export function GET() {
+  return new Response(null, { status: 204, headers: { "cache-control": "no-store" } });
+}

package/templates/next/files/app/error-relay.jsx

@@ -1,7 +1,7 @@
 "use client";
 
 import { useEffect } from "react";
-import { claw, publishStatus, reportError } from "../lib/claw";
+import { claw, publishDesk, publishStatus, reportError } from "../lib/claw";
 
 // Errors React does not catch — a handler throwing, a rejected promise —
 // still reach Makersclaw: window.onerror and unhandledrejection post them
@@ -10,14 +10,19 @@ import { claw, publishStatus, reportError } from "../lib/claw";
 //
 // It also keeps <html data-claw-status> current from _claw/me (on mount
 // and whenever the tab comes back), so reportError can tag an error
-// "preview" while the artifact is a draft. This is the fixed layer's job:
-// the shell is the agent's file and may never call useArtifact().
+// "preview" while the artifact is a draft, and <html
+// data-claw-desk-origin>, so a screen's ask can tell the desk which
+// request to open (lib/claw.js, openInDesk) before any ask has answered.
+// This is the fixed layer's job: the shell is the agent's file and may
+// never call useArtifact().
 export default function ErrorRelay() {
   useEffect(() => {
     const controller = new AbortController();
     const publish = async () => {
       const r = await claw("me", { signal: controller.signal });
-      if (r.ok) publishStatus(r.data?.artifact?.status);
+      if (!r.ok) return;
+      publishStatus(r.data?.artifact?.status);
+      publishDesk(r.data?.desk_origin);
     };
     const onVisible = () => {
       if (document.visibilityState === "visible") publish();

package/templates/next/files/app/escape-relay.jsx

@@ -0,0 +1,27 @@
+"use client";
+
+import { useEffect } from "react";
+import { closeTopLayer, isDeskEscape } from "./frame";
+
+// Escape pressed on the desk, for this app. A sheet open in the App tab
+// covers it; the founder clicks the window's bar above it and presses
+// Escape — the key lands in the desk's document, never in this frame,
+// and the sheet stayed open (2026-09-25; app/frame.js has the whole
+// story, and the contract with the desk, whose half is claw's). The desk
+// posts an Escape it did not use itself into the focused app window;
+// this closes the one layer the key would have closed here: the open
+// popover, else the sheet or dialog on top.
+//
+// This is the fixed layer's job, not the kit's: the kit also installs
+// into apps that are not in a Makersclaw window, and the message is the
+// platform's.
+export default function EscapeRelay() {
+  useEffect(() => {
+    const onMessage = (event) => {
+      if (isDeskEscape(event, window)) closeTopLayer(document);
+    };
+    window.addEventListener("message", onMessage);
+    return () => window.removeEventListener("message", onMessage);
+  }, []);
+  return null;
+}

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

@@ -0,0 +1,218 @@
+// The app lives in a frame: the App tab of its window on the founder's
+// desk. Two things about that frame are not what a page assumes, and the
+// fixed layer (app/auto-refresh.jsx, app/escape-relay.jsx) answers both
+// with the rules below. They are plain functions over a document so
+// `npm test` in the template can hold them to what was seen.
+//
+// 1. A hidden tab is still "visible". The window keeps the App tab
+//    MOUNTED behind Agent, Runs, Activity and Settings (display: none, so
+//    switching back never reloads the app), and the Page Visibility API
+//    speaks for the whole browser tab, not the frame: document.hidden
+//    stays false and innerWidth keeps its last value while the App tab is
+//    off. An IntersectionObserver on the root element does see it — it
+//    reports "not intersecting" the moment the tab is switched away and
+//    "intersecting" when it comes back (measured in the desk's own
+//    window, 2026-09-25). `onScreen` below is that answer.
+//
+// 2. Escape pressed on the desk never reaches the app. A sheet opened in
+//    the app covers the App tab, the founder clicks the window's bar above
+//    it (Running, Reload), and focus is now the desk's: the key goes to
+//    the desk's document, the <dialog> in the frame never hears it, and
+//    the sheet stays open until the app is loaded again (content-calendar
+//    and a podcast guest board, 2026-09-25). The frame boundary is the
+//    only thing in the way — and in production the app is on its own
+//    host, so nothing but a message crosses it. The contract: the desk
+//    hands an Escape it did not use itself to the focused app window as
+//    postMessage({ type: "claw:escape" }), and the app closes ONE layer,
+//    the one Escape would have closed had it landed here. The desk's
+//    half is claw's (its OS shell's Escape, web/src/os/os-keys.ts) and
+//    ships apart from this; until it does, no such message arrives and
+//    nothing here changes what an app does.
+
+/** The message the desk posts into the app's frame for an Escape it did
+ *  not use itself. */
+export const ESCAPE_MESSAGE = "claw:escape";
+
+// ---------------------------------------------------------------------------
+// Auto-refresh
+
+/** How often the page re-renders from the server while it is shown. */
+export const REFRESH_MS = 5000;
+
+/** How long after the last keystroke in a field a refresh still waits:
+ *  long enough to tab from one field to the next, or to the Save button,
+ *  without a refresh landing in between. */
+export const QUIET_MS = 10000;
+
+/** How long the probe may take before the tick counts the app as down. A
+ *  proxy that holds the request — a sandbox waking, a stalled connection
+ *  — would otherwise keep that tick waiting, and skip every tick after
+ *  it, until the browser gave up on the fetch, minutes later. */
+export const PROBE_TIMEOUT_MS = 4000;
+
+// What takes typing. A button, a checkbox or a slider is a click, not a
+// half-typed word, so focus on one does not hold a refresh.
+const NOT_TYPED = new Set(["button", "submit", "reset", "checkbox", "radio", "range", "color", "file", "hidden", "image"]);
+
+function takesTyping(el) {
+  const tag = String(el.tagName || "").toLowerCase();
+  if (tag === "textarea" || tag === "select") return true;
+  if (tag === "input") return !NOT_TYPED.has(String(el.type || "text").toLowerCase());
+  return Boolean(el.isContentEditable);
+}
+
+/** Is the founder in the middle of something a reload would lose?
+ *
+ *  - Focus in the field they typed in last, while it still holds text:
+ *    the half-typed word. `typed` is that field, the target of the last
+ *    `input` event (app/auto-refresh.jsx keeps it). Focus alone does not
+ *    count: the first draft of this rule counted it, and an autofocused
+ *    search box, the note editor record-notes opens focused, or a caret
+ *    parked in a doc held every refresh until the founder clicked
+ *    elsewhere, so the agent's writes never appeared (review before
+ *    0.3.3 was published, 2026-09-25). Nothing typed is nothing lost, and
+ *    an emptied field (a quick-add box its own Enter cleared) holds
+ *    nothing either.
+ *  - A dialog open over the page, whatever was done in it: a sheet's form
+ *    is filled by clicks as much as by keys (a date picked, a menu item
+ *    chosen), and a click fires no `input`. The rows behind a sheet catch
+ *    up within a tick of its closing.
+ *
+ *  The typed field is judged by the `input` event, not by value against
+ *  defaultValue: React keeps a controlled input's value attribute in step
+ *  with what was typed, so the two always agree there, typed or not. */
+export function isEditing(doc, typed = null) {
+  const el = doc.activeElement;
+  if (el && el !== doc.body && typed && (el === typed || el.contains?.(typed)) && takesTyping(el)) {
+    if (el.isContentEditable || String(el.value ?? "") !== "") return true;
+  }
+  return Boolean(doc.querySelector("dialog[open]"));
+}
+
+/** One tick's decision: refresh only when someone can see the page and is
+ *  not typing into it. `quietFor` is the time since the last input event
+ *  (Infinity when there was none). */
+export function shouldRefresh({ visible, onScreen, editing, quietFor }) {
+  return Boolean(visible && onScreen && !editing && quietFor >= QUIET_MS);
+}
+
+/** 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.
+ *
+ *  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
+ *  "up"; it worked, but the browser logs every 404 fetch as a console
+ *  error — twelve red lines a minute in every open app, where a QA pass
+ *  reads an error seen once as a bug (review before publish,
+ *  2026-09-25). A GET, not a HEAD: the platform's product
+ *  proxy routes GET, POST, PUT, PATCH and DELETE and answers a HEAD with
+ *  its own 404 without asking the app (measured through the local stack,
+ *  2026-09-25). */
+export function probeUrl(doc) {
+  const base = doc.documentElement?.getAttribute?.("data-claw-base-path") ?? "";
+  return `${base}/claw-alive`;
+}
+
+/** Will a refresh be answered by the app? Only a 2xx says so, from the
+ *  probe route. Everything else is no: a 5xx (the proxy's 502 while the
+ *  app restarts, its 503 while it wakes or a ship swaps the build), a 401
+ *  or 404 page from the proxy (a grant gone stale, the app deleted), no
+ *  answer, or no answer within PROBE_TIMEOUT_MS. A 401 is no for good
+ *  reason: the reload it would cause follows the proxy's way back for a
+ *  stale grant, a bounce through the dashboard, and the dashboard refuses
+ *  to be framed (claw's web/vercel.json). A refresh must not take the
+ *  frame there on its own.
+ *
+ *  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
+ *  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
+ *  moment between the answer and the refresh; while the app is down, the
+ *  page stays as it is and the next tick asks again. A new build answers
+ *  too, and the refresh after it loads that build (Next reloads for a
+ *  changed build id), which is why a refresh waits for the founder to
+ *  stop typing. */
+export async function answering(url, fetchImpl = globalThis.fetch, timeoutMs = PROBE_TIMEOUT_MS) {
+  if (!url || typeof fetchImpl !== "function") return false;
+  const init = { cache: "no-store", credentials: "same-origin" };
+  if (typeof AbortSignal !== "undefined" && typeof AbortSignal.timeout === "function") init.signal = AbortSignal.timeout(timeoutMs);
+  try {
+    const res = await fetchImpl(url, init);
+    return res.status >= 200 && res.status < 300;
+  } catch {
+    return false; // no answer, or none in time (the signal's TimeoutError)
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Escape from the desk
+
+const matches = (el, selector) => {
+  try {
+    return typeof el.matches === "function" && el.matches(selector);
+  } catch {
+    return false; // a selector this browser does not know
+  }
+};
+
+/** A popover Escape closes: an open auto or hint one (a manual popover —
+ *  a toast — is closed by its own code, never by Escape). */
+function isOpenPopover(el) {
+  const kind = el.getAttribute?.("popover");
+  if (kind == null || kind === "manual") return false;
+  return matches(el, ":popover-open");
+}
+
+/** A dialog Escape closes: an open modal one (the kit's Sheet). */
+function isOpenModal(el) {
+  if (!el.open) return false;
+  try {
+    return el.matches(":modal");
+  } catch {
+    return true; // a browser without :modal: any open dialog
+  }
+}
+
+/** The layer Escape would close, or null: popovers before dialogs (a
+ *  popover is always shown over the dialog it was opened from), and among
+ *  them the one holding focus, else the last in the document — the most
+ *  recently opened, as the browser's top layer orders them. */
+export function topLayer(doc) {
+  const popovers = [...doc.querySelectorAll("[popover]")].filter(isOpenPopover);
+  const dialogs = [...doc.querySelectorAll("dialog[open]")].filter(isOpenModal);
+  for (const layers of [popovers, dialogs]) {
+    if (!layers.length) continue;
+    const focused = doc.activeElement;
+    const holding = focused ? layers.filter((l) => l.contains(focused)) : [];
+    // The innermost of those that hold focus: the one no other contains.
+    const inner = holding.find((l) => !holding.some((o) => o !== l && l.contains(o)));
+    return inner ?? layers[layers.length - 1];
+  }
+  return null;
+}
+
+/** Close the top layer as Escape would; true when there was one. A dialog
+ *  gets requestClose() where the browser has it — `cancel` fires first,
+ *  so a sheet that guards its form is asked, exactly as by the key. */
+export function closeTopLayer(doc) {
+  const layer = topLayer(doc);
+  if (!layer) return false;
+  if (layer.tagName?.toLowerCase() === "dialog") {
+    if (typeof layer.requestClose === "function") layer.requestClose();
+    else layer.close();
+  } else {
+    layer.hidePopover();
+  }
+  return true;
+}
+
+/** Is this message the desk's Escape? Only the window around the frame
+ *  may send it. */
+export function isDeskEscape(event, win) {
+  return Boolean(win && win.parent && win.parent !== win && event?.source === win.parent && event?.data?.type === ESCAPE_MESSAGE);
+}

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

@@ -1,8 +1,10 @@
 import "./globals.css";
 import { cookies, headers } from "next/headers";
+import { Examples } from "../components/parts/fixture";
 import { surfaceNav } from "../surfaces";
 import AutoRefresh from "./auto-refresh";
 import ErrorRelay from "./error-relay";
+import EscapeRelay from "./escape-relay";
 import Shell from "./shell";
 
 // FIXED — the platform agent does not edit this file. Design lives in
@@ -29,11 +31,21 @@ export const metadata = { title: process.env.CLAW_PRODUCT || "Artifact" };
 // with no proxy (local `next dev`, where the link 404s harmlessly). The
 // href is prefixed by hand: Next's basePath applies to next/link and
 // assets, not to a literal <link>.
+//
+// Examples (components/parts/fixture.jsx) are off inside a workspace: an
+// installed app never shows example rows. product_run sets
+// CLAW_ARTIFACT_ID for every workspace app; the store's standalone loop
+// has only DATABASE_URL, so its screens still open on their example.
+// CLAW_EXAMPLES=1 forces them on. Read per request (the layout is
+// dynamic), so where the app runs decides, not where it was built. The
+// provider comes straight from its file, not parts/index.js: the layout
+// needs nothing else from the parts.
 export default async function RootLayout({ children }) {
   const basePath = process.env.CLAW_BASE_PATH || "";
   const name = process.env.CLAW_PRODUCT || "Artifact";
   const wanted = (await headers()).get("x-claw-theme") || (await cookies()).get("claw_theme")?.value;
   const theme = wanted === "light" ? "light" : "dark";
+  const examples = process.env.CLAW_EXAMPLES === "1" || !process.env.CLAW_ARTIFACT_ID;
   return (
     <html lang="en" data-claw-base-path={basePath} data-claw-product={name} data-theme={theme}>
       <head>
@@ -42,9 +54,12 @@ export default async function RootLayout({ children }) {
       <body>
         <AutoRefresh />
         <ErrorRelay />
-        <Shell name={name} surfaces={surfaceNav()}>
-          {children}
-        </Shell>
+        <EscapeRelay />
+        <Examples allowed={examples}>
+          <Shell name={name} surfaces={surfaceNav()}>
+            {children}
+          </Shell>
+        </Examples>
       </body>
     </html>
   );

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
@@ -83,7 +83,9 @@ const SKIP = [
   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$/,
@@ -223,7 +225,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 +239,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 +278,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 +293,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");
 }
 
@@ -625,6 +636,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";