makersclaw 0.6.0 → 0.8.0

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`.
 

package/registry/blocks/file-upload/README.md

@@ -79,7 +79,7 @@ for a file) are exported too, for your own file rows.
 ## Example
 
 ```jsx
-// components/DealFiles.jsx — client
+// components/DealFiles.jsx — client, in a server app
 "use client";
 import { FileUpload } from "./blocks/file-upload";
 
@@ -111,6 +111,12 @@ export default function DealFiles({ deal, onSaveFiles }) {
 }
 ```
 
+A server app's only. `put` needs a route of the app's own to take the
+file (`/api/files` here), and a browser app has none: the data door
+takes no files until uploads have a home. In a browser app, leave
+`onUpload` out and use the block as a picker: read the file in the
+browser, as csv-import does.
+
 One spreadsheet to import, and a profile picture:
 
 ```jsx

package/registry/blocks/flow-canvas/README.md

@@ -111,7 +111,10 @@ re-route as cards move; handle ids are not stored.
   screen). `onExitPresentation()` — Esc and the bar's Exit call it; turn
   `presentation` off there.
 - `height` — the canvas's height, default `560` (px; any CSS length works:
-  `"70vh"`, `"100%"` inside a sized box).
+  `"100%"` inside a sized box, such as the kit's `AppLayout
+  contentMode="fill"` for a board that is the whole surface, the
+  Example). Never a `vh` length: `npm run check` refuses a size taken
+  from the window.
 - `bare` — `false` (default: rounded, bordered). `true`: no border or
   radius, for a full-page board.
 - `label` — the board's accessible name, default `"Board"`; also the list
@@ -364,26 +367,41 @@ one.
 ## Example
 
 ```jsx
-// components/LaunchBoard.jsx — client
+// surfaces/launch.jsx — client: one project's board
 "use client";
 import { useState } from "react";
+import { useSearchParams } from "next/navigation";
+import { useRow } from "../lib/data";
 import { updateRow } from "../lib/actions";
-import { FlowCanvas } from "./blocks/flow-canvas";
+import { AppLayout } from "../components/ui";
+import { FlowCanvas } from "../components/blocks/flow-canvas";
+
+export default function LaunchSurface() {
+  const id = useSearchParams().get("row");
+  const { row: project, loading } = useRow({ source: "projects", id });
+  if (loading || !project) return null;
+  return <LaunchBoard key={project.id} project={project} />;
+}
 
-export default function LaunchBoard({ project }) {
-  const [board, setBoard] = useState(project.board);   // jsonb, may be null
+function LaunchBoard({ project }) {
+  const [board, setBoard] = useState(project.board);   // jsonb, may be null; read once per project
   return (
-    <FlowCanvas
-      value={board ?? undefined}
-      onChange={setBoard}
-      onSave={(b) => updateRow({ source: "public.projects", id: project.id, patch: { board: b } })}
-      label={`${project.name} board`}
-      height="calc(100dvh - 8rem)"
-    />
+    <AppLayout contentMode="fill">
+      <FlowCanvas
+        value={board ?? undefined}
+        onChange={setBoard}
+        onSave={(b) => updateRow({ source: "projects", id: project.id, patch: { board: b } })}
+        label={`${project.name} board`}
+        height="100%"
+        bare
+      />
+    </AppLayout>
   );
 }
 ```
 
+In a server-mode app the same calls are `loadRows` in a server surface and the Server Actions of `lib/actions`.
+
 A card drawn with kit parts, and an agent reading the board:
 
 ```jsx

package/registry/blocks/flow-canvas/flow-canvas.jsx

@@ -3,7 +3,7 @@
 // FlowCanvas — a Miro-like board on React Flow, in the workspace theme,
 // behind one set of props (README.md beside this file).
 //
-// Client only, one static bundle: the modules load with the page (the
+// Client only, one bundle: the modules load with the page (the
 // app's check refuses import()), and the board itself mounts after the
 // first effect (the mount guard). Until then — on the server and in the
 // first client paint — a box of the same size holds the board as text, so

package/registry/blocks/footer/README.md

@@ -87,7 +87,7 @@ button, named to a screen reader ("X", "LinkedIn"), opening a new tab.
 "use client";
 import { Icon } from "./ui";
 import { Footer } from "./blocks/footer";
-import { subscribe } from "../lib/actions";   // your server action
+import { insertRow } from "../lib/actions";
 
 export default function SiteFooter() {
   return (
@@ -102,7 +102,7 @@ export default function SiteFooter() {
       newsletter={{
         body: "One email a month.",
         consent: "I agree to the privacy policy.",
-        onSubscribe: async (email) => subscribe(email),
+        onSubscribe: (email) => insertRow({ source: "subscribers", values: { email } }), // { ok, id } or { ok: false, error }
       }}
       legal="© 2026 Fieldline Ltd. All rights reserved."
       legalLinks={[{ label: "Privacy", href: "/privacy" }, { label: "Terms", href: "/terms" }]}
@@ -111,12 +111,15 @@ export default function SiteFooter() {
 }
 ```
 
+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
 
 - Change the language or currency by itself: `locales[].onChange` is
   yours.
-- Stick to the bottom of a short page: that is your layout's
-  `min-h-dvh` flex column.
+- Stick to the bottom of a short page: that is your layout's. The kit's
+  `AppLayout` content is a flex column, so a `flex-1` above the footer
+  pushes it down on a short page and lets it follow a long one.
 - Paint itself in the primary colour: the look is the workspace
   theme's.
 - Draw store badges: "Get the app" is two buttons with the Apple and

package/registry/blocks/gantt/README.md

@@ -145,15 +145,19 @@ drag saves, as `[{ id, patch }]`), `afterBlockersPatch(task, tasks)`,
 ## Example
 
 ```jsx
-// surfaces/plan.jsx — server: load, hand over
-import { loadRows } from "../lib/data";
+// surfaces/plan.jsx — client: read, hand over
+"use client";
+import { useRows } from "../lib/data";
 import Plan from "../components/Plan";
 
-export default async function PlanSurface() {
-  const { rows, error } = await loadRows({ source: "public.tasks", orderBy: "start asc" });
-  const people = await loadRows({ source: "public.people" });
-  const projects = await loadRows({ source: "public.projects" });
-  return <Plan tasks={rows} people={people.rows} projects={projects.rows} error={error} />;
+export default function PlanSurface() {
+  const tasks = useRows({ source: "tasks", orderBy: "start asc" });
+  const people = useRows({ source: "people" });
+  const projects = useRows({ source: "projects" });
+  return (
+    <Plan tasks={tasks.rows} people={people.rows} projects={projects.rows}
+      loading={tasks.loading || people.loading || projects.loading} error={tasks.error} />
+  );
 }
 ```
 
@@ -171,19 +175,19 @@ const COLUMNS = ["id", "title", "status", "assignees", "start", "due", "progress
 async function save(change) {
   for (const w of changeWrites(change, { columns: COLUMNS, keepNewIds: false })) {
     const r =
-      w.op === "insert" ? await insertRow({ source: "public.tasks", values: w.values, detail: w.values.title })
-      : w.op === "update" ? await updateRow({ source: "public.tasks", id: w.id, patch: w.patch })
-      : await deleteRow({ source: "public.tasks", id: w.id });
+      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 Plan({ tasks, people, projects, error }) {
+export default function Plan({ tasks, people, projects, loading, error }) {
   const [open, setOpen] = useState(null);
   return (
     <>
-      <Gantt tasks={tasks} people={people} projects={projects} onChange={save} onOpen={setOpen} error={error}
+      <Gantt tasks={tasks} people={people} projects={projects} onChange={save} onOpen={setOpen} loading={loading} error={error}
         starters={[{ label: "Product launch", tasks: [{ title: "Scope", days: 2 }, { title: "Build", days: 10 }, { title: "Launch", milestone: true }] }]} />
       <Sheet open={Boolean(open)} onClose={() => setOpen(null)} title={open?.title}>{/* the task's fields */}</Sheet>
     </>
@@ -191,6 +195,8 @@ export default function Plan({ tasks, people, projects, error }) {
 }
 ```
 
+In a server-mode app the same calls are `loadRows` in a server surface and the Server Actions of `lib/actions`.
+
 `keepNewIds: false` lets the table make a new task's id. A link made
 between two tasks created in the same change (a starter) refers to their
 client ids: keep them (`keepNewIds: true`, a text id column) when you

package/registry/blocks/job-panel/README.md

@@ -166,7 +166,7 @@ export default function PhotoStudio({ photos, reload }) {
                   options={[{ value: "square", label: "Square" }, { value: "portrait", label: "Portrait" }]} />
         </Field>
       }
-      onGenerate={(prompt) => job.start(`Make one ${size} product photo: ${prompt}. Save it to public.photos.`)}
+      onGenerate={(prompt) => job.start(`Make one ${size} product photo: ${prompt}. Save it to the photos table.`)}
       title="Making the photo"
       doneTitle="Photo saved"
       results={photos.map((p) => <Image key={p.id} src={p.url} alt={p.prompt} ratio="square" rounded="lg" />)}

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

@@ -98,24 +98,36 @@ tree on its own (`value`, `onEdit(next, { undo?, message? })`, `open`,
 ## Example
 
 ```jsx
+// surfaces/webhook.jsx — client: one integration's settings
 "use client";
 import { useState } from "react";
+import { useSearchParams } from "next/navigation";
+import { useRow } from "../lib/data";
+import { updateRow } from "../lib/actions";
 import { JsonEditor } from "../components/blocks/json-editor";
-import { saveIntegrationSettings } from "../lib/actions";   // your server action → { ok, error? }
 
-export function WebhookSettings({ integration }) {
-  const [settings, setSettings] = useState(integration.settings);
+export default function WebhookSurface() {
+  const id = useSearchParams().get("row");
+  const { row: integration, loading } = useRow({ source: "integrations", id });
+  if (loading || !integration) return null;
+  return <WebhookSettings key={integration.id} integration={integration} />;
+}
+
+function WebhookSettings({ integration }) {
+  const [settings, setSettings] = useState(integration.settings);   // jsonb; read once per integration
   return (
     <JsonEditor
       title="Webhook settings"
       value={settings}
       onChange={setSettings}
-      onSave={(v) => saveIntegrationSettings(integration.id, v)}
+      onSave={(v) => updateRow({ source: "integrations", id: integration.id, patch: { settings: v } })}
     />
   );
 }
 ```
 
+In a server-mode app the same calls are `loadRows` in a server surface and the Server Actions of `lib/actions`.
+
 Inspect a payload, read-only, as text first:
 
 ```jsx

package/registry/blocks/map/README.md

@@ -170,10 +170,23 @@ map.current?.getMap();  // the maplibre Map, for what the props do not cover
 
 ## Example
 
+```jsx
+// surfaces/customers.jsx — client: read, hand over
+"use client";
+import { useRows } from "../lib/data";
+import Customers from "../components/Customers";
+
+export default function CustomersSurface() {
+  const { rows, error, loading } = useRows({ source: "customers", orderBy: "name asc" });
+  if (loading) return null; // rows only once read: to useFixture, a read in flight looks like an empty table
+  return <Customers customers={rows} error={error} />;
+}
+```
+
 ```jsx
 // components/Customers.jsx — client: the map, the list, the popup
 "use client";
-import { Badge, Button } from "./ui";
+import { Badge, Button, Notice } from "./ui";
 import { FixtureNotice, useFixture } from "./parts";
 import { MapView } from "./blocks/map";
 
@@ -182,10 +195,11 @@ const SAMPLE = [
   { name: "Acme Bakery", city: "Porto", lat: 41.1405, lng: -8.6132, status: "at risk" },
 ];
 
-export default function Customers({ customers }) {
+export default function Customers({ customers, error }) {
   const fixture = useFixture(customers, SAMPLE);
   return (
     <div className="grid gap-4">
+      {error ? <Notice tone="danger">{error}</Notice> : null}
       {fixture.isFixture ? <FixtureNotice onClear={fixture.clear} /> : null}
       <MapView
         items={fixture.rows}
@@ -198,7 +212,7 @@ export default function Customers({ customers }) {
           <div className="grid gap-2 pr-8">
             <p className="font-medium">{c.name}</p>
             <p className="text-muted-foreground">{c.city}</p>
-            <Button size="sm" variant="primary" href={`/customers/${c.id}`}>Open</Button>
+            <Button size="sm" variant="primary" href={`/s/customers?row=${c.id}`}>Open</Button>
           </div>
         )}
       />
@@ -207,6 +221,8 @@ export default function Customers({ customers }) {
 }
 ```
 
+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
 
 - Geocode. It maps coordinates; turning an address into them is a

package/registry/blocks/map/map-view.jsx

@@ -5,7 +5,7 @@
 // on them (markers, clusters, the popup) and every control is ours, in the
 // kit and the workspace's tokens.
 //
-// Client only, one static bundle: maplibre loads with the page (see
+// Client only, one bundle: maplibre loads with the page (see
 // maplibre.js), and the map itself mounts after the first effect (the
 // mount guard). Until then — on the server and in the first client paint —
 // the frame, the list and a quiet placeholder are already there, so the

package/registry/blocks/map/maplibre.js

@@ -11,7 +11,7 @@
 //
 //   mapLib     react-map-gl would otherwise load maplibre-gl with an
 //              import() of its own. Handing it the module we import here
-//              keeps the app one static bundle.
+//              keeps the app one bundle.
 //   WORKER_URL maplibre-gl 6 draws tiles in a Web Worker that it loads
 //              from a file beside its own module (import.meta.url). Inside
 //              an app bundle that URL is a build-time file:// path, so the

package/registry/blocks/mind-map/README.md

@@ -96,7 +96,9 @@ string, or nothing (a fresh map). The component runs it on `value`.
 - `placeholder` — what an empty topic shows while it is typed (default
   "New topic").
 - `height` — px or any CSS length, default `600`. A height class in
-  `className` (`h-dvh`, `h-full`, `flex-1`) replaces it.
+  `className` (`h-full`, `min-h-0 flex-1`) replaces it: `min-h-0 flex-1`
+  fills what the surface has left (the Example). Never `h-dvh` or a `vh`
+  height, which `npm run check` refuses.
 - `label` — the map's accessible name (default "Mind map").
 - `onSelectionChange(topic | null)` — the selected topic changed (a side
   panel with its notes).
@@ -162,27 +164,38 @@ one as it was.
 ## Example
 
 ```jsx
-// components/PlanMap.jsx — client
+// surfaces/plan-map.jsx — client: one plan's map
 "use client";
 import { useState } from "react";
+import { useSearchParams } from "next/navigation";
+import { useRow } from "../lib/data";
 import { updateRow } from "../lib/actions";
-import { MindMap, mindMapToText } from "./blocks/mind-map";
+import { MindMap, mindMapToText } from "../components/blocks/mind-map";
 
-export default function PlanMap({ plan }) {
-  const [map, setMap] = useState(plan.map);   // jsonb, may be null
+export default function PlanMapSurface() {
+  const id = useSearchParams().get("row");
+  const { row: plan, loading } = useRow({ source: "plans", id });
+  if (loading || !plan) return null;
+  return <PlanMap key={plan.id} plan={plan} />;
+}
+
+function PlanMap({ plan }) {
+  const [map, setMap] = useState(plan.map);   // jsonb, may be null; read once per plan
   return (
     <MindMap
       value={map ?? undefined}
       defaultValue={{ text: plan.name }}
       onChange={setMap}
-      onSave={(m) => updateRow({ source: "public.plans", id: plan.id, patch: { map: m, map_text: mindMapToText(m) } })}
+      onSave={(m) => updateRow({ source: "plans", id: plan.id, patch: { map: m, map_text: mindMapToText(m) } })}
       label={`${plan.name} map`}
-      className="h-[calc(100dvh-8rem)]"
+      className="min-h-0 flex-1"
     />
   );
 }
 ```
 
+In a server-mode app the same calls are `loadRows` in a server surface and the Server Actions of `lib/actions`.
+
 An agent's outline, straight onto a map:
 
 ```jsx

package/registry/blocks/org-chart/README.md

@@ -73,7 +73,9 @@ One row per person, as a table holds them:
   reports: kit parts (their open deals, a "Message" button).
 - `onSelectionChange(person | null)` — the selected card changed.
 - `height` — px or any CSS length, default `640`. A height class in
-  `className` (`h-dvh`, `h-full`, `flex-1`) replaces it.
+  `className` (`h-full`, `min-h-0 flex-1`) replaces it: `min-h-0 flex-1`
+  fills what the surface has left (the Example). Never `h-dvh` or a `vh`
+  height, which `npm run check` refuses.
 - `label` — the chart's accessible name (default "Org chart").
 - `className` — layout around it (margin, width, height). Never colour.
 
@@ -106,29 +108,32 @@ One row per person, as a table holds them:
 ## Example
 
 ```jsx
-// components/TeamChart.jsx — client
+// surfaces/team.jsx — client: the chart, read and rearranged
 "use client";
-import { useState } from "react";
+import { useRows, whenLanded } from "../lib/data";
 import { updateRow } from "../lib/actions";
-import { OrgChart } from "./blocks/org-chart";
+import { OrgChart } from "../components/blocks/org-chart";
 
-export default function TeamChart({ employees }) {
-  const [people, setPeople] = useState(employees);   // rows of public.employees
+export default function TeamChart() {
+  const { rows: people, loading } = useRows({ source: "employees" });
+  if (loading) return null;
   return (
     <OrgChart
       people={people}
       managerKey="manager_id"
       onChangeManager={async (person, managerId) => {
-        const res = await updateRow({ source: "public.employees", id: person.id, patch: { manager_id: managerId } });
-        if (res.ok) setPeople((list) => list.map((p) => (p.id === person.id ? { ...p, manager_id: managerId } : p)));
+        const res = await updateRow({ source: "employees", id: person.id, patch: { manager_id: managerId } });
+        if (res.ok) await whenLanded(); // the people are read again: the chart draws the new manager
         return res;
       }}
-      className="h-[calc(100dvh-8rem)]"
+      className="min-h-0 flex-1"
     />
   );
 }
 ```
 
+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
 
 - Show a person under two managers (dotted lines, matrix orgs): one

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

@@ -83,7 +83,7 @@ variables the app's Tailwind utilities read. The built-in blocks' CSS
   workspace theme. Tailwind emits a theme variable only when some source
   names it, so this block names every token a page may use
   (`KEEP_TOKENS`). Installing the block is enough.
-- **Outside the app** (a download, a static host),
+- **Outside the app** (a download, a plain file host),
   `standaloneDocument(page, { root })` returns a full HTML document with
   the tokens resolved and inlined. `pageDocument(page, { tokens })` is the
   same function for the server, if you pass it the `:root{…}` string
@@ -105,7 +105,7 @@ variables the app's Tailwind utilities read. The built-in blocks' CSS
 | `actions` | — | Extra top-bar controls before Save, such as landing-builder's Publish. Use kit `Button`s at `size="sm"`. |
 | `saveLabel` | `"Save"` | The Save button's words. |
 | `builderRef` | — | A ref from `usePageBuilder()`. It receives the handle. |
-| `height` | `720` | The builder's height: a number (px) or any CSS length (`"min(760px, 88dvh)"`). It fills its width. |
+| `height` | `720` | The builder's height: a number (px) or any CSS length (`"100%"` in a sized box, such as the kit's `AppLayout contentMode="fill"`; never a `vh` length, which `npm run check` refuses). It fills its width. |
 | `className` | — | Added to the frame. |
 
 ### The handle
@@ -208,31 +208,38 @@ the helpers the panel uses.
 ## Example
 
 ```jsx
+// surfaces/landing.jsx — client: edit one page
 "use client";
-import { useState } from "react";
+import { useSearchParams } from "next/navigation";
+import { useRow } from "../lib/data";
+import { updateRow } from "../lib/actions";
 import { PageBuilder, PageView } from "../components/blocks/page-builder";
-import { saveRow } from "../lib/db";
 
-export function LandingEditor({ row }) {
+export default function LandingEditor() {
+  const id = useSearchParams().get("row");
+  const { row, loading } = useRow({ source: "pages", id });
+  if (loading || !row) return null;
   return (
     <PageBuilder
       key={row.id}
       title={row.title}
       page={row.project ? { project: row.project } : { html: row.html, css: row.css }}
       onSave={async ({ html, css, project }) => {
-        const res = await saveRow("pages", row.id, { html, css, project });
+        const res = await updateRow({ source: "pages", id: row.id, patch: { html, css, project } });
         return res.ok ? { ok: true } : { ok: false, error: "The page was not saved. Check your connection and try again." };
       }}
     />
   );
 }
 
-// the public page, on the server:
+// The finished page, for a surface of its own that reads the row with the same useRow:
 export function LandingPage({ row }) {
   return <PageView page={row} label={row.title} />;
 }
 ```
 
+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
 
 - No live multiplayer. Two people editing the same page is last save wins.

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

@@ -78,7 +78,7 @@ export default function PageBuilderDemo() {
         <Landing />
       </TabPanel>
       <TabPanel tab="fresh" value={tab}>
-        <PageBuilder title="New page" height="min(720px, 88dvh)" />
+        <PageBuilder title="New page" height={720} />
       </TabPanel>
       <TabPanel tab="own" value={tab}>
         <PageBuilder
@@ -86,7 +86,7 @@ export default function PageBuilderDemo() {
           builtIns="basics"
           blocks={OWN_BLOCKS}
           templates={OWN_TEMPLATES}
-          height="min(720px, 88dvh)"
+          height={720}
           onSave={async () => {
             await new Promise((r) => setTimeout(r, 400));
             toast.success("Page saved");
@@ -122,7 +122,7 @@ function Landing() {
         page={{ html: LAUNCH.html }}
         onSave={onSave}
         builderRef={builder}
-        height="min(760px, 88dvh)"
+        height={760}
         onUploadImage={async (file) => {
           await new Promise((r) => setTimeout(r, 500));
           // In an app: upload to storage and return its public address.

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

@@ -12,7 +12,7 @@
 // GrapesJS runs with <Canvas> from @grapesjs/react, so it creates none of
 // its own panels; theme.js repaints the few things it still draws.
 //
-// Client only, one static bundle: the modules load with the page (they are
+// Client only, one bundle: the modules load with the page (they are
 // safe on the server — see grapes.js); the editor is created in an effect
 // after the mount guard. Until then — on the server and in the first client
 // paint — the same frame shows with a skeleton.