makersclaw 0.8.0 → 0.8.1

package/registry/blocks/pace-bar/README.md

@@ -0,0 +1,230 @@
+# PaceBar
+
+Progress against a clock: how far along, and how far along it should be by now.
+
+"58%" alone says little. 58% with the mark at 91% says *behind*. This block
+draws that, four ways:
+
+- **PaceBar**: one bar, filled to its value, with a hard upright tick where it
+  should be by now. The stretch between the fill and the tick is hatched, so
+  "behind" is a shape you see, not a sum you do.
+- **PaceList**: many bars on **one axis**. The period's month names and a tick
+  each Monday run above. **One today line runs unbroken through the whole
+  list**, group headings included. Each row says its percent, who last moved it
+  and the gap in weeks ("4 wk behind").
+- **PaceRuler**: that axis alone, with a flag for today ("Today · 92% gone").
+- **WeekStrip**: the period as its weeks in one row, with a mark on each week a
+  check-in was made.
+
+It draws a result the app has already worked out. It collects no check-ins, it
+changes no number. For a chain of dated phases with gates use `schedule-ruler`;
+for a plain meter with no clock use the kit's `Progress`.
+
+Born in two store apps that each drew it by hand: a goals tracker's today line
+down a whole quarter, and a project monitor's "57% done, 88% of the time gone".
+
+```jsx
+import { PaceBar, PaceList, PaceRuler, WeekStrip, PaceMark, paceOf, paceWords, paceSentence } from "../components/blocks/pace-bar"; // a Makersclaw app ("./blocks/pace-bar" from components/)
+// shadcn project: import { PaceList } from "@/components/makersclaw/blocks/pace-bar"
+```
+
+A client component. It needs the `agent-marks` block (the agent's mark) and no
+npm package. Dates are `'YYYY-MM-DD'` strings and are days, never times, so the
+server and the browser draw the same picture. Positions are percentages;
+nothing is measured.
+
+## The clock
+
+Give a **period** (`start`, `end`, both days included) and **today**. The
+pace is the share of the period that has gone, **today counted**: on Wed 23 Sep
+a quarter that began 1 Jul and ends 30 Sep has 85 of its 92 days gone, so the
+pace is 92%.
+
+Or skip the period and give `pace` yourself (0 to 1): a bar needs no dates.
+
+The block never reads the clock. `today` always comes in as a prop, so a
+server render and a browser render agree.
+
+## Props: PaceBar
+
+- `value`: how far along, 0 to 1 (clamped). `null`: not known.
+- `pace`: where it should be by now, 0 to 1. Left out, it is worked out from
+  `start`, `end` and `today`. `null` on purpose: no tick, pace not judged.
+- `start`, `end`, `today`: the period.
+- `kind`: `"progress"` (default; short of the pace is the gap) or `"spend"`
+  (over the pace is the gap: hours burned against time gone, a budget used).
+- `tone`: `ink` (default), `quiet`, `info`, `success`, `warning`, `danger`,
+  or `auto` (ink while on pace or ahead, warning at 10 points behind, danger at
+  25; success when done; quiet when not judged yet). A tone is a status: leave
+  it `ink` when nothing needs attention.
+- `size`: `lg` (14 px), `md` (10 px, default), `sm` (6 px).
+- `hatch`: draw the gap between the fill and the tick (default true).
+- `animate`: fill from zero on first paint (CSS only), off under reduced
+  motion. `delay`: milliseconds before it starts, to stagger a list (capped
+  at 540).
+- `tolerance`, `graceDays`, `graceFraction`: see "How it judges" below.
+- `words`: the app's vocabulary (below).
+- `label`: what a screen reader calls it. It reads the sum as words
+  (`role="meter"`): "62% done, 92% of the time gone. 4 wk behind".
+- `className`: layout (width, margin). Never colour.
+
+## Props: PaceList
+
+- `rows`: `[{ id, label, sub, value, pace, kind, tone, by, byLabel, meta, note, group, unit }]`
+  - `label`, `sub`: the name and the small line under it.
+  - `value`: 0 to 1. `pace`: only when this row has a clock of its own (it
+    gets its own tick); otherwise the shared line is its pace.
+  - `tone`: as above; default `auto`.
+  - `by`: who last moved it: `"person"` (a filled dot), `"agent"` (the agent's
+    mark) or nothing. `byLabel`: what a screen reader hears (default "A
+    person", "The agent").
+  - `meta`: anything to put in the meta column (an owner's avatar, a count).
+    Needs `metaWidth`.
+  - `note`: replaces the gap words ("1 wk behind · Likely").
+  - `group`: the `id` of a group.
+- `groups`: `[{ id, label, sub, note, empty }]` in the order to draw. A heading
+  row carries the today line too. `empty` is the line shown when the group has
+  no rows. A row whose `group` is not listed goes last, with no heading.
+- `start`, `end`, `today`: the period. They draw the ruler and the line.
+- `pace`: with no period, the shared line's place (0 to 1).
+- `kind`, `tolerance`, `graceDays`, `graceFraction`, `unit`, `warnAt`, `dangerAt`: how rows are
+  judged (below). A row's own `kind` or `unit` wins.
+- `heads`: `{ label, meta, pct, gap }`: the column heads, shown from 42rem of
+  the container's width.
+- `ruler`: draw the axis above the rows (default true).
+- `weekStartsOn`: weekday the week begins on, 0 = Monday (default).
+- `metaWidth`: a CSS length ("8rem") adds a meta column. Without it there is none.
+- `trackWidth` (default `"24rem"`, the most the bar takes), `gapWidth` (`"9rem"`).
+- `size`: bar thickness (default `sm`).
+- `selected`: the `id` of the row to mark as current.
+- `onOpen(row)`: makes each row a button. Leave it out for a read-only list.
+- `loading`, `error`, `onRetry`, `empty`, `emptyAction`: the other states: a
+  skeleton; a danger notice with "Try again"; and, with no rows, an empty panel
+  titled `empty`.
+- `label`, `className`.
+
+Every row is one grid with the same columns, so the bars of all rows start and
+end at the same x: that is the shared axis. Under 42rem of its own width a row is
+its name on one line and its bar and percent under it.
+
+## Props: PaceRuler
+
+`start`, `end`, `today`, `weekStartsOn`, `words`, `showToday` (default true),
+`label`, `className`. It is 44px tall and as wide as its parent: put it in the
+column your own rows share, and draw the line down from it with your rows'
+today position (`axisOf(...).todayAt`).
+
+## Props: WeekStrip
+
+- `start`, `end`, `today`, `weekStartsOn`.
+- `marks`: `[{ id, date, by, label }]`. A mark lands on the week its date falls
+  in (before the first week: the first; after the last: the last). `by`:
+  `"person"`, `"agent"`, or nothing (a hollow ring). More than three marks in a
+  week show "+n".
+- `missed`: put a dashed ring on a past week with no mark at all.
+- `onOpen(week)`: makes each week a button (`{ n, from, to, state, marks }`).
+- `words`: `{ week: "Week" }`. `label`, `className`.
+
+The strip keeps each week at least 1.5rem wide and scrolls sideways when the
+period has too many weeks for the container (focusable, so the keyboard scrolls
+it).
+
+## PaceMark
+
+`<PaceMark by="person" | "agent" label empty missed size />`. Nothing for no
+one; `empty` draws a hollow ring (a mark made by no one), `missed` a dashed one
+(a mark that should be there).
+
+## How it judges
+
+`paceOf({ value, pace, start, end, today, kind, tolerance, graceDays, graceFraction, unit })`
+(also exported, pure) returns the state:
+
+- `done`: progress at 100% or more.
+- `unjudged`: no value, no pace, the period has not started, or it is inside
+  `graceDays` of the start (default 0; a quarterly tracker passes 14), or
+  inside `graceFraction` of the period from its start (0..1; `0.2` is the
+  first fifth, 19 days of a 92-day quarter). The longer of the two counts.
+- `on`: the gap is within `tolerance` whole points of the period (default 5).
+- `worse` / `better`: behind or ahead (progress); over or under (spend).
+
+The gap is said in whole weeks, **at least 1**, from the period's length:
+62% against a pace of 92% in a 92-day quarter is `30` points, 27.6 days, "4 wk
+behind". `unit` is `"week"` (default when there is a period), `"day"` or
+`"point"` (no period: "30 pts behind").
+
+## Words
+
+Every string is the app's to change. `words` merges over these:
+
+```
+on: "On pace"   unjudged: "Not judged yet"   done: "Done"
+today: "Today"   before: "Not started"   after: "Ended"
+units: { week: "wk", day: "d", point: "pts" }
+behind(n, unit)  "4 wk behind"      ahead(n, unit)  "2 wk ahead"
+over(n, unit)    "34 pts over"      under(n, unit)  "17 pts under"
+sentence({ done, gone })       "57% done, 88% of the time gone"
+spendSentence({ done, gone })  "91% used, 57% of the time gone"
+gone(n)  "92% gone"
+```
+
+Also exported, pure and without React, for a screen that wants the same numbers
+in a sentence: `paceOf`, `paceWords(state, words)`, `paceSentence(state,
+words)`, `toneOf(state, { warnAt, dangerAt })`, `periodOf`, `axisOf`,
+`weeksOf`, `marksOnWeeks`, `groupRows`, `dayNumber`, `isoOf`, `dayName`,
+`shortDay`, `percent`, `WORDS`.
+
+## Example
+
+```jsx
+<PaceList
+  label="Q3 goals"
+  start="2026-07-01"
+  end="2026-09-30"
+  today="2026-09-23"
+  graceDays={14}
+  heads={{ label: "Goal", pct: "Done", gap: "Against today" }}
+  metaWidth="7rem"
+  groups={[{ id: "sales", label: "Sales", sub: "2 goals" }, { id: "eng", label: "Engineering", sub: "1 goal" }]}
+  rows={[
+    { id: "a", group: "sales", label: "Close the enterprise gap", value: 0.62, by: "person", meta: owner("Priya") },
+    { id: "b", group: "sales", label: "Turn demos into a motion", value: 0.87 },
+    { id: "c", group: "eng", label: "Keep the rate API fast", value: 0.9, by: "agent" },
+  ]}
+  onOpen={(row) => router.push(`?goal=${row.id}`)}
+/>
+
+<WeekStrip start="2026-07-01" end="2026-09-30" today="2026-09-23" missed
+  marks={[{ id: "m1", date: "2026-09-14", by: "person" }, { id: "m2", date: "2026-09-21", by: "agent" }]} />
+
+// "57% done, 88% of the time gone"
+<p>{paceSentence(paceOf({ value: 0.57, pace: 0.88 }))}</p>
+
+// A budget: 91% of the hours used with 57% of the time gone
+<PaceBar kind="spend" value={0.91} pace={0.57} tone="danger" label="Hours" />
+```
+
+## States drawn
+
+- **Empty**: a panel with what to do. With groups and no rows, each heading says
+  its `empty` line.
+- **One row**, **many rows**, **grouped**.
+- **Very long names**: the name wraps (rows grow); the bar's column is unchanged.
+- **Narrow** (a 320px container): a row is its name above its bar and percent;
+  the ruler is under the column heads.
+- **Wide**: the bar column keeps its `trackWidth`; the name takes the rest.
+- **On pace, behind, ahead, done, not judged yet, before the period, after it.**
+- **Spend**: over the pace hatches from the tick to the fill.
+- **Loading**, **failed** (with Try again), **read-only** (no `onOpen`).
+- Reduced motion: nothing moves unless `animate` is set, and then not under it.
+
+## Notes for the app that places it
+
+- It is a picture. Put the numbers in words beside it (the list does: the
+  percent and the gap words are in every row).
+- Colour is a signal. The fill is ink unless a row is behind (warning, danger)
+  or done (success). Do not tint rows for any other reason.
+- For a goals list, give each group a `note` such as "2 need attention" and
+  compute it from `paceOf(...).state` yourself; the block does not know your
+  words for "needs attention".
+- A row with `by` shows who last moved it; keep the dates in your detail view.

package/registry/blocks/pace-bar/block.json

@@ -0,0 +1,10 @@
+{
+  "name": "pace-bar",
+  "title": "PaceBar",
+  "description": "Progress against a clock. PaceBar is one bar filled to its value with a hard upright tick where it should be by now (the share of a period that has gone), and the stretch between them hatched, so behind is a shape you see; a spend (hours burned against time gone) hatches the other way. PaceList puts many bars on ONE axis: the period's month names and a tick each Monday above, one today line running unbroken through the whole list and its group headings, each row's percent, who last moved it (a person's dot, the agent's mark, or none) and the gap said in weeks (\"4 wk behind\", \"On pace\", \"Not judged yet\", \"Done\"); rows sit in optional groups and a row can be pressed. PaceRuler is the axis alone, with a flag for today (\"Today · 92% gone\"). WeekStrip is the period as its weeks in one row: weeks gone filled, this one marked, a mark on each week a check-in was made (person, agent, none), a dashed ring on a past week with none. The sums are exported as plain functions (paceOf, paceWords, paceSentence: \"57% done, 88% of the time gone\"). Positions are percentages, so it draws the same on the server; narrow, a list row is its name above its bar. Loading, failed and empty states are drawn.",
+  "useWhen": "Any screen where progress belongs to a period and the question is 'are we on pace': a quarter's goals and their key results, a project's work done against its days gone, hours burned against hours sold, a sprint, a savings or budget target, a course or a reading plan, a campaign's delivery against its flight dates, a weekly check-in cadence. Draws a result the app has already worked out; it does not collect check-ins. Not for a chain of dated phases with gates (schedule-ruler), editable bars with dependencies (gantt), a plain meter with no clock (Progress in the kit), or a time series (chart).",
+  "tags": ["pace", "progress", "bar", "target", "behind", "ahead", "on track", "today line", "quarter", "okr", "goals", "key results", "burn", "budget", "spend", "sprint", "weeks behind", "check-in", "cadence", "deadline", "ruler", "agent"],
+  "exports": ["PaceBar", "PaceList", "PaceRuler", "WeekStrip", "PaceMark", "WORDS", "atDay", "axisOf", "dayName", "dayNumber", "groupRows", "isoOf", "marksOnWeeks", "paceOf", "paceSentence", "paceWords", "percent", "periodOf", "shortDay", "toneOf", "weeksOf"],
+  "files": ["index.js", "pace-bar.jsx", "pace-model.js"],
+  "requires": ["agent-marks"]
+}

package/registry/blocks/pace-bar/demo.jsx

@@ -0,0 +1,255 @@
+"use client";
+
+// PaceBar in every state — the gallery's and the smoke test's surface. Not
+// installed into apps: `makersclaw add pace-bar` lays index.js, pace-bar.jsx
+// and pace-model.js only.
+//   One bar      the tones, the sizes, ahead and behind, a spend, no pace,
+//                the fill growing in.
+//   A list       twelve weeks into a quarter: groups, a person's dot and the
+//                agent's mark, a meta column, a press on a row, the gap in
+//                weeks, "Not judged yet" and "Done".
+//   Not judged   the first days of a period.
+//   Long words   a very long name and note.
+//   Narrow       a 320 px container: the bar under the name.
+//   Wide         a container well past 1000 px.
+//   Read-only    no onOpen: nothing is pressable.
+//   Empty groups, plain empty, loading, failed.
+//   The ruler    before, in, and after the period.
+//   WeekStrip    marks by a person, the agent and no one; missed weeks;
+//                a press on a week; many weeks.
+import { useState } from "react";
+import { Avatar, Notice } from "../components/ui";
+import { PaceBar, PaceList, PaceMark, PaceRuler, WeekStrip, paceOf, paceSentence } from "../components/blocks/pace-bar";
+
+const Q = { start: "2026-07-01", end: "2026-09-30" };
+const TODAY = "2026-09-23";
+
+const GROUPS = [
+  { id: "sales", label: "Sales", sub: "3 goals", note: "2 need attention" },
+  { id: "product", label: "Product", sub: "2 goals" },
+  { id: "ops", label: "Operations", sub: "", empty: "No goals this quarter" },
+];
+const owner = (name) => (
+  <span className="flex min-w-0 items-center gap-1.5 text-xs">
+    <Avatar name={name} size="xs" />
+    <span className="truncate">{name.split(" ")[0]}</span>
+  </span>
+);
+const ROWS = [
+  { id: "g1", group: "sales", label: "Close the enterprise gap before the October price change", sub: "3 key results", value: 0.62, by: "person", meta: owner("Priya Raman") },
+  { id: "g2", group: "sales", label: "Turn inbound demos into a repeatable motion", sub: "2 key results", value: 0.87, by: "agent", meta: owner("Marcus Reyes") },
+  { id: "g3", group: "sales", label: "Win back the lapsed accounts", sub: "1 key result", value: 0.75, meta: owner("Hannah Cole"), note: "2 wk behind · Unsure" },
+  { id: "g4", group: "product", label: "Make onboarding self-serve for new merchants", sub: "3 key results", value: 0.86, by: "person", meta: owner("Lena Vogel") },
+  { id: "g5", group: "product", label: "Ship the rate API v2", sub: "Closed 18 Sep", value: 1, by: "person", meta: owner("Daniel Brandt") },
+];
+const LONG = [
+  {
+    id: "l1",
+    label: "An exceptionally long name for a goal that nobody had the heart to shorten, which goes on and on past the end of any sensible line",
+    sub: "and a long small line under it that also keeps going well past where it should have stopped",
+    value: 0.31,
+    by: "agent",
+    note: "A very long note about why this one is where it is and what the owner said on Monday",
+  },
+  { id: "l2", label: "Short", value: 0.93 },
+];
+const EARLY_ROWS = ROWS.slice(0, 3).map((r) => ({ ...r, value: 0.04 }));
+
+const MARKS = [
+  { id: "a", date: "2026-07-13", by: "person" },
+  { id: "b", date: "2026-07-20", by: "person" },
+  { id: "c", date: "2026-07-27", by: "agent" },
+  { id: "d", date: "2026-08-10", by: "person" },
+  { id: "e", date: "2026-08-10", by: "agent" },
+  { id: "f", date: "2026-08-11", by: "person" },
+  { id: "g", date: "2026-08-12" },
+  { id: "h", date: "2026-08-24", by: "agent" },
+  { id: "i", date: "2026-09-07", by: "person" },
+  { id: "j", date: "2026-09-14", by: "person" },
+  { id: "k", date: "2026-09-21", by: "agent" },
+];
+
+function Section({ title, note, children }) {
+  return (
+    <section className="grid min-w-0 gap-2">
+      <h2 className="text-sm font-semibold">{title}</h2>
+      {note ? <p className="text-xs text-muted-foreground">{note}</p> : null}
+      {children}
+    </section>
+  );
+}
+
+function Line({ label, children }) {
+  return (
+    <div className="grid grid-cols-[minmax(0,12rem)_minmax(0,1fr)] items-center gap-4">
+      <span className="truncate text-xs text-muted-foreground">{label}</span>
+      {children}
+    </div>
+  );
+}
+
+export default function Demo() {
+  const [pressed, setPressed] = useState(null);
+  const [week, setWeek] = useState(null);
+  const [grown, setGrown] = useState(0);
+  const sum = paceOf({ value: 0.57, pace: 0.88 });
+
+  return (
+    <div className="grid min-w-0 gap-8 p-6">
+      <Section title="One bar" note="Fill to the value, a tick at the pace, the stretch between hatched. Here the pace is 91%.">
+        <div className="grid max-w-xl gap-4">
+          <Line label="Behind, warning">
+            <PaceBar value={0.58} pace={0.91} tone="warning" size="lg" label="Behind" />
+          </Line>
+          <Line label="Far behind, danger">
+            <PaceBar value={0.3} pace={0.91} tone="danger" label="Far behind" />
+          </Line>
+          <Line label="On pace, ink">
+            <PaceBar value={0.89} pace={0.91} label="On pace" />
+          </Line>
+          <Line label="Ahead, info">
+            <PaceBar value={0.97} pace={0.91} tone="info" size="sm" label="Ahead" />
+          </Line>
+          <Line label="Done, success">
+            <PaceBar value={1} pace={0.91} tone="success" label="Done" />
+          </Line>
+          <Line label="Quiet row">
+            <PaceBar value={0.4} pace={0.91} tone="quiet" size="sm" label="Quiet" />
+          </Line>
+          <Line label="No pace (not judged)">
+            <PaceBar value={0.22} pace={null} tone="quiet" label="No pace" />
+          </Line>
+          <Line label="Auto tone, from a period">
+            <PaceBar {...Q} today={TODAY} value={0.62} tone="auto" label="Auto" />
+          </Line>
+          <Line label="A spend, over the pace">
+            <PaceBar kind="spend" value={0.91} pace={0.57} tone="danger" label="Hours used" />
+          </Line>
+          <Line label="A spend, under the pace">
+            <PaceBar kind="spend" value={0.4} pace={0.57} label="Hours used, under" />
+          </Line>
+          <Line label="Nothing yet, not known">
+            <div className="grid gap-3">
+              <PaceBar value={0} pace={0.5} label="Nothing yet" />
+              <PaceBar value={null} pace={0.5} label="Not known" />
+            </div>
+          </Line>
+        </div>
+        <p className="font-mono text-xs text-muted-foreground">{paceSentence(sum)}</p>
+      </Section>
+
+      <Section title="The fill grows in" note="animate and delay: press to run it again. Nothing moves under reduced motion.">
+        <button type="button" onClick={() => setGrown((n) => n + 1)} className="w-fit rounded-sm border border-border px-2 py-1 text-xs hover:bg-muted">
+          Run again
+        </button>
+        <div key={grown} className="grid max-w-xl gap-3">
+          {[0.62, 0.75, 0.86, 0.9].map((v, i) => (
+            <PaceBar key={v} value={v} pace={0.92} tone="warning" animate delay={i * 120} label={`Row ${i + 1}`} />
+          ))}
+        </div>
+      </Section>
+
+      <Section title="A list" note="Twelve weeks into the quarter. One today line through the groups; the gap in weeks. Press a row.">
+        <div className="rounded-md border border-border">
+          <PaceList
+            label="Q3 goals"
+            {...Q}
+            today={TODAY}
+            graceDays={14}
+            heads={{ label: "Goal", meta: "Owner", pct: "Done", gap: "Against today" }}
+            metaWidth="7rem"
+            groups={GROUPS}
+            rows={ROWS}
+            selected={pressed?.id}
+            onOpen={setPressed}
+          />
+        </div>
+        <p aria-live="polite" className="font-mono text-xs text-muted-foreground">
+          {pressed ? `Pressed: ${pressed.label}` : "Nothing pressed yet"}
+        </p>
+      </Section>
+
+      <Section title="Not judged yet" note="The second day of a quarter: every row shows its number, none a status. The line is still there.">
+        <div className="rounded-md border border-border">
+          <PaceList label="Q4 goals" start="2026-10-01" end="2026-12-31" today="2026-10-06" graceDays={14} heads={{ label: "Goal", pct: "Done", gap: "Against today" }} rows={EARLY_ROWS} />
+        </div>
+      </Section>
+
+      <Section title="Long words" note="Names and notes wrap; the bar column does not move.">
+        <div className="rounded-md border border-border">
+          <PaceList label="Long" {...Q} today={TODAY} rows={LONG} />
+        </div>
+      </Section>
+
+      <Section title="Narrow, 320 px" note="A row is its name, then its bar and percent, then the gap in words.">
+        <div className="w-[320px] max-w-full rounded-md border border-border">
+          <PaceList label="Narrow" {...Q} today={TODAY} groups={GROUPS.slice(0, 2)} rows={ROWS} />
+        </div>
+      </Section>
+
+      <Section title="Wide">
+        <div className="w-[1200px] max-w-none rounded-md border border-border">
+          <PaceList
+            label="Wide"
+            {...Q}
+            today={TODAY}
+            heads={{ label: "Goal", meta: "Owner", pct: "Done", gap: "Against today" }}
+            metaWidth="8rem"
+            trackWidth="32rem"
+            groups={GROUPS}
+            rows={ROWS}
+          />
+        </div>
+      </Section>
+
+      <Section title="Read-only, no groups, a pace and no period" note="No onOpen: nothing is a button. No dates: the line stands where `pace` says (60%).">
+        <div className="rounded-md border border-border">
+          <PaceList label="Read-only" pace={0.6} ruler={false} rows={[{ id: "r1", label: "Reading plan", value: 0.4 }, { id: "r2", label: "Savings", value: 0.72, tone: "success" }]} />
+        </div>
+      </Section>
+
+      <Section title="After the period, and before it">
+        <div className="grid gap-4 rounded-md border border-border py-2">
+          <PaceList label="Ended" {...Q} today="2026-10-12" rows={ROWS.slice(0, 2)} />
+          <PaceList label="Not started" {...Q} today="2026-06-15" rows={ROWS.slice(0, 2)} />
+        </div>
+      </Section>
+
+      <Section title="Empty, loading, failed">
+        <PaceList label="Empty" empty="No goals yet. Start from a template." />
+        <PaceList label="Loading" loading />
+        <PaceList label="Goals" error="The goals could not be read. Check the connection." onRetry={() => setPressed({ id: "retry", label: "Try again" })} />
+      </Section>
+
+      <Section title="PaceRuler alone" note="Before, in, and after the period.">
+        <div className="grid max-w-2xl gap-3">
+          <PaceRuler {...Q} today={TODAY} />
+          <PaceRuler {...Q} today="2026-07-12" />
+          <PaceRuler {...Q} today="2026-06-20" />
+          <PaceRuler {...Q} today="2026-10-12" />
+        </div>
+      </Section>
+
+      <Section title="WeekStrip" note="A person's dot, the agent's mark, a hollow ring for a mark by no one, a dashed ring for a week with none. Press a week.">
+        <div className="grid max-w-2xl gap-4">
+          <WeekStrip {...Q} today={TODAY} marks={MARKS} missed onOpen={setWeek} />
+          <p aria-live="polite" className="font-mono text-xs text-muted-foreground">
+            {week ? `Week ${week.n}, ${week.marks.length} marks` : "No week pressed yet"}
+          </p>
+          <div className="w-[320px] max-w-full">
+            <WeekStrip {...Q} today={TODAY} marks={MARKS} label="Narrow weeks" />
+          </div>
+          <WeekStrip start="2026-01-01" end="2026-12-31" today={TODAY} label="A year" />
+          <div className="flex items-center gap-4 text-xs text-muted-foreground">
+            <span className="flex items-center gap-1.5"><PaceMark by="person" /> a person</span>
+            <span className="flex items-center gap-1.5"><PaceMark by="agent" /> the agent</span>
+            <span className="flex items-center gap-1.5"><PaceMark empty /> no one</span>
+            <span className="flex items-center gap-1.5"><PaceMark missed /> missed</span>
+          </div>
+        </div>
+      </Section>
+
+      <Notice tone="info">Every date is a day, never a time: 2026-09-23 means the same day on the server and in the browser.</Notice>
+    </div>
+  );
+}

package/registry/blocks/pace-bar/index.js

@@ -0,0 +1,22 @@
+// The PaceBar block — `makersclaw add pace-bar`. 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 { PaceBar, PaceList, PaceRuler, WeekStrip, PaceMark } from "./pace-bar";
+export {
+  WORDS,
+  atDay,
+  axisOf,
+  dayName,
+  dayNumber,
+  groupRows,
+  isoOf,
+  marksOnWeeks,
+  paceOf,
+  paceSentence,
+  paceWords,
+  percent,
+  periodOf,
+  shortDay,
+  toneOf,
+  weeksOf,
+} from "./pace-model";