makersclaw 0.6.0 → 0.8.0

package/registry/blocks/page-builder/page-view.jsx

@@ -27,7 +27,7 @@ export function PageView({ page, label, className }) {
 
 /** Browser only: the page as a standalone HTML document with the theme
  *  resolved where `root` sits (colours, faces, radius) — for a download or
- *  a static host that does not load the app's stylesheet. */
+ *  a plain file host that does not load the app's stylesheet. */
 export function standaloneDocument(page, { root, title = "Page", lang = "en" } = {}) {
   return pageDocument(page, { title, lang, tokens: tokenCss(root), fonts: fontLinks(), fontFaces: fontFaceCss() });
 }

package/registry/blocks/page-builder/page.js

@@ -91,7 +91,7 @@ export function templatePage(template) {
 const escapeText = (s) => String(s ?? "").replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c]);
 
 /** A standalone HTML document for the page — for a download, an email
- *  preview, a static host. `tokens` is the `:root{…}` rule tokenCss()
+ *  preview, a plain file host. `tokens` is the `:root{…}` rule tokenCss()
  *  returns in the browser (the theme, resolved); without it the page reads
  *  the variables from whatever stylesheet the host adds. */
 export function pageDocument(page, { title = "Page", lang = "en", tokens = "", fonts = [], fontFaces = "" } = {}) {

package/registry/blocks/pdf-viewer/README.md

@@ -108,7 +108,10 @@ Store a highlight as a row in its own table (`document_id`, `page`,
 - `notes` — open the Highlights list on a wide viewer at first. Default:
   open when there are highlights.
 - `height` — the viewer's height, any CSS length. Default
-  `"min(80vh, 860px)"`; it never goes under 384px.
+  `"min(80vh, 860px)"` (the block's own); it never goes under 384px.
+  Yours is a length, or `"100%"` in a sized box such as the kit's
+  `AppLayout contentMode="fill"`: a `vh` length in your code is refused
+  by `npm run check`.
 - `loading` — `true` shows the skeleton (while you fetch or make the
   file) instead of the empty state.
 - `emptyTitle` · `emptyBody` — the words when `file` is empty. Default
@@ -128,40 +131,42 @@ cancels.
 ## Example
 
 ```jsx
+// surfaces/contract.jsx — client: one document and its highlights
 "use client";
-import { useState } from "react";
+import { useSearchParams } from "next/navigation";
+import { useRow, useRows, whenLanded } from "../lib/data";
+import { deleteRow, insertRow, updateRow } from "../lib/actions";
 import { PdfViewer } from "../components/blocks/pdf-viewer";
-import { insertRow, updateRow, deleteRow } from "../lib/actions";
 
-const source = "public.highlights";
+const source = "highlights";
 
-export function ContractReview({ doc, rows }) {
-  const [highlights, setHighlights] = useState(rows);
+// A write answers once the highlights are read again, so the viewer never
+// shows the list from before it.
+async function landed(res) {
+  if (res.ok) await whenLanded();
+  return res;
+}
+
+export default function ContractReview() {
+  const id = useSearchParams().get("row");
+  const { row: doc, loading } = useRow({ source: "documents", id });
+  const { rows: highlights } = useRows({ source, filter: { document_id: id } });
+  if (loading || !doc) return null;
   return (
     <PdfViewer
       file={doc.url}
       title={doc.title}
       highlights={highlights}
-      onHighlight={async (h) => {
-        const r = await insertRow({ source, values: { document_id: doc.id, ...h } });
-        if (r.ok) setHighlights((list) => [...list, { ...h, id: r.id }]);
-        return r;
-      }}
-      onHighlightChange={async (id, patch) => {
-        const r = await updateRow({ source, id, patch });
-        if (r.ok) setHighlights((list) => list.map((x) => (x.id === id ? { ...x, ...patch } : x)));
-        return r;
-      }}
-      onHighlightDelete={async (id) => {
-        const r = await deleteRow({ source, id });
-        if (r.ok) setHighlights((list) => list.filter((x) => x.id !== id));
-        return r;
-      }}
+      onHighlight={(h) => insertRow({ source, values: { document_id: doc.id, ...h } }).then(landed)}
+      onHighlightChange={(hid, patch) => updateRow({ source, id: hid, patch }).then(landed)}
+      onHighlightDelete={(hid) => deleteRow({ source, id: hid }).then(landed)}
     />
   );
 }
 ```
 
+In a server-mode app the same calls are `loadRows` in a server surface and the Server Actions of `lib/actions`.
+
 Preview a PDF you make (the `pdf-document` block):
 
 ```jsx

package/registry/blocks/pdf-viewer/pdf-viewer.jsx

@@ -6,7 +6,7 @@
 // callbacks. pdf.js (via react-pdf, see ./pdfjs.js) draws the pages; this
 // file is the viewer around them, in the kit and the workspace's tokens.
 //
-// Client only, one static bundle. pdf.js needs the DOM and a worker, and
+// Client only, one bundle. pdf.js needs the DOM and a worker, and
 // the app's check refuses import() (so no next/dynamic): the modules load
 // with the page (the server half through ssr-shim.js), and the viewer is
 // created only after the first effect — the mount guard. Until then, on

package/registry/blocks/pdf-viewer/pdfjs.js

@@ -19,7 +19,7 @@
 // expression with that asset's URL (the app's base path included). So the
 // worker ships with the app, is always the same version as the pdf.js that
 // calls it, and is served from the app's own origin. No import(), so the
-// app's one-static-bundle check is happy.
+// app's one-bundle check (no import()) is happy.
 //
 // It is set here, after react-pdf has loaded, because react-pdf sets its
 // own default when it loads and the later assignment must win. Only in the

package/registry/blocks/pdf-viewer/ssr-shim.js

@@ -7,7 +7,7 @@
 // document.createElement("div") (a CSS feature probe), and react-pdf reads
 // window.location. On the server those throw "window is not defined" and
 // the page fails to render — though the viewer itself only ever renders in
-// the browser (the mount guard). The app is one static bundle (no
+// the browser (the mount guard). The app is one bundle (no
 // import(), no next/dynamic), so the module cannot be kept off the server;
 // it is let load against these stand-ins instead — the same trick as
 // sketch-canvas's ssr-shim.js.

package/registry/blocks/product-detail/README.md

@@ -130,13 +130,16 @@ compareAt, currency })`, `formatPrice(amount, currency, locale)`.
 ## Example
 
 ```jsx
-// surfaces/product.jsx — server: load, hand over
-import { loadRow } from "../lib/data";
+// surfaces/product.jsx — client: read, hand over
+"use client";
+import { useSearchParams } from "next/navigation";
+import { useRow } from "../lib/data";
 import ProductPage from "../components/ProductPage";
 
-export default async function ProductSurface({ params }) {
-  const { row, error } = await loadRow({ source: "public.products", id: params.id });
-  return <ProductPage product={row} error={error} />;
+export default function ProductSurface() {
+  const id = useSearchParams().get("row"); // /s/product?row=<id>
+  const { row, error, loading } = useRow({ source: "products", id });
+  return <ProductPage product={row} loading={loading} error={error} />;
 }
 ```
 
@@ -146,10 +149,11 @@ export default async function ProductSurface({ params }) {
 import { insertRow } from "../lib/actions";
 import { ProductDetail } from "./blocks/product-detail";
 
-export default function ProductPage({ product, error }) {
+export default function ProductPage({ product, loading, error }) {
   return (
     <ProductDetail
       product={product}
+      loading={loading}
       error={error}
       breadcrumb={[{ label: "Shop", href: "/shop" }, { label: product?.name ?? "Product" }]}
       perks={[
@@ -158,7 +162,7 @@ export default function ProductPage({ product, error }) {
       ]}
       onAddToCart={(line) =>
         insertRow({
-          source: "public.cart_items",
+          source: "cart_items",
           values: { product_id: line.id, line_key: line.key, quantity: line.quantity, selected: line.selected },
           detail: `${line.quantity} × ${line.name}`,
         })
@@ -168,6 +172,8 @@ export default function ProductPage({ product, error }) {
 }
 ```
 
+In a server-mode app the same calls are `loadRows` in a server surface and the Server Actions of `lib/actions`.
+
 A digital product with plans, no quantity, and a straight-to-checkout
 button:
 

package/registry/blocks/product-detail/demo.jsx

@@ -142,7 +142,7 @@ const KIT = {
       key: "licence",
       label: "Choose your licence",
       values: [
-        { value: "html", label: "HTML", price: 39, per: "one-time", description: "Static pages with the styles compiled." },
+        { value: "html", label: "HTML", price: 39, per: "one-time", description: "Plain HTML pages with the styles compiled." },
         { value: "react", label: "React", price: 49, per: "one-time", badge: "Popular", description: "Components with props and typed data." },
         { value: "team", label: "Team", price: 149, per: "one-time", description: "React, for up to ten people." },
       ],

package/registry/blocks/product-grid/README.md

@@ -84,37 +84,37 @@ quantities by `key`.
 ## Example
 
 ```jsx
-// surfaces/shop.jsx — server: load, hand over
-import { loadRows } from "../lib/data";
+// surfaces/shop.jsx — client: read, hand over
+"use client";
+import { useRows } from "../lib/data";
 import Shop from "../components/Shop";
 
-export default async function ShopSurface() {
-  const { rows, error } = await loadRows({ source: "public.products", orderBy: "created_at desc" });
-  return <Shop products={rows} error={error} />;
+export default function ShopSurface() {
+  const { rows, error, loading, reload } = useRows({ source: "products", orderBy: "created_at desc" });
+  return <Shop products={rows} loading={loading} error={error} onRetry={reload} />;
 }
 ```
 
 ```jsx
 // components/Shop.jsx — client: the grid and the cart write
 "use client";
-import { useRouter } from "next/navigation";
 import { insertRow } from "../lib/actions";
 import { ProductGrid } from "./blocks/product-grid";
 
-export default function Shop({ products, error }) {
-  const router = useRouter();
+export default function Shop({ products, loading, error, onRetry }) {
   return (
     <ProductGrid
       products={products}
+      loading={loading}
       error={error}
-      onRetry={() => router.refresh()}
+      onRetry={onRetry}
       filters={[
         { key: "category", label: "Category", options: ["Shirts", "Sweaters", "Jackets"] },
         { key: "size", label: "Size", options: ["S", "M", "L", "XL"] },
       ]}
       sort
       onAddToCart={(line) =>
-        insertRow({ source: "public.cart_items", values: { product_id: line.id, line_key: line.key, quantity: 1 }, detail: line.name })
+        insertRow({ source: "cart_items", values: { product_id: line.id, line_key: line.key, quantity: 1 }, detail: line.name })
       }
       label="Shop"
     />
@@ -122,6 +122,8 @@ export default function Shop({ products, error }) {
 }
 ```
 
+In a server-mode app the same calls are `loadRows` in a server surface and the Server Actions of `lib/actions`.
+
 Collection tiles, and a lead picture beside four products:
 
 ```jsx

package/registry/blocks/record-form/README.md

@@ -93,7 +93,7 @@ Validation, first broken rule wins, one message per field:
   error?, errors? }` where `errors` is `{ fieldName: "message" }` — each
   shows under its field and the first one is focused. A throw counts as
   failed. In a Makersclaw app it is one line over `updateRow`:
-  `onSave={(v) => updateRow({ source: "public.products", id: p.id, patch: v })}`.
+  `onSave={(v) => updateRow({ source: "products", id: p.id, patch: v })}`.
 - `container` — `"card"` (default: a Card with `title` and `description`)
   · `"page"` (no box: a page heading, then the sections) · `"dialog"` (a
   centred Sheet; on a phone a bottom sheet). A dialog needs `open` and
@@ -127,10 +127,12 @@ Validation, first broken rule wins, one message per field:
 ## Example
 
 ```jsx
-// components/ProductEditor.jsx — client
+// surfaces/product.jsx — client: one product, edited
 "use client";
-import { updateRow, deleteRow } from "../lib/actions";
-import { RecordForm } from "./blocks/record-form";
+import { useRouter, useSearchParams } from "next/navigation";
+import { useRow } from "../lib/data";
+import { deleteRow, updateRow } from "../lib/actions";
+import { RecordForm } from "../components/blocks/record-form";
 
 const FIELDS = [
   { name: "name", label: "Product name", required: true },
@@ -140,20 +142,35 @@ const FIELDS = [
   { name: "details", label: "Details", type: "textarea" },
 ];
 
-export default function ProductEditor({ product }) {
+export default function ProductEditor() {
+  const router = useRouter();
+  const id = useSearchParams().get("row");
+  const { row: product, loading, error, reload } = useRow({ source: "products", id });
   return (
     <RecordForm
       title="Edit product"
       fields={FIELDS}
-      values={product}
-      onSave={(values) => updateRow({ source: "public.products", id: product.id, patch: values })}
-      onDelete={() => deleteRow({ source: "public.products", id: product.id })}
+      values={product ?? {}}
+      loading={loading}
+      error={error}
+      onRetry={reload}
+      onSave={(values) => updateRow({ source: "products", id, patch: values })}
+      onDelete={async () => {
+        const res = await deleteRow({ source: "products", id });
+        if (res.ok) router.push("/s/products");
+        return res;
+      }}
       deleteLabel="Remove product"
     />
   );
 }
 ```
 
+After a save the row is read again and comes back as `values`: the
+form starts over from what it just saved.
+
+In a server-mode app the same calls are `loadRows` in a server surface and the Server Actions of `lib/actions`.
+
 In a dialog, from a list:
 
 ```jsx
@@ -170,7 +187,7 @@ const [editing, setEditing] = useState(null);
     { title: "Access", fields: [{ name: "role", label: "Role", type: "radio", options: ["Admin", "Member", "Viewer"] }] },
   ]}
   onSave={async (values) => {
-    const res = await updateRow({ source: "public.members", id: editing.id, patch: values });
+    const res = await updateRow({ source: "members", id: editing.id, patch: values });
     return res.ok ? res : { ok: false, errors: res.error?.includes("email") ? { email: "Already in use." } : undefined, error: res.error };
   }}
 />

package/registry/blocks/record-notes/README.md

@@ -73,45 +73,57 @@ One table, a row per note: `record_id`, `author_id`, `body jsonb`,
 ## Example
 
 ```jsx
-// components/DealNotes.jsx — client
+// surfaces/deal-notes.jsx — client: one deal's notes
 "use client";
-import { useState } from "react";
+import { useSearchParams } from "next/navigation";
+import { useArtifact } from "../lib/hooks";
+import { useRows, whenLanded } from "../lib/data";
 import { deleteRow, insertRow, updateRow } from "../lib/actions";
-import { RecordNotes } from "./blocks/record-notes";
-import { docToText } from "./blocks/doc-editor";
+import { RecordNotes } from "../components/blocks/record-notes";
+import { docToText } from "../components/blocks/doc-editor";
 
-export default function DealNotes({ deal, me, team, initial }) {
-  const [notes, setNotes] = useState(initial);
+const source = "deal_notes";
+
+// A write answers once the notes are read again, so the list never shows
+// the notes from before it.
+async function landed(res) {
+  if (res.ok) await whenLanded();
+  return res;
+}
+
+export default function DealNotes() {
+  const dealId = useSearchParams().get("row");
+  const { user } = useArtifact(); // the member signed in: { id, email }
+  const { rows, loading } = useRows({ source, filter: { deal_id: dealId }, orderBy: "created_at desc" });
+  const { rows: team } = useRows({ source: "people", orderBy: "name asc" });
+  const me = { id: user?.email, name: user?.email ?? "You" };
+  // created_by: a before-insert trigger sets it from the member, never the page (the app's README §5)
+  const notes = rows.map((n) => ({
+    id: n.id,
+    author: { id: n.created_by, name: n.created_by },
+    body: n.body,
+    createdAt: n.created_at,
+    updatedAt: n.updated_at,
+  }));
   const findPeople = async (q) =>
     team.filter((p) => p.name.toLowerCase().includes(q.toLowerCase())).map((p) => ({ id: p.id, label: p.name }));
 
-  async function add(doc) {
-    const res = await insertRow({
-      source: "public.deal_notes",
-      values: { deal_id: deal.id, author_id: me.id, body: doc, body_text: docToText(doc) },
-    });
-    if (!res.ok) return res;
-    setNotes((n) => [{ id: res.id, author: me, body: doc, createdAt: new Date() }, ...n]);
-    return { ok: true };
-  }
-
-  async function edit(note, doc) {
-    const updatedAt = new Date();
-    const res = await updateRow({ source: "public.deal_notes", id: note.id, patch: { body: doc, body_text: docToText(doc), updated_at: updatedAt } });
-    if (res.ok) setNotes((n) => n.map((x) => (x.id === note.id ? { ...x, body: doc, updatedAt } : x)));
-    return res;
-  }
-
-  async function remove(note) {
-    const res = await deleteRow({ source: "public.deal_notes", id: note.id });
-    if (res.ok) setNotes((n) => n.filter((x) => x.id !== note.id));
-    return res;
-  }
-
-  return <RecordNotes notes={notes} me={me} onAdd={add} onEdit={edit} onDelete={remove} mentions={findPeople} />;
+  if (loading) return null;
+  return (
+    <RecordNotes
+      notes={notes}
+      me={me}
+      onAdd={(doc) => insertRow({ source, values: { deal_id: dealId, body: doc, body_text: docToText(doc) } }).then(landed)}
+      onEdit={(note, doc) => updateRow({ source, id: note.id, patch: { body: doc, body_text: docToText(doc), updated_at: new Date() } }).then(landed)}
+      onDelete={(note) => deleteRow({ source, id: note.id }).then(landed)}
+      mentions={findPeople}
+    />
+  );
 }
 ```
 
+In a server-mode app the same calls are `loadRows` in a server surface and the Server Actions of `lib/actions`.
+
 Beside the form, on a record page:
 
 ```jsx

package/registry/blocks/search-dialog/README.md

@@ -70,15 +70,29 @@ Both components take these.
 ## Example
 
 ```jsx
+// components/GlobalSearch.jsx — client: search as the member types
 "use client";
-import { useRouter } from "next/navigation";
 import { useState } from "react";
-import { Button } from "../components/ui";
-import { SearchDialog } from "../components/blocks/search-dialog";
+import { useRouter } from "next/navigation";
+import { loadRows, useRows } from "../lib/data";
+import { Button } from "./ui";
+import { SearchDialog } from "./blocks/search-dialog";
+
+const asResult = (d) => ({ id: d.id, kind: "deal", title: d.name, snippet: d.stage });
 
-export function GlobalSearch({ recent, search }) {
+export default function GlobalSearch() {
   const router = useRouter();
   const [open, setOpen] = useState(false);
+  const { rows: recent } = useRows({ source: "deals", orderBy: "updated_at desc", limit: 5 });
+
+  // The app's own table: names that start with what was typed, case ignored.
+  // The dialog aborts the older query through `signal`.
+  async function search(q, { signal }) {
+    const { rows, error } = await loadRows({ source: "deals", filter: { name: { prefix: q } }, orderBy: "name asc", limit: 20, signal });
+    if (error) throw new Error(error); // "Search failed"; an aborted read's answer is ignored
+    return rows.map(asResult);
+  }
+
   return (
     <>
       <Button icon="search" onClick={() => setOpen(true)}>Search</Button>
@@ -86,15 +100,32 @@ export function GlobalSearch({ recent, search }) {
         open={open}
         onOpenChange={setOpen}
         hotkey="k"
-        sections={[{ heading: "Recent", results: recent }]}
-        onSearch={(q) => search(q)}   // a server action returning results
-        onSelect={(r) => router.push(`/${r.kind}s/${r.id}`)}
+        sections={[{ heading: "Recent", results: recent.map(asResult) }]}
+        onSearch={search}
+        onSelect={(r) => router.push(`/s/deals?row=${r.id}`)}
       />
     </>
   );
 }
 ```
 
+The company's records, through the brain (`lib/brain.js`), with
+`meaning: false` while a person types: keywords only, nothing embedded
+or charged. A search by meaning is charged per call; keep it for a
+search page or an Enter.
+
+```jsx
+import { searchBrain } from "../lib/brain";
+
+async function search(q, { signal }) {
+  const { results, error } = await searchBrain({ q, meaning: false, limit: 20, signal });
+  if (error) throw new Error(error);
+  return results.map(({ record, snippet }) => ({ id: record.id, kind: record.kind, title: record.label, snippet }));
+}
+```
+
+In a server-mode app the same calls are `loadRows` in a server surface and the Server Actions of `lib/actions`.
+
 ## What it will not do
 
 - Index anything. It searches the list you give it, or asks your server.

package/registry/blocks/settings-list/README.md

@@ -71,7 +71,7 @@ The matrix (`variant="matrix"`) rows are events:
   false, error }`; a throw counts as failed. Without it, switches and
   selects are shown and cannot be changed. In a Makersclaw app it is one
   line over `saveSetting` (lib/actions.js):
-  `onChange={(row, value) => saveSetting({ source: "public.settings", key: row.key, value })}`.
+  `onChange={(row, value) => saveSetting({ source: "settings", key: row.key, value })}`.
 - `onAction(row, actionKey)` — run a button, a menu item or a remove.
   Return `{ ok }` like `onChange`. Remove the row from `rows` on success
   when it is gone (a signed-out device).
@@ -95,31 +95,43 @@ The matrix (`variant="matrix"`) rows are events:
 ## Example
 
 ```jsx
-// components/Preferences.jsx — client
+// surfaces/preferences.jsx — client: settings, read and saved
 "use client";
+import { useMemo } from "react";
+import { useRows } from "../lib/data";
 import { saveSetting } from "../lib/actions";
-import { SettingsList } from "./blocks/settings-list";
-
-export default function Preferences({ settings }) {
-  const rows = [
-    { key: "digest", icon: "mail", label: "Weekly digest", description: "Every Monday at 8:00.", control: { type: "switch", value: settings.digest === true } },
-    {
-      key: "currency",
-      icon: "dollar",
-      label: "Currency",
-      control: { type: "select", value: settings.currency ?? "usd", options: [{ value: "usd", label: "US dollar" }, { value: "eur", label: "Euro" }] },
-    },
-  ];
+import { SettingsList } from "../components/blocks/settings-list";
+
+export default function Preferences() {
+  const { rows: saved, loading, error, reload } = useRows({ source: "settings" });
+  // Built once per read: until `rows` changes, a row shows the value it saved.
+  const rows = useMemo(() => {
+    const settings = Object.fromEntries(saved.map((s) => [s.key, s.value]));
+    return [
+      { key: "digest", icon: "mail", label: "Weekly digest", description: "Every Monday at 8:00.", control: { type: "switch", value: settings.digest === true } },
+      {
+        key: "currency",
+        icon: "dollar",
+        label: "Currency",
+        control: { type: "select", value: settings.currency ?? "usd", options: [{ value: "usd", label: "US dollar" }, { value: "eur", label: "Euro" }] },
+      },
+    ];
+  }, [saved]);
   return (
     <SettingsList
       title="Preferences"
       rows={rows}
-      onChange={(row, value) => saveSetting({ source: "public.settings", key: row.key, value })}
+      loading={loading}
+      error={error}
+      onRetry={reload}
+      onChange={(row, value) => saveSetting({ source: "settings", key: row.key, value })}
     />
   );
 }
 ```
 
+In a server-mode app the same calls are `loadRows` in a server surface and the Server Actions of `lib/actions`.
+
 Notifications per channel:
 
 ```jsx
@@ -131,7 +143,7 @@ Notifications per channel:
     { key: "mentions", group: "Conversations", label: "Mentions", values: { email: true, push: true } },
     { key: "signin", group: "Security", label: "New sign-in", values: { email: true, push: false }, locked: ["email"] },
   ]}
-  onChange={(row, on, channel) => saveSetting({ mode: "json", source: "public.members", column: "notify", id: me.id, key: `${row.key}.${channel}`, value: on })}
+  onChange={(row, on, channel) => saveSetting({ mode: "json", source: "members", column: "notify", id: me.id, key: `${row.key}.${channel}`, value: on })}
 />
 ```
 
@@ -149,7 +161,7 @@ Signed-in devices, each with sign-out:
     meta: [{ icon: "globe", text: s.place }, { icon: "clock", text: s.lastSeen }],
     control: s.current ? null : { type: "remove", label: `Sign out ${s.device}`, confirm: { title: "Sign out this device?", confirmLabel: "Sign out" } },
   }))}
-  onAction={(row) => deleteRow({ source: "public.sessions", id: row.key })}
+  onAction={(row) => deleteRow({ source: "sessions", id: row.key })}
 />
 ```
 

package/registry/blocks/setup-checklist/README.md

@@ -75,16 +75,15 @@ With no steps it says "Nothing to set up".
 ## Example
 
 ```jsx
-// surfaces/home.jsx — server: work out what is done
-import { loadRows } from "../lib/data";
+// surfaces/home.jsx — client: work out what is done
+"use client";
+import { useCount } from "../lib/data";
 import GettingStarted from "../components/GettingStarted";
 
-export default async function Home() {
-  const [{ rows: members }, { rows: deals }] = await Promise.all([
-    loadRows({ source: "public.members" }),
-    loadRows({ source: "public.deals", limit: 1 }),
-  ]);
-  return <GettingStarted invited={members.length > 1} hasDeal={deals.length > 0} />;
+export default function Home() {
+  const members = useCount({ source: "members" });
+  const deals = useCount({ source: "deals" });
+  return <GettingStarted loading={members.loading || deals.loading} invited={members.count > 1} hasDeal={deals.count > 0} />;
 }
 ```
 
@@ -93,10 +92,11 @@ export default async function Home() {
 "use client";
 import { SetupChecklist } from "./blocks/setup-checklist";
 
-export default function GettingStarted({ invited, hasDeal, onHide }) {
+export default function GettingStarted({ loading, invited, hasDeal, onHide }) {
   return (
     <SetupChecklist
       title="Get started"
+      loading={loading}
       steps={[
         { key: "invite", title: "Invite your team", description: "Bring in the people who own accounts.", actionLabel: "Invite", href: "/team", done: invited },
         { key: "deal", title: "Add your first deal", description: "One deal is enough to see the pipeline work.", actionLabel: "Add a deal", href: "/deals?new=1", done: hasDeal },
@@ -107,6 +107,8 @@ export default function GettingStarted({ invited, hasDeal, onHide }) {
 }
 ```
 
+In a server-mode app the same calls are `loadRows` in a server surface and the Server Actions of `lib/actions`.
+
 In order, with buttons that do the work in place:
 
 ```jsx
@@ -115,11 +117,7 @@ In order, with buttons that do the work in place:
   sequential
   title="Quick start"
   steps={steps}
-  onAction={async (step) => {
-    const res = await runSetupStep(step.key); // your server action, { ok, error }
-    if (res.ok) router.refresh(); // the step comes back done
-    return res;
-  }}
+  onAction={(step) => runAction({ name: "run_setup_step", args: { key: step.key } })} // an action named in references/actions.md; its ok re-reads every hook, so the step comes back done
 />
 ```
 

package/registry/blocks/share-dialog/README.md

@@ -89,7 +89,7 @@ export function ShareProject({ project, members, invite, setRole, remove }) {
         onClose={() => setOpen(false)}
         title={`Share “${project.name}”`}
         people={members}
-        onInvite={(emails, role) => invite(project.id, emails, role)}   // server actions returning { ok, error }
+        onInvite={(emails, role) => invite(project.id, emails, role)}   // each answers { ok } or { ok: false, error }, as lib/actions' writes do
         onRoleChange={(person, role) => setRole(project.id, person.id, role)}
         onRemove={(person) => remove(project.id, person.id)}
         link={`https://app.example.com/p/${project.id}`}