makersclaw 0.2.0 → 0.3.0

package/registry/blocks/pdf-viewer/demo.jsx

@@ -0,0 +1,252 @@
+"use client";
+
+// PdfViewer three ways — the gallery's and the smoke test's surface. Not
+// installed into apps. The PDF is not a file shipped with the demo: it is
+// made in the browser, at load, by the pdf-document block (renderPdf), in
+// the workspace's theme — the pair a quote or proposal screen uses.
+//   Review          a three-page proposal with three highlights (placed by
+//                   their words alone), notes, saves that can be made to fail
+//   Read only       the same file in a phone-width frame: no highlighting,
+//                   the rails as sheets
+//   Empty and error no file yet; a file that is not a PDF
+import { useEffect, useMemo, useState } from "react";
+import { Notice, Switch, TabPanel, Tabs } from "../components/ui";
+import { PdfViewer, usePdfViewer } from "../components/blocks/pdf-viewer";
+import {
+  PdfCallout,
+  PdfCol,
+  PdfDivider,
+  PdfDocument,
+  PdfField,
+  PdfHeading,
+  PdfLabel,
+  PdfLines,
+  PdfRow,
+  PdfStack,
+  PdfTable,
+  PdfText,
+  PdfTotals,
+  formatMoney,
+  renderPdf,
+} from "../components/blocks/pdf-document";
+
+const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// The proposal, written for this demo.
+function Proposal() {
+  const phases = [
+    { id: 1, phase: "Discovery", detail: "Interviews with 8 clinicians and 12 patients; analytics review", weeks: "2", fee: 9800 },
+    { id: 2, phase: "Information architecture", detail: "Site map, navigation, content model", weeks: "2", fee: 8400 },
+    { id: 3, phase: "Design", detail: "Design system, 14 key templates, two rounds of revisions", weeks: "5", fee: 26500 },
+    { id: 4, phase: "Build", detail: "Next.js front end on your CMS, accessibility to WCAG 2.2 AA", weeks: "6", fee: 38200 },
+    { id: 5, phase: "Launch and care", detail: "Migration, redirects, training, 30 days of support", weeks: "2", fee: 7600 },
+  ];
+  const total = phases.reduce((s, p) => s + p.fee, 0);
+  return (
+    <PdfDocument title="Website redesign proposal" author="Northwind Studio" subject="Juniper Health" footer="Northwind Studio  ·  Proposal NW-118  ·  Confidential">
+      <PdfStack gap={4}>
+        <PdfLabel>Proposal NW-118 · 18 September 2026</PdfLabel>
+        <PdfHeading level={1}>A calmer front door for Juniper Health</PdfHeading>
+        <PdfText tone="muted" size="lg" style={{ marginTop: 6 }}>
+          Website redesign and patient portal entry points
+        </PdfText>
+      </PdfStack>
+      <PdfDivider space={20} />
+      <PdfRow gap={24}>
+        <PdfCol>
+          <PdfLabel>Prepared for</PdfLabel>
+          <PdfLines lines={["Priya Raman", "Head of Digital, Juniper Health", "400 Market Street, San Francisco"]} />
+        </PdfCol>
+        <PdfCol>
+          <PdfLabel>Prepared by</PdfLabel>
+          <PdfLines lines={["Maya Chen", "Partner, Northwind Studio", "maya@northwind.studio"]} />
+        </PdfCol>
+        <PdfCol flex={0.8}>
+          <PdfField label="Valid until">16 October 2026</PdfField>
+        </PdfCol>
+      </PdfRow>
+
+      <PdfStack gap={8} style={{ marginTop: 28 }}>
+        <PdfHeading level={2}>Summary</PdfHeading>
+        <PdfText>
+          Juniper's site has grown one page at a time for nine years. Patients now reach the patient portal through four different doors, and half of all calls to the front desk ask where to find a form that is already online.
+        </PdfText>
+        <PdfText>
+          We propose a focused redesign over seventeen weeks: fewer pages, one clear way into the portal, and a design system your team can extend without us. The work is fixed-fee, in five phases, each ending in a review with your team.
+        </PdfText>
+      </PdfStack>
+
+      <PdfStack gap={8} style={{ marginTop: 20 }}>
+        <PdfHeading level={2}>What we heard</PdfHeading>
+        <PdfLines
+          first={false}
+          muted={false}
+          lines={[
+            "•  Patients cannot tell which location a page is about.",
+            "•  Booking starts on the site but ends on the phone.",
+            "•  Clinicians want to update their own profiles.",
+            "•  The portal login is buried three levels deep.",
+          ]}
+        />
+      </PdfStack>
+
+      <PdfStack gap={10} break>
+        <PdfHeading level={2}>Scope and timeline</PdfHeading>
+        <PdfText tone="muted">Five phases, seventeen weeks, starting the week of 5 October 2026.</PdfText>
+        <PdfTable
+          style={{ marginTop: 6 }}
+          columns={[
+            { key: "phase", label: "Phase", flex: 3 },
+            { key: "weeks", label: "Weeks", width: 52, align: "right" },
+            { key: "fee", label: "Fee", width: 84, align: "right", render: (r) => formatMoney(r.fee) },
+          ]}
+          rows={phases}
+        />
+        <PdfTotals rows={[{ label: "Fixed fee", value: formatMoney(total), strong: true }]} />
+        <PdfCallout title="What is not included">
+          Photography, copywriting beyond the fourteen templates, and changes to the portal itself. We are glad to quote for any of these separately.
+        </PdfCallout>
+      </PdfStack>
+
+      <PdfStack gap={8} break>
+        <PdfHeading level={2}>Terms</PdfHeading>
+        <PdfText>
+          Invoices are sent at the start of each phase and are due within 14 days. The design phase includes two rounds of revisions per template; further rounds are billed at the day rate of $1,400.
+        </PdfText>
+        <PdfText>
+          After launch, the care plan renews each year. Fees rise by 4% at each annual renewal unless either side gives 60 days' notice.
+        </PdfText>
+        <PdfText>Either party may end the agreement with 30 days' written notice; work completed up to that date is paid in full.</PdfText>
+        <PdfDivider space={24} />
+        <PdfRow gap={32}>
+          <PdfCol>
+            <PdfLabel>For Northwind Studio</PdfLabel>
+            <PdfText bold>Maya Chen, Partner</PdfText>
+          </PdfCol>
+          <PdfCol>
+            <PdfLabel>For Juniper Health</PdfLabel>
+            <PdfText tone="muted">Name, title and date</PdfText>
+          </PdfCol>
+        </PdfRow>
+      </PdfStack>
+    </PdfDocument>
+  );
+}
+
+// Highlights given by their words only: the viewer finds where they sit.
+const REVIEW_NOTES = [
+  { id: "hl-1", text: "Fees rise by 4% at each annual renewal", note: "Ask for a 3% cap, like last year's contract.", tone: "warning", author: "Priya Raman", createdAt: "2026-09-21" },
+  { id: "hl-2", text: "one clear way into the portal", note: "", tone: "info", author: "Leo Park", createdAt: "2026-09-22" },
+  { id: "hl-3", text: "two rounds of revisions per template", note: "Matches what legal asked for.", tone: "success", author: "Priya Raman", createdAt: "2026-09-22" },
+];
+
+const FIRST_NOTE = REVIEW_NOTES.slice(0, 1);
+
+function useProposal() {
+  const [blob, setBlob] = useState(null);
+  const [error, setError] = useState(null);
+  useEffect(() => {
+    let live = true;
+    renderPdf(<Proposal />)
+      .then((b) => live && setBlob(b))
+      .catch((e) => live && setError(e));
+    return () => {
+      live = false;
+    };
+  }, []);
+  return { blob, error };
+}
+
+function ReviewDemo({ blob }) {
+  const [highlights, setHighlights] = useState(REVIEW_NOTES);
+  const [fail, setFail] = useState(false);
+  const [page, setPage] = useState(1);
+  const viewer = usePdfViewer();
+  const failed = { ok: false, error: "The server didn't answer (the demo's switch is on)." };
+  return (
+    <div className="grid gap-3">
+      <div className="flex flex-wrap items-center justify-between gap-x-6 gap-y-1">
+        <p className="text-sm text-muted-foreground">
+          Select any sentence to highlight it or add a note. <span className="tabular-nums">Page {page}.</span>
+        </p>
+        <Switch id="pdf-fail" label="Make saves fail" checked={fail} onChange={(e) => setFail(e.target.checked)} />
+      </div>
+      <PdfViewer
+        file={blob}
+        loading={!blob}
+        title="Website redesign proposal — Juniper Health"
+        fileName="northwind-proposal-nw-118.pdf"
+        viewerRef={viewer}
+        highlights={highlights}
+        onPageChange={setPage}
+        onHighlight={async (h) => {
+          await wait(450);
+          if (fail) return failed;
+          const id = `hl-${Date.now()}`;
+          setHighlights((list) => [...list, { ...h, id, author: "You", createdAt: new Date().toISOString() }]);
+          return { ok: true, id };
+        }}
+        onHighlightChange={async (id, patch) => {
+          await wait(350);
+          if (fail) return failed;
+          setHighlights((list) => list.map((x) => (x.id === id ? { ...x, ...patch } : x)));
+          return { ok: true };
+        }}
+        onHighlightDelete={async (id) => {
+          await wait(300);
+          if (fail) return failed;
+          setHighlights((list) => list.filter((x) => x.id !== id));
+          return { ok: true };
+        }}
+      />
+    </div>
+  );
+}
+
+function ReadOnlyDemo({ blob }) {
+  return (
+    <div className="grid gap-3">
+      <p className="text-sm text-muted-foreground">No onHighlight: a reader. In a phone-width frame the pages and highlights open as sheets.</p>
+      <div className="mx-auto w-full max-w-[390px]">
+        <PdfViewer file={blob} loading={!blob} title="Website redesign proposal" highlights={FIRST_NOTE} height="720px" />
+      </div>
+    </div>
+  );
+}
+
+function StatesDemo() {
+  const broken = useMemo(() => new Blob(["This is a note, not a PDF."], { type: "application/pdf" }), []);
+  return (
+    <div className="grid gap-4 lg:grid-cols-2">
+      <PdfViewer file={null} title="Signed agreement" height="420px" emptyTitle="No signed copy yet" emptyBody="When Juniper signs, their copy of the agreement shows here." />
+      <PdfViewer file={broken} title="statement-august.pdf" height="420px" />
+    </div>
+  );
+}
+
+export default function PdfViewerDemo() {
+  const [tab, setTab] = useState("review");
+  const { blob, error } = useProposal();
+  return (
+    <div className="grid gap-4">
+      <Tabs
+        aria-label="PdfViewer variants"
+        value={tab}
+        onChange={setTab}
+        tabs={[
+          { key: "review", label: "Review" },
+          { key: "read", label: "Read only" },
+          { key: "states", label: "Empty and error" },
+        ]}
+      />
+      {error ? (
+        <Notice tone="danger" title="The sample PDF couldn't be made">
+          {String(error.message ?? error)}
+        </Notice>
+      ) : null}
+      <TabPanel tab={tab} value={tab}>
+        {tab === "review" ? <ReviewDemo blob={blob} /> : tab === "read" ? <ReadOnlyDemo blob={blob} /> : <StatesDemo />}
+      </TabPanel>
+    </div>
+  );
+}

package/registry/blocks/pdf-viewer/helpers.js

@@ -0,0 +1,270 @@
+// The viewer's plain maths — search, page geometry, highlight rectangles.
+// No DOM and no pdf.js here, so all of it runs in node (and is tested
+// there) and on the server.
+
+// ---- search -----------------------------------------------------------------
+
+const fold = (s) => String(s ?? "").toLocaleLowerCase();
+
+/** Every match of `query` in the pages' text, in reading order.
+ *
+ *    pages  [[str, str, …], …] — each page's text items as pdf.js gives
+ *           them (getTextContent().items[].str), page 1 first
+ *    query  the text looked for, case-insensitive; under 2 characters
+ *           finds nothing (a single letter matches everywhere)
+ *
+ *  → [{ page (1-based), item, start, length }]. A match inside one text
+ *  item only: pdf.js splits lines into items, and a phrase broken across
+ *  two lines is not found (the same as most viewers' quick find). */
+export function findMatches(pages, query) {
+  const q = fold(query).trim();
+  if (q.length < 2) return [];
+  const out = [];
+  (pages ?? []).forEach((items, p) => {
+    (items ?? []).forEach((str, item) => {
+      const s = fold(str);
+      let at = s.indexOf(q);
+      while (at !== -1) {
+        out.push({ page: p + 1, item, start: at, length: q.length });
+        at = s.indexOf(q, at + q.length);
+      }
+    });
+  });
+  return out;
+}
+
+const ESCAPES = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" };
+export const escapeHtml = (s) => String(s ?? "").replace(/[&<>"']/g, (c) => ESCAPES[c]);
+
+/** One text item's HTML with its matches wrapped in <mark>: the text
+ *  layer's custom renderer. `current` is the start offset of the match
+ *  that is selected in this item (or -1); it gets `currentClass` and
+ *  data-current, the others `markClass`. Everything else is escaped. */
+export function markItem(str, matches, { current = -1, markClass = "", currentClass = "" } = {}) {
+  if (!matches?.length) return escapeHtml(str);
+  let html = "";
+  let at = 0;
+  for (const m of [...matches].sort((a, b) => a.start - b.start)) {
+    if (m.start < at) continue;
+    html += escapeHtml(str.slice(at, m.start));
+    const cur = m.start === current;
+    html += `<mark class="${cur ? currentClass : markClass}"${cur ? ' data-current="true"' : ""}>${escapeHtml(str.slice(m.start, m.start + m.length))}</mark>`;
+    at = m.start + m.length;
+  }
+  return html + escapeHtml(str.slice(at));
+}
+
+/** Matches grouped for fast lookup while rendering: "page:item" → [match]. */
+export function indexMatches(matches) {
+  const map = new Map();
+  for (const m of matches ?? []) {
+    const k = `${m.page}:${m.item}`;
+    if (!map.has(k)) map.set(k, []);
+    map.get(k).push(m);
+  }
+  return map;
+}
+
+/** A short excerpt around a match, for a result line: "…the renewal fee of…". */
+export function excerpt(str, start, length, room = 28) {
+  const s = String(str ?? "");
+  const a = Math.max(0, start - room);
+  const b = Math.min(s.length, start + length + room);
+  return `${a > 0 ? "…" : ""}${s.slice(a, b).trim()}${b < s.length ? "…" : ""}`;
+}
+
+// ---- pages and zoom ---------------------------------------------------------
+
+/** The zoom steps the − and + buttons walk. */
+export const ZOOM_STEPS = [0.5, 0.67, 0.75, 0.9, 1, 1.1, 1.25, 1.5, 1.75, 2, 2.5, 3, 4];
+export const MIN_ZOOM = ZOOM_STEPS[0];
+export const MAX_ZOOM = ZOOM_STEPS[ZOOM_STEPS.length - 1];
+
+/** The next zoom step past `scale` in `dir` (+1 in, -1 out). */
+export function stepZoom(scale, dir) {
+  if (dir > 0) return ZOOM_STEPS.find((z) => z > scale + 0.001) ?? MAX_ZOOM;
+  return [...ZOOM_STEPS].reverse().find((z) => z < scale - 0.001) ?? MIN_ZOOM;
+}
+
+export const clampZoom = (z) => Math.min(MAX_ZOOM, Math.max(MIN_ZOOM, Number(z) || 1));
+
+/** The scale at which the widest page fills `width` (px) — "fit width" —
+ *  or, with `height`, at which the tallest fits both ways — "fit page". */
+export function fitScale(sizes, width, height) {
+  if (!sizes?.length || !(width > 0)) return 1;
+  const w = Math.max(...sizes.map((s) => s.width));
+  let z = width / w;
+  if (height > 0) z = Math.min(z, height / Math.max(...sizes.map((s) => s.height)));
+  return clampZoom(Math.round(z * 1000) / 1000);
+}
+
+/** Where each page starts in the scrolling column: the page sizes at
+ *  scale 1, times `scale`, with `gap` px between and `pad` px above the
+ *  first. → { tops: [px], heights: [px], total } */
+export function layoutPages(sizes, scale, gap = 16, pad = 16) {
+  const tops = [];
+  const heights = [];
+  let y = pad;
+  for (const s of sizes ?? []) {
+    tops.push(y);
+    const h = Math.round(s.height * scale);
+    heights.push(h);
+    y += h + gap;
+  }
+  return { tops, heights, total: y - gap + pad };
+}
+
+/** The page (1-based) shown at `y` px down the column: the last page
+ *  whose top is at or above it. */
+export function pageAt(tops, y) {
+  if (!tops?.length) return 1;
+  let lo = 0;
+  let hi = tops.length - 1;
+  while (lo < hi) {
+    const mid = (lo + hi + 1) >> 1;
+    if (tops[mid] <= y) lo = mid;
+    else hi = mid - 1;
+  }
+  return lo + 1;
+}
+
+/** The pages (1-based, inclusive) that touch the window [top, bottom],
+ *  widened by `overscan` pages each way: the ones worth drawing. */
+export function visiblePages(layout, top, bottom, overscan = 1) {
+  const n = layout?.tops?.length ?? 0;
+  if (!n) return [1, 0];
+  const first = pageAt(layout.tops, top);
+  const last = pageAt(layout.tops, bottom);
+  return [Math.max(1, first - overscan), Math.min(n, last + overscan)];
+}
+
+/** Where a page is, as a share of the way down it (0…1) at `y`: kept
+ *  across a zoom so the same line stays in view. */
+export function anchorAt(layout, y) {
+  const page = pageAt(layout.tops, y);
+  const top = layout.tops[page - 1] ?? 0;
+  const h = layout.heights[page - 1] || 1;
+  return { page, frac: Math.min(1, Math.max(0, (y - top) / h)) };
+}
+
+// ---- highlights -------------------------------------------------------------
+
+/** The screen rectangles of a text selection → the highlight's rectangles
+ *  on its page: fractions of the page's box (0…1), so they hold at any
+ *  zoom. Rectangles outside the page are dropped; slivers (a line end,
+ *  a space) are dropped; rectangles on the same line are merged.
+ *
+ *    rects  [{ left, top, width, height }] — client rects of the range
+ *    box    { left, top, width, height } — the page's client rect */
+export function toPageRects(rects, box) {
+  if (!box?.width || !box?.height) return [];
+  const out = [];
+  for (const r of rects ?? []) {
+    const left = Math.max(r.left, box.left);
+    const right = Math.min(r.left + r.width, box.left + box.width);
+    const top = Math.max(r.top, box.top);
+    const bottom = Math.min(r.top + r.height, box.top + box.height);
+    if (right - left < 1 || bottom - top < 2) continue;
+    out.push({ x: (left - box.left) / box.width, y: (top - box.top) / box.height, w: (right - left) / box.width, h: (bottom - top) / box.height });
+  }
+  return mergeRects(out);
+}
+
+/** Merge rectangles on the same line (their vertical middles within half
+ *  a line of each other) that touch or nearly touch; sorted top to
+ *  bottom, left to right. Numbers are rounded to 5 places (plenty for a
+ *  page, and a saved highlight stays small). */
+export function mergeRects(rects, gap = 0.01) {
+  const sorted = [...(rects ?? [])].filter((r) => r.w > 0 && r.h > 0).sort((a, b) => a.y + a.h / 2 - (b.y + b.h / 2) || a.x - b.x);
+  const out = [];
+  for (const r of sorted) {
+    const last = out[out.length - 1];
+    const sameLine = last && Math.abs(last.y + last.h / 2 - (r.y + r.h / 2)) < Math.min(last.h, r.h) / 2;
+    if (sameLine && r.x <= last.x + last.w + gap) {
+      const x = Math.min(last.x, r.x);
+      const y = Math.min(last.y, r.y);
+      last.w = Math.max(last.x + last.w, r.x + r.w) - x;
+      last.h = Math.max(last.y + last.h, r.y + r.h) - y;
+      last.x = x;
+      last.y = y;
+    } else out.push({ ...r });
+  }
+  const r5 = (n) => Math.round(n * 1e5) / 1e5;
+  return out
+    .map((r) => ({ x: r5(r.x), y: r5(r.y), w: r5(r.w), h: r5(r.h) }))
+    .sort((a, b) => a.y - b.y || a.x - b.x);
+}
+
+/** Is the point (fractions of the page) inside any of the rectangles? */
+export const hitRects = (rects, px, py) => (rects ?? []).some((r) => px >= r.x && px <= r.x + r.w && py >= r.y && py <= r.y + r.h);
+
+/** The highlight under a point on a page, the newest first. */
+export function highlightAt(highlights, page, px, py) {
+  for (let i = (highlights ?? []).length - 1; i >= 0; i--) {
+    const h = highlights[i];
+    if (h.page === page && hitRects(h.rects, px, py)) return h;
+  }
+  return null;
+}
+
+/** Highlights sorted as they read: by page, then top to bottom. */
+export function sortHighlights(highlights) {
+  const top = (h) => Math.min(...(h.rects?.length ? h.rects.map((r) => r.y) : [0]));
+  const page = (h) => h.page || Infinity;
+  return [...(highlights ?? [])].sort((a, b) => page(a) - page(b) || top(a) - top(b));
+}
+
+/** A text item from pdf.js (getTextContent().items[i]) → its place on
+ *  the page in PDF units: { str, x, y (the baseline, from the bottom), w,
+ *  h (the font size) }. */
+export function itemBox(item) {
+  const t = item?.transform ?? [1, 0, 0, 1, 0, 0];
+  return { str: item?.str ?? "", x: t[4], y: t[5], w: item?.width ?? 0, h: item?.height || Math.hypot(t[2], t[3]) || 0 };
+}
+
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/** Where a quote sits on a page: the rectangles (fractions of the page) of
+ *  the first place `quote` appears in its text, case-insensitive, across
+ *  line breaks. How a highlight given only by its words ({ page?, text })
+ *  finds its place — an agent can flag a clause without any geometry.
+ *
+ *    items  the page's items as itemBox gives them
+ *    size   the page's { width, height } in PDF units (its viewport at 1)
+ *
+ *  Within an item the x of a partial match is shared out by characters —
+ *  close for body text, not exact for a proportional face. Unrotated
+ *  pages only. → [] when the words are not on the page. */
+export function rectsForQuote(items, quote, size) {
+  const q = String(quote ?? "").replace(/\s+/g, " ").trim();
+  if (q.length < 2 || !size?.width || !size?.height) return [];
+  let joined = "";
+  const spans = [];
+  (items ?? []).forEach((it, i) => {
+    if (!it?.str) return;
+    if (joined && !/\s$/.test(joined)) joined += " ";
+    spans.push({ i, from: joined.length, to: joined.length + it.str.length });
+    joined += it.str;
+  });
+  const m = new RegExp(escapeRe(q).replace(/ /g, "\\s+"), "i").exec(joined);
+  if (!m) return [];
+  const a = m.index;
+  const b = a + m[0].length;
+  const rects = [];
+  for (const sp of spans) {
+    if (sp.to <= a || sp.from >= b) continue;
+    const it = items[sp.i];
+    const len = it.str.length || 1;
+    const s0 = Math.max(a, sp.from) - sp.from;
+    const s1 = Math.min(b, sp.to) - sp.from;
+    const x = it.x + (it.w * s0) / len;
+    const w = (it.w * (s1 - s0)) / len;
+    const top = it.y + it.h * 0.9;
+    const bottom = it.y - it.h * 0.25;
+    rects.push({ x: x / size.width, y: 1 - top / size.height, w: w / size.width, h: (top - bottom) / size.height });
+  }
+  return mergeRects(rects);
+}
+
+/** "Page 3". */
+export const pageLabel = (n) => `Page ${n}`;

package/registry/blocks/pdf-viewer/index.js

@@ -0,0 +1,8 @@
+// The PdfViewer block — `makersclaw add pdf-viewer`. Fixed: compose it
+// through its props (README.md beside this file). The helpers (search,
+// page geometry, highlight rectangles) run anywhere, the server included;
+// the blocks built on this one (proposal-accept, contract review…) import
+// it, never react-pdf or pdfjs-dist directly.
+export { PdfViewer, usePdfViewer } from "./pdf-viewer";
+export { HIGHLIGHT_TONES } from "./notes";
+export { findMatches, toPageRects, mergeRects, sortHighlights, highlightAt, fitScale, ZOOM_STEPS } from "./helpers";