makersclaw 0.2.0 → 0.3.0

package/registry/blocks/org-chart/org.js

@@ -0,0 +1,245 @@
+// The org chart's data and layout — plain functions, no React, no DOM.
+// They run anywhere (the server, an agent's tool, a test).
+//
+// People come in flat, the way a table holds them: each row names its
+// manager. buildOrg turns them into a tree; layoutOrg places the tree top
+// down, managers centred over their reports, and a manager whose reports
+// have no reports of their own gets them as a compact column (a wide row
+// of twelve cards reads worse than a list).
+
+/** Department (or any group) colours, in order: chart hues, which every
+ *  theme derives from its own primary. As hue numbers for Legend/Badge. */
+export const GROUP_HUES = [2, 3, 4, 5, 1];
+
+export const CARD = { width: 248, height: 72 };
+const GAP_X = 20; // between side-by-side teams
+const GAP_Y = 52; // between a manager and the row of reports
+const STACK_INDENT = 32; // a column of reports sits this far in
+const STACK_GAP = 10;
+const ROOT_GAP = 64; // between separate trees
+/** A manager's reports stack as a column when there are at least this
+ *  many and none of them manages anyone. */
+export const STACK_FROM = 3;
+
+/**
+ * Flat people → a tree. Returns { roots, byId }; each node is
+ * { id, person, parentId, depth, children, total } (total: everyone under
+ * them). Someone whose manager is missing, or whose chain of managers
+ * loops, becomes a root.
+ *
+ *   managerKey   the field naming the manager's id (default "managerId")
+ */
+export function buildOrg(people, { managerKey = "managerId" } = {}) {
+  const list = Array.isArray(people) ? people.filter((p) => p && p.id != null) : [];
+  const byId = new Map();
+  for (const p of list) {
+    const id = String(p.id);
+    if (!byId.has(id)) byId.set(id, { id, person: p, parentId: null, depth: 0, children: [], total: 0 });
+  }
+  const managerOf = (id) => {
+    const m = byId.get(id)?.person?.[managerKey];
+    return m != null && byId.has(String(m)) && String(m) !== id ? String(m) : null;
+  };
+  // A chain that comes back to itself: whoever closes the loop is a root.
+  const loops = new Set();
+  for (const id of byId.keys()) {
+    const seen = new Set([id]);
+    let cur = managerOf(id);
+    while (cur) {
+      if (seen.has(cur)) {
+        if (cur === id) loops.add(id);
+        break;
+      }
+      seen.add(cur);
+      cur = managerOf(cur);
+    }
+  }
+  const roots = [];
+  for (const n of byId.values()) {
+    const m = loops.has(n.id) ? null : managerOf(n.id);
+    if (m && !loops.has(n.id)) {
+      n.parentId = m;
+      byId.get(m).children.push(n);
+    } else roots.push(n);
+  }
+  // Anyone still unreached sits in a loop not broken above: a root too.
+  const reached = new Set();
+  const walk = (n, depth) => {
+    if (reached.has(n.id)) return 0;
+    reached.add(n.id);
+    n.depth = depth;
+    n.total = n.children.reduce((s, c) => s + 1 + walk(c, depth + 1), 0);
+    return n.total;
+  };
+  for (const r of roots) walk(r, 0);
+  for (const n of byId.values()) {
+    if (reached.has(n.id)) continue;
+    if (n.parentId) byId.get(n.parentId).children = byId.get(n.parentId).children.filter((c) => c.id !== n.id);
+    n.parentId = null;
+    roots.push(n);
+    walk(n, 0);
+  }
+  return { roots, byId };
+}
+
+/** [root, …, the person's node] — their chain of managers, top first. */
+export function chainOf(byId, id) {
+  const out = [];
+  let n = byId.get(String(id));
+  const seen = new Set();
+  while (n && !seen.has(n.id)) {
+    seen.add(n.id);
+    out.unshift(n);
+    n = n.parentId ? byId.get(n.parentId) : null;
+  }
+  return out;
+}
+
+/** The colour group of each value of `key` ("department"): the first
+ *  seen gets the first hue. Map(value → hue number 1..5). */
+export function groupHues(people, key) {
+  const out = new Map();
+  if (!key) return out;
+  for (const p of people ?? []) {
+    const v = typeof key === "function" ? key(p) : p?.[key];
+    if (v == null || v === "" || out.has(v)) continue;
+    out.set(v, GROUP_HUES[out.size % GROUP_HUES.length]);
+  }
+  return out;
+}
+
+// Rounded right-angle lines through points (a corner radius r).
+export function elbowPath(points, r = 8) {
+  if (points.length < 2) return "";
+  let d = `M${points[0].x},${points[0].y}`;
+  for (let i = 1; i < points.length - 1; i++) {
+    const a = points[i - 1];
+    const b = points[i];
+    const c = points[i + 1];
+    const r1 = Math.min(r, Math.hypot(b.x - a.x, b.y - a.y) / 2, Math.hypot(c.x - b.x, c.y - b.y) / 2);
+    const u = { x: Math.sign(b.x - a.x), y: Math.sign(b.y - a.y) };
+    const v = { x: Math.sign(c.x - b.x), y: Math.sign(c.y - b.y) };
+    d += ` L${b.x - u.x * r1},${b.y - u.y * r1} Q${b.x},${b.y} ${b.x + v.x * r1},${b.y + v.y * r1}`;
+  }
+  const z = points[points.length - 1];
+  return `${d} L${z.x},${z.y}`;
+}
+
+/**
+ * Where every visible card goes. Top down; a manager centred over the
+ * cards of their reports; a folded manager's team hidden; separate trees
+ * side by side.
+ *
+ *   collapsed(node) → true when the node's team is folded
+ *   stack           true (default): reports with no reports of their own
+ *                   become a column once there are STACK_FROM of them
+ *
+ * Returns { items, bounds }. Each item: { id, node, x, y, width, height,
+ * depth, parentId, folded, link } — `link` the line up to the manager, as
+ * points in board px ([] for a root).
+ */
+export function layoutOrg(roots, { collapsed = () => false, stack = true, card = CARD } = {}) {
+  const W = card.width;
+  const H = card.height;
+  const info = new Map();
+  const shown = (n) => (collapsed(n) ? [] : n.children);
+  const measure = (n) => {
+    const kids = shown(n);
+    let mode = "none";
+    let width = W;
+    if (kids.length) {
+      for (const k of kids) measure(k);
+      if (stack && kids.length >= STACK_FROM && kids.every((k) => !k.children.length)) {
+        mode = "stack";
+        width = STACK_INDENT + W;
+      } else {
+        mode = "row";
+        const total = kids.reduce((s, k) => s + info.get(k.id).width, 0) + GAP_X * (kids.length - 1);
+        width = Math.max(W, total);
+      }
+    }
+    info.set(n.id, { mode, width });
+  };
+
+  const items = [];
+  const place = (n, left, top, parent) => {
+    const { mode, width } = info.get(n.id);
+    const kids = shown(n);
+    const me = { id: n.id, node: n, x: left, y: top, width: W, height: H, depth: n.depth, parentId: parent?.id ?? null, folded: kids.length === 0 && n.children.length > 0, link: [] };
+    items.push(me);
+    if (mode === "none") {
+      me.x = left + (width - W) / 2;
+      return me;
+    }
+    if (mode === "stack") {
+      me.x = left;
+      let y = top + H + GAP_Y / 2 + 6;
+      const spine = me.x + STACK_INDENT / 2;
+      for (const k of kids) {
+        const c = place(k, left + STACK_INDENT, y, me);
+        c.link = [
+          { x: spine, y: top + H },
+          { x: spine, y: y + H / 2 },
+          { x: c.x, y: y + H / 2 },
+        ];
+        y += H + STACK_GAP;
+      }
+      return me;
+    }
+    const total = kids.reduce((s, k) => s + info.get(k.id).width, 0) + GAP_X * (kids.length - 1);
+    let x = left + (width - total) / 2;
+    const placed = [];
+    for (const k of kids) {
+      placed.push(place(k, x, top + H + GAP_Y, me));
+      x += info.get(k.id).width + GAP_X;
+    }
+    const a = placed[0].x + W / 2;
+    const b = placed[placed.length - 1].x + W / 2;
+    me.x = (a + b) / 2 - W / 2;
+    const mid = top + H + GAP_Y / 2;
+    for (const c of placed) {
+      c.link = [
+        { x: me.x + W / 2, y: top + H },
+        { x: me.x + W / 2, y: mid },
+        { x: c.x + W / 2, y: mid },
+        { x: c.x + W / 2, y: c.y },
+      ];
+      // Straight down: two points are enough.
+      if (Math.abs(c.link[0].x - c.link[3].x) < 0.5) c.link = [c.link[0], c.link[3]];
+    }
+    return me;
+  };
+
+  for (const r of roots) measure(r);
+  let x = 0;
+  for (const r of roots) {
+    place(r, x, 0, null);
+    x += info.get(r.id).width + ROOT_GAP;
+  }
+
+  let x1 = Infinity;
+  let y1 = Infinity;
+  let x2 = -Infinity;
+  let y2 = -Infinity;
+  for (const it of items) {
+    x1 = Math.min(x1, it.x);
+    y1 = Math.min(y1, it.y);
+    x2 = Math.max(x2, it.x + it.width);
+    y2 = Math.max(y2, it.y + it.height);
+  }
+  return { items, bounds: items.length ? { x: x1, y: y1, width: x2 - x1, height: y2 - y1 } : { x: 0, y: 0, width: 0, height: 0 } };
+}
+
+/** The org as plain text, one person a line, indented under their
+ *  manager: "Maya Chen — VP Engineering (12)". For an agent or search. */
+export function orgToText(people, opts) {
+  const { roots } = buildOrg(people, opts);
+  const out = [];
+  const walk = (n, depth) => {
+    const p = n.person;
+    out.push(`${"  ".repeat(depth)}${depth ? "- " : ""}${p.name ?? n.id}${p.title ? ` — ${p.title}` : ""}${n.total ? ` (${n.total})` : ""}`);
+    for (const c of n.children) walk(c, depth + 1);
+  };
+  for (const r of roots) walk(r, 0);
+  return out.join("\n");
+}

package/registry/blocks/org-chart/person.jsx

@@ -0,0 +1,96 @@
+"use client";
+
+// One person on the chart, as a FlowCanvas node type: a card (face, name,
+// title, a strip in their group's colour), the line up to their manager
+// (an SVG reaching outside the card, so the canvas needs no connectors),
+// and — for a manager — the chip at the card's foot that folds the team
+// and says how big it is.
+//
+// What the chart knows (the selection, the chain being lit, a drag in
+// progress, what a click does) comes from OrgContext, which OrgChart
+// provides around the canvas.
+import { createContext, useContext } from "react";
+import { Avatar, Icon, cx } from "../../ui";
+import { elbowPath } from "./org";
+
+export const OrgContext = createContext(null);
+
+// Group hue → the strip's class, written out whole so Tailwind makes them.
+const STRIP = { 1: "bg-chart-1", 2: "bg-chart-2", 3: "bg-chart-3", 4: "bg-chart-4", 5: "bg-chart-5" };
+
+export function PersonNode({ id, data }) {
+  const o = useContext(OrgContext);
+  if (!o) return null;
+  const { name, title, avatar, hue, direct = 0, total = 0, folded = false, link, parentId } = data ?? {};
+  const selected = o.selectedId === id;
+  const lit = o.chain.has(id) && parentId && o.chain.has(parentId);
+  const isDrop = o.dropId === id;
+  const dragged = o.dragId === id;
+
+  return (
+    <div data-person={id} className="group/person relative size-full">
+      {link ? (
+        <svg aria-hidden="true" width="1" height="1" className="pointer-events-none absolute top-0 left-0 overflow-visible">
+          <path d={elbowPath(link)} className={cx("fill-none transition-[stroke] duration-150 motion-reduce:transition-none", lit ? "stroke-primary" : "stroke-border")} strokeWidth={lit ? 2 : 1.5} strokeLinecap="round" strokeLinejoin="round" />
+        </svg>
+      ) : null}
+      {/* raw: the person's card on the canvas — it takes the pointer
+          (a click selects, a click on the selected card opens it, a drag
+          moves them to a new manager); the keys arrive through OrgChart's
+          handler on the canvas. */}
+      <div
+        className={cx(
+          "relative flex size-full items-center gap-3 overflow-hidden rounded-xl border border-border bg-card py-2 pr-3 pl-4 text-card-foreground shadow-xs",
+          "transition-[box-shadow,opacity,outline-color] duration-150 hover:shadow-md motion-reduce:transition-none",
+          o.coarse ? "" : "nopan",
+          o.draggable ? "cursor-grab" : "cursor-pointer",
+          selected && "ring-2 ring-primary ring-offset-2 ring-offset-background",
+          isDrop && "outline-2 outline-offset-4 outline-primary [outline-style:dashed]",
+          dragged && "opacity-40",
+        )}
+        onPointerDown={(e) => {
+          if (e.button === 0) o.onCardPointerDown(e, id);
+        }}
+      >
+        {hue ? <span aria-hidden="true" className={cx("absolute inset-y-0 left-0 w-1", STRIP[hue])} /> : null}
+        <Avatar name={name} src={avatar} size="md" />
+        <div className="min-w-0 flex-1">
+          <p className="truncate text-sm font-medium" title={name}>
+            {name || "Unnamed"}
+          </p>
+          <p className="truncate text-xs text-muted-foreground" title={title}>
+            {title || " "}
+          </p>
+        </div>
+      </div>
+
+      {direct > 0 ? (
+        // raw: a 22px chip on the card's foot, smaller than any kit button
+        // — the canvas is zoomed out on a big org, and a 36px button would
+        // cover the line to the team. Out of the tab order: Space folds.
+        <button
+          type="button"
+          tabIndex={-1}
+          aria-label={`${folded ? "Show" : "Hide"} ${name}'s team: ${direct} direct, ${total} in all`}
+          title={`${direct} direct report${direct === 1 ? "" : "s"}${total > direct ? ` · ${total} in the team` : ""} — ${folded ? "show" : "hide"}`}
+          onMouseDown={(e) => e.preventDefault()}
+          onPointerDown={(e) => e.stopPropagation()}
+          onClick={(e) => {
+            e.stopPropagation();
+            o.toggle(id);
+          }}
+          className={cx(
+            "nodrag nopan absolute top-full left-1/2 z-10 flex h-[22px] -translate-x-1/2 -translate-y-1/2 items-center gap-0.5 rounded-full border px-2 text-[11px] leading-none font-medium tabular-nums shadow-xs",
+            "transition-colors duration-150 motion-reduce:transition-none",
+            folded ? "border-primary/50 bg-card text-foreground hover:bg-accent" : "border-border bg-card text-muted-foreground hover:text-foreground",
+          )}
+        >
+          {folded ? `+${total}` : direct}
+          <Icon name={folded ? "chevron-down" : "chevron-up"} size={12} />
+        </button>
+      ) : null}
+    </div>
+  );
+}
+
+export const NODE_TYPES = { person: PersonNode };

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

@@ -0,0 +1,257 @@
+# PageBuilder
+
+A visual page editor in the workspace theme, calm like Webflow's canvas
+without its cockpit. The page sits in the middle at desktop, tablet or
+phone width. On the left, **Add** lists blocks as small wireframes —
+sections (hero, features, logos, quote, pricing, questions, call to action,
+footer) and basics (heading, text, button, image, two columns, list,
+divider, space). Click one to add it below the selection, or drag it onto
+the page. **Layers** shows the page as a tree: select, fold, hide while
+editing. On the right, **Design** changes the selected element's look,
+limited to the theme's choices: text colour, background, text size,
+weight, typeface, alignment, spacing, width, corners and border. It also
+edits a link's address or a picture's source and description, and moves,
+duplicates or deletes the element. The top bar has the save state, the
+device toggle, undo and redo, Preview and Save. A new page opens on a
+friendly empty state with starter templates. On a narrow screen the
+panels move to a bottom bar and open as sheets.
+
+It is [GrapesJS](https://github.com/GrapesJS/grapesjs) (BSD-3-Clause, the
+free core — never the commercial Studio SDK) with its React wrapper
+[@grapesjs/react](https://github.com/GrapesJS/react) (MIT). GrapesJS does
+the page model, the canvas, selection, drag and drop, text editing, undo
+and the export. The panels, the top bar, the empty state and the Design
+choices are ours, built from the kit. GrapesJS's own panels, style manager,
+trait manager, asset modal and code viewer are never created. The blocks
+built on this one — `landing-builder` first — import it, never `grapesjs`
+directly.
+
+```jsx
+import { PageBuilder, PageView } from "../components/blocks/page-builder";   // a Makersclaw app ("./blocks/page-builder" from components/)
+import { PageBuilder, PageView } from "@/components/makersclaw/blocks/page-builder";   // a shadcn project
+```
+
+`PageBuilder` is a client component: render it from a `"use client"`
+component. `PageView` and the helpers (`pageDocument`, `cleanHtml`,
+`cleanCss`, `isPageEmpty`, `projectSections`…) work on the server too.
+
+`makersclaw add page-builder` adds `grapesjs` and `@grapesjs/react`
+(pinned, exact) to package.json: run `npm install` after. They load with
+the page, with no `import()`. The editor is created after the first render.
+Until then, and on the server, the frame shows a skeleton.
+
+## The data
+
+The builder hands out a page as three things. You get it from `onSave`,
+from `onChange`, and from the handle's `getPage()`:
+
+```js
+{
+  html: "<section class=\"pb-section pb-center\" …>…</section>…",   // the body's content, cleaned
+  css: ".pb-section{padding:88px 24px;background-color:var(--color-background);…}#i4kd{…}",
+  project: { pages: [ … ], styles: [ … ], assets: [], … },           // GrapesJS project JSON
+}
+```
+
+- **Store `project`** (a `jsonb` column). It is what reopens the page for
+  editing: pass it back as `page={{ project }}`.
+- **Show `html` + `css`** with `PageView`, or publish them. They are the
+  source of truth for what visitors see. They are derived from `project`
+  at save time, so store them next to it instead of recomputing them.
+- `page={{ html, css }}` also opens, as a fresh project. This is how a
+  template, an import or an agent-written page starts.
+- The HTML is cleaned: no `<script>`, no `on*` handlers, no `javascript:`
+  links. The CSS has no `body`, `html` or `*` rules. Only rules the page
+  uses are exported.
+
+### Pages keep the theme
+
+**A page never holds a colour. It names theme tokens, so it repaints when
+the theme changes.** Every Design choice writes a CSS variable:
+`var(--color-primary)`, `var(--color-muted-foreground)`,
+`var(--theme-font-display)`, `var(--theme-radius)`. These are the same
+variables the app's Tailwind utilities read. The built-in blocks' CSS
+(`BASE_CSS`, `pb-` classes) uses them too. Sizes and spacing are plain
+`rem`/`px` steps.
+
+- **In the editor**, the canvas is an iframe that cannot see the app's
+  stylesheet. The builder resolves each token where it sits (its light or
+  dark scheme and any `[data-theme]` scope) and writes the values into the
+  frame. It does this again when the theme changes. It also copies the
+  app's `@font-face` rules, so the page uses the theme's typefaces.
+- **In the app**, `PageView` shows the page. The tokens resolve to the
+  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),
+  `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
+  yourself.
+
+## Props
+
+| Prop | Default | |
+| --- | --- | --- |
+| `page` | empty | The page to open: `{ project }` or `{ html, css }`. Read once, when the editor is created. To open another page, change the component's `key` or call the handle's `setPage`. |
+| `onSave` | — | `async (page) => ({ ok, error? })`. Called by Save and ⌘/Ctrl+S with `{ html, css, project }`. On `{ ok: false }`, the page stays unsaved and a toast shows your `error` with "Try again". The top bar says "Not saved". |
+| `onChange` | — | `(page) => void`, 500 ms after the last edit. Use it for autosave or a live preview elsewhere. |
+| `title` | `"Untitled page"` | The name in the top bar. |
+| `blocks` | `[]` | Your own blocks, added after the built-ins. See "Your own sections". |
+| `builtIns` | `true` | Which built-in blocks to offer: `true` (sections and basics), `"sections"`, `"basics"` or `false`. |
+| `templates` | `STARTER_TEMPLATES` | Whole pages offered in the empty state and in "Start from a template". Pass `[]` for none. |
+| `styles` | `STYLE_GROUPS` | The Design panel's choices. See "The Design choices". |
+| `onUploadImage` | — | `async (file) => ({ ok, url, error? })`. When given, a picture's field gets an Upload button. Without it, people paste an address. |
+| `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. |
+| `className` | — | Added to the frame. |
+
+### The handle
+
+```jsx
+const builder = usePageBuilder();
+<PageBuilder builderRef={builder} … />
+builder.current?.getPage();            // { html, css, project }
+```
+
+`getPage()` · `save()` (runs `onSave`, returns its result) ·
+`addBlock(id)` · `loadTemplate(idOrTemplate)` · `setPage({ html, css } |
+{ project })` · `undo()` · `redo()` · `setDevice("desktop" | "tablet" |
+"mobile")` · `preview(on = true)` · `editor` (the GrapesJS editor, for what
+this block does not wrap; changes made through it are yours to keep
+token-only).
+
+## Your own sections
+
+This is how `landing-builder` builds on this block. A block is plain data:
+
+```js
+const HERO_WAITLIST = {
+  id: "hero-waitlist",                 // unique across built-ins and yours
+  label: "Waitlist hero",              // the tile's name
+  category: "Hero",                    // the Add panel's group heading
+  thumb: "split",                      // a wireframe from THUMB_NAMES
+  description: "Headline, one line and an email button.",   // the tile's tooltip
+  level: "section",                    // "section": added between top-level sections ·
+                                       // "element": added inside the selected box
+                                       // (default: "section" when category is "Sections")
+  html: `<section class="lb-hero" data-gjs-name="Waitlist hero">…</section>`,
+  css: `.lb-hero{padding:96px 24px;background-color:var(--color-muted);color:var(--color-foreground)}`,
+};
+<PageBuilder blocks={[HERO_WAITLIST]} builtIns="basics" templates={LANDING_TEMPLATES} />
+```
+
+- `html` is the markup, or use `content`, a GrapesJS component definition,
+  in its place. `data-gjs-name` names the element in Layers. Any
+  `data-gjs-*` attribute sets that GrapesJS property: for example,
+  `data-gjs-draggable="false"` or `data-gjs-removable="false"` lock a part.
+- `css` is added to the page once, when the editor opens. **Name only
+  tokens for colour** (`var(--color-…)`, from `COLOR_TOKENS`) and
+  `--theme-font-*` / `--theme-radius` for faces and corners. Then your
+  sections repaint with the theme. Prefix your classes (`lb-`), and reuse
+  the built-in `pb-` classes (`pb-button`, `pb-h2`, `pb-lead`,
+  `pb-container`…) when they fit. Add an `@media (max-width: 768px)` rule
+  for the phone layout. The canvas's phone width is a real narrow frame,
+  so media queries work there.
+- Several blocks may share one `css` string. The same rule added twice is
+  one rule.
+
+A **template** is a whole page:
+`{ id, label, description?, thumbs?: ["hero", "features", "cta"], html, css? }`
+or `{ id, label, project }`. `thumbs` draws its card, up to four sections
+tall. Picking a template replaces the page. A toast offers Undo when there
+was something to replace.
+
+`BlockThumb` and `PageThumb` draw the same wireframes elsewhere, for
+example in a landing-builder gallery of templates.
+
+## The Design choices
+
+`STYLE_GROUPS` is a list of groups. Each group is one row of choices:
+
+```js
+{
+  id: "fill", label: "Background", kind: "swatch" | "segmented" | "select",
+  for: ["link", "box"],                // which elements show it: text · link · image · box (all if left out)
+  match: "background-color",           // the property read back to show the current choice
+  options: [
+    { value: "", label: "Default", css: { "background-color": "" } },   // "" = reset: the block's own CSS applies
+    { value: "primary", label: "Primary", css: { "background-color": "var(--color-primary)" } },
+  ],
+}
+```
+
+Picking an option writes its `css` onto that element only (an `#id`
+rule). Any property another option of the group sets is cleared. "Reset"
+beside a group removes the group's properties. "Clear this element's
+style" removes all of them. To offer fewer or different choices, pass
+your own list, filtered from or modelled on `STYLE_GROUPS`. A swatch
+option's `value` is the token name it paints (`primary` →
+`var(--color-primary)`). `groupsFor`, `currentOption` and `patchFor` are
+the helpers the panel uses.
+
+## Mouse, keyboard and touch
+
+- Click an element to select it. Double-click text to edit the words
+  (bold, italic and link in the small toolbar). Double-click a picture to
+  jump to its field. Drag the selected element's handle to move it.
+- ⌘/Ctrl+S saves. ⌘/Ctrl+Z undoes, ⇧⌘Z redoes. Backspace or Delete
+  removes the selection (with Undo in a toast when done from the panel).
+  Esc leaves Preview.
+- The block tiles, the layer tree (↑ ↓ to move, ← → to fold), the swatches
+  (arrow keys) and every control are reachable by keyboard. A tile adds
+  on Enter.
+- On a phone, tap a tile to add it. Dragging is for a mouse.
+
+## Example
+
+```jsx
+"use client";
+import { useState } from "react";
+import { PageBuilder, PageView } from "../components/blocks/page-builder";
+import { saveRow } from "../lib/db";
+
+export function LandingEditor({ row }) {
+  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 });
+        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:
+export function LandingPage({ row }) {
+  return <PageView page={row} label={row.title} />;
+}
+```
+
+## What it will not do
+
+- No live multiplayer. Two people editing the same page is last save wins.
+- No free colour picker, hex field or arbitrary CSS. The Design panel
+  offers the theme's choices only, by design. A block's own `css` is where
+  a fixed design lives.
+- Styles apply at every width. The canvas's device toggle previews the
+  page's own media queries. It does not keep per-device overrides.
+- No forms that submit, and no scripts. The HTML is cleaned of them. A
+  signup form belongs to the app (a block beside `PageView`), not to the
+  page.
+- No asset library. Pictures are an address, or an upload through
+  `onUploadImage`.
+- No publishing, domains or SEO fields. Those belong to `landing-builder`
+  and the app.
+
+## Credits
+
+GrapesJS © Artur Arseniev, BSD-3-Clause. @grapesjs/react © Artur
+Arseniev, MIT. Both are used unmodified, as npm dependencies. The block
+ships none of their code. GrapesJS's stylesheet is imported from the
+package and repainted with the workspace's tokens.

package/registry/blocks/page-builder/block.json

@@ -0,0 +1,14 @@
+{
+  "name": "page-builder",
+  "title": "PageBuilder",
+  "description": "A visual page editor (GrapesJS core) in the workspace theme: our own clean panels instead of GrapesJS's chrome — an Add panel of section and basic blocks (click or drag), a Layers tree, a Design panel limited to theme-token choices (colours, type, spacing, width, corners, borders), a device toggle (desktop, tablet, phone), undo/redo, preview, and a friendly empty state with starter templates. Pages style with CSS variables, so a saved page repaints with the theme. Saves out as { html, css, project }; PageView shows a saved page in an app.",
+  "useWhen": "A screen where someone builds or edits a web page visually: a landing page, a waitlist or launch page, a simple site section, an announcement page. landing-builder is built on it (section templates, publishing). Not for rich text in a document (doc-editor), an email body (newsletter-builder), a form of fields (record-form) or a freeform drawing (sketch-canvas).",
+  "tags": ["page builder", "website builder", "landing page", "grapesjs", "visual editor", "drag and drop", "sections", "templates", "wysiwyg", "html", "css", "no-code", "web page", "layers"],
+  "exports": ["PageBuilder", "usePageBuilder", "readPage", "DEVICES", "PageView", "standaloneDocument", "BlockThumb", "PageThumb", "THUMB_NAMES", "BASE_CSS", "SECTION_BLOCKS", "BASIC_BLOCKS", "STARTER_TEMPLATES", "STYLE_GROUPS", "COLOR_TOKENS", "groupsFor", "currentOption", "patchFor", "tokenCss", "fontFaceCss", "fontLinks", "PAGE_BASE_CSS", "emptyPage", "isPageEmpty", "cleanHtml", "cleanCss", "normalizeBlock", "templatePage", "pageDocument", "projectSections"],
+  "files": ["index.js", "page-builder.jsx", "panels.jsx", "page-view.jsx", "thumbs.jsx", "grapes.js", "theme.js", "tokens.js", "sections.js", "page.js"],
+  "requires": [],
+  "dependencies": {
+    "grapesjs": "0.22.16",
+    "@grapesjs/react": "2.0.0"
+  }
+}