makersclaw 0.7.0 → 0.8.1

package/registry/blocks/tier-map/tier-model.js

@@ -0,0 +1,318 @@
+// The tier map's data and arithmetic — plain functions, no React, no DOM.
+// They run anywhere (the server, an agent's tool, a test).
+//
+// Items come in flat, the way a table holds them: each row names its
+// parent. buildTierModel turns them into a forest and sorts every item into
+// one of three places:
+//
+//   tree        reachable from a top: drawn in tiers, one layer open at a time
+//   unparented  real (not a draft), not reachable from any top
+//   ghost       a draft (`ghost: true`): drawn apart, dashed, never counted
+//
+// A parent that is not in the list is no parent. A loop of parents is
+// broken at the item that comes first in the list, which becomes parentless.
+// Nothing here hangs on bad data.
+
+/** Equal columns of this many rem, at least, are what a tier needs to sit in one row. */
+export const CARD_REM = 11;
+/** A tier of more cards than this never sits in one row; it stacks. */
+export const MAX_COLUMNS = 8;
+
+/**
+ * The key a tier's layout classes are looked up by: how many equal columns
+ * the widest tier so far needs, 1 to MAX_COLUMNS, or NEVER when a tier has
+ * too many cards to sit in one row.
+ */
+export const NEVER = MAX_COLUMNS + 1;
+export function fitKey(count) {
+  const n = Math.floor(Number(count));
+  if (!(n > 1)) return 1;
+  return n > MAX_COLUMNS ? NEVER : n;
+}
+
+/** The container width, in rem, from which a tier of this fit key sits in one row (Infinity: never). */
+export function thresholdRem(key) {
+  if (key >= NEVER) return Infinity;
+  return key <= 1 ? 0 : key * CARD_REM;
+}
+
+const idOf = (value) => (value == null || value === "" ? null : String(value));
+
+/**
+ * Flat items to a model.
+ *
+ *   items   [{ id, parent?, ghost?, ... }]; any other key is kept on `item`
+ *   tops    ids drawn as the first tier, in that order. Default: the real
+ *           items that have no parent and have children.
+ *
+ * Returns { nodes, order, tops, unparented, ghostRoots, ghostOrder }.
+ * A node is { id, item, ghost, parent, up, kids, tier, group, total }:
+ *   parent  the id it names, after bad ones and loops are dropped (or null)
+ *   up      who it hangs under on screen (null for a top, an unparented card)
+ *   kids    ids drawn under it when it is opened (a draft's kids are drafts)
+ *   tier    0 for a top, 1 for its kids… (-1 for what is not in the tree)
+ *   group   "tree" | "unparented" | "ghost"
+ *   total   everything under it, counting kids of kids
+ */
+export function buildTierModel(items, { tops } = {}) {
+  const nodes = new Map();
+  const order = [];
+  for (const item of Array.isArray(items) ? items : []) {
+    const id = idOf(item?.id);
+    if (id == null || nodes.has(id)) continue;
+    nodes.set(id, { id, item, ghost: item.ghost === true, parent: null, up: null, kids: [], tier: -1, group: "unparented", total: 0 });
+    order.push(id);
+  }
+
+  // The parent each item names, if it is somebody in the list and not itself.
+  for (const id of order) {
+    const node = nodes.get(id);
+    const parent = idOf(node.item.parent);
+    node.parent = parent != null && parent !== id && nodes.has(parent) ? parent : null;
+  }
+  breakLoops(nodes, order);
+
+  // Kids: a real item under a real parent; a draft under a draft.
+  for (const id of order) {
+    const node = nodes.get(id);
+    const parent = node.parent == null ? null : nodes.get(node.parent);
+    if (parent && parent.ghost === node.ghost) parent.kids.push(id);
+  }
+
+  // The tops.
+  const real = (id) => nodes.has(id) && !nodes.get(id).ghost;
+  let topIds;
+  if (Array.isArray(tops)) topIds = [...new Set(tops.map(idOf).filter((id) => id != null && real(id)))];
+  else topIds = order.filter((id) => real(id) && nodes.get(id).parent == null && nodes.get(id).kids.length > 0);
+  const topSet = new Set(topIds);
+  // A top is drawn as a top and nowhere else, so it leaves its parent's kids.
+  for (const id of topIds) {
+    const parent = nodes.get(id).parent;
+    if (parent != null) nodes.get(parent).kids = nodes.get(parent).kids.filter((k) => k !== id);
+  }
+
+  // Walk down from the tops; the first way in wins.
+  const walk = (id, tier, up) => {
+    const node = nodes.get(id);
+    node.tier = tier;
+    node.up = up;
+    node.group = "tree";
+    let total = 0;
+    for (const kid of node.kids) {
+      if (nodes.get(kid).group === "tree") continue;
+      walk(kid, tier + 1, id);
+      total += 1 + nodes.get(kid).total;
+    }
+    node.kids = node.kids.filter((k) => nodes.get(k).up === id && nodes.get(k).group === "tree");
+    node.total = total;
+  };
+  for (const id of topIds) walk(id, 0, null);
+
+  // Real items the tops do not reach.
+  const unparented = order.filter((id) => !nodes.get(id).ghost && nodes.get(id).group !== "tree");
+  for (const id of unparented) {
+    const node = nodes.get(id);
+    node.kids = [];
+    node.up = null;
+  }
+
+  // Drafts: a forest of their own, parents first.
+  const ghostRoots = [];
+  const ghostOrder = [];
+  for (const id of order) {
+    const node = nodes.get(id);
+    if (!node.ghost) continue;
+    node.group = "ghost";
+    node.up = node.parent != null && nodes.get(node.parent).ghost ? node.parent : null;
+    if (node.up == null) ghostRoots.push(id);
+  }
+  const lay = (id, depth) => {
+    ghostOrder.push({ id, depth });
+    const node = nodes.get(id);
+    node.tier = depth;
+    let total = 0;
+    for (const kid of node.kids) {
+      lay(kid, depth + 1);
+      total += 1 + nodes.get(kid).total;
+    }
+    node.total = total;
+  };
+  for (const id of ghostRoots) lay(id, 0);
+
+  return { nodes, order, tops: topIds, unparented, ghostRoots, ghostOrder, isTop: (id) => topSet.has(id) };
+}
+
+// A chain of parents that comes back to itself: the member that comes first
+// in the list becomes parentless, so the rest hang under it.
+function breakLoops(nodes, order) {
+  const place = new Map(order.map((id, i) => [id, i]));
+  const seen = new Map(); // id -> 1 on the walk now, 2 done
+  for (const start of order) {
+    if (seen.has(start)) continue;
+    const walked = [];
+    let cur = start;
+    while (cur != null && !seen.has(cur)) {
+      seen.set(cur, 1);
+      walked.push(cur);
+      cur = nodes.get(cur).parent;
+    }
+    if (cur != null && seen.get(cur) === 1) {
+      const loop = walked.slice(walked.indexOf(cur));
+      let first = loop[0];
+      for (const id of loop) if (place.get(id) < place.get(first)) first = id;
+      nodes.get(first).parent = null;
+    }
+    for (const id of walked) seen.set(id, 2);
+  }
+}
+
+// ---- the open path
+
+/**
+ * The ids that are open, one per tier: the first is a top, the second one
+ * of its kids, and so on. Whatever cannot be (an id that is not there, one
+ * with nothing under it, one that is not under the one before) ends the
+ * path there.
+ */
+export function openPath(model, requested) {
+  const out = [];
+  let level = model.tops;
+  for (const raw of Array.isArray(requested) ? requested : []) {
+    const id = idOf(raw);
+    if (id == null || !level.includes(id)) break;
+    const node = model.nodes.get(id);
+    if (!node.kids.length) break;
+    out.push(id);
+    level = node.kids;
+  }
+  return out;
+}
+
+/**
+ * The path after pressing a card in the tree: the card opens (and what was
+ * open at its tier and below closes), or, if it was open, it closes with
+ * everything under it. Any other id leaves the path as it is.
+ */
+export function togglePath(model, path, id) {
+  const key = idOf(id);
+  const node = key == null ? null : model.nodes.get(key);
+  if (!node || node.group !== "tree" || !node.kids.length) return path;
+  const base = path.slice(0, node.tier);
+  return path[node.tier] === key ? base : [...base, key];
+}
+
+/** The ids to open so that this one is on screen: its parents, top first. */
+export function pathTo(model, id) {
+  const out = [];
+  let node = model.nodes.get(idOf(id));
+  if (!node || node.group !== "tree") return out;
+  while (node && node.up != null) {
+    out.unshift(node.up);
+    node = model.nodes.get(node.up);
+  }
+  return out;
+}
+
+/** The tiers on screen for a path: [{ ids, openId }], the tops first. */
+export function tiersOf(model, path) {
+  const tiers = [];
+  let ids = model.tops;
+  for (let i = 0; ids.length; i += 1) {
+    const openId = path[i] ?? null;
+    tiers.push({ ids, openId });
+    if (openId == null) break;
+    ids = model.nodes.get(openId).kids;
+  }
+  return tiers;
+}
+
+// ---- the keys
+
+/** The cards beside this one: same parent, same group, in order. */
+export function siblingsOf(model, id) {
+  const node = model.nodes.get(idOf(id));
+  if (!node) return [];
+  if (node.group === "unparented") return model.unparented;
+  if (node.group === "ghost") return node.up == null ? model.ghostRoots : model.nodes.get(node.up).kids;
+  return node.up == null ? model.tops : model.nodes.get(node.up).kids;
+}
+
+/**
+ * Where an arrow key goes from a card: ← → the card beside it, ↓ its first
+ * kid, ↑ its parent, Home and End the first and last beside it. null when
+ * there is nowhere to go.
+ */
+export function neighbour(model, id, key) {
+  const node = model.nodes.get(idOf(id));
+  if (!node) return null;
+  const side = siblingsOf(model, node.id);
+  const at = side.indexOf(node.id);
+  switch (key) {
+    case "ArrowLeft":
+      return side[at - 1] ?? null;
+    case "ArrowRight":
+      return side[at + 1] ?? null;
+    case "Home":
+      return side[0] ?? null;
+    case "End":
+      return side[side.length - 1] ?? null;
+    case "ArrowDown":
+      return node.kids[0] ?? null;
+    case "ArrowUp":
+      return node.up ?? null;
+    default:
+      return null;
+  }
+}
+
+// ---- what a card says
+
+/** "6 serving it": the count and the app's words for what is under a card. */
+export function countText(count, label = "below") {
+  const text = typeof label === "function" ? label(count) : `${count} ${label}`;
+  return String(text);
+}
+
+/** A bar on a card: { pct, share } for a value 0..1, or null (no bar). A draft has none. */
+export function barOf(item) {
+  if (!item || item.ghost === true) return null;
+  const v = item.value;
+  if (v == null || v === "" || typeof v === "boolean") return null;
+  const n = Number(v);
+  if (!Number.isFinite(n)) return null;
+  const share = Math.min(1, Math.max(0, n));
+  return { share, pct: Math.round(share * 100) };
+}
+
+export const TONES = ["ink", "quiet", "info", "success", "warning", "danger"];
+
+/**
+ * The bar's colour: one of TONES. `auto` (or none) is ink, and success when
+ * the bar is full; a word that is not a tone is ink. A status only.
+ */
+export function toneOf(tone, share) {
+  if (TONES.includes(tone)) return tone;
+  return share != null && share >= 1 ? "success" : "ink";
+}
+
+// ---- the lines between tiers (percentages of the tier's width)
+
+const round = (n) => Math.round(n * 1000) / 1000;
+
+/** The middle of column `index` of `count` equal columns, in percent of the row. */
+export function centreOf(index, count) {
+  return count > 0 ? round(((index + 0.5) / count) * 100) : 50;
+}
+
+/**
+ * The elbow from a card to the row of its kids, as positions in percent:
+ * `parent` (where the line leaves the card), `from` and `to` (the bar across,
+ * from the leftmost to the rightmost of the parent and every kid), `kids`
+ * (where each kid's line drops).
+ */
+export function elbowOf(parentIndex, parentCount, kidCount) {
+  const parent = centreOf(parentIndex, parentCount);
+  const kids = Array.from({ length: kidCount }, (_, i) => centreOf(i, kidCount));
+  const all = [parent, ...kids];
+  return { parent, from: Math.min(...all), to: Math.max(...all), kids };
+}

package/registry/blocks/time-grid/README.md

@@ -0,0 +1,305 @@
+# TimeGrid
+
+Days side by side on an hour grid, with **the agent's proposals in pencil**.
+
+What is already there is **ink**: an event in its kind's colour, a lock on the
+ones another calendar owns. What the agent suggests is **pencil**: a hatched
+card on a dashed edge, sitting on its hour, with a **tag** hanging off it that
+quotes the words it came from ("Thursday at 3pm your time"). A person keeps a
+block and it inks in: the same block, its colours fading from pencil to ink.
+Keep a few at once and they ink in one by one, in the order of the week.
+
+- **Keep all says what it will do before it does it:** "Keeps 7 of 8 in ink:
+  5 Focus, 2 Admin. Leaves "Offer letter" in pencil: it clashes with Standup
+  9:30."
+- **A clash is hatched where two things overlap**, before anything is kept.
+- **A goals strip** (`GoalStrip`) can sit above the days: goals in pencil until
+  kept, and a total against a target that turns red once it is over.
+- Blocks are **events, not tasks**: a date, a start, an end. Drag one to move
+  it, pull its edge to resize (snapping to 15 minutes), drag across free
+  working hours to make one, drop an item in from a list, arrow keys move a
+  focused block, **J** and **K** walk the proposals that are waiting.
+- Hours outside the working day are hatched but still there. Today has a now
+  line. Under 36rem of its own width it shows one day at a time under a strip
+  of days.
+
+```jsx
+import { TimeGrid, GoalStrip } from "../components/blocks/time-grid";   // a Makersclaw app ("./blocks/time-grid" from components/)
+import { TimeGrid, GoalStrip } from "@/components/makersclaw/blocks/time-grid";   // a shadcn project
+```
+
+A client component. No other block is laid with it. The helpers (`planKeepAll`,
+`clashesOf`, `loadOf`…) are plain functions and work on the server.
+
+## Which one: TimeGrid or calendar-view
+
+`calendar-view` is the **tasks** calendar: it is built on `task-model`, takes
+tasks with `start` and `due`, and saves task changes. Use it for work that has
+dates and lives in a task list, for a month, for an agenda, and for a booking
+page's open slots. It does not hold events that are not tasks, and it has no
+pencil.
+
+`time-grid` is for **a person reviewing what an agent would put on their
+week**: plain events plus proposals, kept or dropped one at a time or all at
+once. It reads and saves nothing; every press goes out through a callback.
+
+## Which hook feeds it
+
+None. The events are the app's rows (a calendar mirrored into a table, blocks
+a person made); the proposals are rows the agent wrote. Keep them in the app's
+tables and pass them in. The block never reads or writes: a press goes out
+through `onAction`, `onKeepAll` or `onChange`, the app does the write, and
+hands back the changed rows. **A kept proposal keeps its id.** Either give the
+same row `state: "kept"` (it stays a proposal until the week is committed), or
+move the row into `events` under the same id: the block is the same element
+either way, so it inks in instead of blinking out and back.
+
+## Props
+
+### The week
+
+- `days` — the days shown, in order, `["2026-09-21", …]` (one to seven). An
+  item whose `date` is not one of them is not drawn.
+- `today` — "YYYY-MM-DD", marks the day's header and column.
+- `now` — "HH:MM" (or minutes) for the now line; leave it out and it follows
+  the viewer's clock after mount.
+- `startHour` (5) · `endHour` (21) — the hours on the grid. Time outside is
+  not drawn; an item that crosses an edge is cut to it.
+- `workStart` · `workEnd` — "08:30", "17:30": the working day. Hours outside
+  it are hatched (still there), and a new block can only be made inside it.
+- `hourHeight` (40) — pixels per hour. `snap` (15) — minutes a drag snaps to.
+- `height` — the hour grid's scrolling height, `"34rem"` (never `vh`), or
+  `"fill"`: the grid fills what is left of a bounded parent (a flex column
+  with a height: an `AppLayout` content in `contentMode="fill"`, a bounded
+  `Card`) and its hours scroll inside it, so no app measures the box. Leave
+  it out and the grid is as tall as its hours. `scrollTo` ("08:00") — where
+  it opens; default the working day's start.
+- `locale` ("en-GB") — weekday names. `formatTime(minutes)` — how the grid
+  prints a time (default 24-hour, `9:30`).
+- `corner` — a small label in the top-left (a time zone, "BST").
+- `dayNotes` — `{ "2026-09-21": { text: "5.3 of 9 h", tone: "danger" } }`, a
+  number beside a day's header. `tone`: `neutral` · `primary` · `info` ·
+  `success` · `warning` · `danger`. `loadOf` and `hoursOf` add the minutes up.
+- `renderDayHeader(day, { isToday, index, compact, selected })` — your own
+  header.
+- `above` — a node drawn above the days: `<GoalStrip …/>`, or your own.
+
+### What is drawn
+
+- `events` — ink. `[{ id, date, start, end, title, kind?, locked?, done?,
+  allDay?, caption?, sub?, icon?, draggable? }]`. `start`/`end` are "09:30".
+  No `start` (or `allDay`) puts it in the all-day row. `locked` shows a lock
+  and the block cannot be moved (`explainBlock` says why). `caption` follows
+  the time ("Maya's calendar"); `sub` is a line under the title when the block
+  is tall; `icon` is a kit icon.
+- `proposals` — pencil. The same fields, and:
+  - `state` — `"pencil"` (default) · `"kept"` (drawn in ink, still a proposal,
+    with **Back to pencil**) · `"failed"` ("Didn't add", solid red edge) ·
+    `"replaced"` (struck, faint) · `"was"` (a dotted marker where it used to
+    be, under everything).
+  - `unsure: true` — a dotted edge and "Unsure".
+  - `tag` — `{ quote, source }` (or a string, the quote): hangs off the block
+    when it is selected (`tags="all"` shows every one). Under the block from
+    the left in the first half of the days, from the right in the second
+    half, above it when there is no room below.
+  - `label` — the small line over the title; default the kind's label,
+    "Unsure", "Didn't add"… and for a clash "Clash · Standup 9:30".
+  - `note` — a line at the foot of a tall block ("pencilled in Mon 06:00").
+- `kinds` — `{ focus: { label: "Focus", tone: "primary", solid: true },
+  meeting: { label: "Meeting", tone: "neutral", locked: true }, personal: {
+  label: "Personal", hue: 5 } }`. `tone` is `neutral` · `primary` · `info` ·
+  `success` · `warning` · `danger`; `hue` is `1`–`5` (a categorical colour).
+  Ink is the kind's colour on its edge and a faint wash; `solid` fills it with
+  the accent. `locked` draws a lock on every block of that kind. `icon` is
+  a kit icon.
+- `pencilColor` — `"neutral"` (default; pencil has no colour of its own) or
+  `"kind"` (the dashed edge takes the kind's colour).
+- `pencilClassName` — a class for pencil titles, to set them in the app's
+  display face. Layout and type only, never colour.
+- `drafting` — `[{ date, start, end, label? }]`: the agent still pencilling
+  this in, as a pulsing outline.
+- `draft` — `{ date, start, end, title }`: the block being made while its
+  editor is open.
+- `tags` — `"selected"` (default) · `"all"` · `"none"`.
+- `clashAmong` (false) — also hatch two waiting proposals that overlap each
+  other (by default only a proposal against ink or a kept one).
+
+### What a press does
+
+- `selectedId`, `defaultSelectedId`, `onSelect(id | null)` — the selected
+  block. Pass `selectedId` to control it (from the address, say); leave it out
+  and the block keeps it. A press on empty hours clears it; <kbd>Esc</kbd> too.
+- `onOpen(item, element)` — a block was clicked (or Enter on it): open your
+  record. The block is selected as well.
+- `onAction(item, "keep" | "dismiss" | "unkeep")` — `async`, returns `{ ok:
+  true }` or `{ ok: false, error? }`. Keep and Dismiss are drawn on every
+  waiting proposal (in the block when it is tall, on hover or selection when it
+  is short; the all-day row shows them on the selected one), **Back to
+  pencil** on a kept one. A failure puts a notice over the grid with Try
+  again. **Without `onAction` no buttons are drawn.** The buttons are small
+  because a block is: put the same two in your side panel, full size.
+- `keepAll` — `true`, or `{ label?, skip?, primary? }`. Draws the bar over
+  the grid: the sentence from `planKeepAll` and a **Keep all (7)** button.
+  `skip` is what stays in pencil: `["clash"]` (default), `["clash", "unsure"]`,
+  or `[]`.
+- `onKeepAll(plan)` — `async`, same return. `plan.keep` is the ids to keep,
+  `plan.leave` the ones left and why, `plan.words` the sentence.
+- `onChange(item, change, { proposal })` — `async`, same return. A block was
+  moved or resized: `change` is `{ date, start, end, mode: "move" | "start" |
+  "end", from: { date, start, end } }`, times as "09:30". It shows at once; a
+  failure puts it back and says so. Pencil blocks can be moved too
+  (`proposal: true`). A locked block, a failed or replaced proposal, and an
+  item with `draggable: false` stay put. Without `onChange` nothing moves.
+- `onCompose({ date, start, end })` — a press, or a drag across free working
+  hours, on an empty day. Open your editor (and pass `draft` meanwhile).
+- `onDrop(item, { date, start, end })` — an item from a list was dropped on
+  an hour. Make the list item draggable with `{...timeGridDragProps({ id,
+  title, minutes: 45 })}`. Same return as `onChange`.
+- `explainBlock(item)` — a node: why a locked block cannot be moved ("From
+  Google Calendar · change it there"), shown once where it is when someone
+  tries. `explainOffHours({ date, minute, before })` — the same for a press
+  outside the working day.
+- `readOnly` — to read: no buttons, no drags, no compose, no Keep all.
+- `keys` (true) — <kbd>J</kbd> and <kbd>K</kbd> walk the proposals that are
+  waiting (by day, then by time) and move to their day on a narrow container.
+  The region takes focus with <kbd>Tab</kbd>. They are left alone while someone
+  is typing in a field.
+
+### States and words
+
+- `status` — `ready` (default) · `loading` (grey blocks on the grid) · `failed`
+  (a notice with `error`, and Try again if you pass `onRetry`).
+- `emptyText` — what to say over a grid with nothing on it; `false` says
+  nothing.
+- `words` — the block's few words, to be changed: `allDay`, `keep`, `dismiss`,
+  `unkeep`, `keepAll`, `pencilled`, `unsure`, `failed`, `replaced`, `was`,
+  `clash`, `locked`, `drafting`, `newBlock`, `empty`, `retry`, `back`.
+- `label` ("Week") — the region's accessible name. `className` — layout:
+  width, margin. Never colour.
+
+### GoalStrip
+
+```jsx
+<GoalStrip
+  items={[{ id: "g1", title: "Pricing page live", state: "pencil", mark: "pencilled in" }, …]}
+  summary={{ label: "Focus", value: 11, of: 15, unit: "h", over: false, note: "all placed" }}
+  onSelect={(id) => …}
+/>
+```
+
+`items`: `{ id, title, number?, state: "ink" | "pencil" | "done" | "empty",
+meta?, mark? }`. A goal in pencil is hatched with a dashed edge and fades to
+ink when its `state` changes. `summary`: a total against a target; `over: true`
+turns it red and says "over". `empty`: a node for no goals at all.
+`selectedId` / `onSelect(id)` make the goals buttons.
+
+### Helpers
+
+Plain functions (`import` them from the same folder):
+
+- `planKeepAll(items, { clashes?, kinds?, skip?, fmt? })` — `{ keep, leave,
+  counts, total, words }`: what Keep all will do. The block calls it itself;
+  call it too when a button of yours (a "Commit the week") should say the same.
+- `clashesOf(items, { among? })` — Map id → `[{ withId, title, s, e }]`.
+  `items` are what `readItem` returns.
+- `readItem(raw, { days, lo, hi, snap, pencil })` — an item as the grid draws
+  it (minutes for `s`/`e`).
+- `loadOf(items, date, where?)` — minutes of timed items on a day;
+  `hoursOf(minutes)` → "5.3"; `durationWords(minutes)` → "1 h 30 min".
+- `lookOf(item)`, `isWaiting(item)`, `waitingOrder`, `walkProposal`,
+  `newlyInked`, `previewOf`, `tagPlacement`, `gridLanes`, `namesOf`, `toMin`,
+  `toHHMM`, `clock`.
+
+## Example
+
+A week the agent drafted on Monday, kept one block at a time or all at once:
+
+```jsx
+"use client";
+import { useRows } from "../lib/data";
+import { updateRow, deleteRow } from "../lib/actions";
+import { GoalStrip, TimeGrid } from "../components/blocks/time-grid";
+
+const KINDS = {
+  focus: { label: "Focus", tone: "primary", solid: true },
+  meeting: { label: "Meeting", tone: "neutral", locked: true },
+  admin: { label: "Admin", tone: "success" },
+};
+
+export default function Week({ days }) {
+  const blocks = useRows({ source: "blocks", filter: { week: days[0] } });
+  const goals = useRows({ source: "goals", filter: { week: days[0] } });
+  const rows = blocks.rows ?? [];
+  const toItem = (b) => ({ id: b.id, date: b.day, start: b.starts, end: b.ends, title: b.title, kind: b.kind, note: b.reason });
+  const keep = (ids) => Promise.all(ids.map((id) => updateRow({ source: "blocks", id, patch: { state: "kept" } })));
+
+  return (
+    <TimeGrid
+      days={days}
+      today={days[3]}
+      workStart="08:30"
+      workEnd="17:30"
+      height="36rem"
+      kinds={KINDS}
+      status={blocks.loading ? "loading" : blocks.error ? "failed" : "ready"}
+      error={blocks.error}
+      events={rows.filter((b) => b.state === "committed" || b.kind === "meeting").map(toItem)}
+      proposals={rows.filter((b) => b.state === "pencil" || b.state === "kept").map((b) => ({ ...toItem(b), state: b.state }))}
+      keepAll
+      onKeepAll={async (plan) => (await keep(plan.keep), { ok: true })}
+      onAction={async (item, action) => {
+        if (action === "dismiss") return deleteRow({ source: "blocks", id: item.id });
+        return updateRow({ source: "blocks", id: item.id, patch: { state: action === "keep" ? "kept" : "pencil" } });
+      }}
+      onChange={(item, c) => updateRow({ source: "blocks", id: item.id, patch: { day: c.date, starts: c.start, ends: c.end } })}
+      above={<GoalStrip items={(goals.rows ?? []).map((g) => ({ id: g.id, title: g.title, state: g.kept ? "ink" : "pencil" }))} />}
+    />
+  );
+}
+```
+
+In a server-mode app the same calls are `loadRows` in a server surface and the Server Actions of `lib/actions`.
+
+Proposals on the hours they came for, with the sender's words:
+
+```jsx
+<TimeGrid
+  days={days}
+  pencilColor="kind"
+  kinds={{ meeting: { label: "Meeting", hue: 1 }, todo: { label: "To-do", hue: 4 } }}
+  events={calendar}
+  proposals={found.map((f) => ({
+    id: f.id, date: f.day, start: f.start, end: f.end, title: f.title, kind: f.kind,
+    unsure: f.sureness < 0.7,
+    tag: { quote: f.phrase, source: `${f.sender} · ${f.subject}` },
+  }))}
+  selectedId={openId}
+  onSelect={setOpenId}
+  onAction={(item, action) => decide(item.id, action)}
+/>
+```
+
+## States
+
+Drawn in `demo.jsx`: a planner's week with goals above, locked meetings, focus
+in pencil, Keep, Dismiss, Keep all, a failing drag, a drop from a list;
+proposals with a tag and a hatched clash, a "was" marker and a failed add;
+320 px (one day at a time); seven days and five kinds; one event; very long
+words; empty; loading; failed; read-only.
+
+## What it will not do
+
+- Recurring events, time zones, or blocks that cross midnight: a time is wall
+  time on one day.
+- Fetch or save. Rows come in as props, saves go out through the callbacks.
+- Decide what clashes beyond overlap: two blocks that touch end to start do
+  not clash, and all-day items never do. A rule such as "no meetings after 5"
+  is the app's; mark it in the proposal's `label`.
+- Take the place of the record: a click goes out through `onOpen`; the form,
+  the Commit and the Undo are the page's.
+- Show a month, an agenda or a booking page's open slots. That is
+  `calendar-view`.
+
+A grid 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 time-grid` restores them.

package/registry/blocks/time-grid/block.json

@@ -0,0 +1,10 @@
+{
+  "name": "time-grid",
+  "title": "Time grid",
+  "description": "Days side by side on an hour grid, with the agent's proposals in pencil. What is already there is ink (events in their kind's colour, a lock on the ones another calendar owns); what the agent suggests is pencil: a hatched card on a dashed edge sitting on its hour, with a tag hanging off it that quotes the words it came from (\"Thursday at 3pm your time\"). Keep inks a block in (the same block, so its colours fade from pencil to ink; kept together they ink one by one), Dismiss drops it, Back to pencil takes a kept one back. \"Keep all\" says what it will do before it does it (\"Keeps 7 of 8 in ink: 5 Focus, 2 Admin. Leaves 1 in pencil: it clashes with Standup 9:30.\"). A clash is hatched where a proposal overlaps something already there, before anything is kept. A goals strip (GoalStrip) can sit above the days, goals in pencil until kept, with a total against a target that turns red once it is over. Blocks are events, not tasks: drag to move or resize (snapping to 15 minutes), drag across free working hours to make one, drop an item in from a list, arrow keys move a focused block, J and K walk the proposals that are waiting. Hours outside the working day are hatched but still there; a now line on today; one day at a time under a strip of days when the container is narrow. Loading, failed, empty and read-only are drawn.",
+  "useWhen": "A screen where a person reviews what an agent would put on their week: a weekly planner whose focus blocks are drafted in pencil and committed in ink, an inbox that finds meetings and deadlines in mail and shows each on its hour next to the real calendar with the sender's own words, a shift or room plan an assistant drafts, a day plan with proposals. Events are plain items with a date, a start and an end (not tasks). Not for tasks with start and due dates that live in a task list (calendar-view), for a month, for long timelines (gantt), or for a booking page's open slots (calendar-view).",
+  "tags": ["calendar", "week", "day", "hour grid", "time grid", "schedule", "planner", "pencil", "ink", "proposal", "suggestion", "draft", "keep", "keep all", "dismiss", "ghost", "tag", "clash", "conflict", "overlap", "goals", "focus time", "agent", "inbox to calendar", "weekly planner", "drag", "resize"],
+  "exports": ["TimeGrid", "GoalStrip", "TIME_GRID_MIME", "timeGridDragProps", "PENCIL_STATES", "clashesOf", "clock", "durationWords", "gridLanes", "hoursOf", "isWaiting", "loadOf", "lookOf", "namesOf", "newlyInked", "planKeepAll", "previewOf", "readItem", "tagPlacement", "toHHMM", "toMin", "walkProposal", "waitingOrder"],
+  "files": ["index.js", "time-grid.jsx", "grid-model.js"],
+  "requires": []
+}