@litfamily/litclaude 1.0.21 → 1.0.23

package/plugins/litclaude/lib/mod/state.mjs

@@ -0,0 +1,411 @@
+// Read-only view of LitClaude's own state (and the Git HEAD it works on) for the LIT band. Nothing here writes, spawns, fetches or
+// follows a link: every read goes through an injected `io` ({ stat, read }) that the mod backs with
+// `$.fs.stat(path, { resolve: true })` and `$.fs.read`, and the tests back with a map. A file is read
+// only when it is a regular file, under its size cap, not itself a link, and lands exactly where its
+// spelled path says once every link is resolved, so a symlinked `.litclaude` or state file is skipped.
+//
+// The two roots mirror the hook: `.litclaude` sits at the outermost Git root (project-state-root.mjs),
+// while boulder.json is found the way `lifecycleRootFor` in bin/litclaude-hook.js finds it, walking up
+// from the working directory and across a linked Git worktree to its main checkout.
+
+export const STATE_CAPS = Object.freeze({
+  boulder: 2 * 1024 * 1024,
+  goals: 512 * 1024,
+  ledger: 512 * 1024,
+  small: 64 * 1024,
+  gitMarker: 4096,
+});
+
+// Mirrors PROJECT_MARKERS in rules/constants.mjs, the fallback when no Git root exists.
+const PROJECT_MARKERS = Object.freeze([".git", "pnpm-workspace.yaml", "package.json", "pyproject.toml", "Cargo.toml", "go.mod", ".venv"]);
+export const AUTOLOOP_LIMITS = Object.freeze({ blocks: 8, ms: 30 * 60 * 1000 });
+export const GATE_LIMITS = Object.freeze({ litPlan: 2, probe: 2, motion: 2 });
+
+const splitPath = (path) => String(path).replaceAll("\\", "/").split("/").filter((part, index) => part !== "" || index === 0);
+
+export const normalizePath = (path) => {
+  const parts = [];
+  const raw = String(path).replaceAll("\\", "/");
+  const absolute = raw.startsWith("/");
+  const drive = /^[A-Za-z]:/u.exec(raw)?.[0] ?? "";
+  for (const part of raw.slice(drive.length).split("/")) {
+    if (part === "" || part === ".") continue;
+    if (part === "..") parts.pop();
+    else parts.push(part);
+  }
+  return `${drive}${absolute || drive ? "/" : ""}${parts.join("/")}`;
+};
+
+export const joinPath = (...parts) => normalizePath(parts.filter((part) => part !== "").join("/"));
+
+export const parentOf = (path) => {
+  const normalized = normalizePath(path);
+  const cut = normalized.lastIndexOf("/");
+  if (cut <= 0) return normalized.slice(0, cut + 1) || normalized;
+  const parent = normalized.slice(0, cut);
+  return /^[A-Za-z]:$/u.test(parent) ? `${parent}/` : parent;
+};
+
+const isAbsolute = (path) => /^(?:[A-Za-z]:)?[\\/]/u.test(String(path));
+export const resolvePath = (base, path) => (isAbsolute(path) ? normalizePath(path) : joinPath(base, path));
+
+const ancestors = (start) => {
+  const list = [];
+  let current = normalizePath(start);
+  for (;;) {
+    list.push(current);
+    const parent = parentOf(current);
+    if (parent === current) return list;
+    current = parent;
+  }
+};
+
+const statOf = async (io, path) => {
+  try {
+    return (await io.stat(path)) ?? null;
+  } catch {
+    return null;
+  }
+};
+
+export const resolveStateRoot = async (io, cwd) => {
+  const chain = ancestors(cwd);
+  let outermostGit = null;
+  for (const directory of chain) if (await statOf(io, joinPath(directory, ".git"))) outermostGit = directory;
+  if (outermostGit) return outermostGit;
+  for (const directory of chain) {
+    for (const marker of PROJECT_MARKERS) if (await statOf(io, joinPath(directory, marker))) return directory;
+  }
+  return normalizePath(cwd);
+};
+
+export const resolveLifecycleRoot = async (io, cwd, stateRoot) => {
+  for (const directory of ancestors(cwd)) {
+    if (await statOf(io, joinPath(directory, ".litclaude", "boulder.json"))) return directory;
+    const marker = joinPath(directory, ".git");
+    const stat = await statOf(io, marker);
+    if (stat?.kind === "file" && !stat.isLink && stat.size <= STATE_CAPS.gitMarker) {
+      let text = "";
+      try {
+        text = await io.read(marker);
+      } catch {
+        text = "";
+      }
+      const match = /^gitdir:\s*(.+?)\s*$/mu.exec(text);
+      if (match) {
+        const worktreesDir = parentOf(resolvePath(directory, match[1]));
+        if (splitPath(worktreesDir).at(-1) === "worktrees") {
+          const mainRoot = parentOf(parentOf(worktreesDir));
+          if (await statOf(io, joinPath(mainRoot, ".litclaude", "boulder.json"))) return mainRoot;
+        }
+      }
+    }
+  }
+  return stateRoot;
+};
+
+// One guarded read. `root` is the directory the file must stay under; the comparison is made on
+// resolved paths so a link anywhere between the root and the file shows up as a mismatch.
+export const readGuarded = async (io, root, relative, cap) => {
+  const path = joinPath(root, relative);
+  const stat = await statOf(io, path);
+  if (!stat || stat.isLink || stat.kind !== "file" || !(stat.size <= cap)) return null;
+  if (stat.realPath !== undefined) {
+    const rootStat = await statOf(io, root);
+    const realRoot = rootStat?.realPath;
+    if (realRoot === undefined || normalizePath(stat.realPath) !== joinPath(realRoot, relative)) return null;
+  }
+  try {
+    const text = await io.read(path);
+    return typeof text === "string" && text.length <= cap ? text : null;
+  } catch {
+    return null;
+  }
+};
+
+export const readGuardedJson = async (io, root, relative, cap) => {
+  const text = await readGuarded(io, root, relative, cap);
+  if (text === null) return null;
+  try {
+    const value = JSON.parse(text);
+    return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
+  } catch {
+    return null;
+  }
+};
+
+const str = (value, max = 400) => (typeof value === "string" && value.length > 0 ? value.slice(0, max) : null);
+const int = (value) => (Number.isInteger(value) && value >= 0 ? value : 0);
+const num = (value) => (Number.isFinite(value) ? value : null);
+const time = (value) => {
+  const parsed = typeof value === "string" ? Date.parse(value) : Number.NaN;
+  return Number.isFinite(parsed) ? parsed : null;
+};
+
+// Per-session file names, spelled as hud-ignition.mjs (ignition) and auto-handoff.mjs (session) do.
+export const ignitionFileName = (sessionId) => {
+  const raw = typeof sessionId === "string" && sessionId.trim() ? sessionId.trim() : "unknown-session";
+  return `${raw.replace(/[^A-Za-z0-9._-]/gu, "_").replace(/^\.+/u, "_")}.json`;
+};
+const handoffSessionId = (sessionId) => (typeof sessionId === "string" ? sessionId.replace(/[^A-Za-z0-9_-]/gu, "").slice(0, 64) : "");
+
+export const ignitionRoot = (env) => {
+  const override = env?.LITCLAUDE_HUD_STATE_ROOT?.trim();
+  if (override) return normalizePath(override);
+  return joinPath(env?.TMPDIR?.trim() || "/tmp", "litclaude-hud");
+};
+
+export const parseIgnition = (record, sessionId) => {
+  if (!record || (record.sessionId !== null && record.sessionId !== sessionId)) return null;
+  const discipline = str(record.discipline, 80);
+  return discipline ? { discipline, at: time(record.at) } : null;
+};
+
+const workBelongs = (work, sessionId) =>
+  work.root_session_id === sessionId
+  || work.active_session_id === sessionId
+  || (Array.isArray(work.session_ids) && work.session_ids.includes(sessionId));
+
+const laneList = (lanes) => Object.values(lanes && typeof lanes === "object" ? lanes : {})
+  .filter((lane) => lane && typeof lane === "object")
+  .map((lane) => ({
+    id: str(lane.agent_id, 120) ?? "lane",
+    type: str(lane.agent_type, 80) ?? "agent",
+    status: str(lane.status, 40) ?? "unknown",
+    startedAt: time(lane.started_at),
+  }))
+  .slice(0, 32);
+
+export const parseBoulder = (state, sessionId) => {
+  if (!state || !state.works || typeof state.works !== "object") return { work: null, completed: [] };
+  const completed = Object.values(state.works)
+    .filter((work) => work && work.status === "completed" && workBelongs(work, sessionId))
+    .map((work) => str(work.work_id, 120))
+    .filter(Boolean);
+  const active = state.active_work_id ? state.works[state.active_work_id] : null;
+  if (!active || !["active", "paused"].includes(active.status) || !workBelongs(active, sessionId)) return { work: null, completed };
+  const progress = active.progress && typeof active.progress === "object" ? active.progress : {};
+  const total = int(progress.total);
+  return {
+    work: {
+      id: str(active.work_id, 120) ?? String(state.active_work_id),
+      status: active.status,
+      planName: str(active.plan_name, 200),
+      total,
+      checked: Math.min(int(progress.checked), total),
+      nextTask: str(progress.next_task, 400),
+      lanes: laneList(active.lanes),
+    },
+    completed,
+  };
+};
+
+const CRITERION_STATUSES = new Set(["pass", "fail", "blocked", "pending"]);
+
+export const parseGoals = (state, sessionId) => {
+  if (!state || typeof state.status !== "string") return null;
+  if (typeof state.sessionId === "string" && state.sessionId !== sessionId) return null;
+  const criteria = (Array.isArray(state.criteria) ? state.criteria : []).slice(0, 40).map((criterion, index) => {
+    const evidence = Array.isArray(criterion?.evidence) ? criterion.evidence : [];
+    const status = CRITERION_STATUSES.has(criterion?.status) ? criterion.status : "pending";
+    return {
+      id: str(criterion?.id, 80) ?? `criterion-${index + 1}`,
+      description: str(criterion?.description, 300) ?? "",
+      status,
+      attempts: evidence.length,
+      lastAt: time(evidence.at(-1)?.recordedAt),
+    };
+  });
+  return {
+    objective: str(state.objective, 400) ?? "",
+    status: state.status,
+    autoloop: state.autoloop === true,
+    criteria,
+    blockers: (Array.isArray(state.blockers) ? state.blockers : []).slice(0, 10)
+      .map((blocker) => str(typeof blocker === "string" ? blocker : blocker?.note ?? blocker?.description, 300))
+      .filter(Boolean),
+    lastCheckpoint: str(Array.isArray(state.checkpoints) ? state.checkpoints.at(-1)?.status : null, 40),
+    createdAt: time(state.createdAt),
+  };
+};
+
+export const parseAutoloop = (state) => {
+  if (!state || !Number.isInteger(state.blockCount) || state.blockCount < 0 || !Number.isFinite(state.firstBlockAt)) return null;
+  return { blockCount: state.blockCount, firstBlockAt: state.firstBlockAt };
+};
+
+const forSession = (state, sessionId) => (state && state.sessionId === sessionId ? state : null);
+
+export const parseLitPlanTurn = (state, sessionId) => {
+  const turn = forSession(state, sessionId);
+  return turn ? { blockCount: int(turn.blockCount), warned: turn.warned === true, promptAt: num(turn.promptAt) } : null;
+};
+
+export const parseProbeTurn = (state, sessionId) => {
+  const turn = forSession(state, sessionId);
+  if (!turn) return null;
+  return {
+    editAt: num(turn.editAt),
+    probeAt: num(turn.probeAt),
+    issue: str(turn.issue, 160),
+    issueAt: num(turn.issueAt),
+    paths: (Array.isArray(turn.paths) ? turn.paths : []).map((path) => str(path, 200)).filter(Boolean).slice(0, 5),
+    blockCount: int(turn.blockCount),
+  };
+};
+
+export const parseMotionTurn = (state, sessionId) => {
+  const turn = forSession(state, sessionId);
+  return turn ? { blockCount: int(turn.blockCount), runs: Array.isArray(turn.runs) ? turn.runs.length : 0, notified: turn.notified === true } : null;
+};
+
+const percentOf = (raw) => {
+  const text = typeof raw === "number" ? String(raw) : raw;
+  if (typeof text !== "string" || !/^(?:[1-9]\d?)$/u.test(text.trim())) return null;
+  return Number(text.trim());
+};
+
+// The environment wins over the saved choice, as resolveAutoHandoff in auto-handoff.mjs decides.
+export const parseAutoHandoff = (settings, session, env) => {
+  const flag = env?.LITCLAUDE_AUTO_HANDOFF;
+  const enabled = flag !== undefined ? flag === "1" : settings?.enabled === true;
+  const percent = percentOf(env?.LITCLAUDE_AUTO_HANDOFF_PERCENT !== undefined ? env.LITCLAUDE_AUTO_HANDOFF_PERCENT : settings?.percent ?? null);
+  if (!enabled || percent === null) return null;
+  return {
+    percent,
+    firedAt: num(session?.firedAt),
+    firedAtPercent: num(session?.firedAtPercent),
+    pending: session?.pending === true,
+  };
+};
+
+export const readLitSnapshot = async (io, { cwd, sessionId, env = {} }) => {
+  const stateRoot = await resolveStateRoot(io, cwd);
+  const lifecycleRoot = await resolveLifecycleRoot(io, cwd, stateRoot);
+  const state = (relative, cap = STATE_CAPS.small) => readGuardedJson(io, stateRoot, joinPath(".litclaude", relative), cap);
+  const handoffId = handoffSessionId(sessionId);
+  const [ignition, boulder, goals, autoloop, litPlan, probe, motion, handoffSettings, handoffSession] = await Promise.all([
+    readGuardedJson(io, ignitionRoot(env), ignitionFileName(sessionId), STATE_CAPS.small),
+    readGuardedJson(io, lifecycleRoot, joinPath(".litclaude", "boulder.json"), STATE_CAPS.boulder),
+    state("litgoal/goals.json", STATE_CAPS.goals),
+    state("litgoal/autoloop.json"),
+    state("lit-plan/turn.json"),
+    state("interface-probe/turn.json"),
+    state("motion/turn.json"),
+    state("auto-handoff/settings.json"),
+    handoffId ? state(`auto-handoff/session-${handoffId}.json`) : null,
+  ]);
+  const { work, completed } = parseBoulder(boulder, sessionId);
+  return {
+    stateRoot,
+    lifecycleRoot,
+    ignition: parseIgnition(ignition, sessionId),
+    work,
+    completedWorkIds: completed,
+    goal: parseGoals(goals, sessionId),
+    autoloop: parseAutoloop(autoloop),
+    litPlan: parseLitPlanTurn(litPlan, sessionId),
+    probe: parseProbeTurn(probe, sessionId),
+    motion: parseMotionTurn(motion, sessionId),
+    handoff: parseAutoHandoff(handoffSettings, handoffSession, env),
+  };
+};
+
+const readSmall = async (io, path, cap) => {
+  const stat = await statOf(io, path);
+  if (!stat || stat.kind !== "file" || !(stat.size <= cap)) return null;
+  try {
+    const text = await io.read(path);
+    return typeof text === "string" && text.length <= cap ? text : null;
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * The branch the working directory is on, for the card's bottom edge: the nearest `.git` above
+ * `cwd`, followed through a linked worktree's `gitdir:` file, and its HEAD read as text. A
+ * detached HEAD gives the short commit; anything unreadable gives null.
+ */
+export const readGitBranch = async (io, cwd) => {
+  for (const directory of ancestors(cwd)) {
+    const marker = joinPath(directory, ".git");
+    const stat = await statOf(io, marker);
+    if (!stat) continue;
+    let gitDir = marker;
+    if (stat.kind === "file") {
+      const pointer = await readSmall(io, marker, STATE_CAPS.gitMarker);
+      const match = pointer === null ? null : /^gitdir:\s*(.+?)\s*$/mu.exec(pointer);
+      if (!match) return null;
+      gitDir = resolvePath(directory, match[1]);
+    }
+    const head = (await readSmall(io, joinPath(gitDir, "HEAD"), STATE_CAPS.gitMarker))?.trim();
+    if (!head) return null;
+    const ref = /^ref:\s*refs\/heads\/(.+)$/u.exec(head);
+    if (ref) return ref[1].slice(0, 120);
+    return /^[0-9a-f]{7,64}$/u.test(head) ? head.slice(0, 7) : null;
+  }
+  return null;
+};
+
+// The icon font the installer's opt-in step writes (bin/icon-font.mjs), or the proportional
+// symbols font a person installed some other way, in each per-user font folder.
+const ICON_FONT_NAMES = Object.freeze(["SymbolsNerdFontMono-Regular.ttf", "SymbolsNerdFont-Regular.ttf"]);
+
+export const iconFontCandidates = (env) => {
+  const home = env?.HOME?.trim();
+  const folders = [];
+  if (home) folders.push(joinPath(home, "Library", "Fonts"));
+  const data = env?.XDG_DATA_HOME?.trim() || (home ? joinPath(home, ".local", "share") : "");
+  if (data) folders.push(joinPath(data, "fonts"));
+  const local = env?.LOCALAPPDATA?.trim();
+  if (local) folders.push(joinPath(local, "Microsoft", "Windows", "Fonts"));
+  return folders.flatMap((folder) => ICON_FONT_NAMES.map((name) => joinPath(folder, name)));
+};
+
+/**
+ * Whether the icon font is installed, by stat alone (the font is never read). `note` says what
+ * the band decided and why, for the evidence pane; a folder that cannot be checked counts as no
+ * font, so the band falls back to basic glyphs rather than drawing boxes.
+ */
+export const detectIconFont = async (io, env) => {
+  const candidates = iconFontCandidates(env);
+  if (candidates.length === 0) return { present: false, path: null, note: "basic: no home folder to look in for the icon font" };
+  let unreadable = false;
+  for (const path of candidates) {
+    try {
+      const stat = await io.stat(path);
+      if (stat?.kind === "file") return { present: true, path, note: `nerd: Symbols Nerd Font found at ${path}` };
+    } catch (error) {
+      if (!/ENOENT|no such file|not found/iu.test(String(error?.message ?? error))) unreadable = true;
+    }
+  }
+  return unreadable
+    ? { present: false, path: null, note: "basic: the font folders could not be checked from the band" }
+    : { present: false, path: null, note: "basic: Symbols Nerd Font not found (litclaude-ai install --icon-font)" };
+};
+
+// The litgoal ledger's newest entries for the evidence pane, newest first. Lines that are not JSON
+// objects are skipped; the file is read only under its cap.
+export const readLedgerTail = async (io, stateRoot, limit = 8) => {
+  const text = await readGuarded(io, stateRoot, ".litclaude/litgoal/ledger.jsonl", STATE_CAPS.ledger);
+  if (text === null) return [];
+  const entries = [];
+  for (const line of text.split("\n").reverse()) {
+    if (entries.length >= limit) break;
+    if (!line.trim()) continue;
+    try {
+      const entry = JSON.parse(line);
+      if (!entry || typeof entry !== "object" || Array.isArray(entry)) continue;
+      entries.push({
+        event: str(entry.event, 60) ?? "event",
+        at: time(entry.timestamp),
+        detail: str(entry.criterionId ?? entry.note ?? entry.objective ?? entry.status, 120) ?? "",
+        status: str(entry.status, 40),
+      });
+    } catch {
+      // A torn final line from a concurrent append; the next refresh reads it whole.
+    }
+  }
+  return entries;
+};

package/plugins/litclaude/lib/mod/timeline.mjs

@@ -0,0 +1,152 @@
+// The band's timeline: which animations are running and since when. The surface module keeps one
+// timeline in its local state, folds every new model into it (advanceTimeline), samples it once per
+// frame (sampleTimeline) and stops its frame timer as soon as nothing moves (timelineBusy). Times are
+// the surface module's own frame clock in milliseconds; nothing here reads a wall clock.
+
+import { EASE, TIMINGS, isSettled, phase, retarget, sample, still } from "./motion.mjs";
+
+const PHASES = ["plan", "work", "review"];
+const fractionOf = (model) => (model.progress && model.progress.total > 0 ? Math.min(1, model.progress.done / model.progress.total) : 0);
+
+const entryEnd = (profile) => 3 * profile.duration(TIMINGS.stagger) + profile.duration(TIMINGS.entry);
+
+// One entry per chip: `at` is the firing the model reported, `arrivedAt` when this timeline saw
+// that firing arrive (null for chips already there when the band appeared, so they do not shimmer),
+// and the state crossfade from `from` to `state` starting at `changedAt`.
+const chipsOf = (model, now, previous = null) => Object.fromEntries((model.skills ?? []).map((chip) => {
+  const known = previous?.[chip.id];
+  if (!known || known.at !== chip.at) {
+    return [chip.id, { at: chip.at, arrivedAt: previous === null ? null : now, state: chip.state, from: chip.state, changedAt: now }];
+  }
+  if (known.state !== chip.state) return [chip.id, { ...known, from: known.state, state: chip.state, changedAt: now }];
+  return [chip.id, known];
+}));
+
+export const createTimeline = (model, now, profile) => {
+  const restAt = now + entryEnd(profile);
+  return {
+    enterAt: now,
+    exitAt: null,
+    fill: { from: 0, to: fractionOf(model), at: restAt, dur: profile.duration(TIMINGS.fill) },
+    done: model.progress?.done ?? null,
+    flashAt: null,
+    warn: still(model.ctxWarning ? 1 : 0),
+    phases: Object.fromEntries(PHASES.map((id) => [id, { from: model.phases[id], to: model.phases[id], at: now }])),
+    notice: model.notice ? { data: model.notice, at: restAt } : null,
+    leaving: null,
+    completion: model.completion ? { data: model.completion, at: now } : null,
+    chips: chipsOf(model, now),
+  };
+};
+
+export const advanceTimeline = (timeline, model, now, profile) => {
+  const next = { ...timeline };
+  if (!model.visible && timeline.exitAt === null) next.exitAt = now;
+  if (model.visible && timeline.exitAt !== null) return createTimeline(model, now, profile);
+  next.fill = retarget(timeline.fill, fractionOf(model), now, profile.duration(TIMINGS.fill));
+  const done = model.progress?.done ?? null;
+  if (done !== timeline.done) {
+    next.done = done;
+    if (timeline.done !== null && done !== null) next.flashAt = now;
+  }
+  next.warn = retarget(timeline.warn, model.ctxWarning ? 1 : 0, now, profile.duration(TIMINGS.crossfade));
+  next.phases = Object.fromEntries(PHASES.map((id) => {
+    const current = timeline.phases[id];
+    return [id, current.to === model.phases[id] ? current : { from: current.to, to: model.phases[id], at: now }];
+  }));
+  const incoming = model.notice?.id ?? null;
+  if (incoming !== (timeline.notice?.data.id ?? null)) {
+    next.leaving = timeline.notice ? { data: timeline.notice.data, at: now } : timeline.leaving;
+    next.notice = model.notice ? { data: model.notice, at: now } : null;
+  }
+  if ((model.completion?.id ?? null) !== (timeline.completion?.data.id ?? null)) {
+    next.completion = model.completion ? { data: model.completion, at: now } : null;
+  }
+  next.chips = chipsOf(model, now, timeline.chips);
+  return next;
+};
+
+export const timelineBusy = (timeline, now, profile) => {
+  const d = profile.duration;
+  if (timeline.exitAt !== null) return now < timeline.exitAt + d(TIMINGS.exit);
+  if (now < timeline.enterAt + entryEnd(profile)) return true;
+  if (!isSettled(timeline.fill, now) || !isSettled(timeline.warn, now)) return true;
+  if (timeline.flashAt !== null && now < timeline.flashAt + d(TIMINGS.flash)) return true;
+  if (PHASES.some((id) => timeline.phases[id].from !== timeline.phases[id].to && now < timeline.phases[id].at + d(TIMINGS.crossfade))) return true;
+  if (timeline.notice && now < timeline.notice.at + d(TIMINGS.noticeIn)) return true;
+  if (timeline.leaving && now < timeline.leaving.at + d(TIMINGS.noticeOut)) return true;
+  if (timeline.completion && now < timeline.completion.at + d(TIMINGS.completion)) return true;
+  return Object.values(timeline.chips).some((chip) => (chip.arrivedAt !== null && now < chip.arrivedAt + d(TIMINGS.shimmer))
+    || (chip.from !== chip.state && now < chip.changedAt + d(TIMINGS.crossfade)));
+};
+
+/**
+ * Everything one frame needs, as numbers: how far each pill has popped in (ease-out-back, so it may
+ * pass 1 briefly), the bar's fill, the count flash, the amber mix, each phase's colour crossfade,
+ * the notice row's offset in cells, the completion shimmer and embers, and per chip how far its
+ * arrival has run (`arrive`, 0 to 1; 1 once settled), where full motion's light stands on its
+ * name (`shimmer`, null when none) and its state crossfade.
+ */
+export const sampleTimeline = (timeline, now, profile) => {
+  const d = profile.duration;
+  const exit = timeline.exitAt === null ? 0 : EASE.inCubic(phase(now, timeline.exitAt, d(TIMINGS.exit)));
+  const pills = [0, 1, 2, 3].map((index) => {
+    const popped = profile.enterEase(phase(now, timeline.enterAt + index * d(TIMINGS.stagger), d(TIMINGS.entry)));
+    return Math.max(0, popped * (1 - exit));
+  });
+  const rest = exit > 0 ? 0 : phase(now, timeline.enterAt + entryEnd(profile), 1);
+  const flash = timeline.flashAt === null ? 0 : Math.sin(Math.PI * phase(now, timeline.flashAt, d(TIMINGS.flash)));
+  const phases = Object.fromEntries(PHASES.map((id) => {
+    const { from, to, at } = timeline.phases[id];
+    return [id, { from, to, mix: from === to ? 1 : EASE.inOutCubic(phase(now, at, d(TIMINGS.crossfade))) }];
+  }));
+  let notice = null;
+  if (timeline.notice) {
+    const p = phase(now, timeline.notice.at, d(TIMINGS.noticeIn));
+    notice = { data: timeline.notice.data, offset: Math.max(0, Math.round(14 * (1 - profile.noticeEase(p)))) };
+  } else if (timeline.leaving && now < timeline.leaving.at + d(TIMINGS.noticeOut)) {
+    notice = { data: timeline.leaving.data, offset: Math.round(40 * EASE.inCubic(phase(now, timeline.leaving.at, d(TIMINGS.noticeOut)))) };
+  }
+  let completion = null;
+  if (timeline.completion) {
+    const at = timeline.completion.at;
+    completion = {
+      data: timeline.completion.data,
+      shimmer: profile.shimmer && now >= at + d(50) && now < at + d(50) + d(TIMINGS.shimmer)
+        ? EASE.outCubic(phase(now, at + d(50), d(TIMINGS.shimmer))) * 1.3 - 0.15
+        : null,
+      embers: profile.embers ? phase(now, at, d(TIMINGS.embers)) : null,
+      title: EASE.outCubic(phase(now, at + d(30), d(200))),
+      detail: EASE.outCubic(phase(now, at + d(100), d(200))),
+    };
+  }
+  const chips = Object.fromEntries(Object.entries(timeline.chips).map(([id, chip]) => {
+    const arrive = chip.arrivedAt === null ? 1 : phase(now, chip.arrivedAt, d(TIMINGS.shimmer));
+    return [id, {
+      arrive,
+      shimmer: profile.shimmer && arrive < 1 ? EASE.outCubic(arrive) * 1.3 - 0.15 : null,
+      from: chip.from,
+      to: chip.state,
+      mix: chip.from === chip.state ? 1 : EASE.inOutCubic(phase(now, chip.changedAt, d(TIMINGS.crossfade))),
+    }];
+  }));
+  return {
+    pills,
+    rest,
+    exit,
+    fill: sample(timeline.fill, now),
+    fillGlow: isSettled(timeline.fill, now) ? 0 : Math.sin(Math.PI * phase(now, timeline.fill.at, timeline.fill.dur)),
+    flash,
+    warn: sample(timeline.warn, now),
+    phases,
+    notice,
+    completion,
+    chips,
+  };
+};
+
+/** The final frame of a model, for motion off, surfaces without frame clocks and tests. */
+export const settledSample = (model) => {
+  const profile = { duration: () => 0, enterEase: EASE.linear, noticeEase: EASE.linear, shimmer: false, embers: false };
+  return sampleTimeline(createTimeline(model, 0, profile), 1, profile);
+};