makersclaw 0.1.0

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

@@ -0,0 +1,86 @@
+import { cx } from "./cx";
+import { Button } from "./button";
+import { Icon } from "./icon";
+
+// Static parts: a card, a notice, a badge, a kicker, the empty state.
+// Server-safe (no hooks), so a server surface can use them directly.
+
+const TONES = {
+  neutral: { box: "border-border bg-card text-card-foreground", icon: "info" },
+  info: { box: "border-info/40 bg-card text-card-foreground", icon: "info" },
+  success: { box: "border-success/40 bg-card text-card-foreground", icon: "check" },
+  warning: { box: "border-warning/50 bg-card text-card-foreground", icon: "warning" },
+  danger: { box: "border-destructive/50 bg-card text-card-foreground", icon: "warning" },
+};
+
+/** A raised panel with an optional heading row. */
+export function Card({ title, description, actions, className, children, as: Tag = "section" }) {
+  return (
+    <Tag className={cx("rounded-lg border border-border bg-card p-4 text-card-foreground", className)}>
+      {title || actions ? (
+        <div className="mb-3 flex items-start justify-between gap-3">
+          <div className="min-w-0">
+            {title ? <h2 className="text-base font-semibold leading-tight">{title}</h2> : null}
+            {description ? <p className="mt-0.5 text-sm text-muted-foreground">{description}</p> : null}
+          </div>
+          {actions ? <div className="flex shrink-0 gap-2">{actions}</div> : null}
+        </div>
+      ) : null}
+      {children}
+    </Tag>
+  );
+}
+
+/** One line the user should read, with an optional action. `tone`
+ *  neutral · info · success · warning · danger. Colour is the signal, so
+ *  status tones are for status only — never decoration. */
+export function Notice({ tone = "neutral", title, action, onDismiss, className, children }) {
+  const t = TONES[tone] ?? TONES.neutral;
+  return (
+    <div role={tone === "danger" ? "alert" : "status"} className={cx("flex items-start gap-3 rounded-lg border p-3 text-sm", t.box, className)}>
+      <Icon name={t.icon} className="mt-0.5 shrink-0 text-muted-foreground" />
+      <div className="min-w-0 flex-1">
+        {title ? <p className="font-medium">{title}</p> : null}
+        {children ? <div className={cx(title && "mt-0.5", "text-muted-foreground")}>{children}</div> : null}
+      </div>
+      {action ? <div className="shrink-0">{action}</div> : null}
+      {onDismiss ? (
+        <Button variant="quiet" size="sm" onClick={onDismiss} aria-label="Dismiss" className="-my-1 -mr-1 w-9 px-0">
+          <Icon name="x" />
+        </Button>
+      ) : null}
+    </div>
+  );
+}
+
+/** A small label for a state or a count. */
+export function Badge({ tone = "neutral", className, children }) {
+  const look = {
+    neutral: "bg-muted text-muted-foreground",
+    primary: "bg-primary text-primary-foreground",
+    success: "bg-success/15 text-success",
+    warning: "bg-warning/15 text-warning",
+    danger: "bg-destructive/15 text-destructive",
+    info: "bg-info/15 text-info",
+  }[tone];
+  return <span className={cx("inline-flex items-center rounded-sm px-1.5 py-0.5 text-2xs font-medium uppercase tracking-wide", look, className)}>{children}</span>;
+}
+
+/** The small uppercase line above a heading. */
+export function Kicker({ className, children }) {
+  return <p className={cx("text-2xs font-medium uppercase tracking-wider text-muted-foreground", className)}>{children}</p>;
+}
+
+/** What a surface shows when a real collection is empty AND there is no
+ *  fixture to show (a filter with no matches, a search with no results).
+ *  Says what would appear here and offers the one way to make it. */
+export function Empty({ icon = "search", title, body, action, className }) {
+  return (
+    <div className={cx("grid place-items-center gap-2 rounded-lg border border-dashed border-border px-6 py-10 text-center", className)}>
+      <Icon name={icon} size={22} className="text-muted-foreground" />
+      <p className="text-sm font-medium">{title}</p>
+      {body ? <p className="max-w-prose text-sm text-muted-foreground">{body}</p> : null}
+      {action ? <div className="mt-2">{action}</div> : null}
+    </div>
+  );
+}

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

@@ -0,0 +1,89 @@
+"use client";
+
+import { useEffect, useRef } from "react";
+import { cx } from "./cx";
+import { Button, IconButton } from "./button";
+
+// Sheet — the one overlay. A native <dialog> (focus trap, Esc, scroll
+// lock and the top layer come from the browser), docked to the side the
+// surface asks for. Mobile first: on a narrow window every side becomes
+// a bottom sheet the thumb can reach. Controlled: `open` + `onClose`.
+//
+//   side   end (a rail beside the work; the default) · center (a dialog)
+//          · bottom
+//
+// Confirm below is the "delete this?" case — never window.confirm().
+
+const SIDES = {
+  end:
+    "inset-y-0 right-0 left-auto h-dvh max-h-none w-full max-w-md rounded-none border-l " +
+    "max-sm:inset-x-0 max-sm:top-auto max-sm:bottom-0 max-sm:h-auto max-sm:max-h-[85dvh] max-sm:max-w-none max-sm:rounded-t-xl max-sm:border-l-0 max-sm:border-t",
+  center: "m-auto w-[calc(100%-2rem)] max-w-lg rounded-lg border max-sm:mb-0 max-sm:mt-auto max-sm:w-full max-sm:max-w-none max-sm:rounded-b-none max-sm:rounded-t-xl",
+  bottom: "inset-x-0 top-auto bottom-0 w-full max-w-none max-h-[85dvh] rounded-t-xl border-t",
+};
+
+export function Sheet({ open, onClose, title, description, side = "end", footer, className, children }) {
+  const ref = useRef(null);
+
+  useEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+    if (open && !el.open) el.showModal();
+    else if (!open && el.open) el.close();
+  }, [open]);
+
+  return (
+    <dialog
+      ref={ref}
+      onClose={() => onClose?.()}
+      onClick={(e) => {
+        if (e.target === ref.current) ref.current.close();
+      }}
+      className={cx(
+        "fixed m-0 flex-col bg-popover p-0 text-popover-foreground shadow-xl border-border open:flex",
+        SIDES[side] ?? SIDES.end,
+        className,
+      )}
+      aria-labelledby={title ? "sheet-title" : undefined}
+    >
+      <div className="flex min-h-0 flex-1 flex-col">
+        {title || onClose ? (
+          <header className="flex items-start justify-between gap-3 border-b border-border px-4 py-3">
+            <div className="min-w-0">
+              {title ? <h2 id="sheet-title" className="text-base font-semibold leading-tight">{title}</h2> : null}
+              {description ? <p className="mt-0.5 text-sm text-muted-foreground">{description}</p> : null}
+            </div>
+            <IconButton icon="x" label="Close" size="sm" onClick={() => ref.current?.close()} className="-mr-2" />
+          </header>
+        ) : null}
+        <div className="min-h-0 flex-1 overflow-y-auto px-4 py-4">{children}</div>
+        {footer ? <footer className="flex flex-wrap justify-end gap-2 border-t border-border px-4 py-3">{footer}</footer> : null}
+      </div>
+    </dialog>
+  );
+}
+
+/** A yes/no with the consequence spelled out. `tone="danger"` for a
+ *  destructive confirm. Resolves through `onConfirm`; closes either way. */
+export function Confirm({ open, onClose, onConfirm, title, body, confirmLabel = "Confirm", cancelLabel = "Cancel", tone = "neutral", busy }) {
+  return (
+    <Sheet
+      open={open}
+      onClose={onClose}
+      side="center"
+      title={title}
+      footer={
+        <>
+          <Button variant="quiet" onClick={onClose} disabled={busy}>
+            {cancelLabel}
+          </Button>
+          <Button variant={tone === "danger" ? "danger" : "primary"} onClick={onConfirm} disabled={busy}>
+            {busy ? "Working…" : confirmLabel}
+          </Button>
+        </>
+      }
+    >
+      {body ? <p className="text-sm text-muted-foreground">{body}</p> : null}
+    </Sheet>
+  );
+}

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

@@ -0,0 +1,81 @@
+"use client";
+
+import { useId, useRef } from "react";
+import { cx } from "./cx";
+
+// Tabs — one strip, arrow keys move and select, Home/End jump. Controlled:
+// `value` + `onChange`. The strip is `Tabs`; each panel is a `TabPanel`
+// keyed the same way, so the caller decides what a tab shows. Tabs are
+// for views of ONE thing (a record's notes | history), never for the
+// app's surfaces — those are the shell's nav.
+//
+//   tabs   [{ key, label, count? }]
+
+export function Tabs({ tabs, value, onChange, id, className, "aria-label": ariaLabel }) {
+  const auto = useId();
+  const base = id ?? auto;
+  const refs = useRef([]);
+
+  function onKeyDown(e, index) {
+    const last = tabs.length - 1;
+    let next = null;
+    if (e.key === "ArrowRight") next = index === last ? 0 : index + 1;
+    else if (e.key === "ArrowLeft") next = index === 0 ? last : index - 1;
+    else if (e.key === "Home") next = 0;
+    else if (e.key === "End") next = last;
+    if (next === null) return;
+    e.preventDefault();
+    refs.current[next]?.focus();
+    onChange?.(tabs[next].key);
+  }
+
+  return (
+    <div role="tablist" aria-label={ariaLabel} className={cx("flex gap-1 overflow-x-auto border-b border-border", className)}>
+      {tabs.map((t, i) => {
+        const selected = t.key === value;
+        return (
+          <button
+            key={t.key}
+            ref={(el) => {
+              refs.current[i] = el;
+            }}
+            type="button"
+            role="tab"
+            id={`${base}-tab-${t.key}`}
+            aria-selected={selected}
+            aria-controls={`${base}-panel-${t.key}`}
+            tabIndex={selected ? 0 : -1}
+            onClick={() => onChange?.(t.key)}
+            onKeyDown={(e) => onKeyDown(e, i)}
+            className={cx(
+              "-mb-px inline-flex min-h-11 items-center gap-2 whitespace-nowrap border-b-2 px-3 text-sm outline-none focus-visible:ring-2 focus-visible:ring-ring",
+              selected ? "border-primary font-medium text-foreground" : "border-transparent text-muted-foreground hover:text-foreground",
+            )}
+          >
+            {t.label}
+            {typeof t.count === "number" ? (
+              <span data-nums className="rounded-sm bg-muted px-1.5 text-2xs text-muted-foreground">
+                {t.count}
+              </span>
+            ) : null}
+          </button>
+        );
+      })}
+    </div>
+  );
+}
+
+export function TabPanel({ tab, value, id, className, children }) {
+  const selected = tab === value;
+  return (
+    <div
+      role="tabpanel"
+      id={id ? `${id}-panel-${tab}` : undefined}
+      aria-labelledby={id ? `${id}-tab-${tab}` : undefined}
+      hidden={!selected}
+      className={cx(selected && "pt-4", className)}
+    >
+      {selected ? children : null}
+    </div>
+  );
+}

package/templates/next/files/lib/actions.js

@@ -0,0 +1,187 @@
+"use server";
+
+import { headers } from "next/headers";
+import { revalidatePath } from "next/cache";
+import { ident, logActivity, query } from "./db";
+
+// Every write the app makes. Callable from server and client components
+// alike (they are server actions). Each one goes through lib/db.js,
+// records an activity row, and re-renders the app. Table and column names
+// are quoted through ident(), which refuses anything that is not a plain
+// identifier. Returns { ok } or { ok: false, error }; never throws.
+//
+// `surface` is optional: middleware.js stamps the current surface key on
+// the request, so a surface rarely needs to pass it.
+//
+// `detail` is the founder's sentence for the row. The OS Activity tab
+// prints the action word and then the detail, verbatim, side by side —
+// so a detail never repeats the verb ("added" + "added to leads") and
+// never names the table, which is the app's plumbing, not the founder's
+// words. Pass a detail when the surface can say what changed in plain
+// words; leave it out and the tab shows the action word alone.
+
+async function actor() {
+  try {
+    const email = (await headers()).get("x-claw-user-email");
+    return email ? `user:${email}` : "user:unknown";
+  } catch {
+    return "user:unknown";
+  }
+}
+
+async function surfaceOf(explicit) {
+  if (typeof explicit === "string" && explicit) return explicit;
+  if (explicit && typeof explicit === "object" && typeof explicit.key === "string") return explicit.key;
+  try {
+    return (await headers()).get("x-claw-surface") || null;
+  } catch {
+    return null;
+  }
+}
+
+function done() {
+  revalidatePath("/", "layout");
+}
+
+function fail(error) {
+  const message = error?.message ?? String(error);
+  console.error(`[actions] write failed: ${message}`);
+  return { ok: false, error: message };
+}
+
+/** Change columns of one row. `patch` is { column: value }. */
+export async function updateRow({ source, idColumn = "id", id, patch, surface, action = "edited", detail, data }) {
+  try {
+    const cols = Object.keys(patch ?? {}).filter((c) => patch[c] !== undefined);
+    if (!cols.length) return { ok: false, error: "nothing to change" };
+    const sets = cols.map((c, i) => `${ident(c)} = $${i + 2}`).join(", ");
+    const { rowCount } = await query(
+      `UPDATE ${ident(source)} SET ${sets} WHERE ${ident(idColumn)} = $1`,
+      [id, ...cols.map((c) => patch[c])],
+    );
+    if (!rowCount) return { ok: false, error: "row not found" };
+    await logActivity({
+      action,
+      surface: await surfaceOf(surface),
+      row_ref: id,
+      detail: detail ?? `${cols.join(", ")} changed`,
+      data: data ?? patch,
+      by: await actor(),
+    });
+    done();
+    return { ok: true };
+  } catch (error) {
+    return fail(error);
+  }
+}
+
+/** Move a row to another state (a board column, a stage select). */
+export async function moveRow({ source, idColumn = "id", id, stateColumn, to, surface }) {
+  return updateRow({
+    source,
+    idColumn,
+    id,
+    patch: { [stateColumn]: to },
+    surface,
+    action: "moved",
+    detail: `to ${to}`,
+    data: { [stateColumn]: to },
+  });
+}
+
+/** Add a row. `values` is { column: value }; returns the new id. */
+export async function insertRow({ source, idColumn = "id", values, surface, action = "added", detail }) {
+  try {
+    const cols = Object.keys(values ?? {}).filter((c) => values[c] !== undefined);
+    if (!cols.length) return { ok: false, error: "nothing to add" };
+    const placeholders = cols.map((_, i) => `$${i + 1}`).join(", ");
+    const { rows } = await query(
+      `INSERT INTO ${ident(source)} (${cols.map(ident).join(", ")}) VALUES (${placeholders}) RETURNING ${ident(idColumn)}`,
+      cols.map((c) => values[c]),
+    );
+    const id = rows[0]?.[idColumn];
+    await logActivity({
+      action,
+      surface: await surfaceOf(surface),
+      row_ref: id,
+      detail: detail ?? null,
+      data: values,
+      by: await actor(),
+    });
+    done();
+    return { ok: true, id };
+  } catch (error) {
+    return fail(error);
+  }
+}
+
+export async function deleteRow({ source, idColumn = "id", id, surface, detail }) {
+  try {
+    const { rowCount } = await query(`DELETE FROM ${ident(source)} WHERE ${ident(idColumn)} = $1`, [id]);
+    if (!rowCount) return { ok: false, error: "row not found" };
+    await logActivity({
+      action: "removed",
+      surface: await surfaceOf(surface),
+      row_ref: id,
+      detail: detail ?? null,
+      by: await actor(),
+    });
+    done();
+    return { ok: true };
+  } catch (error) {
+    return fail(error);
+  }
+}
+
+/**
+ * Settings: one key. Table mode updates the (key, value) row in `source`
+ * and inserts one when there is none — an UPDATE then INSERT rather than
+ * ON CONFLICT, because a settings table made with the `sql` verb usually
+ * has a plain `key text` column and Postgres rejects ON CONFLICT without a
+ * unique index on it. JSON mode sets the key inside the jsonb `column` of
+ * the row `id` in `source`.
+ */
+export async function saveSetting({
+  mode = "table",
+  source,
+  keyColumn = "key",
+  valueColumn = "value",
+  column,
+  idColumn = "id",
+  id,
+  key,
+  value,
+  surface,
+}) {
+  try {
+    if (!key) return { ok: false, error: "no key" };
+    if (mode === "json") {
+      const { rowCount } = await query(
+        `UPDATE ${ident(source)} SET ${ident(column)} = jsonb_set(COALESCE(${ident(column)}, '{}'::jsonb), $2::text[], $3::jsonb, true) WHERE ${ident(idColumn)} = $1`,
+        [id, [key], JSON.stringify(value ?? null)],
+      );
+      if (!rowCount) return { ok: false, error: "row not found" };
+    } else {
+      const stored = typeof value === "object" && value !== null ? JSON.stringify(value) : value;
+      const { rowCount } = await query(
+        `UPDATE ${ident(source)} SET ${ident(valueColumn)} = $2 WHERE ${ident(keyColumn)} = $1`,
+        [key, stored],
+      );
+      if (!rowCount) {
+        await query(`INSERT INTO ${ident(source)} (${ident(keyColumn)}, ${ident(valueColumn)}) VALUES ($1, $2)`, [key, stored]);
+      }
+    }
+    await logActivity({
+      action: "edited",
+      surface: await surfaceOf(surface),
+      row_ref: mode === "json" ? id : key,
+      detail: `setting ${key} changed`,
+      data: { [key]: value },
+      by: await actor(),
+    });
+    done();
+    return { ok: true };
+  } catch (error) {
+    return fail(error);
+  }
+}

package/templates/next/files/lib/claw.js

@@ -0,0 +1,219 @@
+// The _claw API: what the Makersclaw gateway answers itself under this
+// product's path, before it proxies anything to the app
+// (docs/ARTIFACT-CONTRACTS.md §5). It is reachable from the BROWSER only —
+// the grant cookie is the identity — so everything here is client-side.
+//
+// Every call resolves; nothing throws. A 404 or a network error means the
+// gateway has no such route yet, and comes back as `unavailable: true` so
+// a surface renders a quiet "not connected yet" state instead of breaking.
+//
+// An app calls four of these. `me` (identity, status) and `events`
+// (errors) are plumbing. `chat` and `cancel` are COMMISSIONING — work the
+// founder asks for from inside the app, streamed back so they can watch
+// it (SOP §2.3); lib/platform.js wraps them as startJob / cancelJob and
+// lib/hooks.js as useJob. What an app still never calls is monitoring:
+// the OS draws Agent, Runs and Activity as tabs on its window. The rest
+// of the gateway's routes (§5) stay reachable through claw() /
+// clawStream() for a surface that has a real reason.
+
+/** The prefix the app is served under. The <html> attribute is set by the
+ *  running server, so it wins over the value inlined at build time. */
+export function clawBasePath() {
+  if (typeof document !== "undefined") {
+    const fromDom = document.documentElement.dataset.clawBasePath;
+    if (fromDom !== undefined) return fromDom;
+  }
+  return process.env.CLAW_BASE_PATH || "";
+}
+
+export function clawUrl(path) {
+  return `${clawBasePath()}/_claw/${String(path).replace(/^\/+/, "")}`;
+}
+
+/**
+ * The artifact's status (draft | active | paused | …), as last heard from
+ * _claw/me. It lives on <html> so that reportError — which runs from
+ * error boundaries with no access to any component's state — can tell a
+ * fault in the live preview of a draft from one in the launched artifact.
+ * app/error-relay.jsx (the fixed layout mounts it) publishes it on mount
+ * and when the tab comes back; useArtifact() publishes it too.
+ */
+export function publishStatus(status) {
+  if (typeof document === "undefined") return;
+  if (typeof status === "string" && status) document.documentElement.dataset.clawStatus = status;
+  else delete document.documentElement.dataset.clawStatus;
+}
+
+export function clawStatus() {
+  if (typeof document === "undefined") return null;
+  return document.documentElement.dataset.clawStatus || null;
+}
+
+// Before launch the artifact is only ever seen in the bench's live preview;
+// `piloting` is the pre-launch status of rows from before this cut.
+const PRELAUNCH = new Set(["draft", "piloting"]);
+
+/** Where an error happened, for _claw/events: the live preview of an
+ *  unlaunched artifact, or the running one. Unknown status → runtime. */
+export function errorSource() {
+  return PRELAUNCH.has(clawStatus()) ? "preview" : "runtime";
+}
+
+async function readError(res) {
+  const text = await res.text().catch(() => "");
+  try {
+    const parsed = JSON.parse(text);
+    return parsed.error || parsed.message || text || res.statusText;
+  } catch {
+    return text || res.statusText || `HTTP ${res.status}`;
+  }
+}
+
+/**
+ * claw("me") / claw("agent", { method: "PATCH", body: {...} })
+ *   → { ok: true, status, data }
+ *   → { ok: false, status, error, unavailable }
+ */
+export async function claw(path, { method = "GET", body, signal } = {}) {
+  let res;
+  try {
+    res = await fetch(clawUrl(path), {
+      method,
+      credentials: "same-origin",
+      cache: "no-store",
+      headers: {
+        accept: "application/json",
+        ...(body !== undefined ? { "content-type": "application/json" } : {}),
+      },
+      body: body !== undefined ? JSON.stringify(body) : undefined,
+      signal,
+    });
+  } catch (error) {
+    if (error?.name === "AbortError") return { ok: false, status: 0, error: "aborted", aborted: true };
+    return { ok: false, status: 0, error: "not reachable", unavailable: true };
+  }
+  if (res.status === 404) {
+    return { ok: false, status: 404, error: "not available yet", unavailable: true };
+  }
+  if (!res.ok) {
+    return { ok: false, status: res.status, error: await readError(res), unavailable: false };
+  }
+  const text = await res.text().catch(() => "");
+  let data = null;
+  if (text) {
+    try {
+      data = JSON.parse(text);
+    } catch {
+      data = text;
+    }
+  }
+  return { ok: true, status: res.status, data };
+}
+
+/** One SSE frame → { event, data }. The gateway names the event on the
+ *  `event:` line; a frame that carries it inside the JSON instead
+ *  (`{type}` or `{event}`) is read the same way. */
+function parseFrame(frame) {
+  let event = "message";
+  const lines = [];
+  for (const raw of frame.split("\n")) {
+    const line = raw.replace(/\r$/, "");
+    if (line.startsWith("event:")) event = line.slice(6).trim();
+    else if (line.startsWith("data:")) lines.push(line.slice(5).replace(/^ /, ""));
+  }
+  if (!lines.length) return null;
+  const text = lines.join("\n");
+  let data = text;
+  try {
+    data = JSON.parse(text);
+  } catch {
+    /* plain text data */
+  }
+  if (event === "message" && data && typeof data === "object") {
+    event = data.event || data.type || event;
+  }
+  return { event, data };
+}
+
+/**
+ * POST and consume a text/event-stream. `onEvent({ event, data })` is
+ * called for every frame as it arrives (delta / tool / done / error for
+ * the chat). Resolves when the stream ends, with the same shape as claw().
+ */
+export async function clawStream(path, body, onEvent, { signal } = {}) {
+  let res;
+  try {
+    res = await fetch(clawUrl(path), {
+      method: "POST",
+      credentials: "same-origin",
+      cache: "no-store",
+      headers: { accept: "text/event-stream", "content-type": "application/json" },
+      body: JSON.stringify(body ?? {}),
+      signal,
+    });
+  } catch (error) {
+    if (error?.name === "AbortError") return { ok: false, status: 0, error: "aborted", aborted: true };
+    return { ok: false, status: 0, error: "not reachable", unavailable: true };
+  }
+  if (res.status === 404) {
+    return { ok: false, status: 404, error: "not available yet", unavailable: true };
+  }
+  if (!res.ok) {
+    return { ok: false, status: res.status, error: await readError(res), unavailable: false };
+  }
+  if (!res.body) return { ok: false, status: res.status, error: "empty stream" };
+
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  const dispatch = (frame) => {
+    const parsed = parseFrame(frame);
+    if (parsed) onEvent(parsed);
+  };
+  try {
+    for (;;) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true }).replace(/\r\n/g, "\n");
+      let idx;
+      while ((idx = buffer.indexOf("\n\n")) >= 0) {
+        dispatch(buffer.slice(0, idx));
+        buffer = buffer.slice(idx + 2);
+      }
+    }
+    if (buffer.trim()) dispatch(buffer);
+  } catch (error) {
+    if (error?.name === "AbortError") return { ok: false, status: 0, error: "aborted", aborted: true };
+    return { ok: false, status: res.status, error: `stream broke: ${String(error)}` };
+  }
+  return { ok: true, status: res.status, data: null };
+}
+
+let posted = 0;
+const seen = new Set();
+
+/**
+ * Report a browser-side error to Makersclaw (POST _claw/events). Deduped
+ * by message+stack and capped per page load, so an error that fires on
+ * every render cannot flood the gateway. Best-effort: never throws.
+ *
+ * `source` defaults to errorSource() — "preview" while the artifact is a
+ * draft, "runtime" once launched — so the bench and the platform agent can
+ * tell the two apart. Pass it only when the caller knows better.
+ */
+export async function reportError({ message, stack, url, source }) {
+  const key = `${message}\n${stack ?? ""}`;
+  if (seen.has(key) || posted >= 20) return { ok: false, status: 0, error: "skipped" };
+  seen.add(key);
+  posted += 1;
+  return claw("events", {
+    method: "POST",
+    body: {
+      kind: "error",
+      source: source ?? errorSource(),
+      message: String(message ?? "error").slice(0, 2000),
+      stack: stack ? String(stack).slice(0, 8000) : undefined,
+      url: url ?? (typeof location !== "undefined" ? location.href : undefined),
+    },
+  });
+}