makersclaw 0.8.0 → 0.8.2

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

@@ -0,0 +1,154 @@
+"use client";
+
+// The editor around the canvas: lays the definition out, folds a for-each
+// on request, and offers the canvas and the outline as two views of one
+// flow. It holds nothing of the definition itself (the screen around it
+// does, as a stack of pure edits from automation-model); it only draws
+// what it is given and says what a person pressed.
+//
+// Editing: `editable` with onInsert / onAddAtSelection. A run:
+// `overlay` (automation-model's overlayOf) and nothing editable.
+
+import { useEffect, useMemo, useRef, useState } from "react";
+import { Icon, cx } from "../../ui";
+import { layoutAutomation, triggerWords as wordsOf } from "../automation-model";
+import { FlowCanvas } from "./flow-canvas";
+import { StepOutline } from "./outline";
+
+/** Under this width the editor opens on the outline. */
+const NARROW = 480;
+
+const BAR_BUTTON = "inline-flex size-7 items-center justify-center rounded-md text-muted-foreground hover:bg-accent disabled:opacity-35 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring";
+
+/** Canvas | Outline, as the head of either view. */
+function ViewToggle({ view, onView }) {
+  const one = (name, icon, label) => (
+    <button
+      type="button"
+      aria-pressed={view === name}
+      onClick={() => onView(name)}
+      className={cx("inline-flex h-7 items-center gap-1.5 rounded-md px-2 text-[13px] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring", view === name ? "bg-accent font-medium text-accent-foreground" : "text-muted-foreground hover:bg-accent")}
+    >
+      <Icon name={icon} size={14} /> {label}
+    </button>
+  );
+  return (
+    <div role="group" aria-label="View" className="flex items-center gap-px rounded-lg border border-border bg-card p-0.5">
+      {one("canvas", "network", "Canvas")}
+      {one("outline", "list", "Outline")}
+    </div>
+  );
+}
+
+/**
+ *   def               the definition shown: { trigger, steps, … }
+ *   selectedId, onSelect(id|null)
+ *   editable          the + buttons and the palette
+ *   onInsert(slot, kind), onAddAtSelection(kind)
+ *   overlay           a run's overlayOf(), or null
+ *   flagged           a Set of step ids with something to fix
+ *   prices            a Map of step id to { credits, max }
+ *   fitKey, revealId  see FlowCanvas
+ *   runnable          a Set of kinds the platform runs
+ *   undo              { canUndo, canRedo, onUndo, onRedo } or null: the history buttons
+ *   onOpenFlow        the gear: open the automation's own settings (draws it when given)
+ */
+export function FlowEditor({ def, selectedId = null, onSelect, editable = false, onInsert, onAddAtSelection, overlay = null, flagged, prices, fitKey, revealId, runnable, undo = null, onOpenFlow, className }) {
+  const rootRef = useRef(null);
+  const [narrow, setNarrow] = useState(false);
+  const [chosen, setChosen] = useState(null);
+  // The canvas is a poor fit for a thumb: under about 480 px of its own
+  // width it opens on the outline, until a person asks for the canvas.
+  useEffect(() => {
+    const el = rootRef.current;
+    if (!el) return undefined;
+    const measure = () => setNarrow(el.clientWidth > 0 && el.clientWidth < NARROW);
+    measure();
+    if (typeof ResizeObserver === "undefined") return undefined;
+    // Measure in the callback, act in the next frame (check rule 17).
+    let raf = 0;
+    const ro = new ResizeObserver(() => {
+      cancelAnimationFrame(raf);
+      raf = requestAnimationFrame(measure);
+    });
+    ro.observe(el);
+    return () => {
+      cancelAnimationFrame(raf);
+      ro.disconnect();
+    };
+  }, []);
+  const view = chosen ?? (narrow ? "outline" : "canvas");
+  const setView = setChosen;
+  const [collapsed, setCollapsed] = useState(() => new Set());
+  const words = wordsOf(def.trigger);
+  const layout = useMemo(() => layoutAutomation(def, { triggerWords: words, collapsed }), [def, words, collapsed]);
+  const steps = layout.nodes.filter((n) => n.type === "step" || n.type === "card").length;
+
+  const toggleCollapse = (id) =>
+    setCollapsed((c) => {
+      const next = new Set(c);
+      if (next.has(id)) next.delete(id);
+      else next.add(id);
+      return next;
+    });
+
+  const history = undo ? (
+    <div role="group" aria-label="History" className="flex items-center gap-px rounded-lg border border-border bg-card p-0.5">
+      <button type="button" aria-label="Undo" disabled={!undo.canUndo} onClick={undo.onUndo} className={BAR_BUTTON}>
+        <Icon name="undo" size={15} />
+      </button>
+      <button type="button" aria-label="Redo" disabled={!undo.canRedo} onClick={undo.onRedo} className={BAR_BUTTON}>
+        <Icon name="redo" size={15} />
+      </button>
+    </div>
+  ) : null;
+
+  const gear = onOpenFlow ? (
+    <button type="button" aria-label="Settings of this automation" title="Settings of this automation" onClick={onOpenFlow} className={cx(BAR_BUTTON, "size-9 rounded-lg border border-border bg-card")}>
+      <Icon name="settings" size={15} />
+    </button>
+  ) : null;
+
+  return (
+    <div ref={rootRef} className={cx("flex min-h-0 min-w-0 flex-1 flex-col", className)}>
+      {view === "outline" ? (
+        <>
+          <div className="flex flex-wrap items-center gap-2 border-b border-border px-3 py-2">
+            {history}
+            <ViewToggle view={view} onView={setView} />
+            {gear}
+          </div>
+          <div data-scroll className="min-h-0 flex-1 overflow-y-auto">
+            <StepOutline def={def} triggerWords={words} selectedId={selectedId} onSelect={onSelect} overlay={overlay} editable={editable} onInsert={onInsert} flagged={flagged} runnable={runnable} />
+          </div>
+        </>
+      ) : (
+        <FlowCanvas
+          layout={layout}
+          selectedId={selectedId}
+          onSelect={onSelect}
+          editable={editable}
+          onInsert={onInsert}
+          onAddAtSelection={onAddAtSelection}
+          onToggleCollapse={toggleCollapse}
+          overlay={overlay}
+          flagged={flagged}
+          prices={prices}
+          fitKey={fitKey}
+          revealId={revealId}
+          runnable={runnable}
+          info={
+            <>
+              {history}
+              <div className="rounded-lg border border-border bg-card px-2.5 py-1 text-[13px] text-muted-foreground">
+                <b className="font-semibold text-foreground">{steps}</b> {steps === 1 ? "step" : "steps"}
+              </div>
+              <ViewToggle view={view} onView={setView} />
+              {gear}
+            </>
+          }
+        />
+      )}
+    </div>
+  );
+}

package/registry/blocks/flow-editor/index.js

@@ -0,0 +1,6 @@
+// The FlowEditor block — `makersclaw add flow-editor`. Fixed: compose it
+// through its props (README.md beside this file).
+export { FlowCanvas } from "./flow-canvas";
+export { FlowEditor } from "./flow-editor";
+export { Minimap } from "./minimap";
+export { StepOutline } from "./outline";

package/registry/blocks/flow-editor/minimap.jsx

@@ -0,0 +1,78 @@
+"use client";
+
+// The map in the corner: the whole flow small, the part you are looking at
+// outlined. Press or drag on it to go there. In a run it wears the run's
+// colours, so a long flow shows where it went wrong at a glance.
+
+import { useRef } from "react";
+import { cx } from "../../ui";
+
+export const MAP_W = 176;
+export const MAP_H = 104;
+
+const DOT = {
+  idle: "bg-muted-foreground/60",
+  done: "bg-success",
+  would: "bg-primary/60",
+  running: "bg-info",
+  failed: "bg-destructive",
+  fixed: "bg-primary",
+  waiting: "bg-warning",
+  skipped: "bg-muted-foreground/30",
+  unknown: "bg-muted-foreground/60",
+  notreached: "bg-muted-foreground/25",
+};
+
+/**
+ *   layout    automation-model's layoutAutomation()
+ *   view      { x, y, k }: where the canvas is
+ *   size      { w, h }: the canvas's size
+ *   overlay   a run's overlayOf(), or null
+ *   onCenter(worldX, worldY)
+ */
+export function Minimap({ layout, view, size, overlay, onCenter }) {
+  const ref = useRef(null);
+  const b = layout.bounds;
+  if (b.w <= 0 || b.h <= 0) return null;
+  const s = Math.min((MAP_W - 16) / b.w, (MAP_H - 24) / b.h);
+  const ox = (MAP_W - b.w * s) / 2 - b.x * s;
+  const oy = (MAP_H - b.h * s) / 2 + 6 - b.y * s;
+  const rect = (x, y, w, h) => ({ left: x * s + ox, top: y * s + oy, width: Math.max(2, w * s), height: Math.max(2, h * s) });
+  const vp = rect(-view.x / view.k, -view.y / view.k, size.w / view.k, size.h / view.k);
+
+  const at = (e) => {
+    const r = ref.current?.getBoundingClientRect();
+    if (r) onCenter((e.clientX - r.left - ox) / s, (e.clientY - r.top - oy) / s);
+  };
+
+  return (
+    <div
+      ref={ref}
+      data-nopan
+      role="img"
+      aria-label="Map of the whole flow"
+      style={{ width: MAP_W, height: MAP_H }}
+      className="absolute bottom-3 right-3 z-[6] cursor-pointer overflow-hidden rounded-lg border border-border bg-card shadow-sm"
+      onPointerDown={(e) => {
+        e.stopPropagation();
+        e.currentTarget.setPointerCapture?.(e.pointerId);
+        at(e);
+      }}
+      onPointerMove={(e) => {
+        if (e.buttons) at(e);
+      }}
+    >
+      <span className="absolute left-2 top-1 text-2xs font-medium text-muted-foreground">Map</span>
+      {layout.groups.map((g) => (
+        <span key={g.id} style={rect(g.x, g.y, g.w, g.h)} className="absolute rounded-sm border border-dashed border-muted-foreground/40" />
+      ))}
+      {layout.nodes
+        .filter((n) => n.type === "step" || n.type === "trigger" || n.type === "card")
+        .map((n) => {
+          const state = overlay ? (overlay.nodes.get(n.id) ?? "notreached") : "idle";
+          return <span key={n.id} style={rect(n.x, n.y, n.w, n.h)} className={cx("absolute rounded-[2px]", DOT[state] ?? DOT.idle)} />;
+        })}
+      <span style={vp} className="absolute rounded-sm border-2 border-foreground/70 bg-foreground/5" />
+    </div>
+  );
+}

package/registry/blocks/flow-editor/outline.jsx

@@ -0,0 +1,134 @@
+"use client";
+
+// The same flow as an outline: the trigger, then every step in order, a
+// condition's branches and a loop's steps nested under it. It is the
+// phone's second view (the canvas is a poor fit for a thumb), and a way in
+// for anyone who works by keyboard or with a screen reader: every step is
+// a button, and every place a step can go has an "Add a step" button.
+
+import { useState } from "react";
+import { Icon, cx } from "../../ui";
+import { Glyph, KINDS, fixTag, stepSub, stepTitle, triggerGlyph, triggerTitle } from "../automation-model";
+import { StepPicker } from "../step-picker";
+
+const STATE_ICON = { done: "check", would: "pencil", running: "loader", failed: "x", fixed: "wand", waiting: "clock", skipped: "minus", unknown: "circle-help" };
+const STATE_TONE = { done: "bg-success", would: "bg-muted-foreground", running: "bg-info", failed: "bg-destructive", fixed: "bg-primary", waiting: "bg-warning", skipped: "bg-muted-foreground", unknown: "bg-muted-foreground" };
+const FACE = { plain: "text-muted-foreground", model: "text-primary", agent: "text-primary bg-primary/15 border-primary" };
+
+const slotKey = (s) => `${s.list.at}:${"step" in s.list ? s.list.step : ""}:${s.index}`;
+
+/**
+ *   def            the definition: { trigger, steps }
+ *   triggerWords   the trigger in words
+ *   selectedId     a step id, "trigger", or null
+ *   onSelect(id)
+ *   overlay        a run's overlayOf(), or null
+ *   editable, onInsert(slot, kind)   the "Add a step" buttons
+ *   flagged        a Set of step ids with something to fix
+ *   runnable       a Set of kinds the platform runs
+ */
+export function StepOutline({ def, triggerWords, selectedId = null, onSelect, overlay = null, editable = false, onInsert, flagged, runnable }) {
+  const [open, setOpen] = useState(null);
+
+  const adder = (slot, label = "Add a step") => {
+    if (!editable || !onInsert) return null;
+    const key = slotKey(slot);
+    return open === key ? (
+      <StepPicker
+        inline
+        runnable={runnable}
+        onClose={() => setOpen(null)}
+        onPick={(kind) => {
+          setOpen(null);
+          onInsert(slot, kind);
+        }}
+      />
+    ) : (
+      <button type="button" onClick={() => setOpen(key)} className="inline-flex min-h-9 items-center gap-1.5 rounded-md border border-dashed border-border px-2.5 text-[13px] text-muted-foreground hover:border-solid hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring">
+        <span aria-hidden="true">+</span> {label}
+      </button>
+    );
+  };
+
+  const row = (step, state) => {
+    const info = KINDS[step.kind] ?? KINDS.action;
+    const sum = overlay?.summary.get(step.id);
+    const sel = selectedId === step.id;
+    return (
+      <button
+        type="button"
+        aria-pressed={sel}
+        onClick={() => onSelect?.(step.id)}
+        className={cx(
+          "flex w-full min-w-0 items-center gap-2.5 rounded-lg border bg-card px-2.5 py-2 text-left text-card-foreground hover:bg-accent focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+          sel ? "border-foreground" : flagged?.has(step.id) || state === "failed" ? "border-destructive" : state === "would" ? "border-primary/70" : "border-border",
+          state === "notreached" && "border-dashed opacity-60",
+          state === "would" && "border-dashed",
+        )}
+      >
+        <span className={cx("inline-flex size-9 shrink-0 items-center justify-center rounded-lg border border-border", FACE[info.tone] ?? FACE.plain)}>
+          <Glyph name={info.glyph} size={18} />
+        </span>
+        <span className="grid min-w-0 flex-1 gap-0.5">
+          <b className="break-words text-[13px] font-semibold">{stepTitle(step)}</b>
+          <span className="break-words text-xs text-muted-foreground">{stepSub(step)}</span>
+          {sum?.fix ? <span className="text-xs text-primary">{fixTag(sum.fix)}</span> : null}
+          {sum && state === "failed" && sum.words ? <span className="text-xs text-destructive">{sum.words}</span> : null}
+          {sum?.unchecked ? <span className="text-xs text-muted-foreground">Not checked</span> : sum && state === "would" && sum.would ? <span className="text-xs text-primary">{sum.would}</span> : null}
+        </span>
+        {state && STATE_ICON[state] ? (
+          <span className={cx("inline-flex size-5 shrink-0 items-center justify-center rounded-full text-background", STATE_TONE[state])}>
+            <Icon name={STATE_ICON[state]} size={13} className={state === "running" ? "animate-spin motion-reduce:animate-none" : undefined} />
+          </span>
+        ) : null}
+      </button>
+    );
+  };
+
+  const list = (steps, ref) => (
+    <ol className="m-0 grid list-none gap-1.5 p-0">
+      {steps.map((step, i) => {
+        const state = overlay ? (overlay.nodes.get(step.id) ?? "notreached") : null;
+        return (
+          <li key={step.id} className="grid gap-1.5">
+            {adder({ list: ref, index: i })}
+            {row(step, state)}
+            {step.kind === "condition" ? (
+              <div className="grid gap-2 border-l-2 border-border pl-3">
+                <div className="grid gap-1.5">
+                  <h5 className="m-0 text-xs font-semibold text-muted-foreground">Yes</h5>
+                  {list(step.then ?? [], { at: "then", step: step.id })}
+                </div>
+                <div className="grid gap-1.5">
+                  <h5 className="m-0 text-xs font-semibold text-muted-foreground">No</h5>
+                  {list(step.else ?? [], { at: "else", step: step.id })}
+                </div>
+              </div>
+            ) : null}
+            {step.kind === "loop" ? <div className="grid gap-1.5 border-l-2 border-dashed border-border pl-3">{list(step.steps ?? [], { at: "loop", step: step.id })}</div> : null}
+          </li>
+        );
+      })}
+      <li className="grid gap-1.5">{adder({ list: ref, index: steps.length }, steps.length === 0 ? "Add the first step" : "Add a step")}</li>
+    </ol>
+  );
+
+  const triggerType = def.trigger?.type;
+  return (
+    <div className="grid min-w-0 content-start gap-3 p-3">
+      <div className={cx("flex min-w-0 items-center gap-2.5 rounded-lg border bg-card px-2.5 py-2 text-card-foreground", selectedId === "trigger" ? "border-foreground" : "border-border")}>
+        <span className="inline-flex size-9 shrink-0 items-center justify-center rounded-lg border border-border text-muted-foreground">
+          <Glyph name={triggerGlyph(triggerType)} size={18} />
+        </span>
+        <span className="grid min-w-0 flex-1 gap-0.5">
+          <b className="text-[13px] font-semibold">{triggerTitle(triggerType)}</b>
+          <span className="text-xs text-muted-foreground">{triggerWords}</span>
+        </span>
+        <button type="button" aria-pressed={selectedId === "trigger"} onClick={() => onSelect?.("trigger")} className="rounded-md px-2 py-1 text-[13px] text-muted-foreground underline hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring">
+          Edit
+        </button>
+      </div>
+      {list(def.steps ?? [], { at: "root" })}
+    </div>
+  );
+}

package/registry/blocks/library-shelf/README.md

@@ -0,0 +1,117 @@
+# LibraryShelf
+
+"Start from a template": a shelf of starting points from the Library, in
+a few named columns. Each item is its mark or cover, its name, one muted
+fact ("6 stages", "PDF") and a **Use** at its end.
+
+Use is your async callback. While it runs the button spins; then the
+item says **Used**; a failure shows its reason under the item. A heading
+names the shelf and where its items come from.
+
+Grown in the CRM (0.7.0) as "Start from a template · CRM starting points,
+from the Library". Every app ships its first Library collection; this is
+where it shows.
+
+```jsx
+import { LibraryShelf } from "../components/blocks/library-shelf";   // a Makersclaw app ("./blocks/library-shelf" from components/)
+import { LibraryShelf } from "@/components/makersclaw/blocks/library-shelf";   // a shadcn project
+```
+
+A client component. The Example is at the end.
+
+## Which hook feeds it
+
+```js
+const library = useLibraryItems("crm-starting-points");   // lib/hooks.js
+// → { items, total, previewOnly, hasMore, loadMore, loading, loadingMore, error, unavailable, … }
+```
+
+`useLibraryItems(id)` reads `GET _claw/library/collections/<id>/items`:
+a files collection's items, `{ id, title, description, tags, format,
+preview_url, locked, … }`, a page at a time. Give the whole answer to
+`library`. On a Free plan a paid collection is a preview: the shelf says
+how many more come with a paid plan, and a `locked` item has no Use.
+
+## Props
+
+Two ways in: `library` with `onUse(item)`, or `sections` you shaped.
+
+### From the Library
+
+- `library` — what `useLibraryItems()` returns. The shelf draws one
+  column of its items, each with its cover (`preview_url`) or its
+  format's glyph, and the format as its fact.
+- `onUse(item)` — async, answers `{ ok: true }` or `{ ok: false, error }`
+  (a throw counts as failed). What Use does with a Library item: ask the
+  agent to copy it in, open it as a draft. The Library door never writes;
+  a copy into the workspace is the agent's.
+- `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. Default "Nothing on
+  this shelf yet."
+
+Under the items: "Show more" when `hasMore`, "N more come with a paid
+plan" on a preview, the error's words, or "The Library is not connected
+yet." Skeleton lines while the first page is out.
+
+### Sections you shaped
+
+- `sections` — `[{ key, title, items }]`, side by side from 48rem of the
+  shelf's own width, stacked below. An item:
+  - `id`, `label` — the name.
+  - `meta` — one short muted fact after it ("6 stages"). It truncates, and
+    the label too: no row is wider than its box. Never a sentence.
+  - `description` — a sentence under the label, muted, wrapping onto as
+    many lines as it needs ("Turn a developer's line into a customer's").
+  - `mark` — a node before it (a stage's dot, an icon).
+  - `onUse()` — async `{ ok }`. Without it the item has no Use.
+  - `useLabel` — default "Use". `used` — already used. `usedLabel` —
+    default "Used". `once: false` — usable again.
+  - `locked` — a lock instead of Use.
+
+`libraryShelfItems(items, { onUse, useLabel, once })` turns Library items
+into shelf items, for a shelf of several collections.
+
+### Both
+
+- `title` — default "Start from a template".
+- `source` — where the items come from ("CRM starting points, from the
+  Library"), muted after the title.
+- `icon` — a kit `Icon` name before the title. Default `"layers"`.
+- `className` — layout around it. Never colour.
+
+## Who may do what
+
+Any member who can open the app reads the shelf. A paid collection on a
+Free plan shows its preview; the Upgrade is on the desk's Library window,
+never in the app.
+
+## Never
+
+- Never read the Library inside the block: the items come in as props.
+- Never keep a `file_url`: Use asks for the item when it is pressed.
+- Never offer an Upgrade or a price here: money is the desk's.
+
+## Example
+
+The CRM's starting points on an empty board, straight from its
+collection.
+
+```jsx
+"use client";
+import { ask } from "../lib/platform";
+import { useLibraryItems } from "../lib/hooks";
+import { LibraryShelf } from "../components/blocks/library-shelf";
+
+export default function StartFrom() {
+  const library = useLibraryItems("crm-starting-points", { limit: 12 });
+  return (
+    <LibraryShelf
+      source="CRM starting points, from the Library"
+      library={library}
+      sectionTitle="Sales processes"
+      onUse={(item) => ask({ text: `Set up the sales process "${item.title}" from the Library (item ${item.id}).` })}
+    />
+  );
+}
+```

package/registry/blocks/library-shelf/block.json

@@ -0,0 +1,28 @@
+{
+  "name": "library-shelf",
+  "title": "LibraryShelf",
+  "description": "A shelf of starting points from the Library, in a few named columns (sales processes, follow-up emails, saved searches): each item its mark or cover, its name, one muted fact (\"6 stages\", \"PDF\") and a Use at its end. Use goes out through an async callback that answers { ok }; the item says it is being used, then Used, and the reason in place when it fails. It takes sections you shaped, or what useLibraryItems() returns (lib/hooks.js) with onUse(item): the collection's items with their covers, Show more, \"N more come with a paid plan\" on a preview, locked items without a Use, and a quiet \"not connected yet\".",
+  "useWhen": "An empty or new screen that offers the app's own starting points from the Library (\"Start from a template\"): a CRM's starting processes and follow-up emails, a planner's templates, a deck app's starter decks, a growth app's examples. Not for a gallery of large previews (a card grid over useLibraryItems), a picker inside a form (Combobox) or the records themselves.",
+  "tags": [
+    "library",
+    "templates",
+    "starting points",
+    "shelf",
+    "empty state",
+    "use",
+    "collection",
+    "onboarding",
+    "examples",
+    "start from"
+  ],
+  "exports": [
+    "LibraryShelf",
+    "libraryShelfItems"
+  ],
+  "files": [
+    "index.js",
+    "library-shelf.jsx",
+    "probe-rules.js"
+  ],
+  "requires": []
+}

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

@@ -0,0 +1,68 @@
+"use client";
+
+// LibraryShelf with sections, and straight from fake useLibraryItems()
+// answers: a preview with more to load, loading, empty, refused and not
+// connected yet — the gallery's and the smoke test's surface. Not
+// installed into apps.
+import { useState } from "react";
+import { Icon } from "../components/ui";
+import { LibraryShelf } from "../components/blocks/library-shelf";
+
+const wait = (ms, r) => new Promise((res) => setTimeout(() => res(r), ms));
+const DOTS = { "chart-1": "bg-chart-1", "chart-4": "bg-chart-4" };
+const dot = (tone) => <span aria-hidden="true" className={`size-[7px] shrink-0 rounded-full ${DOTS[tone]}`} />;
+
+const ITEMS = [
+  { id: "i1", title: "Seed deck, 12 slides", format: "slides", preview_url: null, locked: false },
+  { id: "i2", title: "Investor update, monthly", format: "document", locked: false },
+  { id: "i3", title: "A landing page for a waitlist with a very long name that has to truncate", format: "html", locked: false },
+  { id: "i4", title: "Pricing page teardown", format: "pdf", locked: true },
+];
+
+const base = { total: null, previewOnly: false, hasMore: false, loading: false, loadingMore: false, error: null, unavailable: false, loadMore: () => undefined };
+
+export default function LibraryShelfDemo() {
+  const [items, setItems] = useState(ITEMS.slice(0, 3));
+  const [loadingMore, setLoadingMore] = useState(false);
+  const library = {
+    ...base,
+    items,
+    total: 9,
+    previewOnly: true,
+    hasMore: items.length < 4,
+    loadingMore,
+    loadMore: () => {
+      setLoadingMore(true);
+      setTimeout(() => {
+        setItems(ITEMS);
+        setLoadingMore(false);
+      }, 700);
+    },
+  };
+  return (
+    <div className="grid gap-8 p-6">
+      <LibraryShelf
+        source="CRM starting points, from the Library"
+        sections={[
+          {
+            key: "p",
+            title: "Sales processes",
+            items: [
+              { id: "a", label: "Selling yearly plans", meta: "6 stages", mark: dot("chart-1"), onUse: () => wait(600) },
+              { id: "b", label: "A funding round", meta: "7 stages", description: "From the first intro to the wire: investors, diligence and the close, one stage each.", mark: dot("chart-4"), onUse: () => wait(400, { ok: false, error: "There is already a process called A funding round." }) },
+            ],
+          },
+          { key: "e", title: "Follow-up emails", items: [{ id: "c", label: "After a demo", mark: <Icon name="mail" size={14} className="text-muted-foreground" />, onUse: () => wait(300), once: false, useLabel: "Look" }] },
+          { key: "s", title: "Saved searches", items: [{ id: "d", label: "Waiting on you", mark: <Icon name="filter" size={14} className="text-muted-foreground" />, used: true }] },
+        ]}
+      />
+      <LibraryShelf title="Start from a deck" source="Pitch decks, from the Library" icon="file" sectionTitle="Decks and updates" library={library} onUse={() => wait(600, { ok: true })} />
+      <div className="grid gap-6 [grid-template-columns:repeat(auto-fit,minmax(min(100%,18rem),1fr))]">
+        <LibraryShelf title="Loading" library={{ ...base, items: [], loading: true }} onUse={() => undefined} />
+        <LibraryShelf title="Empty" library={{ ...base, items: [] }} onUse={() => undefined} />
+        <LibraryShelf title="Refused" library={{ ...base, items: [], error: "This collection is not on your workspace's shelf." }} onUse={() => undefined} />
+        <LibraryShelf title="Not connected yet" library={{ ...base, items: [], unavailable: true }} onUse={() => undefined} />
+      </div>
+    </div>
+  );
+}

package/registry/blocks/library-shelf/index.js

@@ -0,0 +1,3 @@
+// The LibraryShelf block — `makersclaw add library-shelf`. Fixed: compose
+// it through its props (README.md beside this file).
+export { LibraryShelf, libraryShelfItems } from "./library-shelf";