@heyramzi/social 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ramzi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,33 @@
-# Temporary Holding Version
+# @heyramzi/social
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The heuristics for scripts and posts, written once. CutKit's script check and UpSys's Jev loop
+are different apps with their own copy, weights and contracts, and both import their rules from
+here so a rule changes in one place.
+
+| Entry | What it holds | Read by |
+| --- | --- | --- |
+| `./story` | Checks with no model: `openerFault` (greeting, hidden point, scene first), `hedgeScan`, `flatRun`, `HOOK_MAX_WORDS` | CutKit's offline lint, `./shorts` |
+| `./questions` | `storyQuestions({ field, piece, reader })`: the story questions a judge model answers, in the surface's own words | CutKit's check, Jev's `short`, `opening`, `post` and `x` surfaces |
+| `./hooks` | One regex per hook-library shape, and the banned shape | `./shorts` |
+| `./shorts` | `matchHook` and `auditShorts`, the skeleton of a Short | `heyramzi-slop --register=shorts` in `@heyramzi/lint` |
+
+Fix copy never lives here. A question in the bank says what to ask; the app says what to tell
+the person when the answer drags the grade down.
+
+## Adding a question
+
+Add it to `storyQuestions` with its `source`. It earns a place in a surface once
+`pnpm jev train <surface>` in UpSys keeps it, and in CutKit's check once it has done that on
+`short`. The `script` wording CutKit already ships is pinned in `questions.test.mjs`, because the
+judge's answers move when a word does.
+
+## Calibration
+
+A rule here is measured against the CutKit corpus before an app gates on it. On 14 Oct 2026,
+over 5,089 punctuated Short transcripts from 23 creators, a sentence-rhythm rule (4 sentences in
+a row at one length) fired on 30.5% of winners and 27.9% of the rest, so it isn't here. `flatRun`
+flags 57% of winners and 60% of the rest: CutKit shows it as a nudge, never a fail.
+
+```
+pnpm test
+```

package/hooks.d.ts

@@ -0,0 +1,10 @@
+export interface HookShape {
+  n: number;
+  family: string;
+  test: RegExp;
+  second?: boolean;
+  maxWords?: number;
+  alone?: boolean;
+}
+export declare const hookShapes: HookShape[];
+export declare const bannedHook: RegExp;

package/hooks.js

@@ -0,0 +1,114 @@
+/** One regex per hook-library shape, keyed by its number. The prose lives in shorts-script. */
+const N = "(?:\\d+|two|three|four|five|six|seven|eight|nine|ten|twelve)";
+
+export const hookShapes = [
+  { n: 1, family: "Promise", test: /^here(?:'s| is) the only\b/i },
+  { n: 2, family: "Promise", test: /^(?:here(?:'s| is)|this is) how (?:to|you|i)\b/i },
+  { n: 3, family: "Promise", test: new RegExp(`^here are ${N}\\b`, "i") },
+  {
+    n: 4,
+    family: "Promise",
+    second: true,
+    test: /\bi (?:use|built|made) (?:a|an|the) [\w ]{1,24}(?:i call|called)\b/i,
+  },
+  { n: 5, family: "Diagnosis", test: /^the (?:real )?reason (?:your|you)\b/i },
+  { n: 6, family: "Diagnosis", test: /^this is the most\b/i },
+  { n: 7, family: "Diagnosis", test: /\bthe fastest way to\b.*\bthe fastest way to\b/i },
+  {
+    n: 8,
+    family: "Received-wisdom break",
+    test: /^(?:everyone|everybody|people)(?: will| keep)? (?:tells?|telling|says?|saying) you\b|, bro[.!?]?$/i,
+  },
+  { n: 9, family: "Received-wisdom break", test: /^you (?:do not|don't) need\b/i },
+  { n: 10, family: "Received-wisdom break", test: /^every \w+ (?:is|are)\b/i },
+  {
+    n: 11,
+    family: "Received-wisdom break",
+    test: /^[^.?!,]{2,50} or [^.?!,]{2,50}[.?]$/i,
+    maxWords: 10,
+  },
+  {
+    n: 12,
+    family: "In medias res",
+    test: /^(?:can't|couldn't|just|still|got|lost|spent|found|watched)\b/i,
+  },
+  { n: 13, family: "In medias res", test: /^i(?:'m| am) (?:processing|realizing|still)\b/i },
+  { n: 14, family: "In medias res", test: /^i regret\b/i },
+  { n: 15, family: "Tribe", test: /^if you want to\b.*\bbut\b/i },
+  {
+    n: 17,
+    family: "Tribe",
+    test: /^if you(?:'re| are) [^,]{2,40}, you (?:gotta|have to|need to|should|must)\b/i,
+  },
+  {
+    n: 18,
+    family: "Tribe",
+    test: /^there are (?:fully grown |grown )?\w+(?: \w+)? (?:out there|who)\b/i,
+  },
+  {
+    n: 19,
+    family: "Artefact",
+    test: /^(?:so )?i (?:saw|got|found) this (?:comment|post|email|message|dm|video|review)\b/i,
+  },
+  { n: 20, family: "Artefact", test: /^(?:open|pull up|go to) (?:your|the)\b/i },
+  { n: 21, family: "Artefact", test: /^pro [\w ]{1,24} tip\b/i },
+  {
+    n: 22,
+    family: "Number",
+    test: new RegExp(`^i (?:spent|tested|tried|ran|used|asked) (?:the last |over )?${N}\\b`, "i"),
+  },
+  { n: 23, family: "Number", test: /^\d[\d,.]*%?\s.*\bso\b/i },
+  { n: 24, family: "Number", test: new RegExp(`^${N} [a-z]+`, "i") },
+  {
+    n: 25,
+    family: "Number",
+    test: /^[\w'-]+(?: [\w'-]+)?, [\w'-]+(?: [\w'-]+)?,? (?:and )?[\w'-]+(?: [\w'-]+)?\.$/i,
+    maxWords: 8,
+  },
+  { n: 26, family: "Number", test: /^every \w+(?: \w+)? (?:does|do|has) this\b/i },
+  {
+    n: 27,
+    family: "Question",
+    test: /^(?:(?:do|does|is|are|can|will|should|did) [^?]{3,80}|what happens when [^?]{3,80})\?$/i,
+  },
+  { n: 28, family: "Question", test: /^(?:you know|do you know) (?:who|what|why|how)\b/i },
+  { n: 29, family: "Confession", test: /^i have a confession\b/i },
+  {
+    n: 31,
+    family: "News",
+    test: /^(?:breaking news\b|[\w.\- ]{1,30} just (?:killed|replaced|ended|dropped|changed|released|launched|did it again)\b)/i,
+  },
+  { n: 32, family: "News", test: /^this is the (?:one|only|new) \w+(?: \w+)? you need\b/i },
+  {
+    n: 33,
+    family: "News",
+    test: /^this (?:has (?:got )?to be|might be|is) the (?:craziest|best|wildest|biggest)\b/i,
+  },
+  {
+    n: 34,
+    family: "Contradiction",
+    test: /^(?:i don't think there's a (?:more|better)\b|[\w.\- ]{2,30} (?:lies|fails|breaks) more than you think\b)/i,
+  },
+  {
+    n: 35,
+    family: "Contradiction",
+    test: /^most people (?:don't|do not) (?:know|realize|realise)\b/i,
+  },
+  {
+    n: 36,
+    family: "Promise",
+    test: new RegExp(`^(?:turn on|add|type|use) (?:these|this) (?:${N} )?\\w+`, "i"),
+  },
+  { n: 37, family: "Promise", test: /^how (?:an?|the) [\w'’ -]{2,40} would\b/i },
+  {
+    n: 38,
+    family: "News",
+    test: /^[\w.$'’ -]{2,40} just (?:turned down|said no to|walked away from|rejected)\b/i,
+  },
+  { n: 39, family: "Diagnosis", test: /^the difference between an? [\w -]{1,30} and an? \w+/i },
+  // Shape 16 qualifies the audience and opens no gap, so it only counts beside another shape.
+  { n: 16, family: "Tribe", alone: false, test: /^if you\b/i },
+];
+
+// Shape 30: our worst post ran 2 views on it.
+export const bannedHook = /^(?:when i (?:first )?started|i used to think|one year ago,? i)\b/i;

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@heyramzi/social",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "The social-media heuristics CutKit and UpSys share: hook shapes, the Shorts audit, the story checks with no model in them, and the story question bank a judge model answers",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/heyramzi/vibe-kit.git",
+    "directory": "packages/social"
+  },
+  "files": [
+    "hooks.js",
+    "hooks.d.ts",
+    "questions.js",
+    "questions.d.ts",
+    "shorts.js",
+    "shorts.d.ts",
+    "story.js",
+    "story.d.ts",
+    "package.json"
+  ],
+  "type": "module",
+  "imports": {
+    "#social/*": "./*"
+  },
+  "exports": {
+    "./hooks": {
+      "types": "./hooks.d.ts",
+      "default": "./hooks.js"
+    },
+    "./questions": {
+      "types": "./questions.d.ts",
+      "default": "./questions.js"
+    },
+    "./shorts": {
+      "types": "./shorts.d.ts",
+      "default": "./shorts.js"
+    },
+    "./story": {
+      "types": "./story.d.ts",
+      "default": "./story.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test \"*.test.mjs\""
+  }
+}

package/questions.d.ts

@@ -0,0 +1,22 @@
+export type StoryQuestion = { instructions: string; source: string } & (
+  | { type: "noul"; criteria?: undefined }
+  /** Ordered low to high. */
+  | { type: "score"; criteria: string[] }
+);
+
+export type StoryQuestionId =
+  | "opening_speed"
+  | "contrast"
+  | "rehook"
+  | "stakes"
+  | "intro_order"
+  | "visual_first"
+  | "head_fake"
+  | "villain"
+  | "atomic_share";
+
+export declare function storyQuestions(voice: {
+  field: string;
+  piece: string;
+  reader: string;
+}): Record<StoryQuestionId, StoryQuestion>;

package/questions.js

@@ -0,0 +1,70 @@
+/**
+ * The story questions a judge model answers, written once and asked in each surface's words.
+ * Which ones a surface asks, its weights and its fix copy stay in the app.
+ */
+
+const KALLAWAY = "Kallaway, How to Master Storytelling (youtube.com/watch?v=WluuZB_ck9Q)";
+
+/**
+ * @param {{ field: string, piece: string, reader: string }} voice
+ *   `field` is the state key the judge reads ("script"), `piece` what it is ("video"),
+ *   `reader` who meets it ("viewer").
+ */
+export function storyQuestions({ field, piece, reader }) {
+  const f = `\`${field}\``;
+  const keep = reader === "viewer" ? "keep watching" : "keep reading";
+  const once = reader === "viewer" ? "one watch" : "one read";
+  return {
+    opening_speed: {
+      type: "score",
+      instructions: `How fast does the ${f} say what the ${piece} is about and what the ${reader} gets? Judge the first two sentences.`,
+      criteria: [
+        `After more than two sentences the ${reader} still doesn't know the subject or the payoff.`,
+        "The subject shows up in the first two sentences but the payoff stays unclear.",
+        "The subject is clear in the first sentence, the payoff by the second.",
+        "One short sentence of about ten words names both the subject and the outcome.",
+      ],
+      source: "Kallaway interrupt theory: subject, stakes, speed, clarity",
+    },
+    contrast: {
+      type: "noul",
+      instructions: `In its first three sentences, does the ${f} set what the ${reader} already believes or does against something different, stated ('most people do A, this does B') or implied ('this is 8 times faster')?`,
+      source: "Kallaway headfake; vidIQ: statement adds contrast",
+    },
+    rehook: {
+      type: "noul",
+      instructions: `Halfway through, does the ${f} add a new question, a higher stake, a revealed mechanism, or bring back the problem from the opening and show that a better answer is still ahead, giving the ${reader} a new reason to ${keep}? A sentence that only announces what's next ('this is where it gets crazy') doesn't count.`,
+      source: `Kallaway rehook and rebuy; ${KALLAWAY}`,
+    },
+    stakes: {
+      type: "noul",
+      instructions: `Does the ${f} name who it's about, what they could lose, and why now?`,
+      source: "Kallaway addiction loop: a character, something at risk, urgency",
+    },
+    intro_order: {
+      type: "noul",
+      instructions: `In its first two sentences, does the ${f} say what is happening and why it matters to the ${reader} before it says who, when or where? Opening on a time and place ('Last month I was at a conference in Miami') or on the author's credentials counts as no.`,
+      source: `Kallaway W order: what and why, then who and how, then when and where; ${KALLAWAY}`,
+    },
+    visual_first: {
+      type: "noul",
+      instructions: `Does the first sentence of the ${f} name something the ${reader} can picture at once, such as a physical object, a screen, a result or a number, rather than only an idea?`,
+      source: `Kallaway: visual hooks beat audio-only hooks, show while you tell; ${KALLAWAY}`,
+    },
+    head_fake: {
+      type: "noul",
+      instructions: `Does the ${f} lead the ${reader} toward one answer and then give a different one that its earlier details make sense of? A twist with no clues before it counts as no.`,
+      source: `Kallaway addiction loop: prediction error, the head fake; ${KALLAWAY}`,
+    },
+    villain: {
+      type: "noul",
+      instructions: `Does the ${f} set the ${reader} against a named opponent: a person, company, group, tool, habit or belief it paints as the problem?`,
+      source: `Kallaway: a missing villain; ${KALLAWAY}`,
+    },
+    atomic_share: {
+      type: "noul",
+      instructions: `After ${once}, could the ${reader} retell the main point of the ${f} to a friend in one sentence of under 10 words?`,
+      source: `Kallaway atomic shareability, the Paul Revere effect; ${KALLAWAY}`,
+    },
+  };
+}

package/shorts.d.ts

@@ -0,0 +1,9 @@
+export type HookMatch =
+  | { shape: number; banned: true }
+  | { vague: true }
+  | { shape: number; family: string; alone: boolean };
+export declare function matchHook(first: string, second?: string): HookMatch | null;
+export declare function auditShorts(text: string): {
+  hook: HookMatch | null;
+  findings: { kind: "shorts"; id: string; detail: string }[];
+};

package/shorts.js

@@ -0,0 +1,111 @@
+import { bannedHook, hookShapes } from "#social/hooks.js";
+import { HOOK_MAX_WORDS, openerFault } from "#social/story.js";
+
+const SENTENCE = /[^.!?]+(?:[.!?]+["'”’)]*|$)/g;
+const COUNT =
+  /\b(?:no\.? ?\d|number (?:one|two|three|four|five|\d)|step (?:one|two|three|four|\d)|(?:the )?first|second|third|fourth)\b/gi;
+const REPLY_CTA = /\b(?:comment|dm me|type|reply)\b/i;
+
+/** The spoken part of a note: header lines and everything under a `---` divider are notes to self. */
+function spoken(text) {
+  const body = text.split(/^-{3,}\s*$/m)[0];
+  return body
+    .split("\n")
+    .filter((line) => /[.!?]["'”’)]*\s*$/.test(line.trim()))
+    .join(" ")
+    .trim();
+}
+
+const words = (s) => s.split(/\s+/).filter(Boolean).length;
+
+const STOP = new Set(
+  "that this with they them their there then than what when where which your yours from have been were will would could should about into just like more most some such very also only even ever never always because while these those other every thing things people".split(
+    " ",
+  ),
+);
+const content = (s) =>
+  (s.toLowerCase().match(/[a-z']{4,}/g) ?? [])
+    .map((w) => w.replace(/s$/, ""))
+    .filter((w) => !STOP.has(w));
+/** Two short sentences that swap 2 nearby words around a shared frame: "good team, bad plan. good plans, bad teams." */
+function chiasmus(sentences) {
+  for (let i = 0; i + 1 < sentences.length; i++) {
+    const short = (s) => s.split(/\s+/).length <= 18;
+    if (!short(sentences[i]) || !short(sentences[i + 1])) continue;
+    const a = content(sentences[i]),
+      b = content(sentences[i + 1]);
+    const once = (arr, w) => arr.indexOf(w) === arr.lastIndexOf(w);
+    for (let x = 0; x < a.length; x++)
+      for (let y = x + 1; y < a.length; y++) {
+        const p = a[x],
+          q = a[y];
+        if (p === q || y - x > 2) continue;
+        const bp = b.indexOf(p),
+          bq = b.indexOf(q);
+        if (
+          bp !== -1 &&
+          bq !== -1 &&
+          bq < bp &&
+          bp - bq <= 2 &&
+          once(a, p) &&
+          once(a, q) &&
+          once(b, p) &&
+          once(b, q)
+        ) {
+          const kept = a.filter((w) => w !== p && w !== q && b.includes(w));
+          const ordered = kept.every((w, k) => k === 0 || b.indexOf(kept[k - 1]) < b.indexOf(w));
+          if (kept.length >= 1 && ordered) return `${sentences[i]} ${sentences[i + 1]}`;
+        }
+      }
+  }
+  return null;
+}
+
+/** Which library shape the opening runs on, or why it runs on none. */
+export function matchHook(first, second = "") {
+  const hook = first.trim();
+  if (bannedHook.test(hook)) return { shape: 30, banned: true };
+  const fault = openerFault(hook);
+  if (fault === "opaque" || fault === "scene") return { vague: true };
+  for (const s of hookShapes) {
+    const target = s.second ? second.trim() : hook;
+    if (s.maxWords && words(target) > s.maxWords) continue;
+    if (s.test.test(target)) return { shape: s.n, family: s.family, alone: s.alone === false };
+  }
+  return null;
+}
+
+/** The hook and the skeleton of a Short, per the shorts-script skill. */
+export function auditShorts(text) {
+  const findings = [];
+  const sentences = (spoken(text).match(SENTENCE) ?? []).map((s) => s.trim()).filter(Boolean);
+  if (sentences.length === 0) return { hook: null, findings };
+  const [first, second] = sentences;
+  const push = (id, detail) => findings.push({ kind: "shorts", id, detail });
+
+  const hook = matchHook(first, second);
+  if (!hook) push("hook-shape", `"${first}" matches no shape in the hook library`);
+  else if (hook.vague) push("hook-vague", `"${first}" hides the plot or opens on a time and place`);
+  else if (hook.banned) push("hook-banned", `"${first}" is shape 30, banned`);
+  else if (hook.alone)
+    push("hook-alone", `"${first}" is shape 16, which qualifies the audience and opens no gap`);
+  if (words(first) > HOOK_MAX_WORDS)
+    push("hook-length", `the hook is ${words(first)} words, the window takes ${HOOK_MAX_WORDS}`);
+
+  const clefts = sentences.filter(
+    (s) => /^What [^?]{3,60}?\b(?:is|are|was|were)\s/.test(s) && !s.endsWith("?"),
+  );
+  if (clefts.length > 1)
+    push("what-cleft", `${clefts.length} "What X is Y" sentences; 1 per script`);
+  const mirror = chiasmus(sentences);
+  if (mirror) push("chiasmus", `mirrored close: "${mirror}"`);
+
+  const counted = (sentences.slice(1).join(" ").match(COUNT) ?? []).length;
+  if (counted < 2)
+    push("uncounted-steps", `${counted} count markers in the body; name the steps out loud`);
+
+  const close = sentences.slice(-2).join(" ");
+  if (!REPLY_CTA.test(close)) push("cta-reply", "the close carries no reply-trigger CTA");
+
+  return { hook, findings };
+}

package/story.d.ts

@@ -0,0 +1,16 @@
+export declare const HOOK_MAX_WORDS: number;
+export type OpenerFault = "greeting" | "opaque" | "scene";
+export declare function openerFault(text: string): OpenerFault | null;
+export declare function wordCount(text: string): number;
+export declare function firstSentence(text: string): string;
+export declare const HEDGES: string[];
+export declare function hedgeScan(text: string): {
+  pass: boolean;
+  dense: boolean;
+  total: number;
+  found: string[];
+};
+export declare const FLAT_RUN_WORDS: number;
+export declare const FLAT_RUN_MIN_WORDS: number;
+export declare const WORDS_PER_SECOND: number;
+export declare function flatRun(text: string): { words: number; seconds: number; flagged: boolean };

package/story.js

@@ -0,0 +1,127 @@
+/**
+ * The story checks that need no model: how a script or post opens, hedges and turns.
+ * CutKit and the Shorts gate both read these. Fix copy stays in each app.
+ */
+
+/** The window a hook gets: past this the first sentence is still talking when the swipe comes. */
+export const HOOK_MAX_WORDS = 15;
+
+// WHY: every short-form source we read names a greeting opener as the top failure.
+const GREETING =
+  /^(hey|hi|hello|welcome|so basically|in this video|today we're going to|today i'm going to|let me tell you)\b/iu;
+// Kallaway's classroom: hiding the plot loses the swipe.
+const OPAQUE =
+  /^(?:wait (?:till|until) you see|you(?:['’]re| are) (?:never |not )?(?:going to|gonna) believe)/iu;
+// Kallaway's W order: what and why first, who and how next, when and where last. A time and
+// place in the first words is the icing served before the cake.
+const SCENE =
+  /^(?:(?:last|this) (?:week|month|year|summer|winter),? i was\b|it was an? (?:[\w,]+ ){0,3}(?:night|day|morning|evening)\b)/iu;
+
+/** The rule an opening breaks: a greeting, a hidden point or a scene set first. Null when clean. */
+export function openerFault(text) {
+  const opening = text.trim();
+  if (GREETING.test(opening)) return "greeting";
+  if (OPAQUE.test(opening)) return "opaque";
+  if (SCENE.test(opening)) return "scene";
+  return null;
+}
+
+export const wordCount = (text) => text.split(/\s+/u).filter(Boolean).length;
+
+export function firstSentence(text) {
+  return text.trim().split(/(?<=[.!?])(?:\s|$)|\n+/u, 1)[0] ?? "";
+}
+
+// WHY no "if": 6 of the 10 viral scripts in CutKit's REAL_SHORTS say "if you", 2 in their first line.
+export const HEDGES = [
+  "maybe",
+  "might",
+  "could",
+  "probably",
+  "perhaps",
+  "possibly",
+  "hopefully",
+  "kind of",
+  "sort of",
+  "i think",
+  "i guess",
+];
+
+const hedgePattern = (hedge, flags) => new RegExp(`\\b${hedge.replaceAll(" ", "\\s+")}\\b`, flags);
+
+/**
+ * Honest uncertainty is fine, so only a hedge in the first 2 sentences, or more than 1 per
+ * 100 words, fails. `found` names the hedges to cut.
+ */
+export function hedgeScan(text) {
+  const words = wordCount(text);
+  const early = text
+    .trim()
+    .split(/(?<=[.!?])(?:\s|$)/u)
+    .slice(0, 2)
+    .join(" ");
+  const earlyFound = HEDGES.filter((hedge) => hedgePattern(hedge, "iu").test(early));
+  const total = HEDGES.reduce(
+    (sum, hedge) => sum + (text.match(hedgePattern(hedge, "igu")) ?? []).length,
+    0,
+  );
+  const dense = total > Math.max(1, words / 100);
+  const found = earlyFound.length
+    ? earlyFound
+    : dense
+      ? HEDGES.filter((hedge) => hedgePattern(hedge, "iu").test(text))
+      : [];
+  return { pass: earlyFound.length === 0 && !dense, dense, total, found };
+}
+
+// The words that turn a story: a contrast, or a list stepping on.
+const TURNS = new Set([
+  "but",
+  "actually",
+  "except",
+  "however",
+  "yet",
+  "though",
+  "instead",
+  "until",
+  "whereas",
+  // WHY: a list moves on at each step, and 5 of 10 viral scripts in REAL_SHORTS turn only that way.
+  "next",
+  "first",
+  "second",
+  "third",
+  "finally",
+]);
+/** A stretch longer than this with no turn in it drifts. South Park's rule: but or therefore, never and then. */
+export const FLAT_RUN_WORDS = 70;
+/** Below this length a whole script is one breath, so a flat run says nothing. */
+export const FLAT_RUN_MIN_WORDS = 120;
+export const WORDS_PER_SECOND = 2.5;
+
+/** The longest run of words with no turn, a question or a numbered step in it. */
+export function flatRun(text) {
+  const raw = text.split(/\s+/u).filter(Boolean);
+  const words = raw.map((word) => word.toLowerCase().replace(/[^a-z]/gu, ""));
+  let run = 0;
+  let worst = 0;
+  for (let index = 0; index < words.length; index += 1) {
+    // WHY the pair: "turns out" turns on two words, so one token never matches it.
+    if (words[index] === "turns" && words[index + 1] === "out") {
+      run = 0;
+      index += 1;
+      continue;
+    }
+    if (
+      TURNS.has(words[index] ?? "") ||
+      raw[index]?.includes("?") ||
+      /^\d+[.)]$/u.test(raw[index] ?? "")
+    )
+      run = 0;
+    else {
+      run += 1;
+      worst = Math.max(worst, run);
+    }
+  }
+  const flagged = raw.length > FLAT_RUN_MIN_WORDS && worst > FLAT_RUN_WORDS;
+  return { words: worst, seconds: Math.round(worst / WORDS_PER_SECOND), flagged };
+}