makersclaw 0.6.0 → 0.7.0

package/registry/blocks/calendar-view/README.md

@@ -157,22 +157,46 @@ const getSlots = useCallback(({ from, to }) =>
 ## Example
 
 ```jsx
+// surfaces/schedule.jsx — client: the tasks on a calendar
 "use client";
 import { useState } from "react";
-import { Sheet } from "./ui";
-import { CalendarView } from "./blocks/calendar-view";
+import { useRows } from "../lib/data";
+import { deleteRow, insertRow, updateRow } from "../lib/actions";
+import { Sheet } from "../components/ui";
+import { CalendarView } from "../components/blocks/calendar-view";
+import { changeWrites } from "../components/blocks/task-model";
+
+const COLUMNS = ["id", "title", "status", "assignees", "start", "due", "project"];
+
+// One change of the calendar's, as the rows it writes (task-list's README has the same).
+async function save(change) {
+  for (const w of changeWrites(change, { columns: COLUMNS, keepNewIds: false })) {
+    const r =
+      w.op === "insert" ? await insertRow({ source: "tasks", values: w.values, detail: w.values.title })
+      : w.op === "update" ? await updateRow({ source: "tasks", id: w.id, patch: w.patch })
+      : await deleteRow({ source: "tasks", id: w.id });
+    if (r?.ok === false) return r;
+  }
+  return { ok: true };
+}
 
-export default function Schedule({ tasks, people, projects, onChange }) {
+export default function Schedule() {
+  const tasks = useRows({ source: "tasks", orderBy: "start asc" });
+  const people = useRows({ source: "people" });
+  const projects = useRows({ source: "projects" });
   const [open, setOpen] = useState(null);
   return (
     <>
-      <CalendarView tasks={tasks} people={people} projects={projects} onChange={onChange} onOpen={setOpen} defaultMode="week" />
+      <CalendarView tasks={tasks.rows} people={people.rows} projects={projects.rows} onChange={save} onOpen={setOpen} defaultMode="week"
+        loading={tasks.loading || people.loading || projects.loading} error={tasks.error} />
       <Sheet open={Boolean(open)} onClose={() => setOpen(null)} title={open?.title}>…</Sheet>
     </>
   );
 }
 ```
 
+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
 
 - Recurring events, time zones, or events that are not tasks: a repeat

package/registry/blocks/cart/README.md

@@ -94,33 +94,35 @@ The checkout step:
 ## Example
 
 ```jsx
-// components/Basket.jsx — client
+// surfaces/basket.jsx — client: the cart, read and changed
 "use client";
 import { useState } from "react";
+import { useRows } from "../lib/data";
 import { deleteRow, updateRow } from "../lib/actions";
-import { Cart } from "./blocks/cart";
+import { Cart } from "../components/blocks/cart";
 
-export default function Basket({ items, error }) {
+export default function Basket() {
+  const { rows: items, error, loading } = useRows({ source: "cart_items", orderBy: "created_at asc" });
   const [step, setStep] = useState("cart");
   return (
     <Cart
       items={items}
+      loading={loading}
       error={error}
       step={step}
       shipping={0}
       tax="Calculated at payment"
       note="Free delivery on every order this month."
-      onQuantityChange={(item, quantity) => updateRow({ source: "public.cart_items", id: item.id, patch: { quantity } })}
-      onRemove={(item) => deleteRow({ source: "public.cart_items", id: item.id })}
+      onQuantityChange={(item, quantity) => updateRow({ source: "cart_items", id: item.id, patch: { quantity } })}
+      onRemove={(item) => deleteRow({ source: "cart_items", id: item.id })}
       onCheckout={() => setStep("checkout")}
       onBack={() => setStep("cart")}
       continueHref="/shop"
       terms="I agree to the terms of sale"
-      onPay={async (details) => {
-        const res = await fetch("/api/checkout", { method: "POST", body: JSON.stringify(details) });
-        if (!res.ok) return { ok: false, error: "We could not start the payment. Try again." };
-        const { transactionId } = await res.json();
-        window.Paddle?.Checkout.open({ transactionId });
+      onPay={async () => {
+        // Paddle.js opens its checkout in the browser from price ids: no route of the app's own.
+        if (!window.Paddle) return { ok: false, error: "Payments have not loaded. Try again." };
+        window.Paddle.Checkout.open({ items: items.map((i) => ({ priceId: i.price_id, quantity: i.quantity })) });
         return { ok: true };
       }}
     />
@@ -128,6 +130,8 @@ export default function Basket({ items, error }) {
 }
 ```
 
+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
 
 - Take a card number, expiry or CVC. Payment is Paddle's overlay or page,

package/registry/blocks/chart/README.md

@@ -244,15 +244,20 @@ sharing one key, say).
 ## Example
 
 ```jsx
-// surfaces/sales.jsx — server: load, hand over
-import { loadRows } from "../lib/data";
+// surfaces/sales.jsx — client: read, hand over
+"use client";
+import { useRows } from "../lib/data";
 import SalesCharts from "../components/SalesCharts";
 
-export default async function SalesSurface() {
-  const { rows: months, error } = await loadRows({ source: "public.revenue_by_month", orderBy: "month asc" });
-  const { rows: stages } = await loadRows({ source: "public.deals_by_stage", orderBy: "position asc" });
-  const { rows: visits } = await loadRows({ source: "public.visits_by_slot", orderBy: "position asc" });
-  return <SalesCharts months={months} stages={stages} visits={visits} error={error} />;
+export default function SalesSurface() {
+  const months = useRows({ source: "revenue_by_month", orderBy: "month asc" });
+  const stages = useRows({ source: "deals_by_stage", orderBy: "position asc" });
+  const visits = useRows({ source: "visits_by_slot", orderBy: "position asc" });
+  if (months.loading || stages.loading || visits.loading) return null;
+  return (
+    <SalesCharts months={months.rows} stages={stages.rows} visits={visits.rows}
+      error={months.error ?? stages.error ?? visits.error} />
+  );
 }
 ```
 
@@ -303,6 +308,8 @@ export default function SalesCharts({ months, stages, visits, error }) {
 }
 ```
 
+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
 
 - Sort, group or sum: the rows come shaped. Totals by month or by stage

package/registry/blocks/chat/README.md

@@ -214,29 +214,53 @@ and the hint in its bar, Send at the end. The picker leaves out files
 ## Example
 
 ```jsx
-// components/SupportChat.jsx — client: one ticket's conversation
+// surfaces/ticket.jsx — client: one ticket's conversation
 "use client";
 import { useState } from "react";
+import { useSearchParams } from "next/navigation";
+import { loadRows, useRow, useRows, whenLanded } from "../lib/data";
 import { insertRow } from "../lib/actions";
-import { ChatThread } from "./blocks/chat";
-
-export default function SupportChat({ ticket, initial }) {
-  const [messages, setMessages] = useState(initial);
-  const patch = (id, change) => setMessages((all) => all.map((m) => (m.id === id ? { ...m, ...change } : m)));
+import { ChatThread } from "../components/blocks/chat";
+
+const source = "ticket_messages";
+const PAGE = 200;
+const oldestFirst = (rows) => [...rows].reverse();
+const asMessage = (r) => ({ id: r.id, role: r.from_agent ? "assistant" : "user", content: r.body, createdAt: r.created_at });
+
+export default function SupportChat() {
+  const id = useSearchParams().get("row");
+  const { row: ticket } = useRow({ source: "tickets", id });
+  // The newest page, read again after every write.
+  const { rows, loading } = useRows({ source, filter: { ticket_id: id }, orderBy: "created_at desc", limit: PAGE });
+  const [earlier, setEarlier] = useState({ rows: [], more: true }); // what onLoadMore read, oldest first
+  const [sending, setSending] = useState([]);                        // sent, not read back yet
+  const seen = new Map([...earlier.rows, ...oldestFirst(rows)].map((r) => [r.id, r]));
+  const shown = [...seen.values()];
+
+  async function loadMore() {
+    const oldest = shown[0]?.created_at;
+    if (!oldest) return;
+    const r = await loadRows({ source, filter: { ticket_id: id, created_at: { lt: oldest } }, orderBy: "created_at desc", limit: PAGE });
+    // What is on screen is kept too: new messages push the oldest out of the page above.
+    if (!r.error) setEarlier({ rows: [...oldestFirst(r.rows), ...shown], more: r.rows.length === PAGE });
+  }
 
   async function send(text) {
-    const id = crypto.randomUUID();
-    const draft = { id, role: "user", content: text, createdAt: new Date().toISOString(), status: "sending" };
-    setMessages((all) => [...all, draft]);
-    const r = await insertRow({ source: "public.ticket_messages", values: { id, ticket_id: ticket.id, body: text }, detail: text });
-    patch(id, r.ok ? { status: undefined } : { status: "failed", error: r.error });
+    const mid = crypto.randomUUID();
+    setSending((all) => [...all, { id: mid, role: "user", content: text, createdAt: new Date().toISOString(), status: "sending" }]);
+    const r = await insertRow({ source, values: { id: mid, ticket_id: id, body: text }, detail: text });
+    if (r.ok) await whenLanded(); // read back: it is in `rows` now
+    setSending((all) => (r.ok ? all.filter((m) => m.id !== mid) : all.map((m) => (m.id === mid ? { ...m, status: "failed", error: r.error } : m))));
   }
 
+  if (loading || !ticket) return null;
   return (
     <ChatThread
-      messages={messages}
+      messages={[...shown.map(asMessage), ...sending.filter((m) => !seen.has(m.id))]}
       onSend={send}
-      onRetry={(m) => { setMessages((all) => all.filter((x) => x.id !== m.id)); send(m.content); }}
+      onRetry={(m) => { setSending((all) => all.filter((x) => x.id !== m.id)); send(m.content); }}
+      onLoadMore={loadMore}
+      hasMore={rows.length === PAGE && earlier.more}
       assistantName={ticket.agent_name}
       userName="You"
       label={`Ticket ${ticket.number}`}
@@ -245,6 +269,12 @@ export default function SupportChat({ ticket, initial }) {
 }
 ```
 
+`onLoadMore` reads the page before the oldest message shown:
+`loadRows({ source, filter: { ticket_id, created_at: { lt: oldest } } })`,
+the same filter in a server app's `loadRows` and the door.
+
+In a server-mode app the same calls are `loadRows` in a server surface and the Server Actions of `lib/actions`.
+
 With the AI SDK in a shadcn project, `useChat()` already has the shape:
 `<ChatThread messages={messages} onSend={(text) => sendMessage({ text })}
 streaming={status === "streaming" || status === "submitted"} onStop={stop}

package/registry/blocks/code-editor/README.md

@@ -193,6 +193,10 @@ export function QueryBox({ runQuery }) {
 }
 ```
 
+Running SQL a member typed is a server app's only: `runQuery` is a
+Server Action of the app's own. A browser app has no such call, since no
+route of the data door runs SQL a member typed.
+
 JSON, read-only, fixed height:
 
 ```jsx

package/registry/blocks/code-editor/code-editor.jsx

@@ -5,7 +5,7 @@
 // as you type) or plain text; line numbers, problems drawn on the text,
 // find and replace, and a run hook on Cmd/Ctrl+Enter.
 //
-// Client only, one static bundle. CodeMirror needs the DOM, and the app's
+// Client only, one bundle. CodeMirror needs the DOM, and the app's
 // check refuses import() (so no next/dynamic): the modules load with the
 // page, and the editor itself is created only after the first effect (the
 // mount guard). Until then — on the server and in the first client paint —

package/registry/blocks/comment-box/README.md

@@ -79,32 +79,39 @@ The other exports, for a thread of your own:
 ## Example
 
 ```jsx
-// components/TaskComments.jsx — client
+// surfaces/task.jsx — client: one task's comments
 "use client";
-import { useState } from "react";
+import { useSearchParams } from "next/navigation";
+import { useArtifact } from "../lib/hooks";
+import { useRows, whenLanded } from "../lib/data";
 import { insertRow } from "../lib/actions";
-import { CommentBox } from "./blocks/comment-box";
-import { docToText } from "./blocks/doc-editor";
-
-export default function TaskComments({ task, me, team, initial }) {
-  const [comments, setComments] = useState(initial);
+import { CommentBox } from "../components/blocks/comment-box";
+import { docToText } from "../components/blocks/doc-editor";
+
+export default function TaskComments() {
+  const taskId = useSearchParams().get("row");
+  const { user } = useArtifact(); // the member signed in: { id, email }
+  const { rows, loading } = useRows({ source: "comments", filter: { task_id: taskId }, orderBy: "created_at asc" });
+  const { rows: team } = useRows({ source: "people", orderBy: "name asc" });
+  // created_by: a before-insert trigger sets it from the member, never the page (the app's README §5)
+  const comments = rows.map((c) => ({ id: c.id, author: c.created_by, body: c.body, createdAt: c.created_at }));
   const findPeople = async (q) =>
     team.filter((p) => p.name.toLowerCase().includes(q.toLowerCase())).map((p) => ({ id: p.id, label: p.name }));
 
   async function post(doc) {
-    const res = await insertRow({
-      source: "public.comments",
-      values: { task_id: task.id, author_id: me.id, body: doc, body_text: docToText(doc) },
-    });
+    const res = await insertRow({ source: "comments", values: { task_id: taskId, body: doc, body_text: docToText(doc) } });
     if (!res.ok) return { ok: false, error: res.error };
-    setComments((c) => [...c, { id: res.id, author: me, body: doc, createdAt: new Date() }]);
+    await whenLanded(); // the comment is read back before the box clears
     return { ok: true };
   }
 
-  return <CommentBox comments={comments} onPost={post} author={me} mentions={findPeople} />;
+  if (loading) return null;
+  return <CommentBox comments={comments} onPost={post} author={user ? { name: user.email } : undefined} mentions={findPeople} />;
 }
 ```
 
+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
 
 - Edit or delete a posted comment, react, or reply in a nested thread: the

package/registry/blocks/contact-section/README.md

@@ -107,10 +107,10 @@ It is a client component: render it from a `"use client"` component.
 ## Example
 
 ```jsx
-// components/Contact.jsx
+// components/Contact.jsx — client: a message is a row
 "use client";
+import { insertRow } from "../lib/actions";
 import { ContactSection } from "./blocks/contact-section";
-import { sendContactMessage } from "../lib/actions";   // your server action
 
 export default function Contact() {
   return (
@@ -124,15 +124,16 @@ export default function Contact() {
       ]}
       topics={{ options: ["Sales", "Support", "Partnerships"], required: true }}
       consent="I agree to the privacy policy."
-      onSubmit={async (values) => {
-        const res = await sendContactMessage(values);
-        return res.ok ? { ok: true } : { ok: false, error: res.error };
-      }}
+      onSubmit={(values) => insertRow({ source: "contact_messages", values })} // { ok, id } or { ok: false, error }
     />
   );
 }
 ```
 
+The row is the message: the app's agent, or a job, answers it.
+
+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
 
 - Send anything: `onSubmit` is yours (save a row, email the team).

package/registry/blocks/csv-import/README.md

@@ -93,33 +93,55 @@ creates, fields }` (each row's `__problems` is `{ key: message }`) ·
 ## Example
 
 ```jsx
+// surfaces/import.jsx — client: contacts from a spreadsheet
 "use client";
 import { useRouter } from "next/navigation";
-import { insertRow } from "../lib/actions";
-import { CsvImport } from "./blocks/csv-import";
+import { useRows } from "../lib/data";
+import { runAction } from "../lib/actions";
+import { CsvImport } from "../components/blocks/csv-import";
 
-export default function ImportContacts({ fields, team }) {
+const FIELDS = [
+  { key: "name", name: "Name", type: "text", required: true },
+  { key: "email", name: "Email", type: "text", required: true },
+  { key: "owner", name: "Owner", type: "person" },
+];
+
+export default function ImportContacts() {
   const router = useRouter();
+  const { rows: team } = useRows({ source: "people", orderBy: "name asc" });
   return (
     <CsvImport
-      fields={fields}
+      fields={FIELDS}
       people={team}
       noun="contact"
       onImport={async ({ rows }) => {
-        let imported = 0;
-        for (const { id, ...values } of rows) {
-          const r = await insertRow({ source: "public.contacts", values });
-          if (!r.ok) return { ok: false, error: `Stopped after ${imported} contacts: ${r.error}` };
-          imported++;
-        }
-        return { ok: true, imported };
+        // One action, one transaction: a write per row would stop halfway,
+        // and the door takes 300 writes a minute.
+        const r = await runAction({ name: "import_contacts", args: { rows: rows.map(({ id, ...values }) => values) } });
+        return r.ok ? { ok: true, imported: r.result?.imported } : r;
       }}
-      onDone={() => router.push("/contacts")}
+      onDone={() => router.push("/s/contacts")}
     />
   );
 }
 ```
 
+The action, named in `references/actions.md` and made with `sql`:
+
+```sql
+create or replace function import_contacts(args jsonb) returns jsonb
+language sql as $$
+  with made as (
+    insert into contacts (name, email, owner)
+    select name, email, owner from jsonb_populate_recordset(null::contacts, args->'rows')
+    returning 1
+  )
+  select jsonb_build_object('imported', count(*)) from made
+$$;
+```
+
+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
 
 - Excel files (.xlsx) are not read: save the sheet as CSV first (the

package/registry/blocks/data-table/README.md

@@ -252,8 +252,19 @@ argument, `ids`, is every selected id, including rows not on this page.
 
 ```jsx
 const [q, setQ] = useState({ search: "", filters: {}, sort: [], page: 1, pageSize: 25 });
-// …read rows + total for q on the server (a Server Action, a route)…
-<DataTable manual rows={pageRows} rowCount={total} loading={pending}
+// One page through the door: the filter grammar, an order, limit and offset.
+const filter = {
+  ...Object.fromEntries(Object.entries(q.filters).filter(([, values]) => values.length)),
+  customer: q.search ? { prefix: q.search } : undefined,   // starts with, case ignored
+};
+const page = useRows({ source: "invoices", filter, orderBy: q.sort.map((s) => `${s.key} ${s.dir}`).join(", ") || undefined,
+  limit: q.pageSize, offset: (q.page - 1) * q.pageSize });
+const total = useCount({ source: "invoices", filter });
+const { status, ...others } = filter;   // a facet counts over the other filters
+const byStatus = useCountBy({ source: "invoices", column: "status", filter: others });
+const statusCounts = Object.entries(byStatus.counts).map(([value, count]) => ({ value, label: value, count }));
+
+<DataTable manual rows={page.rows} rowCount={total.count} loading={page.loading || total.loading}
   search={q.search} onSearchChange={(search) => setQ((s) => ({ ...s, search }))}
   filters={q.filters} onFiltersChange={(filters) => setQ((s) => ({ ...s, filters }))}
   sort={q.sort} onSortChange={(sort) => setQ((s) => ({ ...s, sort }))}
@@ -262,6 +273,12 @@ const [q, setQ] = useState({ search: "", filters: {}, sort: [], page: 1, pageSiz
   columns={COLUMNS} facets={[{ key: "status", options: statusCounts }]} />
 ```
 
+`useRows`, `useCount` and `useCountBy` are `lib/data.js`'s in a browser
+app. `offset` goes up to 10,000; past it, page with `cursor` (the last
+answer's `next`, given when `orderBy` names one column). A server app's
+own `loadRows` takes no `offset`: its `"use client"` component takes
+these hooks from `lib/door.js`.
+
 The pure helpers the table uses are exported too — `processRows`,
 `searchRows`, `filterRows`, `sortRows`, `facetOptions`, `nextSort`,
 `groupRows`, `groupValueOf` and `useControllable` — so a surface can compute the same answer the table
@@ -269,12 +286,25 @@ shows (a total over the filtered rows) without drawing it twice.
 
 ## Example
 
+```jsx
+// surfaces/invoices.jsx — client: read, hand over
+"use client";
+import { useRows } from "../lib/data";
+import Invoices from "../components/Invoices";
+
+export default function InvoicesSurface() {
+  const { rows, error, loading } = useRows({ source: "invoices", orderBy: "due asc" });
+  if (loading) return null; // rows only once read: to useFixture, a read in flight looks like an empty table
+  return <Invoices invoices={rows} error={error} />;
+}
+```
+
 ```jsx
 // components/Invoices.jsx — client: the table, the row sheet
 "use client";
 import { useState } from "react";
 import { updateRow } from "../lib/actions";
-import { Badge, Button, Sheet } from "./ui";
+import { Badge, Button, Notice, Sheet } from "./ui";
 import { FixtureNotice, useFixture } from "./parts";
 import { DataTable } from "./blocks/data-table";
 
@@ -283,7 +313,7 @@ const COLUMNS = [
   { key: "number", header: "Invoice", sortable: true, hideable: false },
   { key: "customer", header: "Customer", sortable: true },
   { key: "status", header: "Status", sortable: true, cell: (r) => <Badge tone={TONE[r.status]}>{r.status}</Badge> },
-  { key: "amount", header: "Amount", sortable: true, align: "end", cell: (r) => `$${r.amount.toLocaleString()}` },
+  { key: "amount", header: "Amount", sortable: true, align: "end", cell: (r) => `$${Number(r.amount).toLocaleString()}` }, // numeric arrives as text
   { key: "due", header: "Due", sortable: true },
 ];
 const SAMPLE = [
@@ -291,14 +321,15 @@ const SAMPLE = [
   { number: "INV-1002", customer: "Acme Ltd", status: "overdue", amount: 450, due: "2026-09-01" },
 ];
 
-export default function Invoices({ invoices }) {
+export default function Invoices({ invoices, error }) {
   const fixture = useFixture(invoices, SAMPLE);
   const [open, setOpen] = useState(null);
   const markPaid = (rows) =>
-    Promise.all(rows.map((r) => updateRow({ source: "public.invoices", id: r.id, patch: { status: "paid" } })))
+    Promise.all(rows.map((r) => updateRow({ source: "invoices", id: r.id, patch: { status: "paid" } })))
       .then((all) => all.find((r) => r.ok === false) ?? { ok: true });
   return (
     <div className="grid gap-4">
+      {error ? <Notice tone="danger">{error}</Notice> : null}
       {fixture.isFixture ? <FixtureNotice onClear={fixture.clear} /> : null}
       <DataTable
         label="Invoices"
@@ -323,6 +354,8 @@ export default function Invoices({ invoices }) {
 }
 ```
 
+In a server-mode app the same calls are `loadRows` in a server surface and the Server Actions of `lib/actions`.
+
 ### Details, groups and totals
 
 A budget: line items under departments, sorted within them, a subtotal
@@ -364,8 +397,8 @@ the row and the rest in the menu:
   ]} />
 ```
 
-`setStatus` and `remove` return a promise of `{ ok }`, as a Server Action
-does; a failure is said above the table.
+`setStatus` and `remove` return a promise of `{ ok }`, as `updateRow` and
+`deleteRow` do; a failure is said above the table.
 
 ## What it will not do
 

package/registry/blocks/diagram/diagram.jsx

@@ -2,7 +2,7 @@
 
 // Diagram — Mermaid text drawn in the workspace theme, with zoom and pan.
 //
-// Client only, one static bundle: Mermaid needs the DOM to measure text,
+// Client only, one bundle: Mermaid needs the DOM to measure text,
 // and the app's check refuses import() (so no next/dynamic). The modules
 // load with the page; the drawing happens after the first effect (the
 // mount guard). Until then — on the server and in the first client paint —

package/registry/blocks/doc-editor/README.md

@@ -144,20 +144,30 @@ on a partial one):
 ## Example
 
 ```jsx
-// components/DealNotes.jsx — client
+// surfaces/deal.jsx — client: one deal's notes
 "use client";
 import { useState } from "react";
+import { useSearchParams } from "next/navigation";
+import { useRow, useRows } from "../lib/data";
 import { updateRow } from "../lib/actions";
-import { DocEditor } from "./blocks/doc-editor";
+import { DocEditor } from "../components/blocks/doc-editor";
+
+export default function DealSurface() {
+  const id = useSearchParams().get("row");
+  const { row: deal, loading } = useRow({ source: "deals", id });
+  const { rows: team } = useRows({ source: "people", orderBy: "name asc" });
+  if (loading || !deal) return null;
+  return <DealNotes key={deal.id} deal={deal} team={team} />;
+}
 
-export default function DealNotes({ deal, team }) {
-  const [doc, setDoc] = useState(deal.notes);   // jsonb, may be null
+function DealNotes({ deal, team }) {
+  const [doc, setDoc] = useState(deal.notes);   // jsonb, may be null; read once per deal, so a read never moves the cursor
   return (
     <DocEditor
       value={doc}
       onChange={(d) => {
         setDoc(d);
-        updateRow({ source: "public.deals", id: deal.id, patch: { notes: d } });   // debounce this in a real app
+        updateRow({ source: "deals", id: deal.id, patch: { notes: d } });   // debounce this in a real app
       }}
       mentions={async (q) => team.filter((p) => p.name.toLowerCase().includes(q.toLowerCase())).map((p) => ({ id: p.id, label: p.name }))}
       placeholder="Notes on this deal…"
@@ -167,13 +177,15 @@ export default function DealNotes({ deal, team }) {
 }
 ```
 
+In a server-mode app the same calls are `loadRows` in a server surface and the Server Actions of `lib/actions`.
+
 A comment box that posts on Cmd/Ctrl+Enter and clears itself:
 
 ```jsx
 const box = useDocEditor();
 const post = async (doc) => {
   if (isDocEmpty(doc)) return;
-  const res = await insertRow({ source: "public.comments", values: { body: doc, body_text: docToText(doc) } });
+  const res = await insertRow({ source: "comments", values: { body: doc, body_text: docToText(doc) } });
   if (res.ok) box.current?.clear();
 };
 

package/registry/blocks/doc-editor/doc-editor.jsx

@@ -2,7 +2,7 @@
 
 // DocEditor — BlockNote, in the workspace theme, behind one set of props.
 //
-// Client only, one static bundle. BlockNote needs the DOM, and the app's
+// Client only, one bundle. BlockNote needs the DOM, and the app's
 // check refuses import() (so no next/dynamic): the modules load with the
 // page, and the editor itself is created only after the first effect
 // (the mount guard). Until then — on the server and in the first client

package/registry/blocks/doc-page/README.md

@@ -75,22 +75,27 @@ out without waiting for the answer.
 ## Example
 
 ```jsx
-// components/WikiPage.jsx — client
+// surfaces/wiki.jsx — client: one page, read and saved
 "use client";
+import { useSearchParams } from "next/navigation";
+import { useRow, useRows } from "../lib/data";
 import { updateRow } from "../lib/actions";
-import { DocPage } from "./blocks/doc-page";
+import { DocPage } from "../components/blocks/doc-page";
 
-export default function WikiPage({ page, team, canEdit }) {
+export default function WikiPage() {
+  const id = useSearchParams().get("row");
+  const { row: page, loading } = useRow({ source: "wiki_pages", id });
+  const { rows: team } = useRows({ source: "people", orderBy: "name asc" });
+  if (loading || !page) return null;
   return (
     <DocPage
       id={page.id}
       title={page.title}
       icon={page.icon}
       doc={page.body}
-      readOnly={!canEdit}
-      meta={`Edited by ${page.edited_by_name}`}
+      meta={`Edited by ${page.edited_by}`}   // a before-update trigger sets edited_by (the app's README §5)
       onSave={({ id, title, icon, doc }) =>
-        updateRow({ source: "public.wiki_pages", id, patch: { title, icon, body: doc } })
+        updateRow({ source: "wiki_pages", id, patch: { title, icon, body: doc } })
       }
       mentions={async (q) =>
         team.filter((p) => p.name.toLowerCase().includes(q.toLowerCase())).map((p) => ({ id: p.id, label: p.name }))
@@ -100,6 +105,11 @@ export default function WikiPage({ page, team, canEdit }) {
 }
 ```
 
+The page reads `title`, `icon` and `doc` when `id` changes and owns the
+draft in between, so the read after each save never moves the cursor.
+
+In a server-mode app the same calls are `loadRows` in a server surface and the Server Actions of `lib/actions`.
+
 For search or a preview, keep a plain-text copy beside the doc:
 `docToText(doc)` from the doc-editor block, saved in the same `onSave`.