makersclaw 0.7.0 → 0.8.1

package/registry/blocks/time-grid/demo.jsx

@@ -0,0 +1,279 @@
+"use client";
+
+// TimeGrid in the states a screen meets — the gallery's and the smoke
+// test's surface. Not installed into apps: `makersclaw add time-grid` lays
+// index.js, time-grid.jsx and grid-model.js only.
+//   Week          a planner's week: goals above the days, meetings that are
+//                 locked, focus blocks in pencil, Keep, Dismiss, Keep all
+//                 (it says what it will do), a clash, a day's total
+//   Inbox         proposals on their hour with a tag hanging off the
+//                 selected one, a clash hatched, a moved meeting's "was"
+//   Narrow        the week in a 320 px column: one day at a time
+//   Seven days    a full week, kinds told apart by colour
+//   One, long     one event; words with no break to wrap at
+//   Empty, loading, failed, read-only
+import { useMemo, useState } from "react";
+import { Switch } from "../components/ui";
+import { GoalStrip, TimeGrid, hoursOf, loadOf, timeGridDragProps } from "../components/blocks/time-grid";
+
+const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+
+const DAYS = ["2026-09-21", "2026-09-22", "2026-09-23", "2026-09-24", "2026-09-25"];
+const WEEK = [...DAYS, "2026-09-26", "2026-09-27"];
+const TODAY = "2026-09-24";
+
+const KINDS = {
+  focus: { label: "Focus", tone: "primary", solid: true },
+  meeting: { label: "Meeting", tone: "neutral", locked: true },
+  admin: { label: "Admin", tone: "success" },
+  break: { label: "Break", tone: "warning" },
+  personal: { label: "Personal", hue: 5 },
+};
+
+const MEETINGS = [
+  { id: "m1", date: DAYS[0], start: "09:30", end: "10:00", title: "Standup", kind: "meeting" },
+  { id: "m2", date: DAYS[1], start: "09:30", end: "10:00", title: "Standup", kind: "meeting" },
+  { id: "m3", date: DAYS[1], start: "14:00", end: "15:00", title: "Pricing review with Tom", kind: "meeting" },
+  { id: "m4", date: DAYS[2], start: "09:30", end: "10:00", title: "Standup", kind: "meeting" },
+  { id: "m5", date: DAYS[3], start: "09:30", end: "10:00", title: "Standup", kind: "meeting" },
+  { id: "m6", date: DAYS[3], start: "11:00", end: "12:00", title: "Candidate call", kind: "meeting" },
+  { id: "m7", date: DAYS[4], start: "09:30", end: "10:00", title: "Standup", kind: "meeting" },
+  { id: "f0", date: DAYS[2], start: "13:00", end: "14:30", title: "Support lead scorecard", kind: "focus", done: true },
+];
+
+const DRAFT = [
+  { id: "p1", date: DAYS[0], start: "10:15", end: "12:15", title: "Pricing page copy", kind: "focus", note: "pencilled in Mon 06:00" },
+  { id: "p2", date: DAYS[0], start: "14:00", end: "15:00", title: "Inbox and approvals", kind: "admin" },
+  { id: "p3", date: DAYS[1], start: "10:30", end: "12:30", title: "Draft the offer letter template", kind: "focus", note: "due Thursday; the morning before standup" },
+  { id: "p4", date: DAYS[2], start: "09:00", end: "11:00", title: "Screen support lead candidates", kind: "focus" },
+  { id: "p5", date: DAYS[3], start: "10:30", end: "12:30", title: "Ship the pricing page", kind: "focus" },
+  { id: "p6", date: DAYS[4], start: "13:00", end: "15:00", title: "Friday review", kind: "focus" },
+];
+
+const GOALS = [
+  { id: "g1", title: "Pricing page live with the new tiers", state: "pencil", mark: "pencilled in" },
+  { id: "g2", title: "Offer letter template approved", state: "pencil", mark: "pencilled in" },
+  { id: "g3", title: "Support lead job post live", state: "ink", meta: "kept" },
+  { id: "g4", title: "Quarterly numbers sent to the board", state: "done", meta: "done" },
+];
+
+function useWeek() {
+  const [events, setEvents] = useState(MEETINGS);
+  const [proposals, setProposals] = useState(DRAFT);
+  const [log, setLog] = useState("");
+  const [selected, setSelected] = useState(null);
+
+  const keepOne = (id, state) => setProposals((all) => all.map((p) => (p.id === id ? { ...p, state } : p)));
+  const onAction = async (item, id) => {
+    await wait(300);
+    if (id === "dismiss") setProposals((all) => all.filter((p) => p.id !== item.id));
+    else keepOne(item.id, id === "keep" ? "kept" : "pencil");
+    setLog(`${id}: ${item.title}`);
+    return { ok: true };
+  };
+  const onKeepAll = async (plan) => {
+    await wait(400);
+    setProposals((all) => all.map((p) => (plan.keep.includes(p.id) ? { ...p, state: "kept" } : p)));
+    setLog(`Keep all: ${plan.keep.length} blocks`);
+    return { ok: true };
+  };
+  const onChange = async (item, change, meta) => {
+    await wait(250);
+    if (item.id === "p4") return { ok: false, error: "The calendar is not answering. Try again." };
+    const patch = (all) => all.map((x) => (x.id === item.id ? { ...x, date: change.date, start: change.start, end: change.end } : x));
+    if (meta.proposal) setProposals(patch);
+    else setEvents(patch);
+    setLog(`${change.mode}: ${item.title} → ${change.date} ${change.start}–${change.end}`);
+    return { ok: true };
+  };
+  const onCompose = ({ date, start, end }) => {
+    setEvents((all) => [...all, { id: `n${all.length}`, date, start, end, title: "New block", kind: "focus" }]);
+    setLog(`Made ${date} ${start}–${end}`);
+  };
+  const onDrop = async (item, slot) => {
+    await wait(300);
+    setEvents((all) => [...all, { id: `d${all.length}`, ...slot, title: item.title, kind: "admin" }]);
+    return { ok: true };
+  };
+  return { events, proposals, log, selected, setSelected, onAction, onKeepAll, onChange, onCompose, onDrop, reset: () => { setEvents(MEETINGS); setProposals(DRAFT); setLog(""); } };
+}
+
+const notesOf = (events, proposals) => {
+  const out = {};
+  for (const d of DAYS) {
+    const all = [...events, ...proposals.filter((p) => p.state === "kept")];
+    const mins = loadOf(all.map((i) => ({ ...i, s: Number(i.start.slice(0, 2)) * 60 + Number(i.start.slice(3)), e: Number(i.end.slice(0, 2)) * 60 + Number(i.end.slice(3)) })), d);
+    out[d] = { text: `${hoursOf(mins)} of 9 h`, tone: mins > 9 * 60 ? "danger" : "neutral" };
+  }
+  return out;
+};
+
+const MAIL_EVENTS = [
+  { id: "e1", date: DAYS[0], start: "09:30", end: "10:00", title: "Standup" },
+  { id: "e2", date: DAYS[1], start: "11:00", end: "12:00", title: "Board prep" },
+  { id: "e3", date: DAYS[3], start: "14:30", end: "15:15", title: "1:1 with Tom" },
+  { id: "e4", date: DAYS[3], allDay: true, title: "Offsite, Lisbon" },
+];
+const MAIL_PROPOSALS = [
+  { id: "x1", date: DAYS[3], start: "15:00", end: "15:30", title: "Pilot scope for Q4 with Priya", kind: "meeting", tag: { quote: "Thursday at 3pm your time", source: "Priya Raman · Re: Pilot scope for Q4 · 11:25" } },
+  { id: "x2", date: DAYS[1], start: "16:00", end: "16:30", title: "Intro call with Dana", kind: "meeting", tag: { quote: "Tuesday at 4?", source: "Dana Whitfield · Re: Intro · 09:02" } },
+  { id: "x3", date: DAYS[2], start: "10:00", end: "10:30", title: "Send the signed order form", kind: "todo", unsure: true },
+  { id: "x4", date: DAYS[0], start: "15:00", end: "15:45", title: "Monday is gone too", kind: "meeting", state: "was" },
+  { id: "x5", date: DAYS[4], start: "09:00", end: "09:30", title: "Review the vendor contract", kind: "meeting", state: "failed" },
+];
+const MAIL_KINDS = { meeting: { label: "Meeting", hue: 1 }, deadline: { label: "Deadline", hue: 2 }, todo: { label: "To-do", hue: 4 } };
+
+const LONG = "Supercalifragilisticexpialidocious".repeat(4);
+
+function Section({ title, children, note }) {
+  return (
+    <section className="grid gap-3">
+      <h3 className="m-0 text-base font-semibold">{title}</h3>
+      {children}
+      {note ? <p className="m-0 text-xs text-muted-foreground">{note}</p> : null}
+    </section>
+  );
+}
+
+export default function TimeGridDemo() {
+  const week = useWeek();
+  const [mailSel, setMailSel] = useState("x1");
+  const [mail, setMail] = useState(MAIL_PROPOSALS);
+  const [readOnly, setReadOnly] = useState(false);
+  const notes = useMemo(() => notesOf(week.events, week.proposals), [week.events, week.proposals]);
+  const kept = week.proposals.filter((p) => p.state === "kept").length;
+
+  return (
+    <div className="grid gap-10 p-6">
+      <Section title="A planner’s week" note={week.log ? `Last: ${week.log}` : "Press Keep on a block, Keep all, drag a block (the Screen support lead one fails once), or drag across free hours."}>
+        <div className="flex items-center gap-4">
+          <Switch id="tg-ro" label="Read-only" checked={readOnly} onChange={(e) => setReadOnly(e.target.checked)} />
+          <button type="button" className="justify-self-start text-xs underline" onClick={week.reset}>
+            Put it all back in pencil
+          </button>
+        </div>
+        <TimeGrid
+          label="Week 39"
+          days={DAYS}
+          today={TODAY}
+          now="10:20"
+          startHour={5}
+          endHour={21}
+          workStart="08:30"
+          workEnd="17:30"
+          scrollTo="08:00"
+          height="34rem"
+          kinds={KINDS}
+          events={week.events}
+          proposals={week.proposals}
+          dayNotes={notes}
+          selectedId={week.selected}
+          onSelect={week.setSelected}
+          keepAll={{ label: "Keep all" }}
+          onAction={week.onAction}
+          onKeepAll={week.onKeepAll}
+          onChange={week.onChange}
+          onCompose={week.onCompose}
+          onDrop={week.onDrop}
+          readOnly={readOnly}
+          explainBlock={(b) => `${b.title} is on your calendar. Change it there.`}
+          explainOffHours={({ before }) => (before ? "Before your working day. Nothing is pencilled in here." : "After your working day.")}
+          above={<GoalStrip items={GOALS} summary={{ label: "Focus", value: hoursOf(10 * 60 + kept * 120), of: 15, unit: "h", note: `${kept} kept` }} />}
+        />
+        <ul className="m-0 grid list-none gap-1 p-0 text-xs">
+          {["Reply to Priya", "Book the offsite flights"].map((t, i) => (
+            <li key={t} {...timeGridDragProps({ id: `t${i}`, title: t, minutes: 45 })} className="w-fit cursor-grab rounded-md border border-border bg-card px-2 py-1">
+              {t} <span className="text-muted-foreground">drag onto the week</span>
+            </li>
+          ))}
+        </ul>
+      </Section>
+
+      <Section title="Inbox to calendar: words pinned to the hour" note="The selected proposal’s tag quotes the sender. The clash is hatched before anything is added; “was” is the meeting it replaces; the last one did not go in.">
+        <TimeGrid
+          label="Week 39 inbox"
+          days={DAYS}
+          today={TODAY}
+          now="13:10"
+          startHour={8}
+          endHour={19}
+          hourHeight={52}
+          height="30rem"
+          corner="BST"
+          pencilColor="kind"
+          kinds={MAIL_KINDS}
+          events={MAIL_EVENTS}
+          proposals={mail}
+          selectedId={mailSel}
+          onSelect={setMailSel}
+          onAction={async (item, id) => {
+            await wait(250);
+            if (id === "dismiss") setMail((all) => all.filter((p) => p.id !== item.id));
+            else setMail((all) => all.map((p) => (p.id === item.id ? { ...p, state: id === "keep" ? "kept" : "pencil" } : p)));
+            return { ok: true };
+          }}
+        />
+      </Section>
+
+      <Section title="Narrow (320): one day at a time">
+        <div className="w-80 max-w-full">
+          <TimeGrid label="Narrow" days={DAYS} today={TODAY} now="10:20" startHour={7} endHour={19} height="24rem" kinds={KINDS} events={MEETINGS} proposals={DRAFT} defaultSelectedId="p5" onAction={async () => ({ ok: true })} />
+        </div>
+      </Section>
+
+      <Section title="Seven days, five kinds">
+        <TimeGrid
+          label="Seven days"
+          days={WEEK}
+          today={TODAY}
+          now="10:20"
+          startHour={7}
+          endHour={20}
+          height="26rem"
+          kinds={KINDS}
+          events={[
+            ...MEETINGS,
+            { id: "b1", date: DAYS[0], start: "12:30", end: "13:15", title: "Lunch", kind: "break" },
+            { id: "b2", date: WEEK[5], start: "09:00", end: "11:00", title: "Climbing", kind: "personal" },
+            { id: "b3", date: WEEK[6], start: "10:00", end: "12:00", title: "Weekly shop and cook", kind: "personal" },
+          ]}
+        />
+      </Section>
+
+      <Section title="One event">
+        <TimeGrid label="One" days={[DAYS[0]]} startHour={8} endHour={14} height="16rem" kinds={KINDS} events={[MEETINGS[0]]} />
+      </Section>
+
+      <Section title="Very long words">
+        <TimeGrid
+          label="Long"
+          days={DAYS.slice(0, 3)}
+          startHour={8}
+          endHour={16}
+          height="18rem"
+          kinds={KINDS}
+          events={[{ id: "l1", date: DAYS[0], start: "09:00", end: "11:00", title: LONG, kind: "admin", caption: LONG }]}
+          proposals={[{ id: "l2", date: DAYS[1], start: "09:00", end: "11:00", title: LONG, kind: "focus", label: LONG, tag: { quote: LONG, source: LONG } }]}
+          defaultSelectedId="l2"
+          onAction={async () => ({ ok: true })}
+        />
+      </Section>
+
+      <Section title="Empty">
+        <TimeGrid label="Empty" days={DAYS} today={TODAY} startHour={8} endHour={14} height="14rem" emptyText="No meetings yet. Connect a calendar and they appear here." />
+      </Section>
+
+      <Section title="Loading">
+        <TimeGrid label="Loading" days={DAYS} today={TODAY} startHour={8} endHour={16} height="16rem" status="loading" />
+      </Section>
+
+      <Section title="Failed">
+        <TimeGrid label="Failed" days={DAYS} status="failed" error="The calendar did not answer. Nothing was changed." onRetry={() => {}} />
+      </Section>
+
+      <Section title="Read-only">
+        <TimeGrid label="Read-only" days={DAYS} today={TODAY} startHour={8} endHour={17} height="18rem" kinds={KINDS} events={MEETINGS} proposals={DRAFT} readOnly />
+      </Section>
+    </div>
+  );
+}

package/registry/blocks/time-grid/grid-model.js

@@ -0,0 +1,322 @@
+// The time grid's arithmetic: times as minutes, days as 'YYYY-MM-DD', how
+// overlapping blocks share a day's width, which pencilled blocks clash with
+// what is already there, what "Keep all" will do (in words, before it does
+// it), and where a dragged block lands. Pure: no React, no DOM, no clock.
+// The component (time-grid.jsx) draws what this returns;
+// test/time-grid.test.mjs pins it.
+
+export const WEEKDAYS_EN = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
+
+/** '09:30', '9:30', '09:30:00' or '2026-09-24T09:30' → 570; a number passes (rounded); else null. */
+export function toMin(v) {
+  if (typeof v === "number") return Number.isFinite(v) ? Math.round(v) : null;
+  const m = /(?:^|T|\s)(\d{1,2}):(\d{2})/.exec(String(v ?? ""));
+  if (!m) return null;
+  const h = Number(m[1]);
+  const mi = Number(m[2]);
+  return h > 24 || mi > 59 ? null : h * 60 + mi;
+}
+
+/** 570 → '09:30' (what a save sends). */
+export const toHHMM = (min) => `${String(Math.floor(min / 60)).padStart(2, "0")}:${String(min % 60).padStart(2, "0")}`;
+
+/** 570 → '9:30', 1020 → '17:00': the grid's printed clock (24-hour). */
+export const clock = (min) => `${Math.floor(min / 60) % 24}:${String(min % 60).padStart(2, "0")}`;
+
+/** '9:00–11:30'. */
+export const span = (s, e, fmt = clock) => `${fmt(s)}–${fmt(e)}`;
+
+/** 90 → '1 h 30 min', 45 → '45 min', 120 → '2 h'. */
+export function durationWords(min) {
+  const m = Math.max(0, Math.round(min));
+  const h = Math.floor(m / 60);
+  const r = m % 60;
+  if (!h) return `${r} min`;
+  return r ? `${h} h ${r} min` : `${h} h`;
+}
+
+/** 320 → '5.3' (hours, one decimal, no trailing .0): for a day's total beside its header. */
+export function hoursOf(min, digits = 1) {
+  const f = 10 ** digits;
+  const v = Math.round((min / 60) * f) / f;
+  return String(v);
+}
+
+/** 0 = Sunday … 6 = Saturday, from 'YYYY-MM-DD'; 0 for anything else. */
+export function weekdayIndex(iso) {
+  const m = /^(\d{4})-(\d{2})-(\d{2})/.exec(String(iso ?? ""));
+  return m ? new Date(Date.UTC(Number(m[1]), Number(m[2]) - 1, Number(m[3]))).getUTCDay() : 0;
+}
+
+/** The day of the month as a number ('2026-09-24' → 24). */
+export const dateNum = (iso) => Number(String(iso ?? "").slice(8, 10)) || 0;
+
+export const clamp = (v, a, b) => Math.max(a, Math.min(b, v));
+
+export const snapRound = (m, snap) => Math.round(m / snap) * snap;
+export const snapFloor = (m, snap) => Math.floor(m / snap) * snap;
+
+// ---- reading what the app hands in -------------------------------------
+
+/**
+ * An item as the grid draws it: minutes for its times, a day it can be
+ * placed on, and nothing else invented. An item with no day in `days` is
+ * dropped; a timed item with no length gets one `snap` long; a timed item
+ * wholly outside [lo, hi] is dropped, and one that crosses an edge is cut
+ * to it (`cutStart` / `cutEnd` say so).
+ */
+export function readItem(raw, { days, lo, hi, snap = 15, pencil = false }) {
+  if (!raw || raw.id == null) return null;
+  if (!days.includes(raw.date)) return null;
+  const base = { ...raw, id: String(raw.id), pencil };
+  if (raw.allDay) return { ...base, allDay: true, s: null, e: null };
+  let s = toMin(raw.start);
+  let e = toMin(raw.end);
+  if (s == null) return { ...base, allDay: true, s: null, e: null };
+  if (e == null || e <= s) e = s + snap;
+  if (e <= lo || s >= hi) return null;
+  return { ...base, allDay: false, s: Math.max(s, lo), e: Math.min(e, hi), cutStart: s < lo, cutEnd: e > hi };
+}
+
+/** Overlapping blocks share a day's width, calendar-style: lane and lane count per id. */
+export function gridLanes(items) {
+  const out = new Map();
+  const sorted = [...items].sort((a, b) => a.s - b.s || b.e - a.e);
+  let group = [];
+  let groupEnd = -1;
+  const flush = () => {
+    const ends = [];
+    for (const it of group) {
+      let lane = ends.findIndex((end) => end <= it.s);
+      if (lane < 0) {
+        lane = ends.length;
+        ends.push(it.e);
+      } else ends[lane] = it.e;
+      out.set(it.id, { lane, lanes: 1 });
+    }
+    for (const it of group) out.get(it.id).lanes = ends.length;
+    group = [];
+    groupEnd = -1;
+  };
+  for (const it of sorted) {
+    if (group.length && it.s >= groupEnd) flush();
+    group.push(it);
+    groupEnd = Math.max(groupEnd, it.e);
+  }
+  if (group.length) flush();
+  return out;
+}
+
+// ---- pencil and ink ------------------------------------------------------
+
+/** What a proposal can be. `pencil` is the default. */
+export const PENCIL_STATES = ["pencil", "kept", "failed", "replaced", "was"];
+
+/** The look an item is drawn in: ink (an event, or a kept proposal), or one of the pencil looks. */
+export function lookOf(item) {
+  if (!item.pencil) return "ink";
+  const st = PENCIL_STATES.includes(item.state) ? item.state : "pencil";
+  if (st === "kept") return "ink";
+  if (st === "pencil" && item.unsure) return "unsure";
+  return st;
+}
+
+/** Is this proposal still waiting for a person? (Failed and replaced ones are not asked again; "was" is only a marker.) */
+export const isWaiting = (item) => item.pencil && lookOf(item) !== "ink" && lookOf(item) !== "failed" && lookOf(item) !== "replaced" && lookOf(item) !== "was";
+
+/** The proposals that are waiting, in the order a person reads a week: by day, then by time. */
+export function waitingOrder(items, days) {
+  return items
+    .filter(isWaiting)
+    .sort((a, b) => days.indexOf(a.date) - days.indexOf(b.date) || (a.s ?? -1) - (b.s ?? -1) || (a.id < b.id ? -1 : 1));
+}
+
+/** J (1) and K (-1): the id of the next waiting proposal; none selected → the first (or the last going back). */
+export function walkProposal(items, days, currentId, dir = 1) {
+  const list = waitingOrder(items, days);
+  if (!list.length) return null;
+  const at = list.findIndex((i) => i.id === String(currentId));
+  if (at < 0) return (dir >= 0 ? list[0] : list[list.length - 1]).id;
+  return list[(at + dir + list.length) % list.length].id;
+}
+
+/**
+ * The ids whose look changed from a pencil look to ink between two renders:
+ * the ones that were just kept (or committed). In the order they sit in
+ * the week, so they can ink in one by one. `before` is a Map id → look.
+ */
+export function newlyInked(before, items, days) {
+  const out = items.filter((i) => before.get(i.id) && before.get(i.id) !== "ink" && lookOf(i) === "ink");
+  return out
+    .sort((a, b) => days.indexOf(a.date) - days.indexOf(b.date) || (a.s ?? -1) - (b.s ?? -1))
+    .map((i) => i.id);
+}
+
+// ---- clashes -------------------------------------------------------------
+
+/**
+ * Where each waiting proposal overlaps something that is already there
+ * (ink events, and kept proposals; never another waiting one unless
+ * `among` is true). Returns Map id → [{ withId, title, s, e, at }] where s..e
+ * is the overlap, in minutes and `at` is when the other one starts. All-day items never clash.
+ */
+export function clashesOf(items, { among = false } = {}) {
+  const out = new Map();
+  const timed = items.filter((i) => !i.allDay && i.s != null);
+  for (const p of timed) {
+    if (!isWaiting(p)) continue;
+    for (const o of timed) {
+      if (o.id === p.id || o.date !== p.date) continue;
+      const solid = lookOf(o) === "ink";
+      if (!solid && !(among && isWaiting(o))) continue;
+      const s = Math.max(p.s, o.s);
+      const e = Math.min(p.e, o.e);
+      if (e <= s) continue;
+      if (!out.has(p.id)) out.set(p.id, []);
+      out.get(p.id).push({ withId: o.id, title: o.title ?? "", s, e, at: o.s });
+    }
+  }
+  return out;
+}
+
+/** "Standup 9:30", or "Standup 9:30 and Review 11:00" / "Standup 9:30 and 2 more". */
+export function namesOf(list, fmt = clock, max = 2) {
+  const names = list.map((c) => {
+    const t = c.at ?? c.s;
+    return t != null ? `${c.title} ${fmt(t)}`.trim() : c.title;
+  });
+  if (names.length <= max) return names.length > 1 ? `${names.slice(0, -1).join(", ")} and ${names[names.length - 1]}` : (names[0] ?? "");
+  return `${names.slice(0, max).join(", ")} and ${names.length - max} more`;
+}
+
+// ---- Keep all: what it will do, said before it does it -------------------
+
+/**
+ * What "Keep all" will do. `skip` names what stays in pencil: "clash" (it
+ * overlaps something) and/or "unsure" (the item says it is). The rest are
+ * kept. Returns
+ *   { keep: [ids], leave: [{ id, title, reason }], counts: [{ kind, label, n }], total, words }
+ * `words` is the sentence the screen shows next to the button.
+ */
+export function planKeepAll(items, { clashes, kinds = {}, skip = ["clash"], fmt = clock } = {}) {
+  const waiting = items.filter(isWaiting);
+  const clash = clashes ?? clashesOf(items);
+  const keep = [];
+  const leave = [];
+  for (const it of waiting) {
+    if (skip.includes("clash") && clash.has(it.id)) leave.push({ id: it.id, title: it.title ?? "", reason: "clash", with: clash.get(it.id) });
+    else if (skip.includes("unsure") && it.unsure) leave.push({ id: it.id, title: it.title ?? "", reason: "unsure" });
+    else keep.push(it);
+  }
+  const byKind = new Map();
+  for (const it of keep) {
+    const k = it.kind ?? "";
+    byKind.set(k, (byKind.get(k) ?? 0) + 1);
+  }
+  const counts = [...byKind].map(([kind, n]) => ({ kind, n, label: kinds[kind]?.label ?? kind }));
+  const total = waiting.length;
+  let words;
+  if (!total) words = "Nothing is waiting in pencil.";
+  else {
+    const head = keep.length
+      ? `Keeps ${keep.length === total ? `all ${total}` : `${keep.length} of ${total}`} in ink${counts.length > 1 || (counts[0] && counts[0].label) ? `: ${counts.map((c) => `${c.n} ${c.label}`.trim()).join(", ")}` : ""}.`
+      : "Nothing can be kept as it is.";
+    const clashed = leave.filter((l) => l.reason === "clash");
+    const unsure = leave.filter((l) => l.reason === "unsure");
+    const tails = [];
+    if (clashed.length)
+      tails.push(
+        clashed.length === 1
+          ? `Leaves ${clashed[0].title ? `“${clashed[0].title}”` : "1"} in pencil: it clashes with ${namesOf(clashed[0].with, fmt, 1)}.`
+          : `Leaves ${clashed.length} in pencil, they clash: ${clashed
+              .slice(0, 2)
+              .map((l) => `${l.title ? `“${l.title}”` : "one"} with ${namesOf(l.with, fmt, 1)}`)
+              .join(", ")}${clashed.length > 2 ? ` and ${clashed.length - 2} more` : ""}.`,
+      );
+    if (unsure.length) tails.push(`Leaves ${unsure.length} in pencil: ${unsure.length === 1 ? "it is" : "they are"} not sure.`);
+    words = [head, ...tails].join(" ");
+  }
+  return { keep: keep.map((i) => i.id), leave, counts, total, words };
+}
+
+// ---- a day's load, for the number beside its header ----------------------
+
+/** Minutes of timed items on `date`, whose look and kind pass `where`. */
+export function loadOf(items, date, where = () => true) {
+  let sum = 0;
+  for (const i of items) if (i.date === date && !i.allDay && i.s != null && where(i)) sum += i.e - i.s;
+  return sum;
+}
+
+// ---- where a gesture lands ----------------------------------------------
+
+/**
+ * The block as it would land. `g` is the gesture ({ kind: "create" | "move"
+ * | "start" | "end", anchor?, offset?, s0?, e0?, date? }), `at` the pointer
+ * as { date, minute } (minute is fractional), `box` the limits
+ * { lo, hi, ws, we, snap }. null when the pointer is nowhere.
+ */
+export function previewOf(g, at, box) {
+  if (!at) return null;
+  const { lo, hi, ws, we, snap } = box;
+  if (g.kind === "create") {
+    const lower = ws ?? lo;
+    const upper = we ?? hi;
+    const cur = clamp(at.minute, lower, upper);
+    let s;
+    let e;
+    if (cur >= g.anchor) {
+      s = g.anchor;
+      e = Math.max(g.anchor + snap, Math.ceil(cur / snap) * snap);
+    } else {
+      s = snapFloor(cur, snap);
+      e = g.anchor + snap;
+    }
+    return { date: g.date, start: clamp(s, lower, upper - snap), end: clamp(e, lower + snap, upper), mode: "create" };
+  }
+  const dur = g.e0 - g.s0;
+  if (g.kind === "move") {
+    const s = clamp(snapRound(at.minute - g.offset, snap), lo, hi - dur);
+    return { id: g.id, date: at.date, start: s, end: s + dur, mode: "move" };
+  }
+  if (g.kind === "end") {
+    const e = clamp(snapRound(at.minute, snap), g.s0 + snap, hi);
+    return { id: g.id, date: g.date, start: g.s0, end: e, mode: "end" };
+  }
+  const s = clamp(snapRound(at.minute, snap), lo, g.e0 - snap);
+  return { id: g.id, date: g.date, start: s, end: g.e0, mode: "start" };
+}
+
+/** An arrow key on a focused block, as the change it asks for (or null). Shift+↑/↓ changes the length. */
+export function keyChange(key, shift, item, { days, lo, hi, snap }) {
+  const dur = item.e - item.s;
+  if (key === "ArrowUp" && shift) return { date: item.date, start: item.s, end: Math.max(item.s + snap, item.e - snap), mode: "end" };
+  if (key === "ArrowDown" && shift) return { date: item.date, start: item.s, end: Math.min(hi, item.e + snap), mode: "end" };
+  if (key === "ArrowUp") {
+    const s = Math.max(lo, item.s - snap);
+    return { date: item.date, start: s, end: s + dur, mode: "move" };
+  }
+  if (key === "ArrowDown") {
+    const s = Math.min(hi - dur, item.s + snap);
+    return { date: item.date, start: s, end: s + dur, mode: "move" };
+  }
+  if (key === "ArrowLeft" || key === "ArrowRight") {
+    const i = days.indexOf(item.date) + (key === "ArrowLeft" ? -1 : 1);
+    if (i < 0 || i >= days.length) return null;
+    return { date: days[i], start: item.s, end: item.e, mode: "move" };
+  }
+  return null;
+}
+
+// ---- the tag and where it hangs ------------------------------------------
+
+/**
+ * A tag hangs off a block. Under it, left-aligned, unless the block is in
+ * the right half of the days (then right-aligned, so it stays inside the
+ * grid) or the room under it runs out (then it hangs above).
+ */
+export function tagPlacement({ dayIndex, dayCount, bottom, top, bodyHeight, tagHeight = 64 }) {
+  const side = dayCount > 1 && dayIndex >= Math.ceil(dayCount / 2) ? "right" : "left";
+  const above = bottom + 6 + tagHeight > bodyHeight && top - 6 - tagHeight >= 0;
+  return { side, above };
+}

package/registry/blocks/time-grid/index.js

@@ -0,0 +1,25 @@
+// The TimeGrid block — `makersclaw add time-grid`. 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 { TimeGrid, GoalStrip, TIME_GRID_MIME, timeGridDragProps } from "./time-grid";
+export {
+  PENCIL_STATES,
+  clashesOf,
+  clock,
+  durationWords,
+  gridLanes,
+  hoursOf,
+  isWaiting,
+  loadOf,
+  lookOf,
+  namesOf,
+  newlyInked,
+  planKeepAll,
+  previewOf,
+  readItem,
+  tagPlacement,
+  toHHMM,
+  toMin,
+  walkProposal,
+  waitingOrder,
+} from "./grid-model";