makersclaw 0.8.0 → 0.8.1

package/registry/blocks/schedule-ruler/README.md

@@ -0,0 +1,148 @@
+# ScheduleRuler
+
+A dated chain drawn to scale, and how it stands against its promise.
+
+One picture answers "when does this finish, and against what?". A day axis
+(a tick each Monday, a taller one on the 1st). The chain's segments as
+bars. A gate post at the end of a segment, built from its exit criteria as
+pips. Milestones as diamonds. The target as a solid line, the forecast as a
+dashed one, today as a line in the accent. Between target and forecast the
+gap, hatched: **green when the forecast lands early (slack), red when it
+lands late (an overrun)**, counted in working days and labelled "+3 d" or
+"3 d slack".
+
+It draws a result the app has already worked out. It does not schedule,
+drag or link anything: for bars you edit, with dependencies, use `gantt`.
+
+Born in three store apps that each drew it by hand: a phase planner's phase
+ruler with gate dates, a Gantt planner's gap ruler beside the sentence, a
+roadmap's forecast against its target.
+
+```jsx
+import { ScheduleRuler, GapRuler, ScheduleStrip } from "../components/blocks/schedule-ruler"; // a Makersclaw app ("./blocks/schedule-ruler" from components/)
+// shadcn project: import { ScheduleRuler } from "@/components/makersclaw/blocks/schedule-ruler"
+```
+
+A client component. No npm packages, no other block. Dates are `'YYYY-MM-DD'`
+strings and are days, never times, so the server and the browser draw the
+same picture. Positions are percentages of the chain; nothing is measured.
+
+## Props
+
+`ScheduleRuler`:
+
+- `segments` — `[{ id, label, start, end, status, sub, gate }]`, in order.
+  - `start`, `end`: 'YYYY-MM-DD', both days included. A segment without
+    both, or ending before it starts, is left off; a line below the picture
+    says how many.
+  - `status`: `done` (solid, success) · `active` (solid ink) · `planned`
+    (an ink outline, the default) · `late` (solid accent) · `draft` (dashed,
+    breathing).
+  - `sub`: the small line under the name; default the segment's number.
+  - `gate`: `{ date?, pips: [{ id, label, met }] }`. The post stands at
+    `date` (default the segment's end). The pips are the exit criteria:
+    met is filled green, not met is a ring, with "2/4" beside the date.
+    A gate whose date has passed with criteria open shows its date in the
+    destructive tone; one with every criterion met has a green post. A gate
+    with no `pips` is just a dated post.
+- `milestones` — `[{ id, date, label, done, side }]`. `done` fills the
+  diamond. `side` ("right" default, or "left") is where the name goes; it
+  flips when there is no room.
+- `target` — the promise, 'YYYY-MM-DD'. Drawn as a solid line at the end of
+  that day.
+- `forecast` — where the chain will finish. **Left out, it is the chain's
+  last day.** `null` for none. Drawn as a dashed line, in the gap's tone.
+- `today` — 'YYYY-MM-DD' or null for no line.
+- `start` — the chain's start, when it begins before its first segment.
+- `ghost` — `[{ start, end }]`: where the segments sat in an earlier
+  version, dashed above the bars.
+- `count` — `"working"` (default; Monday to Friday) or `"calendar"`: which
+  days the gap counts. `workweek` — weekday numbers that count, 0 being
+  Monday (default `[0,1,2,3,4]`).
+- `words` — the app's vocabulary: `{ target: "Deadline", forecast, today,
+  on: "On target", over: (n) => "+" + n + " d", slack: (n) => n + " d slack",
+  undated: (n) => ..., early }`. Every key is optional.
+- `compact` — no gate posts and no flag words; the picture only.
+- `minWidth` — the least width in px the chain is drawn at (560). A
+  narrower container scrolls it sideways.
+- `from`, `to` — 'YYYY-MM-DD' to fix the window (`to` is its last day).
+  Default: everything drawn, with a little air.
+- `fitToday` — widen the window to take in today (default true). `false`:
+  today is drawn only when it already falls inside.
+- `onOpen({ kind, id, item })` — makes bars, gates and diamonds buttons
+  (`kind` is "segment", "gate" or "milestone"; `item` is what you passed,
+  with `s`/`e` day numbers added on a segment). Leave it out for a
+  read-only picture: nothing is pressable.
+- `loading`, `error`, `onRetry`, `empty`, `emptyAction` — the other states:
+  a skeleton; a danger notice with a "Try again" button when `onRetry` is
+  given (`error` may be a string); and with nothing dated, an empty panel
+  titled `empty` (default "Nothing is dated yet") with `emptyAction` in it.
+- `label` — what a screen reader hears first ("Website relaunch").
+  `className` — layout only.
+
+`GapRuler` — the target against the forecast and nothing else, about 380px
+wide, for a sentence to sit beside: `target`, `forecast` (both required),
+`count`, `workweek`, `words`, `label` (replaces the words under the ruler),
+`width` (the most px it takes), `className`.
+
+`ScheduleStrip` — the chain in one small row for a list: `segments`,
+`target`, `forecast`, `today`, `count`, `workweek`, `height` (16), `label`,
+`className`. Put the numbers in words beside it.
+
+Also exported, pure and without React, for a screen that wants the same
+numbers in a sentence: `gapOf({ target, forecast, count })` (`{ state:
+"over" | "slack" | "on", days, from, to }`), `gapWords`, `daysBetween`,
+`dayNumber`, `isoOf`, `shortDay`, `dayName`, `gateOf`, `frameOf`, `axisOf`,
+`layoutLanes`, `placeLabel`, `readSegments`, `readMilestones`,
+`summaryOf`, `WORKWEEK`.
+
+## Example
+
+```jsx
+<ScheduleRuler
+  label="Website relaunch"
+  segments={[
+    { id: "d", label: "Discovery", start: "2026-09-07", end: "2026-09-25", status: "done",
+      gate: { pips: [{ id: "a", met: true }, { id: "b", met: true }] } },
+    { id: "x", label: "Design", start: "2026-09-28", end: "2026-10-23", status: "active", sub: "1 of 3 met",
+      gate: { pips: [{ id: "a", met: true }, { id: "b", met: false }, { id: "c", met: false }] } },
+  ]}
+  milestones={[{ id: "k", date: "2026-10-02", label: "Kickoff held", done: true }]}
+  target="2026-10-16"
+  today="2026-10-12"
+  words={{ target: "Deadline" }}
+  onOpen={({ kind, id }) => router.push(`?${kind}=${id}`)}
+/>
+
+<GapRuler target={project.target} forecast={plan.finish} />
+```
+
+## States drawn
+
+- **Empty**: nothing dated. A panel with what to do (`empty`, `emptyAction`).
+- **One segment**, **many segments**: the window fits what is drawn.
+- **Very long names**: a bar's name is cut to one line (its full text is
+  the bar's title and, with `onOpen`, its accessible name); milestones and
+  gates that would touch take another row instead of sitting on one
+  another.
+- **Slack, overrun, on target**: green hatch and "3 d slack"; red hatch and
+  "+3 d"; no hatch and "On target".
+- **Narrow** (a 320px container): the chain keeps its `minWidth` and scrolls
+  sideways (focusable, so the keyboard can scroll it); under 36rem of its
+  own width the chain is also listed in words below it.
+- **Wide**: the chain stretches; the labels have more room than they need.
+- **Loading**, **failed** (with Try again), **read-only** (no `onOpen`).
+- Reduced motion: only a `draft` bar breathes, and it holds still.
+
+## Notes for the app that places it
+
+- It is a picture. Always put the numbers in words beside it as well (the
+  sentence "Public launch lands Tue 3 Nov, seven working days after the
+  target"). A screen reader hears one summary line of the whole chain, built
+  from what is drawn.
+- The block counts the gap in days; it does not know your holidays. If your
+  finish date already allows for them, pass `count="calendar"` or a
+  `workweek`, or draw the gap words yourself with `words`.
+- `forecast` left out is the chain's last day. To draw a promise with no
+  forecast, pass `forecast={null}`.
+- Colour is a signal here and nowhere else: green is early, red is late.

package/registry/blocks/schedule-ruler/block.json

@@ -0,0 +1,10 @@
+{
+  "name": "schedule-ruler",
+  "title": "Schedule ruler",
+  "description": "A dated chain drawn to scale on a day axis (a tick each Monday, a taller one on the 1st): the segments of the chain as bars with their names and status (done, in progress, planned, late, draft), a gate post at the end of a segment built from its exit criteria as pips (met are filled, with a 2/4 count, and the date turns to the warning tone once it has passed with criteria open), milestone diamonds with their names, a solid target line, a dashed forecast line, today as a line in the accent, and between target and forecast the gap hatched: green slack or a red overrun, counted in working days and labelled \"+3 d\" or \"3 d slack\". Earlier positions can show as dashed ghosts. GapRuler is the target against the forecast alone, for a sentence to sit beside; ScheduleStrip is the chain in one small row for a list. Positions are percentages, so it draws the same on the server; under 36rem of its own width the chain scrolls and is also listed in words. Loading, failed and empty states are drawn.",
+  "useWhen": "A screen that answers 'when does this finish, and against what promise': a project's phases and gates, a launch plan's finish against its target date, a roadmap row's forecast against its deadline, a delivery chain, a renewal or audit timeline. Draws a result the app has already worked out; it does not schedule. Not for editable bars with dependencies (gantt), days on a month grid (calendar-view), or the age of one thing against a limit (day-ruler).",
+  "tags": ["schedule", "timeline", "ruler", "phases", "gates", "milestones", "target", "deadline", "forecast", "slack", "overrun", "slip", "working days", "finish", "today line", "exit criteria", "roadmap", "project"],
+  "exports": ["ScheduleRuler", "GapRuler", "ScheduleStrip", "axisOf", "dayName", "dayNumber", "daysBetween", "frameOf", "gapOf", "gapWords", "gateOf", "isoOf", "layoutLanes", "placeLabel", "readMilestones", "readSegments", "shortDay", "summaryOf", "WORKWEEK"],
+  "files": ["index.js", "schedule-ruler.jsx", "ruler-model.js"],
+  "requires": []
+}

package/registry/blocks/schedule-ruler/demo.jsx

@@ -0,0 +1,181 @@
+"use client";
+
+// ScheduleRuler in every state — the gallery's and the smoke test's
+// surface. Not installed into apps: `makersclaw add schedule-ruler` lays
+// index.js, schedule-ruler.jsx and ruler-model.js only.
+//   A chain      five stages with gates built from pips, milestones, a
+//                target the forecast overruns, the earlier plan as ghosts;
+//                a press on a bar, a gate or a diamond says what it was.
+//   Slack        the same chain finishing early: green.
+//   Long words   a very long stage and milestone name in a crowded stretch.
+//   Compact      the chain without gate words and flags.
+//   Narrow       a 320 px container: the chain scrolls and is listed below.
+//   Wide         a container well past 1000 px.
+//   Read-only    no onOpen: nothing is pressable.
+//   Loading, failed and empty.
+//   GapRuler and ScheduleStrip alone.
+import { useState } from "react";
+import { Notice } from "../components/ui";
+import { GapRuler, ScheduleRuler, ScheduleStrip } from "../components/blocks/schedule-ruler";
+
+const TODAY = "2026-10-12";
+
+const STAGES = [
+  {
+    id: "disc",
+    label: "Discovery",
+    start: "2026-09-07",
+    end: "2026-09-25",
+    status: "done",
+    sub: "3 of 3 met",
+    gate: { date: "2026-09-25", pips: [{ id: "a", label: "Scope signed", met: true }, { id: "b", label: "Budget approved", met: true }, { id: "c", label: "Owner named", met: true }] },
+  },
+  {
+    id: "design",
+    label: "Design",
+    start: "2026-09-28",
+    end: "2026-10-23",
+    status: "active",
+    sub: "2 of 4 met",
+    gate: {
+      date: "2026-10-23",
+      pips: [{ id: "a", label: "Wireframes reviewed", met: true }, { id: "b", label: "Brand approved", met: true }, { id: "c", label: "Accessibility pass", met: false }, { id: "d", label: "Content outline", met: false }],
+    },
+  },
+  {
+    id: "build",
+    label: "Build",
+    start: "2026-10-26",
+    end: "2026-11-27",
+    status: "planned",
+    sub: "0 of 3 met",
+    gate: { date: "2026-11-27", pips: [{ id: "a", label: "Feature complete", met: false }, { id: "b", label: "Tests green", met: false }, { id: "c", label: "Security review", met: false }] },
+  },
+  { id: "test", label: "Testing", start: "2026-11-30", end: "2026-12-11", status: "planned", sub: "0 of 2 met", gate: { date: "2026-12-11", pips: [{ id: "a", label: "No open blockers", met: false }, { id: "b", label: "Sign-off", met: false }] } },
+  { id: "launch", label: "Launch", start: "2026-12-14", end: "2026-12-16", status: "draft", sub: "being written" },
+];
+const MILESTONES = [
+  { id: "m1", date: "2026-10-02", label: "Kickoff held", done: true },
+  { id: "m2", date: "2026-11-06", label: "Beta to ten customers" },
+  { id: "m3", date: "2026-12-04", label: "Press embargo lifts" },
+];
+const EARLIER = [
+  { start: "2026-09-07", end: "2026-09-22" },
+  { start: "2026-09-23", end: "2026-10-16" },
+  { start: "2026-10-19", end: "2026-11-20" },
+  { start: "2026-11-23", end: "2026-12-04" },
+];
+
+const EARLY = STAGES.map((s) => (s.id === "launch" ? { ...s, status: "planned", sub: "0 of 1 met" } : s)).slice(0, 4);
+
+const CROWDED = [
+  { id: "one", label: "An exceptionally long name for the first stage of this chain", start: "2026-10-05", end: "2026-10-09", status: "active", sub: "a very long second line that cannot fit", gate: { date: "2026-10-09", pips: [{ id: "a", met: true }, { id: "b", met: false }, { id: "c", met: false }, { id: "d", met: false }, { id: "e", met: false }, { id: "f", met: false }] } },
+  { id: "two", label: "Second", start: "2026-10-12", end: "2026-10-13", status: "planned", gate: { date: "2026-10-13", pips: [{ id: "a", met: false }] } },
+  { id: "three", label: "Third", start: "2026-10-14", end: "2026-10-15", status: "planned", gate: { date: "2026-10-15", pips: [{ id: "a", met: false }, { id: "b", met: false }] } },
+  { id: "four", label: "Fourth stage", start: "2026-10-16", end: "2026-10-30", status: "late", gate: { date: "2026-10-30" } },
+];
+const CROWDED_MILES = [
+  { id: "x1", date: "2026-10-07", label: "The extremely long milestone name goes here" },
+  { id: "x2", date: "2026-10-08", label: "Another one right beside it" },
+  { id: "x3", date: "2026-10-14", label: "Third" },
+];
+
+const ROWS = [
+  { name: "Website relaunch", segments: STAGES, target: "2026-12-11" },
+  { name: "Billing migration", segments: EARLY, target: "2026-12-24" },
+  { name: "On the nose", segments: EARLY, target: "2026-12-11" },
+  { name: "No promise yet", segments: STAGES.slice(0, 3) },
+];
+
+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>
+  );
+}
+
+export default function Demo() {
+  const [pressed, setPressed] = useState(null);
+  return (
+    <div className="grid min-w-0 gap-8 p-6">
+      <Section title="A chain" note="Press a bar, a gate or a diamond. The forecast runs three working days past the target.">
+        <ScheduleRuler
+          label="Website relaunch"
+          segments={STAGES}
+          milestones={MILESTONES}
+          target="2026-12-11"
+          forecast="2026-12-16"
+          today={TODAY}
+          ghost={EARLIER}
+          onOpen={setPressed}
+        />
+        <p aria-live="polite" className="font-mono text-xs text-muted-foreground">
+          {pressed ? `Pressed ${pressed.kind}: ${pressed.item.label}` : "Nothing pressed yet"}
+        </p>
+      </Section>
+
+      <Section title="Slack" note="Four stages, the last gate on 11 Dec; the target is 24 Dec, so the days between are slack.">
+        <ScheduleRuler label="Billing migration" segments={EARLY} target="2026-12-24" today={TODAY} words={{ target: "Deadline" }} />
+      </Section>
+
+      <Section title="On the nose" note="The forecast is the target: one line and the words 'On target'.">
+        <ScheduleRuler label="On the nose" segments={EARLY} target="2026-12-11" today={TODAY} />
+      </Section>
+
+      <Section title="Long words, crowded" note="Milestones and gates a day apart stack into lanes instead of sitting on one another.">
+        <ScheduleRuler label="Crowded" segments={CROWDED} milestones={CROWDED_MILES} target="2026-10-28" today="2026-10-13" />
+      </Section>
+
+      <Section title="Compact">
+        <ScheduleRuler compact label="Compact" segments={STAGES} target="2026-12-11" forecast="2026-12-16" today={TODAY} />
+      </Section>
+
+      <Section title="Narrow, 320 px" note="The chain scrolls sideways; below it the same chain in words.">
+        <div className="w-[320px] max-w-full rounded-md border border-border p-3">
+          <ScheduleRuler label="Narrow" segments={STAGES} milestones={MILESTONES} target="2026-12-11" forecast="2026-12-16" today={TODAY} />
+        </div>
+      </Section>
+
+      <Section title="Wide">
+        <div className="w-[1200px] max-w-none rounded-md border border-border p-4">
+          <ScheduleRuler label="Wide" segments={STAGES} milestones={MILESTONES} target="2026-12-11" forecast="2026-12-16" today={TODAY} />
+        </div>
+      </Section>
+
+      <Section title="Read-only" note="No onOpen: nothing is a button.">
+        <ScheduleRuler label="Read-only" segments={STAGES} target="2026-12-11" forecast="2026-12-16" today={TODAY} />
+      </Section>
+
+      <Section title="Loading, failed, empty">
+        <ScheduleRuler label="Loading" loading />
+        <ScheduleRuler label="Schedule" error="The dates could not be read. Check the connection." onRetry={() => setPressed({ kind: "retry", item: { label: "Try again" } })} />
+        <ScheduleRuler label="Empty" empty="No phases have dates yet" segments={[{ id: "u", label: "Draft", start: "", end: "" }]} />
+      </Section>
+
+      <Section title="GapRuler" note="The target against the forecast, for a sentence to sit beside.">
+        <div className="grid gap-4 @container">
+          <GapRuler target="2026-12-11" forecast="2026-12-16" />
+          <GapRuler target="2026-12-24" forecast="2026-12-11" />
+          <GapRuler target="2026-12-11" forecast="2026-12-11" />
+          <GapRuler target="2026-12-11" forecast="2026-12-12" count="calendar" words={{ over: (n) => `${n} day late` }} />
+        </div>
+      </Section>
+
+      <Section title="ScheduleStrip" note="One row of the chain, for a row in a list.">
+        <div className="grid max-w-xl gap-3">
+          {ROWS.map((r) => (
+            <div key={r.name} className="grid grid-cols-[minmax(0,10rem)_minmax(0,1fr)] items-center gap-4">
+              <span className="truncate text-sm font-medium">{r.name}</span>
+              <ScheduleStrip label={r.name} segments={r.segments} target={r.target} today={TODAY} />
+            </div>
+          ))}
+        </div>
+      </Section>
+
+      <Notice tone="info">Every date is a day, never a time: 2026-12-11 means the same day on the server and in the browser.</Notice>
+    </div>
+  );
+}

package/registry/blocks/schedule-ruler/index.js

@@ -0,0 +1,21 @@
+// The ScheduleRuler block — `makersclaw add schedule-ruler`. Fixed: compose
+// it through its props (README.md beside this file).
+export { ScheduleRuler, GapRuler, ScheduleStrip } from "./schedule-ruler";
+export {
+  axisOf,
+  dayName,
+  dayNumber,
+  daysBetween,
+  frameOf,
+  gapOf,
+  gapWords,
+  gateOf,
+  isoOf,
+  layoutLanes,
+  placeLabel,
+  readMilestones,
+  readSegments,
+  shortDay,
+  summaryOf,
+  WORKWEEK,
+} from "./ruler-model";

package/registry/blocks/schedule-ruler/ruler-model.js

@@ -0,0 +1,239 @@
+// The schedule ruler's arithmetic: dates, working days, the gap between a
+// target and a forecast, the window, the axis ticks, and where labels go
+// so none sits on another. Pure: no React, no DOM, no clock. The component
+// (schedule-ruler.jsx) draws what this returns; test/schedule-ruler.test.mjs
+// pins it.
+//
+// A "day" here is a whole number: days since 1970-01-01 in UTC, so a date
+// string means the same day on the server and in the browser.
+
+export const DAY_MS = 86400000;
+export const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+export const WEEKDAYS = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"];
+/** Monday to Friday, as weekdayOf() numbers it (0 is Monday). */
+export const WORKWEEK = [0, 1, 2, 3, 4];
+
+/** 'YYYY-MM-DD' (or an ISO time) to a day number; null when it is not a date. */
+export function dayNumber(iso) {
+  const m = /^(\d{4})-(\d{2})-(\d{2})/.exec(String(iso ?? ""));
+  if (!m) return null;
+  const t = Date.UTC(Number(m[1]), Number(m[2]) - 1, Number(m[3]));
+  const d = new Date(t);
+  // 2026-02-31 is not a day: Date rolls it over, and the roll-over shows.
+  if (d.getUTCMonth() !== Number(m[2]) - 1) return null;
+  return Math.round(t / DAY_MS);
+}
+
+/** A day number back to 'YYYY-MM-DD'. */
+export function isoOf(day) {
+  const d = new Date(day * DAY_MS);
+  return `${d.getUTCFullYear()}-${String(d.getUTCMonth() + 1).padStart(2, "0")}-${String(d.getUTCDate()).padStart(2, "0")}`;
+}
+
+/** 0 is Monday, 6 is Sunday. */
+export const weekdayOf = (day) => (new Date(day * DAY_MS).getUTCDay() + 6) % 7;
+export const dateOfMonth = (day) => new Date(day * DAY_MS).getUTCDate();
+export const monthOf = (day) => new Date(day * DAY_MS).getUTCMonth();
+export const yearOf = (day) => new Date(day * DAY_MS).getUTCFullYear();
+
+/** "11 Dec" */
+export const shortDay = (day) => `${dateOfMonth(day)} ${MONTHS[monthOf(day)]}`;
+/** "Fri 11 Dec" */
+export const dayName = (day) => `${WEEKDAYS[weekdayOf(day)]} ${shortDay(day)}`;
+
+/** Does this day count? `count` is "working" (the workweek only) or "calendar" (every day). */
+export function isCounted(day, count = "working", workweek = WORKWEEK) {
+  return count === "calendar" ? true : workweek.includes(weekdayOf(day));
+}
+
+/**
+ * Signed days from `from` to `to`, counting the days after `from` up to and
+ * including `to`: Mon to Wed is 2 working days, Wed to Mon is -2. The same
+ * rule everywhere, so "+3 d" means the same on the ruler, in a sentence and
+ * in a table.
+ */
+export function daysBetween(from, to, { count = "working", workweek = WORKWEEK } = {}) {
+  if (from == null || to == null) return null;
+  if (to === from) return 0;
+  const [a, b, sign] = to > from ? [from + 1, to, 1] : [to + 1, from, -1];
+  let n = 0;
+  for (let d = a; d <= b; d += 1) if (isCounted(d, count, workweek)) n += 1;
+  return sign * n;
+}
+
+/**
+ * The gap between a target and a forecast finish.
+ *   over   the forecast is later than the target: the days between are an overrun
+ *   slack  the forecast is earlier: the days between are room to spare
+ *   on     no counted day between them
+ * `from` and `to` are the first and last day of the hatched stretch.
+ * Null when either date is missing.
+ */
+export function gapOf({ target, forecast, count = "working", workweek = WORKWEEK } = {}) {
+  const t = typeof target === "number" ? target : dayNumber(target);
+  const f = typeof forecast === "number" ? forecast : dayNumber(forecast);
+  if (t == null || f == null) return null;
+  const days = Math.abs(daysBetween(t, f, { count, workweek }));
+  if (days === 0) return { state: "on", days: 0, from: null, to: null, target: t, forecast: f };
+  return f > t
+    ? { state: "over", days, from: t + 1, to: f, target: t, forecast: f }
+    : { state: "slack", days, from: f + 1, to: t, target: t, forecast: f };
+}
+
+/** "+3 d" for an overrun, "3 d slack" for room to spare, "On target" for none. */
+export function gapWords(gap, words = {}) {
+  if (!gap) return "";
+  if (gap.state === "over") return (words.over ?? ((n) => `+${n} d`))(gap.days);
+  if (gap.state === "slack") return (words.slack ?? ((n) => `${n} d slack`))(gap.days);
+  return words.on ?? "On target";
+}
+
+/**
+ * The segments that can be drawn: both dates real and the end not before
+ * the start. `skipped` counts the rest, so a screen can say so.
+ */
+export function readSegments(segments) {
+  const out = [];
+  let skipped = 0;
+  for (const [i, seg] of (segments ?? []).entries()) {
+    const s = dayNumber(seg?.start);
+    const e = dayNumber(seg?.end);
+    if (s == null || e == null || e < s) {
+      skipped += 1;
+      continue;
+    }
+    out.push({ ...seg, id: seg.id ?? `segment-${i}`, s, e });
+  }
+  return { segs: out, skipped };
+}
+
+/** Milestones with a real date, in date order. */
+export function readMilestones(milestones) {
+  const out = [];
+  for (const [i, m] of (milestones ?? []).entries()) {
+    const d = dayNumber(m?.date);
+    if (d != null) out.push({ ...m, id: m.id ?? `milestone-${i}`, day: d });
+  }
+  return out.sort((a, b) => a.day - b.day);
+}
+
+/**
+ * How a gate stands: how many of its exit criteria are met, and
+ *   met      every criterion met (a gate with criteria)
+ *   open     some are not, and the gate day is today or ahead
+ *   overdue  some are not, and the gate day has passed
+ *   bare     no criteria listed: just a date
+ */
+export function gateOf(gate, endDay, today) {
+  if (!gate) return null;
+  const day = dayNumber(gate.date) ?? endDay;
+  const pips = Array.isArray(gate.pips) ? gate.pips : [];
+  const total = pips.length;
+  const met = pips.filter((p) => p?.met).length;
+  const t = typeof today === "number" ? today : dayNumber(today);
+  let state = "bare";
+  if (total) state = met === total ? "met" : t != null && day < t ? "overdue" : "open";
+  return { day, pips, met, total, state };
+}
+
+/**
+ * The window of days the ruler shows. `days` are day numbers (a segment
+ * contributes its start and the day after its end). The window gets a little
+ * air either side; `from` and `to` (day numbers, `to` exclusive) override.
+ * x(day) is the day's left edge as a percentage of the window.
+ */
+export function frameOf({ days = [], from = null, to = null, padBefore = null, padAfter = null } = {}) {
+  const real = days.filter((d) => Number.isFinite(d));
+  if (!real.length && from == null && to == null) return null;
+  const lo = Math.min(...(real.length ? real : [from ?? to]));
+  const hi = Math.max(...(real.length ? real : [to ?? from]));
+  const span0 = Math.max(1, hi - lo);
+  const air = Math.max(2, Math.round(span0 * 0.025));
+  const r0 = from ?? lo - (padBefore ?? air);
+  const r1 = Math.max(r0 + 1, to ?? hi + (padAfter ?? air));
+  const span = r1 - r0;
+  return { r0, r1, span, x: (day) => ((day - r0) / span) * 100 };
+}
+
+/**
+ * The axis: a tick each Monday while the window is short enough to read
+ * them, a taller one on each month's 1st (each quarter's, past about two
+ * years), and the month names. The window's first day names its month
+ * unless the next month starts right after it.
+ */
+export function axisOf(r0, r1) {
+  const span = r1 - r0;
+  const quarters = span > 800;
+  const weeks = [];
+  const months = [];
+  if (span <= 150) for (let d = r0; d < r1; d += 1) if (weekdayOf(d) === 0) weeks.push(d);
+  let nextFirst = null;
+  for (let d = r0; d < r1; d += 1) {
+    if (dateOfMonth(d) === 1 && (!quarters || monthOf(d) % 3 === 0)) {
+      nextFirst ??= d;
+      months.push({ day: d, label: MONTHS[monthOf(d)], year: monthOf(d) === 0, tick: true });
+    }
+  }
+  const startsOnFirst = dateOfMonth(r0) === 1;
+  const crowded = !startsOnFirst && nextFirst != null && ((nextFirst - r0) / span) * 100 < 9;
+  if (!startsOnFirst && !crowded && !quarters) months.unshift({ day: r0, label: MONTHS[monthOf(r0)], year: true, tick: false });
+  else if (crowded && months.length) months[0] = { ...months[0], year: true };
+  if (!months.length) months.push({ day: r0, label: MONTHS[monthOf(r0)], year: true, tick: false });
+  return { weeks, months: months.map((m) => ({ ...m, label: m.year ? `${m.label} ${yearOf(m.day)}` : m.label })) };
+}
+
+/** Pixels a character of the small mono face takes (about); a label's width is a guess from its text. */
+export const CHAR_PX = 7.4;
+
+/** A label's width as a percentage of a chain `minWidth` px wide (the narrowest it is ever drawn). */
+export const labelPct = (chars, minWidth, extraPx = 12) => ((chars * CHAR_PX + extraPx) / minWidth) * 100;
+
+/**
+ * Where a label sits against the line it belongs to. It starts at the line
+ * and runs right; when it would run past the window's right edge it ends at
+ * the line and runs left instead (and the reverse at the left edge).
+ * Returns the side and the percentage interval the label covers.
+ */
+export function placeLabel({ x, width, prefer = "right" }) {
+  let side = prefer;
+  if (side === "right" && x + width > 100) side = "left";
+  if (side === "left" && x - width < 0 && x + width <= 100) side = "right";
+  const x0 = side === "right" ? x : x - width;
+  return { side, x0, x1: x0 + width };
+}
+
+/**
+ * Lanes for labels that would overlap: sorted left to right, each item takes
+ * the first lane whose last label ended at least `gap` percent before it
+ * starts. `items` are { id, x0, x1 } in percent; returns { lanes: {id: n},
+ * count } (count is the number of lanes used, 0 for none).
+ */
+export function layoutLanes(items, gap = 1) {
+  const ends = [];
+  const lanes = {};
+  const sorted = [...items].sort((a, b) => a.x0 - b.x0 || String(a.id).localeCompare(String(b.id)));
+  for (const it of sorted) {
+    let lane = ends.findIndex((end) => end + gap <= it.x0);
+    if (lane === -1) lane = ends.length;
+    ends[lane] = it.x1;
+    lanes[it.id] = lane;
+  }
+  return { lanes, count: ends.length };
+}
+
+/** The same line a screen reader hears for the whole ruler, built from what is drawn. */
+export function summaryOf({ label = "Schedule", segs = [], milestones = [], target = null, forecast = null, gap = null, today = null, words = {} }) {
+  const parts = segs.map((p) => {
+    const g = p.gate;
+    const crit = g?.total ? `, gate ${g.met} of ${g.total} met` : "";
+    return `${p.label}${p.status ? `, ${p.status}` : ""}, ${shortDay(p.s)} to ${shortDay(p.e)}${crit}`;
+  });
+  for (const m of milestones) parts.push(`${m.label}${m.done ? ", done" : ""}, ${shortDay(m.day)}`);
+  const head = parts.length ? parts.join("; ") : "nothing dated";
+  const tail = [];
+  if (target != null) tail.push(`${words.target ?? "Target"} ${dayName(target)}`);
+  if (forecast != null && gap?.state !== "on") tail.push(`${words.forecast ?? "Forecast"} ${dayName(forecast)}`);
+  if (gap) tail.push(gap.state === "on" ? (words.on ?? "On target") : `${gap.days} ${gap.days === 1 ? "day" : "days"} ${gap.state === "over" ? "over" : "of slack"}`);
+  if (today != null) tail.push(`${words.today ?? "Today"} ${dayName(today)}`);
+  return `${label}: ${head}${tail.length ? `; ${tail.join("; ")}` : ""}`;
+}