makersclaw 0.7.0 → 0.8.1

package/registry/blocks/library-shelf/library-shelf.jsx

@@ -0,0 +1,211 @@
+"use client";
+
+// A shelf of starting points from the Library, in named columns, each
+// with a Use (the app kit, D15; grown in the CRM, 0.7.0). Two ways in:
+// `sections` you shaped, or `library` — what useLibraryItems() returns
+// (lib/hooks.js) — with `onUse(item)`, which draws one column of the
+// collection's items, each with its cover, and the hook's paging, preview
+// and "not connected yet". Props in, callbacks out; the block never reads
+// the Library itself. Tokens only.
+
+import { useState } from "react";
+import { Button, Icon, Image, Skeleton, cx } from "../../ui";
+
+/** A Library item's format, as a word and a glyph. */
+const FORMATS = {
+  pdf: { word: "PDF", icon: "file" },
+  image: { word: "Picture", icon: "image" },
+  html: { word: "Web page", icon: "globe" },
+  slides: { word: "Slides", icon: "layers" },
+  document: { word: "Document", icon: "file" },
+  sheet: { word: "Sheet", icon: "table" },
+  archive: { word: "Archive", icon: "archive" },
+};
+
+/** Library items (useLibraryItems' `items`) as shelf items. */
+export function libraryShelfItems(items, { onUse, useLabel, once } = {}) {
+  return (items ?? []).filter(Boolean).map((item) => {
+    const f = FORMATS[item.format] ?? { word: null, icon: "file" };
+    return {
+      id: item.id,
+      label: item.title ?? "Untitled",
+      meta: item.locked ? "Paid plan" : f.word,
+      mark: item.preview_url ? (
+        <Image src={item.preview_url} alt="" ratio="square" rounded="sm" className="size-7 shrink-0" />
+      ) : (
+        <Icon name={f.icon} size={14} className="shrink-0 text-muted-foreground" />
+      ),
+      locked: Boolean(item.locked),
+      onUse: onUse && !item.locked ? () => onUse(item) : undefined,
+      useLabel,
+      once,
+    };
+  });
+}
+
+function ShelfItem({ item }) {
+  const [state, setState] = useState(item.used ? "used" : "idle");
+  const [error, setError] = useState(null);
+  async function use() {
+    if (!item.onUse || state === "busy") return;
+    setState("busy");
+    setError(null);
+    let r;
+    try {
+      r = await item.onUse();
+    } catch (e) {
+      r = { ok: false, error: e?.message ?? String(e) };
+    }
+    if (r && r.ok === false) {
+      setState("idle");
+      setError(r.error || "Couldn't use it. Try again.");
+      return;
+    }
+    setState(item.once === false ? "idle" : "used");
+  }
+  const used = state === "used" || item.used;
+  return (
+    <li className="grid grid-cols-1 min-w-0 gap-0.5 border-b border-border py-1 last:border-b-0" data-shelf-item>
+      <div className="flex min-h-[30px] min-w-0 items-center gap-2">
+        {item.mark ?? null}
+        {/* The meta gives way, to an ellipsis, before the label does. It was
+            shrink-0, and a long meta ran the label down to nothing (UI
+            review X3). Neither may be wider than the row. */}
+        <span className="min-w-0 truncate" title={typeof item.label === "string" ? item.label : undefined} data-shelf-label>
+          {item.label}
+        </span>
+        {item.meta ? (
+          <span className="min-w-0 shrink-[4] truncate text-xs text-muted-foreground" title={typeof item.meta === "string" ? item.meta : undefined}>
+            {item.meta}
+          </span>
+        ) : null}
+        <span className="ml-auto shrink-0">
+          {item.locked ? (
+            <Icon name="lock" size={12} className="text-muted-foreground" label="Comes with a paid plan" />
+          ) : used ? (
+            <span className="inline-flex items-center gap-1 text-xs text-success">
+              <Icon name="check" size={12} />
+              {item.usedLabel ?? "Used"}
+            </span>
+          ) : item.onUse ? (
+            <Button size="sm" variant="quiet" loading={state === "busy"} onClick={use} aria-label={`${item.useLabel ?? "Use"}: ${typeof item.label === "string" ? item.label : "this"}`}>
+              {item.useLabel ?? "Use"}
+            </Button>
+          ) : null}
+        </span>
+      </div>
+      {item.description ? <p className="m-0 min-w-0 break-words pb-1 text-xs text-muted-foreground">{item.description}</p> : null}
+      {error ? (
+        <p role="alert" className="pb-1 text-xs text-destructive">
+          {error}
+        </p>
+      ) : null}
+    </li>
+  );
+}
+
+/** What a library read says under its items: loading, more, a preview, refusals. */
+function LibraryFoot({ library, count }) {
+  const l = library ?? {};
+  if (l.unavailable) return <p className="text-[13px] text-muted-foreground">The Library is not connected yet.</p>;
+  if (l.error) return <p role="alert" className="text-[13px] text-destructive">{l.error}</p>;
+  const hidden = l.previewOnly && typeof l.total === "number" ? l.total - count : 0;
+  return (
+    <>
+      {hidden > 0 ? (
+        <p className="flex items-center gap-1.5 text-[13px] text-muted-foreground">
+          <Icon name="lock" size={12} className="shrink-0" />
+          {hidden} more come with a paid plan.
+        </p>
+      ) : null}
+      {l.hasMore && l.loadMore ? (
+        <Button size="sm" variant="quiet" className="justify-self-start" loading={l.loadingMore} onClick={() => l.loadMore()}>
+          Show more
+        </Button>
+      ) : null}
+    </>
+  );
+}
+
+/**
+ * The shelf.
+ *
+ *   title     "Start from a template"
+ *   source    "CRM starting points, from the Library"
+ *   icon      a kit Icon name before the title (default "layers")
+ *   sections  [{ key, title, items: [{ id, label, meta?, description?, mark?, onUse?, useLabel?,
+ *              used?, usedLabel?, once?, locked? }] }]
+ *            meta is ONE short fact ("6 stages", "PDF"); it truncates, and
+ *            so does the label, so no row is ever wider than its box. A
+ *            sentence is a `description`: it sits under the label and wraps.
+ *
+ * Or straight from the Library:
+ *
+ *   library       what useLibraryItems(id) returns ({ items, total,
+ *                 previewOnly, hasMore, loadMore, loading, loadingMore,
+ *                 error, unavailable })
+ *   onUse(item)   async → { ok } | { ok: false, error }: what Use does
+ *                 with a Library item (ask the agent to copy it in, open
+ *                 it as a draft); a locked item has no Use
+ *   sectionTitle  the column's title (default none)
+ *   useLabel      default "Use"; once — false: an item can be used again
+ *   empty         the line when the collection has nothing
+ */
+export function LibraryShelf({
+  title = "Start from a template",
+  source,
+  icon = "layers",
+  sections: given,
+  library,
+  onUse,
+  sectionTitle,
+  useLabel,
+  once,
+  empty = "Nothing on this shelf yet.",
+  className,
+}) {
+  const fromLibrary = !given && Boolean(library);
+  const libItems = fromLibrary ? libraryShelfItems(library.items, { onUse, useLabel, once }) : [];
+  const sections = given ?? (fromLibrary && libItems.length ? [{ key: "library", title: sectionTitle, items: libItems }] : []);
+  const loading = fromLibrary && library.loading && !libItems.length;
+  return (
+    <section data-library-shelf aria-label={title} className={cx("grid grid-cols-1 min-w-0 gap-3", className)}>
+      <div className="flex flex-wrap items-center gap-2 text-[13px]">
+        <Icon name={icon} size={16} className="text-muted-foreground" />
+        <b className="font-semibold">{title}</b>
+        {source ? <span className="text-muted-foreground">· {source}</span> : null}
+      </div>
+      {loading ? (
+        <div aria-busy="true" aria-label="Loading" className="grid grid-cols-1 gap-2 rounded-[var(--radius)] border border-border px-3.5 py-3">
+          <Skeleton className="w-2/3" />
+          <Skeleton className="w-1/2" />
+          <Skeleton className="w-3/5" />
+        </div>
+      ) : fromLibrary && !libItems.length && !library.unavailable && !library.error ? (
+        <p className="text-[13px] text-muted-foreground">{empty}</p>
+      ) : null}
+      {sections.length ? (
+      <>
+      {/* Side by side by the shelf's own width, not the window's: an app on
+          the desk is often 800px with a rail beside it, where three columns
+          cut every name to its first letter (CRM 0.7.1). */}
+      <div className="@container min-w-0">
+      <div className="grid grid-cols-1 min-w-0 rounded-[var(--radius)] border border-border @3xl:grid-cols-[repeat(auto-fit,minmax(14rem,1fr))]">
+        {sections.map((s) => (
+          <div key={s.key ?? s.title} className="grid grid-cols-1 min-w-0 content-start gap-0.5 border-b border-border px-3.5 py-3 last:border-b-0 @3xl:border-b-0 @3xl:border-r @3xl:last:border-r-0">
+            {s.title ? <h3 className="text-xs font-semibold text-muted-foreground">{s.title}</h3> : null}
+            <ul className="m-0 grid grid-cols-1 list-none p-0 text-[13px]">
+              {s.items.map((it) => (
+                <ShelfItem key={it.id} item={it} />
+              ))}
+            </ul>
+          </div>
+        ))}
+      </div>
+      </div>
+      </>
+      ) : null}
+      {fromLibrary ? <LibraryFoot library={library} count={libItems.length} /> : null}
+    </section>
+  );
+}

package/registry/blocks/library-shelf/probe-rules.js

@@ -0,0 +1,15 @@
+// The layout rules this block ships for the store's probe (makersclaw-store
+// scripts/probe.mjs --suite); see top-bar/probe-rules.js. Nothing imports this.
+export default {
+  block: "library-shelf",
+  rules: [
+    {
+      id: "label-never-cut-to-nothing",
+      kind: "visible-text",
+      note: "UI review X3: the meta ran the label down to a letter",
+      scope: "[data-library-shelf]",
+      target: "[data-shelf-label], li > div > span.truncate:not(.text-xs)",
+      min: 3,
+    },
+  ],
+};

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

@@ -0,0 +1,222 @@
+# MarginNotes
+
+Passages of text with notes in the margin, **level with the words they are
+about**. On a wide container each passage is a row: the words on one side,
+its notes on the other. On a narrow one (under about 42rem) the notes stack
+under the passage they belong to.
+
+A note is one of four kinds, each with its own tone and its own buttons:
+
+- **source** — where the words came from: a title, a line of detail, the
+  words that were read, a link.
+- **flag** — "No source. Check this line." with **It's true**, **Cut it**,
+  **Ask where it came from**.
+- **cut** — the words struck through where they stand, the reason in the
+  margin, **Put back** (or a lock when nobody may put them back).
+- **comment** — what someone thought of the line.
+
+An app can change any of them or add its own kind.
+
+The words a note is about (`quote`) are marked in the passage: dotted for a
+source, wavy for a flag, struck for a cut, washed for a comment. **The
+selected note and its passage are linked**: click a passage or a note, or
+press <kbd>J</kbd> and <kbd>K</kbd> to walk the notes that still need a
+person. A settled note folds to one line with what was decided and a
+**Reopen**.
+
+```jsx
+import { MarginNotes } from "../components/blocks/margin-notes";   // a Makersclaw app ("./blocks/margin-notes" from components/)
+import { MarginNotes } from "@/components/makersclaw/blocks/margin-notes";   // a shadcn project
+```
+
+A client component. `makersclaw add margin-notes` lays `agent-marks` with
+it. The helpers (`walkNext`, `inlineMarks`, `countNotes`…) are plain
+functions and work on the server.
+
+## Which hook feeds it
+
+None. The passages are the app's words (a draft, a transcript); the notes are
+rows the agent or a person wrote beside them. Keep them in the app's tables
+and pass them in. The block never reads or writes: a press goes out through
+`onAction`, the app does the write, and hands back the changed notes.
+
+## Props
+
+- `passages` — the words, in reading order: `[{ id, text, lead?, label?,
+  level?, node? }]`. `text` is plain words. `lead` is a short figure before
+  them (a time `00:12`, a number); `label` a name above them (a speaker, a
+  section); `level` `2` · `3` · `4` draws the passage as a heading. `node`
+  (a React node) draws your own markup instead of `text`: a note's `quote`
+  cannot mark inside it (the card shows the quote instead), but a cut still
+  strikes it whole.
+- `notes` — `[{ id, passage, kind, … }]`. `passage` is the id of the
+  passage it sits by; a note whose passage is not in the list is drawn
+  after the last row under `orphanTitle`. The rest:
+  - `kind` — `source` · `flag` · `cut` · `comment`, or one of your `kinds`.
+  - `title` — the note's heading ("v3.0.0", "No source. Check this line.").
+  - `meta` — a muted line under it ("tern-app/tern · shipped Tue 22 Sep").
+  - `text` — the note's words (a reason, a comment).
+  - `detail` — the proof: the words that were read, under a dashed rule.
+  - `quote` — the words **in the passage** the note is about. The first
+    place they appear (ignoring case) is marked. Without one a `cut` strikes
+    the whole passage; the other kinds mark nothing in the words.
+  - `by` — `"agent"` or `{ agent: true }` draws the agent's mark; any other
+    string or `{ name }` is shown as a name.
+  - `at` — when, in words ("12:31", "Tue 22 Sep").
+  - `href`, `hrefLabel` — "Open the source" (default) as a link that opens
+    in a new tab.
+  - `locked` — words for why nothing can be done to this note ("On the
+    never-list: margins"). A locked note shows a lock and no buttons.
+  - `state` — `"settled"` folds the note to a line: `answer` ("You said
+    it's true") and `at`, and the kind's **Reopen** if it has one. Settled
+    notes mark nothing in the words and are skipped by <kbd>J</kbd> and
+    <kbd>K</kbd>.
+  - `actions` — `[{ id, label, variant?, icon? }]`, replacing the kind's
+    buttons for this note.
+  - `label`, `tone`, `hue`, `mark` — this note's chip words, status tone
+    (`neutral` · `primary` · `info` · `success` · `warning` · `danger`),
+    categorical colour `1`–`5` (for a family of cuts: pricing, other people,
+    in confidence, length), and mark (`underline` · `wavy` · `strike` ·
+    `highlight` · `none`) over the kind's.
+- `selected`, `defaultSelected`, `onSelect(id | null)` — the selected
+  note's id. Pass `selected` to control it (from the address, say); leave it
+  out and the block keeps it. <kbd>Esc</kbd> clears it.
+- `onAction(note, actionId)` — `async`, returns `{ ok: true }` or
+  `{ ok: false, error? }`. Called when a button is pressed; the button shows
+  its spinner until it answers, and a failure prints its `error` under the
+  note, where it happened. A throw counts as a failure. A settled note's
+  Reopen calls it with `"reopen"`. **Without `onAction` no buttons are
+  drawn.**
+- `kinds` — changes to the built-ins, or new kinds, by id: `{ flag: {
+  label: "Check" }, aside: { label: "Aside", tone: "primary", icon:
+  "message-circle", mark: "highlight", actions: [] } }`. Fields are `label`,
+  `icon` (a kit icon), `tone`, `mark`, `actions`, and `reopen` (`false`, or
+  `{ label }`). Each field you give replaces that one field.
+- `side` — `right` (default) or `left`: which side of the words the margin
+  is on. Narrow, the notes are always under the words.
+- `marginWidth` — `sm` (15rem) · `md` (18rem, default) · `lg` (22rem).
+- `marginTitle` — a heading over the whole thing ("Where each paragraph
+  came from"), with the count line beside it.
+- `showNotes` — `false` hides the margin and its marks: the words alone.
+- `textSize` — `sm` · `md` (default) · `lg`.
+- `status` — `ready` (default) · `loading` (rows of grey bars) · `failed`
+  (a notice with `error`, and Try again if you pass `onRetry`).
+- `readOnly` — notes to read: no buttons, no Reopen.
+- `keys` — <kbd>J</kbd> and <kbd>K</kbd> walk the notes (default `true`).
+- `noNotes`, `orphanTitle`, `emptyTitle`, `emptyBody`, `countLabels` — the
+  block's few words, to be changed (`countLabels`: `{ open, settled }`).
+- `label` — the region's accessible name.
+- `className` — layout: width, margin, height. Never colour.
+
+### Keys
+
+On the region (it takes focus with Tab): <kbd>J</kbd> the next note that
+still needs a person, <kbd>K</kbd> the one before, <kbd>Esc</kbd> clears the
+selection. On a passage with notes: <kbd>Enter</kbd> or <kbd>Space</kbd>
+selects its first note, again its next, after the last none. The walk moves
+focus to the note, scrolls it into view (without animation when the person
+has asked for less motion) and a hidden line says "Note 2 of 5". The keys
+are left alone while someone is typing in a field.
+
+### Helpers
+
+Plain functions (`import` them from the same folder):
+
+- `walkNext(notes, currentId, dir)` — the id J (`1`) or K (`-1`) goes to.
+- `inlineMarks(text, notes, markOf)` — a passage's words cut into pieces
+  by the notes' quotes: `{ segments: [{ text, ids }], whole }`.
+- `arrangeNotes(passages, notes)` — `{ byPassage, ordered, orphans }`.
+- `countNotes(notes)`, `countWords(counts)` — `{ total, open, settled,
+  byKind }` and "3 open · 1 settled".
+- `resolveKinds(changes)`, `noteLook(note, kinds)`, `actionsOf(note, kinds)`
+  — the kinds, and what a note looks like and offers.
+- `MARGIN_KINDS` — the built-in kinds.
+
+## Example
+
+An issue with a source beside each paragraph, and a line the agent could
+not source:
+
+```jsx
+"use client";
+import { useRows } from "../lib/data";
+import { updateRow } from "../lib/actions";
+import { MarginNotes } from "../components/blocks/margin-notes";
+
+export default function Issue({ issueId }) {
+  const paragraphs = useRows({ source: "issue_paragraphs", filter: { issue_id: issueId }, orderBy: "position asc" });
+  const notes = useRows({ source: "paragraph_notes", filter: { issue_id: issueId } });
+  if (paragraphs.loading || notes.loading) return <MarginNotes status="loading" />;
+  return (
+    <MarginNotes
+      marginTitle="Where each paragraph came from"
+      passages={(paragraphs.rows ?? []).map((p) => ({ id: p.id, text: p.body, level: p.is_heading ? 3 : undefined }))}
+      notes={(notes.rows ?? []).map((n) => ({
+        id: n.id,
+        passage: n.paragraph_id,
+        kind: n.kind,                       // "source" · "flag"
+        title: n.title,
+        meta: n.meta,
+        detail: n.excerpt,
+        quote: n.quote,
+        by: n.by_agent ? "agent" : undefined,
+        state: n.settled_at ? "settled" : undefined,
+        answer: n.answer,
+      }))}
+      onAction={(note, action) =>
+        updateRow({ source: "paragraph_notes", id: note.id, patch: { answer: action, settled_at: action === "reopen" ? null : new Date().toISOString() } })
+      }
+    />
+  );
+}
+```
+
+In a server-mode app the same calls are `loadRows` in a server surface and the Server Actions of `lib/actions`.
+
+A transcript with the cut words struck, a family colour per reason, and a
+lock for what may never come back:
+
+```jsx
+<MarginNotes
+  side="left"
+  marginWidth="lg"
+  textSize="sm"
+  passages={lines.map((l) => ({ id: l.id, lead: l.clock, label: l.speaker, text: l.words }))}
+  notes={cuts.map((c) => ({
+    id: c.id,
+    passage: c.line_id,
+    kind: "cut",
+    hue: c.family,                 // 1..5, one colour per reason family
+    label: c.reason,               // "Pricing", "A third party"…
+    text: c.note,
+    locked: c.on_never_list ? `On the never-list: ${c.on_never_list}.` : undefined,
+    state: c.put_back ? "settled" : undefined,
+    answer: "Put back",
+  }))}
+  onAction={(note, action) => putBack(note.id)}
+/>
+```
+
+## States
+
+Drawn in `demo.jsx`: sources and a flag that settles in place, cuts with
+the margin on the left, 320 px (notes under the words), one passage, very
+long words, passages with an empty margin, no passages, loading, failed,
+read-only.
+
+## What it will not do
+
+- Edit the words. A passage is read; to change it, open it in your editor
+  (a flag's "Cut it" goes out through `onAction` and your app changes the
+  text).
+- Mark the same quote twice in one passage, or a quote that spans two
+  passages: the first place it appears is marked, in the passage the note
+  is on.
+- Put a note anywhere but beside its passage's row. A long note makes its
+  row taller.
+- Keep the app's data. Settled, cut, put back: all come back in through
+  `notes`.
+
+A margin 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 margin-notes` restores them.

package/registry/blocks/margin-notes/block.json

@@ -0,0 +1,10 @@
+{
+  "name": "margin-notes",
+  "title": "MarginNotes",
+  "description": "Passages of text with notes in the margin, level with the words they are about (stacked under each passage when the container is narrow). Four kinds of note, each with its tone and its buttons: source (where the words came from: a title, a line of detail, the words read), flag (\"No source. Check this line.\" with It's true, Cut it, Ask where it came from), cut (the words struck through, with the reason, Put back, or a lock when nobody may put them back) and comment. The words a note is about are marked in the passage; the selected passage and its note are linked, and J and K walk the notes that still need a person. A settled note folds to one line with what was decided and a Reopen. Saves go out through one callback, onAction(note, actionId).",
+  "useWhen": "A piece of writing is read against what stands behind it: a newsletter issue with a source beside every paragraph, a blog post with the claims that need a person, minutes whose transcript shows what was cut and why, a review with a reviewer's comments beside the lines. Not a thread of comments with no text beside it (comment-box), not one note log for a record (record-notes), not suggested edits inside an editor (doc-editor), not a screenshot with pins (annotate).",
+  "tags": ["margin", "notes", "marginalia", "sources", "citations", "provenance", "fact check", "flag", "claim", "check", "cut", "struck", "redact", "transcript", "minutes", "review", "comment", "proof", "annotation", "agent"],
+  "exports": ["MarginNotes", "MARGIN_KINDS", "TONES", "MARKS", "resolveKinds", "noteLook", "actionsOf", "isSettled", "arrangeNotes", "walkNext", "cycleNote", "findQuote", "inlineMarks", "countNotes", "countWords"],
+  "files": ["index.js", "margin-notes.jsx", "margin-model.js"],
+  "requires": ["agent-marks"]
+}

package/registry/blocks/margin-notes/demo.jsx

@@ -0,0 +1,144 @@
+"use client";
+
+// MarginNotes in the states a screen meets — the gallery's and the smoke
+// test's surface. Not installed into apps: `makersclaw add margin-notes`
+// lays index.js, margin-notes.jsx and margin-model.js only.
+//   Sources       an issue, a source beside each paragraph, one line with
+//                 none to flag (It's true, Cut it, Ask where; settles in place)
+//   Cuts          a transcript with the cut words struck and the reason in
+//                 the margin on the left, four hues, a lock, Put back
+//   Narrow        the same issue in a 320 px column: notes under the words
+//   One           a single passage with a single note
+//   Long          words and a note with no break to wrap at
+//   Empty         no passages; and passages with no notes
+//   Loading, failed, read-only
+import { useState } from "react";
+import { Switch } from "../components/ui";
+import { MarginNotes } from "../components/blocks/margin-notes";
+
+const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+
+const ISSUE = [
+  { id: "p1", level: 3, text: "Offline mode, for the whole day" },
+  { id: "p2", text: "At 6am the tech app downloads the day’s jobs, maps and forms. In a basement plant room or past the last mast, your techs open jobs and fill in forms as usual." },
+  { id: "p3", text: "Search now finds a job by address, customer or part number, so nobody scrolls a list at the van door." },
+  { id: "p4", text: "PS. Offline mode cut sync errors by 90% in the pilot." },
+  { id: "p5", text: "You get this because you use Tern." },
+];
+
+const ISSUE_NOTES = [
+  { id: "s1", passage: "p1", kind: "source", title: "v3.0.0", meta: "tern-app/tern-mobile · shipped Tue 22 Sep", detail: "Release v3.0.0 of the tech app", href: "https://example.com/releases/v3.0.0", hrefLabel: "Open the release", quote: "Offline mode" },
+  { id: "s2", passage: "p2", kind: "source", title: "v3.0.0", meta: "tern-app/tern-mobile · shipped Tue 22 Sep", detail: "offline queue for jobs, maps and forms; background sync on reconnect", quote: "downloads the day’s jobs, maps and forms" },
+  { id: "s3", passage: "p3", kind: "source", title: "PR 482", meta: "tern-app/tern · merged Wed 23 Sep · Leo Brandt", detail: "search: index part numbers on job lines; add address and customer fields", quote: "address, customer or part number" },
+  { id: "s3b", passage: "p3", kind: "comment", by: "Maya", at: "12:31", text: "Say it as one sentence, not a list.", quote: "scrolls a list" },
+  { id: "f1", passage: "p4", kind: "flag", by: "agent", title: "No source. Check this line.", text: "The PS claims a 90% drop in sync errors. Nothing in the log or the blog says so.", quote: "90% in the pilot" },
+];
+
+function useNotes(start) {
+  const [notes, setNotes] = useState(start);
+  const [log, setLog] = useState("");
+  const onAction = async (note, id) => {
+    await wait(350);
+    if (note.id === "f1" && id === "ask") return { ok: false, error: "The mail did not go. Try again." };
+    setNotes((all) =>
+      all.map((n) => {
+        if (n.id !== note.id) return n;
+        if (id === "confirm") return { ...n, state: "settled", answer: "You said it’s true", at: "12:48" };
+        if (id === "cut") return { ...n, kind: "cut", title: "Cut by you", text: "No source for it.", quote: undefined, actions: undefined };
+        if (id === "putback") return { ...n, state: "settled", answer: "Put back", at: "12:50" };
+        if (id === "reopen") return { ...n, state: "open", answer: undefined };
+        return n;
+      }),
+    );
+    setLog(`${id}: ${note.id}`);
+    return { ok: true };
+  };
+  return { notes, onAction, log };
+}
+
+const FAMILY = { 1: "Commercial", 2: "Other people", 3: "In confidence", 4: "Length" };
+const CALL = [
+  { id: "t1", lead: "00:04", label: "Leo Park", text: "Honestly, our margin on this account is basically gone." },
+  { id: "t2", lead: "00:12", label: "Dana Whitfield", text: "Our last agency was useless with reporting, so this is already better." },
+  { id: "t3", lead: "00:31", label: "Sam Ortiz", text: "We agreed the TikTok pilot runs in Q4, owner to be agreed." },
+  { id: "t4", lead: "01:02", label: "Leo Park", text: "Ha, I do love a Friday afternoon call. Anyway." },
+];
+const CALL_NOTES = [
+  { id: "c1", passage: "t1", kind: "cut", hue: 1, label: FAMILY[1], by: "agent", text: "Our margin; before the client joined.", locked: "On the never-list: margins. Nobody can put this back." },
+  { id: "c2", passage: "t2", kind: "cut", hue: 2, label: FAMILY[2], by: "agent", text: "About their previous agency." },
+  { id: "c3", passage: "t4", kind: "cut", hue: 4, label: FAMILY[4], by: "agent", text: "A joke; nothing decided." },
+];
+
+const LONG = "Supercalifragilisticexpialidocious".repeat(4);
+
+export default function MarginNotesDemo() {
+  const issue = useNotes(ISSUE_NOTES);
+  const narrow = useNotes(ISSUE_NOTES);
+  const call = useNotes(CALL_NOTES);
+  const [showNotes, setShowNotes] = useState(true);
+  const [picked, setPicked] = useState(null);
+
+  return (
+    <div className="grid gap-10 p-6">
+      <section className="grid gap-3">
+        <div className="flex flex-wrap items-center gap-3">
+          <h3 className="m-0 text-base font-semibold">Sources and a flag</h3>
+          <Switch id="mn-show" label="Show the margin" checked={showNotes} onChange={(e) => setShowNotes(e.target.checked)} />
+        </div>
+        <MarginNotes passages={ISSUE} notes={issue.notes} onAction={issue.onAction} showNotes={showNotes} marginTitle="Where each paragraph came from" selected={picked} onSelect={setPicked} />
+        <p className="m-0 text-xs text-muted-foreground">{issue.log ? `Last: ${issue.log}` : "Press J or K, or click a paragraph."}</p>
+      </section>
+
+      <section className="grid gap-3">
+        <h3 className="m-0 text-base font-semibold">Cuts, struck where they were said (margin on the left)</h3>
+        <MarginNotes passages={CALL} notes={call.notes} onAction={call.onAction} side="left" marginWidth="lg" marginTitle="The call, with every cut" textSize="sm" />
+      </section>
+
+      <section className="grid gap-3">
+        <h3 className="m-0 text-base font-semibold">Narrow (320)</h3>
+        <div className="w-80 max-w-full">
+          <MarginNotes passages={ISSUE} notes={narrow.notes} onAction={narrow.onAction} defaultSelected="f1" />
+        </div>
+      </section>
+
+      <section className="grid gap-3">
+        <h3 className="m-0 text-base font-semibold">One passage, one note</h3>
+        <MarginNotes passages={[ISSUE[3]]} notes={[ISSUE_NOTES[4]]} keys={false} />
+      </section>
+
+      <section className="grid gap-3">
+        <h3 className="m-0 text-base font-semibold">Very long words</h3>
+        <MarginNotes
+          passages={[{ id: "l1", label: LONG, text: `${LONG} is the whole of this line, and it has no break to wrap at: ${LONG}.` }]}
+          notes={[{ id: "ln", passage: "l1", kind: "flag", title: LONG, text: `${LONG}`, detail: `${LONG} ${LONG}`, quote: LONG.slice(0, 20) }]}
+          onAction={async () => ({ ok: true })}
+        />
+      </section>
+
+      <section className="grid gap-3">
+        <h3 className="m-0 text-base font-semibold">Passages, nothing in the margin</h3>
+        <MarginNotes passages={ISSUE.slice(0, 3)} notes={[]} marginTitle="Sources" />
+      </section>
+
+      <section className="grid gap-3">
+        <h3 className="m-0 text-base font-semibold">No passages</h3>
+        <MarginNotes passages={[]} notes={[]} emptyTitle="No issue drafted yet" emptyBody="When the agent drafts one, each paragraph appears here beside where it came from." />
+      </section>
+
+      <section className="grid gap-3">
+        <h3 className="m-0 text-base font-semibold">Loading</h3>
+        <MarginNotes status="loading" />
+      </section>
+
+      <section className="grid gap-3">
+        <h3 className="m-0 text-base font-semibold">Failed</h3>
+        <MarginNotes status="failed" error="The sources could not be read." onRetry={() => undefined} />
+      </section>
+
+      <section className="grid gap-3">
+        <h3 className="m-0 text-base font-semibold">Read-only</h3>
+        <MarginNotes passages={ISSUE} notes={ISSUE_NOTES} readOnly marginTitle="Where each paragraph came from" />
+      </section>
+    </div>
+  );
+}

package/registry/blocks/margin-notes/index.js

@@ -0,0 +1,20 @@
+// The MarginNotes block — `makersclaw add margin-notes`. Fixed: compose it
+// through its props (README.md beside this file). The model's helpers are
+// plain functions; they work on the server too.
+export { MarginNotes } from "./margin-notes";
+export {
+  MARGIN_KINDS,
+  TONES,
+  MARKS,
+  resolveKinds,
+  noteLook,
+  actionsOf,
+  isSettled,
+  arrangeNotes,
+  walkNext,
+  cycleNote,
+  findQuote,
+  inlineMarks,
+  countNotes,
+  countWords,
+} from "./margin-model";