@ossclip/core 0.1.0

package/src/content-rect.ts

@@ -0,0 +1,324 @@
+
+/**
+ * Letterbox detection (PLAN 2026-07-28 Task 7).
+ *
+ * A source file's frame is not always its picture. A screen-recorded or
+ * re-exported clip can carry black bars baked into the pixels — one real case
+ * probed as 1440×2560 portrait while the actual shot was a landscape strip
+ * with bars above and below. Every geometric consumer then reasoned about the
+ * wrong frame: `video-top` showed mostly bar, `blurred-behind` blurred black
+ * into more black, the face detector searched an area two-thirds empty, and
+ * `sourceAspect` described the container instead of the picture.
+ *
+ * The fix is one measurement, made early and consumed everywhere: the CONTENT
+ * RECT — the largest area that is ever non-black across sampled frames. It is
+ * a property of the source, cached beside `face.json`, and each downstream
+ * ffmpeg pass prepends a `crop` to it so the rest of the pipeline never sees
+ * the bars at all.
+ *
+ * Detection is ffmpeg's own `cropdetect` (parsed from stderr exactly the way
+ * `detectSilences` reads `silencedetect`), not hand-rolled pixel scanning.
+ * The union across samples is what keeps a dark shot honest: a bar has to be
+ * black in EVERY sampled frame, so a night scene that ever shows anything at
+ * its edges keeps its full frame.
+ */
+
+/** Pixel rect inside the source frame. */
+export interface ContentRect {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+  /** True when the rect IS the frame — nothing to trim, no crop pass runs. */
+  full: boolean;
+}
+
+/** One cropdetect measurement, with the source time it was taken at. */
+export interface CropSample {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+  /** Source seconds, from cropdetect's own `t:` field. */
+  tSec: number;
+}
+
+/**
+ * Per-frame `crop=W:H:X:Y` lines from cropdetect's stderr, with timestamps.
+ *
+ * The timestamp is not decoration: a source whose framing changes mid-take
+ * needs to know WHEN it changed, not merely that two different rects were seen.
+ * ffmpeg prints `t:` on the same line, so this costs nothing.
+ */
+export function parseCropdetect(stderr: string): CropSample[] {
+  const out: CropSample[] = [];
+  for (const line of stderr.split("\n")) {
+    const m = line.match(/crop=(\d+):(\d+):(\d+):(\d+)/);
+    if (!m) continue;
+    const t = line.match(/\bt:(-?[\d.]+)/);
+    out.push({
+      w: Number(m[1]),
+      h: Number(m[2]),
+      x: Number(m[3]),
+      y: Number(m[4]),
+      tSec: t ? Number(t[1]) : 0,
+    });
+  }
+  return out;
+}
+
+/**
+ * A bar thinner than this fraction of its dimension is treated as not there.
+ * Encoder padding and edge vignetting produce a few dark rows on perfectly
+ * ordinary footage; trimming them would change every geometry downstream to
+ * chase two invisible pixels.
+ */
+const SNAP_FRAC = 0.02;
+
+/**
+ * Below this share of the frame the measurement is refused. A clip dark
+ * enough to "detect" a content rect this small is a clip cropdetect cannot be
+ * trusted on — a fade-from-black or a genuinely dim shot — and cropping a
+ * video to a sliver on bad evidence is far worse than leaving bars alone.
+ */
+const MIN_CONTENT_FRAC = 0.25;
+
+/**
+ * The stable rect from per-frame measurements: the UNION of everything any
+ * sample considered content, snapped per side so hairline bars don't trigger
+ * a crop, and refused outright when the result is implausibly small.
+ */
+export function stableContentRect(
+  rects: ReadonlyArray<{ x: number; y: number; w: number; h: number }>,
+  width: number,
+  height: number,
+): ContentRect {
+  const whole: ContentRect = { x: 0, y: 0, w: width, h: height, full: true };
+  if (rects.length === 0 || width <= 0 || height <= 0) return whole;
+
+  let left = Infinity;
+  let top = Infinity;
+  let right = -Infinity;
+  let bottom = -Infinity;
+  for (const r of rects) {
+    left = Math.min(left, r.x);
+    top = Math.min(top, r.y);
+    right = Math.max(right, r.x + r.w);
+    bottom = Math.max(bottom, r.y + r.h);
+  }
+
+  // Snap each side independently: a real top bar must survive even when the
+  // left and right edges are content to the pixel.
+  if (left / width < SNAP_FRAC) left = 0;
+  if (top / height < SNAP_FRAC) top = 0;
+  if ((width - right) / width < SNAP_FRAC) right = width;
+  if ((height - bottom) / height < SNAP_FRAC) bottom = height;
+
+  const w = right - left;
+  const h = bottom - top;
+  if (w <= 0 || h <= 0) return whole;
+  if ((w * h) / (width * height) < MIN_CONTENT_FRAC) return whole;
+  if (left === 0 && top === 0 && w === width && h === height) return whole;
+  // Even offsets/sizes keep yuv420 encoders happy; expand outward so the
+  // rounding never shaves a row of picture (a black hairline would).
+  const x = left - (left % 2);
+  const y = top - (top % 2);
+  return {
+    x,
+    y,
+    w: Math.min(width - x, w + (w % 2)),
+    h: Math.min(height - y, h + (h % 2)),
+    full: false,
+  };
+}
+
+/** A stretch of source time over which the framing does not change. */
+export interface ContentRectSegment {
+  /** Source seconds. */
+  startSec: number;
+  endSec: number;
+  rect: ContentRect;
+}
+
+/**
+ * A framing run must survive BOTH of these to be believed. Together they are
+ * what replaces the union rule's protection (PLAN Task C, step C2).
+ *
+ * The union existed because a genuinely dim frame can "detect" a false crop;
+ * measuring per segment reintroduces that risk at segment granularity, where a
+ * single dark frame in the middle of a good run could carve out a bogus crop.
+ * A run of one is therefore never a framing change — it is an anomaly, and it
+ * is absorbed into its neighbours. The wall-time floor covers the same failure
+ * on a densely-sampled source, where three consecutive odd frames can still
+ * span a third of a second.
+ */
+const MIN_RUN_SAMPLES = 2;
+const MIN_RUN_SEC = 0.75;
+
+/** Two rects describe the same framing if every side agrees within a hair. */
+function sameFraming(a: ContentRect, b: ContentRect, width: number, height: number): boolean {
+  const tolX = width * SNAP_FRAC;
+  const tolY = height * SNAP_FRAC;
+  return (
+    Math.abs(a.x - b.x) <= tolX &&
+    Math.abs(a.w - b.w) <= tolX &&
+    Math.abs(a.y - b.y) <= tolY &&
+    Math.abs(a.h - b.h) <= tolY
+  );
+}
+
+/**
+ * The source's framing over time (PLAN Task C).
+ *
+ * Task 7 modelled framing as one rect per source, which is right for a clip
+ * that was letterboxed once on export. The author's own clip is not that: it
+ * alternates a landscape strip with full-bleed portrait five times, 24.0s of
+ * 63.5s letterboxed. Under a single-rect model `stableContentRect` correctly
+ * refused to crop — a bar has to be black in EVERY sample and here it is not —
+ * so every bar rendered as a bar.
+ *
+ * Each sample is classified through `stableContentRect` on its own, so the
+ * hairline snapping and the implausibly-small refusal still apply per frame.
+ * Consecutive like-classified samples become runs; runs too small to believe
+ * are absorbed. A source with uniform framing collapses to exactly one segment,
+ * which is Task 7's behaviour unchanged.
+ */
+export function contentRectTimeline(
+  samples: readonly CropSample[],
+  width: number,
+  height: number,
+  durationSec: number,
+): ContentRectSegment[] {
+  const whole: ContentRect = { x: 0, y: 0, w: width, h: height, full: true };
+  const wholeTimeline = [{ startSec: 0, endSec: durationSec, rect: whole }];
+  if (samples.length === 0 || width <= 0 || height <= 0) return wholeTimeline;
+
+  const sorted = [...samples].sort((a, b) => a.tSec - b.tSec);
+  const classified = sorted.map((s) => ({
+    tSec: s.tSec,
+    rect: stableContentRect([s], width, height),
+  }));
+
+  // Group consecutive like-framed samples.
+  type Run = { rect: ContentRect; from: number; to: number; count: number };
+  const runs: Run[] = [];
+  for (const c of classified) {
+    const last = runs[runs.length - 1];
+    if (last && sameFraming(last.rect, c.rect, width, height)) {
+      last.to = c.tSec;
+      last.count += 1;
+    } else {
+      runs.push({ rect: c.rect, from: c.tSec, to: c.tSec, count: 1 });
+    }
+  }
+
+  // Absorb runs too small to be a real framing change. Repeat until stable:
+  // dropping one run can make its neighbours adjacent and mergeable, and a
+  // single pass would leave those split.
+  let changed = true;
+  while (changed && runs.length > 1) {
+    changed = false;
+    for (let i = 0; i < runs.length; i++) {
+      const r = runs[i]!;
+      if (r.count >= MIN_RUN_SAMPLES && r.to - r.from >= MIN_RUN_SEC) continue;
+      // Absorb into the LONGER neighbour — the one more likely to be the truth.
+      const prev = runs[i - 1];
+      const next = runs[i + 1];
+      const into = !prev ? next : !next ? prev : prev.count >= next.count ? prev : next;
+      if (!into) continue;
+      into.from = Math.min(into.from, r.from);
+      into.to = Math.max(into.to, r.to);
+      into.count += r.count;
+      runs.splice(i, 1);
+      changed = true;
+      break;
+    }
+  }
+
+  // Merge any neighbours that now agree, then lay the runs onto the timeline.
+  const merged: Run[] = [];
+  for (const r of runs) {
+    const last = merged[merged.length - 1];
+    if (last && sameFraming(last.rect, r.rect, width, height)) {
+      last.to = Math.max(last.to, r.to);
+      last.count += r.count;
+    } else {
+      merged.push({ ...r });
+    }
+  }
+
+  return merged.map((r, i) => ({
+    // The change happened somewhere between the last sample of one run and the
+    // first of the next; the midpoint is the least-wrong guess and keeps the
+    // boundary off any sampled frame.
+    startSec: i === 0 ? 0 : (merged[i - 1]!.to + r.from) / 2,
+    endSec: i === merged.length - 1 ? durationSec : (r.to + merged[i + 1]!.from) / 2,
+    rect: r.rect,
+  }));
+}
+
+/**
+ * The exact framing-change instant inside a densely-sampled window
+ * (NORMALIZE plan, boundary refinement).
+ *
+ * The coarse timeline places a boundary midway between two 2 Hz samples —
+ * ±0.25s of slack, which was fine while the boundary only steered a render-
+ * time crop but is not fine once segments are BAKED: every frame on the wrong
+ * side of a baked boundary is cropped with the wrong window, and a quarter
+ * second of bar-edged frames at each of nine boundaries is exactly the class
+ * of artifact the bake exists to remove.
+ *
+ * Given per-frame samples spanning the coarse boundary, this finds the gap
+ * between the last frame still framed like `before` and the first framed like
+ * `after`, and returns its midpoint. Frames matching neither (transition
+ * wipes, encoder smear) are skipped. Null — keep the coarse boundary — when
+ * the window never actually straddles the change.
+ */
+export function pickTransition(
+  samples: readonly CropSample[],
+  before: ContentRect,
+  after: ContentRect,
+  width: number,
+  height: number,
+): number | null {
+  let lastBefore: number | null = null;
+  for (const s of [...samples].sort((a, b) => a.tSec - b.tSec)) {
+    const rect = stableContentRect([s], width, height);
+    if (sameFraming(rect, before, width, height)) {
+      lastBefore = s.tSec;
+    } else if (sameFraming(rect, after, width, height)) {
+      // The first after-framed frame only counts once a before-framed frame
+      // has been seen — otherwise the window started past the change and the
+      // "transition" would be an artifact of where the window was cut.
+      return lastBefore === null ? null : (lastBefore + s.tSec) / 2;
+    }
+  }
+  return null;
+}
+
+/**
+ * The content rect active at a SOURCE time. Half-open, so a boundary belongs to
+ * the segment starting there. Times outside the timeline clamp to its ends
+ * rather than falling back to the full frame — a clamp keeps a rounding error
+ * at a boundary from flashing the bars back on for one frame.
+ */
+export function contentRectAt(
+  timeline: readonly ContentRectSegment[],
+  tSec: number,
+  frame?: { width: number; height: number },
+): ContentRect {
+  if (timeline.length === 0) {
+    return { x: 0, y: 0, w: frame?.width ?? 0, h: frame?.height ?? 0, full: true };
+  }
+  if (tSec < timeline[0]!.startSec) return timeline[0]!.rect;
+  for (const seg of timeline) {
+    if (tSec >= seg.startSec && tSec < seg.endSec) return seg.rect;
+  }
+  return timeline[timeline.length - 1]!.rect;
+}
+
+/** The ffmpeg `crop=` filter string for a rect (no-op rects return ""). */
+export function cropFilter(rect: ContentRect | null | undefined): string {
+  if (!rect || rect.full) return "";
+  return `crop=${rect.w}:${rect.h}:${rect.x}:${rect.y}`;
+}

package/src/cover.ts

@@ -0,0 +1,216 @@
+import { readFile, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { run } from "./exec";
+
+/**
+ * Cover image selection (FINDINGS §31).
+ *
+ * Instagram and Facebook both accept a custom uploaded cover, so nothing has
+ * to be pickable from the video's own frames — which is why ossclip writes a
+ * separate `<out>.cover.jpg` rather than burning a title card into the head of
+ * the reel. Spending the first 2-3 seconds on a static card would fight the
+ * "hook in the first ~2s" policy directly, and a separate file can be
+ * restyled without re-rendering a minute of video.
+ *
+ * This module picks WHICH frame. The banner is drawn by the renderer.
+ */
+
+/**
+ * A cover banner is a headline, not a sentence (FINDINGS §35). The producer
+ * shipped 13 words across five lines by reusing the video's hook verbatim; at
+ * grid-tile size that is unreadable. The reference covers run 4-9 words.
+ *
+ * Stated in the schema AND enforced here, because a `.describe()` is a request
+ * and this is a constraint — the same reason `normalizeBeatSheet` exists.
+ */
+export const COVER_MAX_WORDS = 9;
+
+/** Trailing words that cannot end a headline — the truncation reads as broken. */
+const DANGLING = new Set([
+  "a", "an", "and", "as", "at", "but", "by", "for", "from", "in", "is", "it",
+  "of", "on", "or", "the", "to", "with", "that", "this", "my", "your", "so",
+]);
+
+/**
+ * Cut a headline down to `maxWords`, preferring a natural break.
+ *
+ * A dash or colon usually separates a complete claim from its elaboration, so
+ * the first clause is a real headline rather than a sentence with its end
+ * lopped off. Only when that is still too long does this truncate — and then
+ * it refuses to stop on a preposition or article, which is what makes a
+ * truncation look like a bug instead of an edit.
+ */
+export function coverHeadline(text: string, maxWords = COVER_MAX_WORDS): string {
+  const clean = text.trim().replace(/\s+/g, " ");
+  if (!clean) return clean;
+  const words = (s: string): string[] => s.split(" ").filter(Boolean);
+  if (words(clean).length <= maxWords) return clean;
+
+  // First clause, if it stands on its own — never a two-word fragment. Even
+  // when the clause is itself too long it is the better thing to cut down,
+  // since truncating it can never wander past the dash into the elaboration.
+  const clause = clean.split(/\s*[—–:]\s*|\s+-\s+/)[0]!.trim();
+  const base = words(clause).length >= 3 ? clause : clean;
+  const out = words(base).slice(0, maxWords);
+  while (out.length > 3 && DANGLING.has(out[out.length - 1]!.toLowerCase().replace(/\W/g, ""))) {
+    out.pop();
+  }
+  // A clause that ended on its own punctuation keeps it; a cut does not.
+  return out.join(" ").replace(/[,;:—–-]+$/, "");
+}
+
+/** Where the face sits in the COVER frame, as fractions of it. */
+export interface CoverFace {
+  centerXFrac: number;
+  centerYFrac: number;
+  sizeFrac: number;
+}
+
+export interface CoverCandidate {
+  timeSec: number;
+  /** Variance of the Laplacian — higher is sharper, lower is motion-blurred. */
+  sharpness: number;
+  hasFace: boolean;
+  /** The box, when one was found — the banner routes around it (FINDINGS §33). */
+  face?: CoverFace;
+  score: number;
+}
+
+/**
+ * Detection frame: the 9:16 cover frame at analysis size.
+ *
+ * Deliberately NOT face.ts's plain `scale`. That one measures the SOURCE, and
+ * its fractions feed the video crop math. This one measures the COVER, which
+ * is a centre crop to 1080×1920 — so it applies the identical crop first.
+ * Without that, a face box measured on a stretched 16:9 source would place the
+ * cover banner against geometry the cover does not have.
+ */
+const DET_W = 360;
+const DET_H = 640;
+export const COVER_CROP_VF =
+  `scale=${DET_W}:${DET_H}:force_original_aspect_ratio=increase,crop=${DET_W}:${DET_H}`;
+
+/**
+ * Variance of the Laplacian over a grayscale frame — the standard cheap
+ * sharpness measure. A frame caught mid-motion has most of its energy smeared
+ * away and scores low, which is exactly what a cover must not be.
+ */
+export function laplacianVariance(pixels: Uint8Array, w: number, h: number): number {
+  let sum = 0;
+  let sumSq = 0;
+  let n = 0;
+  for (let y = 1; y < h - 1; y++) {
+    for (let x = 1; x < w - 1; x++) {
+      const i = y * w + x;
+      const lap =
+        4 * pixels[i]! - pixels[i - 1]! - pixels[i + 1]! - pixels[i - w]! - pixels[i + w]!;
+      sum += lap;
+      sumSq += lap * lap;
+      n++;
+    }
+  }
+  if (n === 0) return 0;
+  const mean = sum / n;
+  return sumSq / n - mean * mean;
+}
+
+/**
+ * Score a candidate. A face is close to mandatory — a cover without the
+ * speaker is a cover for a different video — and among frames that have one,
+ * sharpness decides. Earlier frames win ties so the cover matches the opening.
+ */
+export function scoreCandidate(c: {
+  timeSec: number;
+  durationSec: number;
+  sharpness: number;
+  hasFace: boolean;
+  maxSharpness: number;
+}): number {
+  const face = c.hasFace ? 1 : 0;
+  const sharp = c.maxSharpness > 0 ? c.sharpness / c.maxSharpness : 0;
+  const earliness = 1 - Math.min(1, c.timeSec / Math.max(1e-6, c.durationSec));
+  return face * 2 + sharp + earliness * 0.3;
+}
+
+export interface PickCoverOptions {
+  /** Frames to sample across the searched window. */
+  samples?: number;
+  /** Fraction of the take to search — the cover should match the opening. */
+  searchFraction?: number;
+  cacheDir?: string;
+  /**
+   * Locates the face in a sampled frame, in that frame's own fractions.
+   * Returns the box rather than a boolean because the banner has to route
+   * around it (FINDINGS §33), and the frame it was measured on is the only
+   * frame whose geometry is certainly the cover's.
+   */
+  detectFace?: (pixels: Uint8Array, w: number, h: number) => CoverFace | null;
+  /**
+   * ffmpeg filter trimming the source to its content rect (PLAN Task 7),
+   * applied BEFORE the cover's own centre crop — otherwise the cover frames a
+   * canvas that is two-thirds baked-in black bar.
+   */
+  cropVf?: string;
+}
+
+/**
+ * Pick the best cover frame from the take: sharp, face present, early.
+ *
+ * Note on "eyes open" (§31): pico's cascade locates a face box but carries no
+ * eye state, and adding a landmark model for one thumbnail is not worth the
+ * dependency — sharpness plus a face is what this measures. A blink is a real
+ * residual risk; `--cover <path>` is the escape hatch.
+ */
+export async function pickCoverFrame(
+  tools: { ffmpegPath: string },
+  videoPath: string,
+  durationSec: number,
+  opts: PickCoverOptions = {},
+): Promise<CoverCandidate | null> {
+  const samples = opts.samples ?? 12;
+  const searchFraction = opts.searchFraction ?? 0.2;
+  const window = Math.max(1, durationSec * searchFraction);
+  const candidates: CoverCandidate[] = [];
+  const raw: Array<{
+    timeSec: number;
+    sharpness: number;
+    hasFace: boolean;
+    face?: CoverFace;
+  }> = [];
+
+  for (let i = 0; i < samples; i++) {
+    const t = (window * (i + 0.5)) / samples;
+    const framePath = join(opts.cacheDir ?? ".", `cover-frame-${i}.gray`);
+    await run(tools.ffmpegPath, [
+      "-v", "error",
+      "-ss", t.toFixed(3),
+      "-i", videoPath,
+      "-frames:v", "1",
+      "-vf", `${opts.cropVf ? `${opts.cropVf},` : ""}${COVER_CROP_VF}`,
+      "-pix_fmt", "gray",
+      "-f", "rawvideo",
+      "-y", framePath,
+    ]);
+    const pixels = new Uint8Array(await readFile(framePath));
+    await unlink(framePath).catch(() => {});
+    if (pixels.length < DET_W * DET_H) continue;
+    const face = opts.detectFace?.(pixels, DET_W, DET_H) ?? undefined;
+    raw.push({
+      timeSec: t,
+      sharpness: laplacianVariance(pixels, DET_W, DET_H),
+      hasFace: face !== undefined,
+      face,
+    });
+  }
+  if (raw.length === 0) return null;
+
+  const maxSharpness = Math.max(...raw.map((r) => r.sharpness));
+  for (const r of raw) {
+    candidates.push({
+      ...r,
+      score: scoreCandidate({ ...r, durationSec: window, maxSharpness }),
+    });
+  }
+  candidates.sort((a, b) => b.score - a.score);
+  return candidates[0]!;
+}

package/src/cta.ts

@@ -0,0 +1,68 @@
+/**
+ * Which comment-CTA asks the keyword mechanic is allowed to fire on.
+ *
+ * `ChatMock`'s keyword path (FINDINGS §16/§28b) implements exactly one shape of
+ * ask: **"comment AGENTS and I'll send it"** — a distinctive word the viewer
+ * literally types, given the whole frame because the ask IS the message, with
+ * the same word quoted in the caption while it is on screen.
+ *
+ * A **"reply with a number"** ask is a different shape wearing the same clothes.
+ * The author's clip says "which one did you not know? Type in the comments the
+ * number of it"; the producer read `number` as the keyword, so the render showed
+ * a `"NUMBER"` pill and the caption read `comments the "NUMBER"`. Nobody is
+ * meant to type the word "number" — they are meant to reply with a digit the
+ * producer cannot know in advance. The mechanic has nothing to render, so it
+ * must not fire at all.
+ *
+ * The discriminator is lexical and deliberately narrow: the words below are
+ * REFERENTIAL — they point at the reply rather than being it. A content noun
+ * ("guide", "template", "agents") stays usable, because rejecting those would
+ * break the very CTA the feature exists for. A rejection is always reported;
+ * silently dropping a CTA the author wrote is worse than rendering a wrong one,
+ * because only one of those is visible.
+ */
+
+/**
+ * Words that name the reply instead of being it. Not a stopword list — several
+ * of these are perfectly good nouns elsewhere; they are unusable only in the
+ * one position "the word you type in the comments".
+ */
+const REFERENTIAL = new Set([
+  "number", "numbers", "digit", "answer", "answers", "reply", "replies",
+  "comment", "comments", "response", "responses", "word", "words",
+  "below", "above", "thing", "something", "anything", "option", "choice",
+  "yours", "mine", "same", "which",
+]);
+
+/**
+ * Function words. A CTA keyword is a thing the viewer types on purpose, so a
+ * pronoun or determiner is always a misread of the sentence around it.
+ */
+const FUNCTION_WORDS = new Set([
+  "it", "this", "that", "these", "those", "one", "ones", "them", "they",
+  "me", "you", "your", "my", "our", "their", "his", "her", "its",
+  "a", "an", "the", "of", "to", "in", "on", "at", "for", "and", "or",
+  "is", "are", "was", "be", "do", "did", "does", "here", "there", "what",
+  "who", "how", "why", "when", "where", "if", "so", "but", "yes", "no",
+]);
+
+/**
+ * Why this keyword cannot drive the CTA mechanic, or `null` when it can.
+ *
+ * Returns a human-readable reason rather than a boolean so the caller can log
+ * WHICH rule fired — a silent suppression here would look identical to a take
+ * that simply had no CTA.
+ */
+export function rejectCtaKeyword(keyword: string | undefined | null): string | null {
+  const word = (keyword ?? "").trim().toLowerCase();
+  if (!word) return "empty";
+  // A digit is the reply itself, never the word naming it.
+  if (/^\d+$/.test(word)) return `"${word}" is a digit, not a word to type`;
+  if (word.length < 3) return `"${word}" is too short to be a comment keyword`;
+  if (REFERENTIAL.has(word)) {
+    return `"${word}" names the reply rather than being it — this is a ` +
+      `"reply with a number" ask, not a comment-a-keyword ask`;
+  }
+  if (FUNCTION_WORDS.has(word)) return `"${word}" is a function word`;
+  return null;
+}