makersclaw 0.2.0 → 0.3.1

package/registry/blocks/diagram/palette.js

@@ -0,0 +1,313 @@
+// The diagram's colours are the workspace's tokens.
+//
+// Mermaid draws with concrete colours and derives shades from them, so it
+// cannot read var(--color-primary). At run time the block reads each token
+// from the page (resolvePalette, the browser half at the bottom), and
+// mermaidTheme turns that palette into Mermaid's `themeVariables`: node
+// fills are soft tints of the primary and the chart hues on the card,
+// lines are muted-foreground, text is the foreground, notes a warning tint,
+// and the pie / git / mind-map colours are the chart hues. No colour value
+// is written in this file: every one comes from the page.
+//
+// Everything but resolvePalette() is a plain function of plain objects,
+// so it runs in node and on the server.
+
+/** The tokens read from the page. */
+export const SLOTS = [
+  "background",
+  "foreground",
+  "card",
+  "card-foreground",
+  "muted",
+  "muted-foreground",
+  "border",
+  "primary",
+  "primary-foreground",
+  "accent",
+  "destructive",
+  "success",
+  "warning",
+  "info",
+  "chart-1",
+  "chart-2",
+  "chart-3",
+  "chart-4",
+  "chart-5",
+];
+
+const HEXISH = /^#?([0-9a-f]{6})([0-9a-f]{2})?$/i;
+
+/** "#rrggbb" → [r, g, b], or null. */
+export function parseHex(value) {
+  const m = HEXISH.exec(String(value ?? "").trim());
+  if (!m) return null;
+  const n = parseInt(m[1], 16);
+  return [(n >> 16) & 255, (n >> 8) & 255, n & 255];
+}
+
+const byte = (n) => Math.max(0, Math.min(255, Math.round(n))).toString(16).padStart(2, "0");
+export const toHex = ([r, g, b]) => "#" + byte(r) + byte(g) + byte(b);
+
+/** `t` of colour a over (1 - t) of colour b, both hex. */
+export function mix(a, b, t) {
+  const x = parseHex(a);
+  const y = parseHex(b);
+  if (!x || !y) return a ?? b ?? null;
+  const k = Math.max(0, Math.min(1, t));
+  return toHex([0, 1, 2].map((i) => x[i] * k + y[i] * (1 - k)));
+}
+
+/** Relative luminance, 0 (black) … 1 (white). */
+export function luminance(hex) {
+  const c = parseHex(hex);
+  if (!c) return 0;
+  const [r, g, b] = c.map((v) => {
+    const s = v / 255;
+    return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+  });
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+
+const contrast = (a, b) => {
+  const [x, y] = [luminance(a), luminance(b)].sort((p, q) => q - p);
+  return (x + 0.05) / (y + 0.05);
+};
+
+/** Of the theme's own ink and paper, whichever reads on `fill`. */
+export function readableOn(fill, palette) {
+  const ink = palette.foreground;
+  const paper = palette.background;
+  if (!ink || !paper) return ink ?? paper;
+  return contrast(fill, ink) >= contrast(fill, paper) ? ink : paper;
+}
+
+/** A stable fingerprint: equal strings, nothing to redraw. */
+export const paletteKey = (p) =>
+  Object.keys(p ?? {})
+    .sort()
+    .map((k) => `${k}=${p[k]}`)
+    .join(";");
+
+/**
+ * Mermaid's `themeVariables` (theme "base") from a palette of hex colours.
+ * An empty palette gives {} — Mermaid's own base look — so a page without
+ * the tokens still draws.
+ */
+export function mermaidTheme(palette, { fontFamily } = {}) {
+  const p = palette ?? {};
+  if (!p.foreground || !p.card) return fontFamily ? { fontFamily } : {};
+  const card = p.card;
+  const fg = p["card-foreground"] ?? p.foreground;
+  const soft = (slot, t = 0.16) => mix(p[slot] ?? p.primary ?? fg, card, t);
+  const edge = (slot, t = 0.6) => mix(p[slot] ?? p.primary ?? fg, card, t);
+  const dark = luminance(card) < 0.4;
+  const hues = ["chart-1", "chart-2", "chart-3", "chart-4", "chart-5"].map((s) => p[s] ?? p.primary ?? fg);
+  const hueAt = (i) => hues[i % hues.length];
+  const softAt = (i) => mix(hueAt(i), card, i < 5 ? 0.22 : 0.4);
+  const out = {
+    darkMode: dark,
+    background: card,
+    fontFamily: fontFamily || undefined,
+    fontSize: "14px",
+    useGradient: false,
+    dropShadow: "none",
+
+    primaryColor: soft("primary"),
+    primaryTextColor: fg,
+    primaryBorderColor: edge("primary"),
+    secondaryColor: soft("chart-2"),
+    secondaryTextColor: fg,
+    secondaryBorderColor: edge("chart-2"),
+    tertiaryColor: p.muted ?? soft("primary", 0.08),
+    tertiaryTextColor: fg,
+    tertiaryBorderColor: p.border ?? edge("primary", 0.3),
+    lineColor: p["muted-foreground"] ?? fg,
+    arrowheadColor: p["muted-foreground"] ?? fg,
+    textColor: fg,
+    titleColor: fg,
+    mainBkg: soft("primary"),
+    nodeBkg: soft("primary"),
+    nodeBorder: edge("primary"),
+    nodeTextColor: fg,
+    clusterBkg: p.muted ?? card,
+    clusterBorder: p.border ?? edge("primary", 0.3),
+    defaultLinkColor: p["muted-foreground"] ?? fg,
+    edgeLabelBackground: card,
+    labelBackgroundColor: card,
+
+    noteBkgColor: soft("warning", 0.16),
+    noteTextColor: fg,
+    noteBorderColor: edge("warning", 0.5),
+
+    // sequence
+    actorBkg: soft("primary"),
+    actorBorder: edge("primary"),
+    actorTextColor: fg,
+    actorLineColor: p["muted-foreground"] ?? fg,
+    signalColor: fg,
+    signalTextColor: fg,
+    labelBoxBkgColor: p.muted ?? card,
+    labelBoxBorderColor: p.border ?? fg,
+    labelTextColor: fg,
+    loopTextColor: fg,
+    activationBkgColor: p.muted ?? card,
+    activationBorderColor: p.border ?? fg,
+    sequenceNumberColor: readableOn(p["muted-foreground"] ?? fg, p),
+
+    // gantt
+    sectionBkgColor: p.muted ?? card,
+    altSectionBkgColor: card,
+    sectionBkgColor2: p.muted ?? card,
+    gridColor: p.border ?? fg,
+    taskBkgColor: soft("primary", 0.3),
+    taskBorderColor: edge("primary"),
+    taskTextColor: fg,
+    taskTextLightColor: fg,
+    taskTextDarkColor: fg,
+    taskTextOutsideColor: fg,
+    taskTextClickableColor: p.primary ?? fg,
+    activeTaskBkgColor: soft("chart-2", 0.3),
+    activeTaskBorderColor: edge("chart-2"),
+    doneTaskBkgColor: p.muted ?? card,
+    doneTaskBorderColor: p.border ?? fg,
+    critBkgColor: soft("destructive", 0.24),
+    critBorderColor: p.destructive ?? fg,
+    todayLineColor: p.destructive ?? fg,
+    vertLineColor: p["muted-foreground"] ?? fg,
+    excludeBkgColor: p.muted ?? card,
+
+    // state, class, er
+    stateBkg: soft("primary"),
+    stateLabelColor: fg,
+    compositeBackground: p.muted ?? card,
+    compositeTitleBackground: p.muted ?? card,
+    compositeBorder: p.border ?? fg,
+    altBackground: p.muted ?? card,
+    innerEndBackground: fg,
+    specialStateColor: fg,
+    transitionColor: p["muted-foreground"] ?? fg,
+    transitionLabelColor: fg,
+    classText: fg,
+    rowOdd: card,
+    rowEven: p.muted ?? card,
+    relationColor: p["muted-foreground"] ?? fg,
+    relationLabelBackground: card,
+    relationLabelColor: fg,
+    requirementBackground: soft("primary"),
+    requirementBorderColor: edge("primary"),
+    requirementTextColor: fg,
+
+    errorBkgColor: soft("destructive", 0.2),
+    errorTextColor: p.destructive ?? fg,
+
+    // pie
+    pieTitleTextColor: fg,
+    pieSectionTextColor: readableOn(hueAt(1), p),
+    pieLegendTextColor: fg,
+    pieStrokeColor: card,
+    pieOuterStrokeColor: p.border ?? card,
+    pieOpacity: "1",
+
+    // quadrant
+    quadrant1Fill: softAt(0),
+    quadrant2Fill: softAt(1),
+    quadrant3Fill: softAt(2),
+    quadrant4Fill: softAt(3),
+    quadrant1TextFill: fg,
+    quadrant2TextFill: fg,
+    quadrant3TextFill: fg,
+    quadrant4TextFill: fg,
+    quadrantPointFill: p.primary ?? fg,
+    quadrantPointTextFill: fg,
+    quadrantXAxisTextFill: fg,
+    quadrantYAxisTextFill: fg,
+    quadrantTitleFill: fg,
+    quadrantInternalBorderStrokeFill: p.border ?? fg,
+    quadrantExternalBorderStrokeFill: p.border ?? fg,
+
+    // xy chart
+    xyChart: {
+      backgroundColor: card,
+      titleColor: fg,
+      xAxisLabelColor: fg,
+      xAxisTitleColor: fg,
+      xAxisTickColor: p["muted-foreground"] ?? fg,
+      xAxisLineColor: p.border ?? fg,
+      yAxisLabelColor: fg,
+      yAxisTitleColor: fg,
+      yAxisTickColor: p["muted-foreground"] ?? fg,
+      yAxisLineColor: p.border ?? fg,
+      plotColorPalette: hues.join(","),
+    },
+    scaleLabelColor: fg,
+    commitLabelColor: fg,
+    commitLabelBackground: p.muted ?? card,
+    tagLabelColor: fg,
+    tagLabelBackground: p.muted ?? card,
+    tagLabelBorder: p.border ?? fg,
+  };
+  for (let i = 0; i < 12; i++) {
+    out[`pie${i + 1}`] = i < 5 ? hueAt(i) : mix(hueAt(i), card, 0.55);
+    out[`cScale${i}`] = softAt(i);
+    out[`cScaleLabel${i}`] = fg;
+  }
+  for (let i = 0; i < 8; i++) {
+    out[`git${i}`] = hueAt(i);
+    out[`gitInv${i}`] = readableOn(hueAt(i), p);
+    out[`gitBranchLabel${i}`] = readableOn(hueAt(i), p);
+  }
+  for (let i = 0; i < 8; i++) out[`fillType${i}`] = softAt(i);
+  return out;
+}
+
+// ---- the browser half -------------------------------------------------------
+
+/** Read every slot from the CSS variables in effect at `el` (so a theme
+ *  scoped to an ancestor counts). A probe takes `color: var(--color-…)`;
+ *  the browser resolves var(), light-dark(), mixes and relative colours
+ *  into its computed colour, and a 1×1 canvas turns that into bytes
+ *  whatever syntax it came back in. */
+export function resolvePalette(el) {
+  if (typeof document === "undefined" || !el) return {};
+  const probe = document.createElement("span");
+  probe.setAttribute("aria-hidden", "true");
+  probe.style.position = "absolute";
+  probe.style.visibility = "hidden";
+  probe.style.pointerEvents = "none";
+  el.appendChild(probe);
+  const canvas = document.createElement("canvas");
+  canvas.width = 1;
+  canvas.height = 1;
+  const ctx = canvas.getContext?.("2d", { willReadFrequently: true });
+  const out = {};
+  // The card first: a see-through token (the border is 15% ink) is laid
+  // over it, so what Mermaid gets is the colour as it looks on the card.
+  const order = ["card", ...SLOTS.filter((s) => s !== "card")];
+  try {
+    for (const slot of order) {
+      probe.style.color = "";
+      probe.style.color = `var(--color-${slot})`;
+      const computed = getComputedStyle(probe).color;
+      if (!computed) continue;
+      if (!ctx) {
+        const hex = parseHex(computed);
+        if (hex) out[slot] = toHex(hex);
+        continue;
+      }
+      ctx.clearRect(0, 0, 1, 1);
+      if (out.card) {
+        ctx.fillStyle = out.card;
+        ctx.fillRect(0, 0, 1, 1);
+      }
+      ctx.fillStyle = "transparent";
+      ctx.fillStyle = computed;
+      ctx.fillRect(0, 0, 1, 1);
+      const [r, g, b, a] = ctx.getImageData(0, 0, 1, 1).data;
+      if (a === 0) continue;
+      out[slot] = toHex([r, g, b]);
+    }
+  } finally {
+    probe.remove();
+  }
+  return out;
+}

package/registry/blocks/diagram/source.js

@@ -0,0 +1,98 @@
+// Reading Mermaid text: what kind of diagram it is, and what went wrong.
+// Plain functions of strings, so they run in node and on the server.
+
+const KINDS = [
+  [/^flowchart\b|^graph\b/, "Flowchart"],
+  [/^sequenceDiagram\b/, "Sequence diagram"],
+  [/^classDiagram(?:-v2)?\b/, "Class diagram"],
+  [/^stateDiagram(?:-v2)?\b/, "State diagram"],
+  [/^erDiagram\b/, "Entity relationships"],
+  [/^journey\b/, "User journey"],
+  [/^gantt\b/, "Gantt chart"],
+  [/^pie\b/, "Pie chart"],
+  [/^quadrantChart\b/, "Quadrant chart"],
+  [/^requirementDiagram\b/, "Requirements"],
+  [/^gitGraph\b/, "Git graph"],
+  [/^mindmap\b/, "Mind map"],
+  [/^timeline\b/, "Timeline"],
+  [/^sankey(?:-beta)?\b/, "Sankey diagram"],
+  [/^xychart(?:-beta)?\b/, "XY chart"],
+  [/^block(?:-beta)?\b/, "Block diagram"],
+  [/^packet(?:-beta)?\b/, "Packet diagram"],
+  [/^kanban\b/, "Kanban"],
+  [/^architecture(?:-beta)?\b/, "Architecture"],
+  [/^radar(?:-beta)?\b/, "Radar chart"],
+  [/^C4\w*/, "C4 diagram"],
+];
+
+/** The first line that says something: past blank lines, %% comments and
+ *  a --- front-matter block. */
+export function firstStatement(source) {
+  const lines = String(source ?? "").split("\n");
+  let i = 0;
+  if (lines[0]?.trim() === "---") {
+    i = 1;
+    while (i < lines.length && lines[i].trim() !== "---") i++;
+    i++;
+  }
+  for (; i < lines.length; i++) {
+    const t = lines[i].trim();
+    if (t && !t.startsWith("%%")) return { line: i + 1, text: t };
+  }
+  return null;
+}
+
+/** "Flowchart", "Sequence diagram"… or null when the text names no kind. */
+export function diagramKind(source) {
+  const first = firstStatement(source);
+  if (!first) return null;
+  for (const [re, name] of KINDS) if (re.test(first.text)) return name;
+  return null;
+}
+
+/** The diagram's own title (`title …` in front matter or a line), or null. */
+export function diagramTitle(source) {
+  const m = /^\s*(?:title\s*:?\s*)(.+)$/m.exec(String(source ?? ""));
+  return m ? m[1].trim().replace(/^["']|["']$/g, "") : null;
+}
+
+/**
+ * What a Mermaid error means, for people: { line, message, detail }.
+ * `line` is 1-based in the source, or null when Mermaid did not say.
+ * `message` is ours ("Line 3 has a mistake"), `detail` Mermaid's own
+ * words, trimmed of the ASCII art pointer.
+ */
+export function describeError(error, source) {
+  const raw = String(error?.message ?? error?.str ?? error ?? "").trim();
+  const hash = error?.hash;
+  let line = null;
+  if (Number.isFinite(hash?.loc?.first_line)) line = hash.loc.first_line;
+  else if (Number.isFinite(hash?.line)) line = hash.line + 1;
+  else {
+    const m = /\bline[:\s]+(\d+)/i.exec(raw);
+    if (m) line = Number(m[1]);
+  }
+  const lines = String(source ?? "").split("\n");
+  if (line != null) line = Math.max(1, Math.min(lines.length, line));
+
+  if (!firstStatement(source)) return { line: null, message: "There is no diagram here yet", detail: "Start with a type on the first line: flowchart LR, sequenceDiagram, gantt, pie…" };
+  if (/No diagram type detected|UnknownDiagramError/i.test(raw) || (!diagramKind(source) && !line)) {
+    const first = firstStatement(source);
+    return {
+      line: first.line,
+      message: "The first line should name the diagram type",
+      detail: `"${first.text.slice(0, 40)}" is not one Mermaid knows. Try flowchart LR, sequenceDiagram, classDiagram, stateDiagram-v2, erDiagram, gantt, pie, mindmap or timeline.`,
+    };
+  }
+  const detail = raw
+    .split("\n")
+    .filter((l) => !/^\s*-*\^\s*$/.test(l) && !/^\.\.\./.test(l.trim()))
+    .filter((l) => !/^Parse error on line \d+:?$/i.test(l.trim()))
+    .join(" ")
+    .replace(/\s+/g, " ")
+    .replace(/^Error:\s*/, "")
+    .replace(/^Parsing failed:\s*/, "")
+    .replace(/ at offset: \d+, skipped \d+ characters?\./g, ".")
+    .trim();
+  return { line, message: line ? `Line ${line} has a mistake` : "Mermaid could not read this diagram", detail: detail || null };
+}

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

@@ -0,0 +1,215 @@
+# DocEditor
+
+A Notion-style rich-text editor in the workspace theme. Type `/` for a
+block (headings, lists, checklists, quotes, code, tables, images,
+dividers), or use markdown shortcuts (`#`, `-`, `1.`, `[]`, `>`). Select
+text for the formatting toolbar; hover a block for its drag handle. `@`
+mentions a person, `{` inserts a merge field; both sit in the text as
+chips. In `minimal` mode it is a comment box: no side menu, no `/` menu,
+and Cmd/Ctrl+Enter submits.
+
+It is [BlockNote](https://www.blocknotejs.org) (MPL-2.0) underneath, with
+its colours, face and radius mapped onto the workspace's tokens. The
+other text blocks — `doc-page`, `comment-box`, `record-notes`,
+`email-composer`, `meeting-notes`, `brief-doc`, `knowledge-base` — are
+built on this one: they import it, never `@blocknote/*`.
+
+```jsx
+import { DocEditor, docToMarkdown } from "../components/blocks/doc-editor";   // a Makersclaw app ("./blocks/doc-editor" from components/)
+import { DocEditor, docToMarkdown } from "@/components/makersclaw/blocks/doc-editor";   // a shadcn project
+```
+
+`DocEditor` is a client component: render it from a `"use client"`
+component. The helpers (`docToMarkdown`, `docToText`, `docChecklist`…) are
+plain functions and work on the server too.
+
+`makersclaw add doc-editor` adds `@blocknote/core`, `@blocknote/react` and
+`@blocknote/shadcn` (pinned, exact) to package.json: run `npm install`
+after. It loads with the page (no `import()`): the editor is created
+after the first render, and until then — on the server — the box shows
+the doc's words as plain text.
+
+## The data
+
+The document is BlockNote's JSON: an array of blocks. Store it as it
+comes out of `onChange` (a `jsonb` column).
+
+```js
+[
+  { id: "…", type: "heading", props: { level: 2 }, content: [{ type: "text", text: "Launch", styles: {} }], children: [] },
+  { id: "…", type: "paragraph", content: [
+      { type: "text", text: "Hi ", styles: {} },
+      { type: "field", props: { key: "first_name", label: "First name" } },
+      { type: "text", text: ", ", styles: {} },
+      { type: "mention", props: { id: "u-42", label: "Priya Raman" } },
+      { type: "text", text: " will call.", styles: { bold: true } },
+  ], children: [] },
+  { id: "…", type: "checkListItem", props: { checked: false }, content: [{ type: "text", text: "Send the deck", styles: {} }], children: [] },
+]
+```
+
+- Block types: `paragraph`, `heading` (`props.level` 1–3), `bulletListItem`,
+  `numberedListItem`, `checkListItem` (`props.checked`), `toggleListItem`,
+  `quote`, `codeBlock` (`props.language`), `table`, `image` (`props.url`,
+  `caption`), `divider`. Blocks nest through `children`.
+- Inline content: `text` (`styles`: `bold`, `italic`, `underline`,
+  `strike`, `code`), `link` (`href`, `content`), and two of ours:
+  - `{ type: "mention", props: { id, label } }` — a person, drawn `@Label`.
+  - `{ type: "field", props: { key, label } }` — a merge field, drawn as a
+    chip with its label, written out as `{key}` or its value.
+- When you write a doc by hand (a starter doc, a template), ids, `props`
+  and `children` may be left out and `content` may be a string:
+  `[{ type: "paragraph", content: "Hello" }]`. The editor gives blocks
+  ids on the first edit; give them ids yourself when something reads
+  them before that (`setChecklistItem` on a starter checklist).
+
+## Props
+
+- `value` — the doc, controlled. A new `value` that differs from what the
+  editor last sent through `onChange` replaces the document (loading
+  another record). Pass back exactly what `onChange` gave you and nothing
+  resets.
+- `defaultValue` — the starting doc, uncontrolled. With neither, the doc
+  starts empty.
+- `onChange(doc)` — every edit, with the whole doc. Debounce a save
+  yourself (doc-page does).
+- `editable` — `true` (default). `false` shows the doc read-only: no
+  caret, no menus.
+- `placeholder` — shown while the doc is empty (and on the server while
+  it is).
+- `minimal` — `false` (default). `true` for a comment box: no side menu
+  (drag handles, +), no `/` menu, no emoji picker, smaller text, no
+  padding of its own. Mentions, fields and the formatting toolbar still
+  work.
+- `compact` — `false` (default). `true` keeps the full editor (menus,
+  handles) in a short box: 4rem at least instead of 10rem. For a doc cut
+  into many small sections (brief-doc).
+- `autoFocus` — put the caret in it when it mounts.
+- `onSubmit(doc)` — called on Cmd/Ctrl+Enter (and not passed to the
+  editor). Post a comment, send a reply. Clear the box yourself through
+  the handle (below).
+- `onKeyDown(event)` — every other key, before the editor sees it
+  (`event.preventDefault()` stops it).
+- `mentions` — `async (query) => [{ id, label, description? }]`: turns on
+  `@`. Called as the person types after `@` (`query` is the text after
+  it, `""` at first); return at most 20. A throw shows nothing. The chosen
+  person goes in as a mention chip.
+- `fields` — `[{ key, label }]`: turns on merge fields. `{` opens a menu of
+  them, filtered as you type; the `/` menu lists them under "Fields".
+  Each goes in as a field chip showing its label.
+- `slashItems` — more entries for the `/` menu: `[{ title, onSelect(handle),
+  subtext?, aliases?, group?, icon? }]`. `onSelect` gets the handle
+  (below); `group` puts it under a heading ("Other" when left out);
+  `icon` is a kit icon name. BlockNote's own entries come first.
+- `uploadFile` — `async (file) => url`: lets an image block upload a
+  file (without it, an image is added by URL).
+- `editorRef` — a ref (`useDocEditor()`) that receives the handle.
+- `label` — the accessible name of the editing area ("Meeting notes").
+- `className` — layout around it (width, margin, min-height). Never colour.
+
+The handle (`editorRef.current`, and what a slash item's `onSelect` gets):
+
+- `focus()` · `clear()` · `isEmpty()` · `getDoc()` · `setDoc(doc)`
+- `insertText(text)` · `insertField(key, label?)` · `insertMention({ id, label })`
+  — at the caret.
+- `editor` — the BlockNote editor itself, for anything else
+  (`editor.insertBlocks(…)`, `editor.getTextCursorPosition()`). Reaching
+  for it ties you to BlockNote's API; prefer the methods above.
+
+The helpers (import them from the block; they take a doc and never throw
+on a partial one):
+
+- `emptyDoc()` — `[{ type: "paragraph", content: [] }]`.
+- `isDocEmpty(doc)` — no text, chip or non-paragraph block. Use it to
+  disable Post.
+- `docToText(doc, { fields? })` — plain text: one line per block (an empty
+  paragraph is an empty line), children indented, list markers kept
+  (`- `, `1. `, `[ ] `/`[x] `), a mention as `@Label`, a field as its value
+  or `{key}`. `fields` is `{ key: value }` or `(key, props) => value`; an
+  empty value leaves `{key}` in place.
+- `docToMarkdown(doc, { fields? })` — GitHub markdown: headings, nested
+  lists, `- [ ]` checklists, quotes, fenced code, tables, images, dividers,
+  bold/italic/strike/code, links; mentions and fields as in `docToText`.
+  Lossy where markdown has no word: underline, colours, alignment.
+- `docChecklist(doc)` — `[{ id, text, checked, depth, mentions: [{ id,
+  label }] }]`, every checklist item in order, nested ones too. Read an
+  owner off its mentions.
+- `setChecklistItem(doc, id, checked)` — a new doc with that item ticked
+  or not (for a side list of action items).
+- `docFields(doc)` — `[{ key, label, count }]`, the merge fields the doc
+  uses, in order of first use. Compare with a recipient's values to warn
+  of a missing one.
+- `docMentions(doc)` — `[{ id, label, count }]`, the people it mentions.
+
+## Example
+
+```jsx
+// components/DealNotes.jsx — client
+"use client";
+import { useState } from "react";
+import { updateRow } from "../lib/actions";
+import { DocEditor } from "./blocks/doc-editor";
+
+export default function DealNotes({ deal, team }) {
+  const [doc, setDoc] = useState(deal.notes);   // jsonb, may be null
+  return (
+    <DocEditor
+      value={doc}
+      onChange={(d) => {
+        setDoc(d);
+        updateRow({ source: "public.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…"
+      label="Deal notes"
+    />
+  );
+}
+```
+
+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) } });
+  if (res.ok) box.current?.clear();
+};
+
+<DocEditor minimal editorRef={box} onSubmit={post} mentions={findPeople} placeholder="Write a comment…" />
+```
+
+An email body with merge fields, filled per recipient:
+
+```jsx
+const FIELDS = [{ key: "first_name", label: "First name" }, { key: "company", label: "Company" }];
+
+<DocEditor value={body} onChange={setBody} fields={FIELDS} />
+const text = docToText(body, { fields: contact });                        // "Hi Ana, …"
+const missing = docFields(body).filter((f) => !contact[f.key]);          // warn before sending
+```
+
+## What it will not do
+
+- Collaborate live (several carets at once): that is BlockNote's Yjs
+  mode, not wired here. Saves are last-write-wins.
+- Export to PDF or Word, multi-column layouts or AI writing: those are
+  BlockNote's `xl-` packages (GPL / commercial), which never come here.
+- Colour text: the toolbar has no colour picker (the theme has no red or
+  purple to offer). Coloured text pasted in is shown in status and chart
+  tokens.
+- Upload files, audio or video: an image by URL, or through your
+  `uploadFile`.
+- Render on the server as rich text: the server shows the plain text
+  (`docToText`) until the editor mounts. For a read-only page that must
+  be rich in the HTML, render `docToMarkdown` yourself.
+
+An editor it cannot be is your own component in `components/` — not an
+edit to this block. Its files are fixed: `npm run check` refuses a change,
+and `makersclaw add doc-editor` restores them.
+
+## Credits
+
+BlockNote (https://github.com/TypeCellOS/BlockNote), MPL-2.0 — installed
+from npm as a dependency, not copied here. See THIRD-PARTY-NOTICES.md.

package/registry/blocks/doc-editor/block.json

@@ -0,0 +1,15 @@
+{
+  "name": "doc-editor",
+  "title": "DocEditor",
+  "description": "A Notion-style rich-text editor (BlockNote) painted in the workspace theme: headings, lists, checklists, quotes, code, tables, images and dividers from a / menu or markdown shortcuts, a formatting toolbar, drag handles; @mentions and {merge fields} as inline chips; a minimal mode for comment boxes with Cmd/Ctrl+Enter to submit. The document is BlockNote JSON; helpers turn it into markdown or plain text and read its checklist, fields and mentions.",
+  "useWhen": "A screen edits rich text: a wiki or doc page, notes on a record, a brief, meeting notes, an email body with merge fields, a comment field with mentions. The other text blocks (doc-page, record-notes, comment-box…) are built on it. Not for one line of plain text (the kit's Input) or a form of fields (record-form).",
+  "tags": ["editor", "rich text", "document", "notion", "blocknote", "markdown", "notes", "wiki", "mention", "merge field", "slash", "comment", "checklist", "wysiwyg"],
+  "exports": ["DocEditor", "useDocEditor", "docToMarkdown", "docToText", "emptyDoc", "isDocEmpty", "docChecklist", "setChecklistItem", "docFields", "docMentions"],
+  "files": ["index.js", "doc-editor.jsx", "schema.jsx", "theme.js", "doc.js", "shadcn-classes.js"],
+  "requires": [],
+  "dependencies": {
+    "@blocknote/core": "0.55.0",
+    "@blocknote/react": "0.55.0",
+    "@blocknote/shadcn": "0.55.0"
+  }
+}