makersclaw 0.3.2 → 0.5.1

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

@@ -1,26 +1,53 @@
 "use client";
 
-import { useEffect } from "react";
+import { useEffect, useRef, useTransition } from "react";
 import { useRouter } from "next/navigation";
+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 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 while the page is
+// shown; router.refresh() keeps form state and scroll, a reload would not.
+//
+// The rules are app/frame.js's (refreshLoop, and the reasons with each):
+//
+//   - 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();
+  const [pending, startTransition] = useTransition();
+  const landed = useRef([]); // the loop's waits for the refresh in flight
+
+  // 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]);
+
   useEffect(() => {
-    const tick = () => {
-      if (document.visibilityState === "visible") router.refresh();
-    };
-    const id = setInterval(tick, EVERY_MS);
-    document.addEventListener("visibilitychange", tick);
-    return () => {
-      clearInterval(id);
-      document.removeEventListener("visibilitychange", tick);
-    };
+    const loop = refreshLoop({
+      doc: document,
+      refresh: () =>
+        new Promise((done) => {
+          landed.current.push(done);
+          startTransition(() => router.refresh());
+        }),
+    });
+    return () => loop.stop();
   }, [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,409 @@
+// 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: the
+ *  wait between one refresh landing and the next asking. */
+export const REFRESH_MS = 5000;
+
+/** The longest wait between two refreshes, however slow the last was. */
+export const MAX_REFRESH_MS = 60000;
+
+/** How long a refresh may stay pending before the loop stops waiting for
+ *  it: a transition a navigation overtook never reports back, and one
+ *  that never lands must not end the refreshing for good. */
+export const REFRESH_SETTLE_MS = 60000;
+
+/** How long a shown page may go without a sign of anyone — a key, the
+ *  pointer, a touch, a wheel, focus — before the refresh stops. The
+ *  platform stops an app nobody used for 30 minutes, and every refresh is
+ *  a use: a tab left open on a screen nobody looks at kept its app, and
+ *  the sandbox under it, running all night. The same 30 minutes here, so
+ *  an app left open is an app left alone. */
+export const UNATTENDED_MS = 30 * 60 * 1000;
+
+/** What counts as someone there. */
+export const PRESENCE_EVENTS = ["pointerdown", "pointermove", "keydown", "wheel", "touchstart", "focusin"];
+
+/** What a surface puts on its root to keep the page as it is: no refresh,
+ *  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
+ *  every navigation. */
+export const REFRESH_OFF = '[data-claw-refresh="off"]';
+
+/** 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, is not
+ *  typing into it, and no surface on it has opted out. `quietFor` is the
+ *  time since the last input event (Infinity when there was none). */
+export function shouldRefresh({ visible, onScreen, editing, quietFor, optedOut = false }) {
+  return Boolean(visible && onScreen && !editing && !optedOut && quietFor >= QUIET_MS);
+}
+
+/** Has a surface on the page opted out (REFRESH_OFF on its root)? */
+export function refreshOptedOut(doc) {
+  try {
+    return Boolean(doc.querySelector(REFRESH_OFF));
+  } catch {
+    return false;
+  }
+}
+
+/** The wait before the next tick: the interval, plus what the last tick
+ *  cost — its probe and its refresh — so a busy stack is asked less often
+ *  the busier it is, up to MAX_REFRESH_MS. */
+export function nextRefreshIn(lastCostMs = 0) {
+  const cost = Number.isFinite(lastCostMs) && lastCostMs > 0 ? lastCostMs : 0;
+  return Math.min(MAX_REFRESH_MS, REFRESH_MS + cost);
+}
+
+/** 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)
+  }
+}
+
+/** `promise`, or undefined once `ms` have passed, whichever comes first. */
+function within(promise, ms, timers) {
+  let timer = null;
+  const late = new Promise((resolve) => (timer = timers.setTimeout(resolve, ms)));
+  return Promise.race([Promise.resolve(promise).catch(() => undefined), late]).finally(() => timers.clearTimeout(timer));
+}
+
+/**
+ * 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() }
+ *
+ * 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
+ * interval was cut off by the next one — 100+ refreshes in two minutes on
+ * an idle page, a 502 or 503 whenever the stack was busy — and a page left
+ * open in a hidden tab kept asking, so the platform's idle sweep never
+ * stopped its app (install test and basics wave, 2026-09-27). Now:
+ *
+ *   - one tick at a time: the next is timed only once the last refresh
+ *     has landed, REFRESH_MS plus what the last tick cost (nextRefreshIn);
+ *   - no timer at all while the page is hidden or behind the window's
+ *     other tabs; coming back ticks at once, so the rows are current;
+ *   - none either after UNATTENDED_MS shown with no sign of anyone
+ *     (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).
+ *
+ * The rules are asked again after the probe: typing may have started, or
+ * the tab changed, while it was on its way.
+ */
+export function refreshLoop({
+  doc,
+  refresh,
+  probe = () => answering(probeUrl(doc)),
+  now = () => Date.now(),
+  timers = globalThis,
+  Observer = globalThis.IntersectionObserver,
+}) {
+  let onScreen = true;
+  let lastInput = -Infinity;
+  let typed = null; // the field the last `input` event came from
+  let timer = null;
+  let busy = false; // a probe or a refresh is out
+  let stopped = false;
+  let cost = 0; // what the last tick took, probe and refresh
+  let lastSeen = now(); // the last sign of someone; opening the page is one
+  let unattended = false; // stopped for want of anyone: the next sign ticks
+
+  const visible = () => doc.visibilityState === "visible";
+  const ready = () =>
+    shouldRefresh({
+      visible: visible(),
+      onScreen,
+      editing: isEditing(doc, typed),
+      quietFor: now() - lastInput,
+      optedOut: refreshOptedOut(doc),
+    });
+
+  const cancel = () => {
+    timers.clearTimeout(timer);
+    timer = null;
+  };
+  // Timed only while shown and attended: hidden, the loop waits for the
+  // page to come back (onVisible, the observer), and unattended for the
+  // next sign of someone (seen), rather than for a clock.
+  const schedule = () => {
+    cancel();
+    if (!stopped && !busy && !unattended && visible() && onScreen) timer = timers.setTimeout(tick, nextRefreshIn(cost));
+  };
+
+  async function tick() {
+    cancel();
+    if (stopped || busy) return;
+    if (visible() && onScreen && now() - lastSeen >= UNATTENDED_MS) {
+      unattended = true;
+      return;
+    }
+    if (!ready()) return schedule();
+    busy = true;
+    const started = now();
+    try {
+      if ((await probe()) && !stopped && ready()) await within(refresh(), REFRESH_SETTLE_MS, timers);
+    } catch {
+      // A probe or a refresh that throws is one that did not land; the
+      // next tick asks again. Never an unhandled rejection: the error
+      // relay would report every one to the platform.
+    } finally {
+      busy = false;
+      cost = now() - started;
+    }
+    schedule();
+  }
+
+  const onInput = (event) => {
+    lastInput = now();
+    typed = event.target;
+  };
+  // Someone is there. After a stop for want of anyone, refresh at once.
+  const seen = () => {
+    lastSeen = now();
+    if (!unattended) return;
+    unattended = false;
+    tick();
+  };
+  // Back on screen: someone looked, and the rows may be old.
+  const back = () => {
+    lastSeen = now();
+    unattended = false;
+    tick();
+  };
+  const onVisible = () => (visible() ? back() : cancel());
+
+  let observer = null;
+  if (typeof Observer === "function") {
+    observer = new Observer((entries) => {
+      const was = onScreen;
+      onScreen = entries[entries.length - 1].isIntersecting;
+      if (onScreen && !was) back();
+      else if (!onScreen) cancel();
+    });
+    observer.observe(doc.documentElement);
+  }
+  const PASSIVE = { capture: true, passive: true };
+  const win = doc.defaultView ?? null;
+  doc.addEventListener("visibilitychange", onVisible);
+  doc.addEventListener("input", onInput, true);
+  for (const type of PRESENCE_EVENTS) doc.addEventListener(type, seen, PASSIVE);
+  win?.addEventListener?.("focus", seen);
+  schedule();
+
+  return {
+    stop() {
+      stopped = true;
+      cancel();
+      observer?.disconnect();
+      doc.removeEventListener("visibilitychange", onVisible);
+      doc.removeEventListener("input", onInput, true);
+      for (const type of PRESENCE_EVENTS) doc.removeEventListener(type, seen, PASSIVE);
+      win?.removeEventListener?.("focus", seen);
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// 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>
   );