@sonordev/contracts 2.0.0 → 2.1.0

package/CHANGELOG.md

@@ -1,5 +1,53 @@
 # Changelog
 
+## 2.1.0
+
+A minor release: one new entry, `@sonordev/contracts/voice`. Every other entry is unchanged.
+
+- **New entry `@sonordev/contracts/voice`**: the house voice's contraction rule, so every app that checks or rewrites copy agrees on it.
+  - `findUncontracted(text, options?)` finds full forms that should be
+    contractions ("do not" to "don't", "it is" to "it's", "let us look" to
+    "let's look") and returns each one with its position, the matched text and
+    the suggestion, first-letter case kept.
+  - It leaves alone what can't contract where it stands: a clause-final "it
+    is" or "we are" (negations skip that guard, so "We do not." still becomes
+    "We don't."), "what it is and why", "can not only", a "what is" question, a
+    heading that opens with "What Is" (when `titleLike` is set), and "let us
+    know" and "let us help". "let us" only contracts at the start of a sentence and
+    before look, start, begin, consider, turn, see, review, compare, break,
+    dig, recap, unpack, explore, examine, revisit, focus, go, talk, move, "get
+    started", "step back" or "zoom out". "have" and "has" on their own are
+    never touched, though "have not" and "has not" still contract.
+  - `contractText(text, options?)` applies those findings and returns the new
+    text.
+  - `findContracted(text, options?)` is the reverse rule for question-form
+    headings and FAQ questions: it finds contractions ("What's") and suggests
+    the full form ("What is").
+  - `VOICE_MASK` is the one character that stands in for text the rule must
+    not touch.
+- **Options**: `titleLike` marks a heading or title. `protectedRanges` takes
+  half-open `[start, end)` ranges (code, quotations, link destinations) that
+  are never rewritten and never read as a clause end, except a protected line
+  break, which still ends its line. An infinite bound means
+  "from the start" or "to the end". A malformed range (NaN, not a number,
+  start after end), or a truthy value that isn't an array, protects the whole
+  text, so a bad range can never cause code to be rewritten.
+- **Lines**: multi-line text is read one line at a time. Nothing matches
+  across a line break, and the end of a line ends a clause. A "\r" before a
+  "\n" or at the very end of the text is part of the line ending. Hits carry
+  offsets into the whole string.
+- **Known limits**: the rule is deliberately plain. "must not only" and "will
+  not only" contract, "need not" contracts even where "need" is a noun, "let
+  us" is read by its position and next word rather than its meaning, a
+  decimal, a domain or an initial hides a "what is" question, a straight
+  apostrophe doesn't end a clause, only spaces and tabs join the words of a
+  pair, all-caps input gets a mixed-case suggestion, and `findContracted`
+  always expands "'s" to "is" and "'d" to "would" and expands "ain't" like any
+  other "n't" word ("ai not"). The README lists each one with an example.
+- Anything that isn't a string is read as no text, so a stray number or object
+  can't throw.
+- No new dependencies, and CommonJS and ESM builds like every other entry.
+
 ## 2.0.0
 
 A major for one entry, `slots`, plus three new entries; every other entry is unchanged.

package/README.md

@@ -22,6 +22,118 @@ pnpm add @sonordev/contracts
 | `@sonordev/contracts/site-cache` | The cache tags a site's Sonor fetches carry and the revalidation route's path, payload and ping | site-kit tags and serves the route, sonor-api calls it |
 | `@sonordev/contracts/site-edit` | Edit on page: the messages between a framed site and the dashboard, trusted origins, how a slot is found on the page | site-kit's overlay, the dashboard's visual editor |
 | `@sonordev/contracts/portfolio` | Where a portfolio number comes from and which may headline; the live-frame message | sonor-api, Signal, agency-site-kit |
+| `@sonordev/contracts/voice` | The house voice's contraction rule. `findUncontracted` and `contractText` find and apply full forms that should be contractions; `findContracted` finds the contractions a question-form heading should expand | anything that checks or rewrites copy: Sonor's APIs and dashboard |
+
+## The voice contract
+
+`voice` is the contraction rule for written copy, so every app that checks or
+rewrites it agrees. It's the rule Sonor's article checker has always applied,
+moved here so it exists once.
+
+- **What it finds.** Full forms that should be contractions: "do not" becomes
+  "don't", "it is" becomes "it's", "let us look" becomes "let's look". The
+  first letter's case is kept ("DO NOT" gives "Don't"), and the suggestion
+  always uses a straight apostrophe. There are 36 pairs, and a negation wins
+  an overlap ("we would not" gives "we wouldn't", not "we'd not").
+- **What it leaves alone.** A pronoun and verb ("it is", "we are", "you will")
+  at the end of a clause ("until it is."), or before "and", "or", "but" or
+  "nor" ("what it is and why"). Negations skip that guard: "We do not." still
+  becomes "We don't.". "can not" before "only" ("it can not only save time").
+  "what is" when the next ".", "!" or "?" after it turns out to be a "?", and
+  "What Is" at the start of a line when you mark the text as a heading.
+  "let us" unless it starts a sentence and the next word is one of
+  look, start, begin, consider, turn, see, review, compare, break, dig, recap,
+  unpack, explore, examine, revisit, focus, go, talk, move, "get started",
+  "step back" or "zoom out" ("let us know" and "let us help" mean "allow us").
+  "have" and "has" on their own ("we have a team") are never touched, though
+  "have not" and "has not" still contract ("haven't", "hasn't").
+- **Lines.** Text is read one line at a time: split on "\n". A "\r" right
+  before a "\n", or at the very end of the text, is part of the line ending;
+  any other "\r" is ordinary text. If you've already split the text into lines
+  yourself and a line keeps a final "\r" you want read as text, replace it with
+  `VOICE_MASK` first.
+  Nothing matches across a line break, and the end of a line ends a clause.
+  Every hit's `index` is an offset into the whole string you passed in.
+- **The other direction.** `findContracted` finds the contractions a
+  question-form heading or FAQ question should spell out ("What's" becomes
+  "What is"). It only reports; whether a text is a
+  question is the caller's call, and a caller shouldn't apply these blindly.
+
+What the caller does:
+
+- **Mask what isn't prose.** Code, quotations and link destinations shouldn't
+  be rewritten. Pass their `[start, end)` positions as `protectedRanges`, or
+  replace them with `VOICE_MASK` yourself. Every protected character is masked
+  except "\n" and "\r", which stay as they are, so a protected line break still
+  ends its line. A masked span separates
+  words, can't sit inside a phrase, and counts as text that follows. Ranges
+  can arrive in any order, and overlap or touch. An infinite bound clamps to
+  the start or end of the text, and an empty or out-of-text range is ignored.
+  A malformed range (NaN, not a number, start after end), or a truthy value
+  that isn't an array, protects the whole text, so a bad range never causes
+  code to be rewritten. A falsy value means no ranges.
+- **Pass a string.** Anything else (a number, an object, `null`) is read as no
+  text: nothing is found and `contractText` hands it back unchanged.
+- **Pass a bare heading.** Set `titleLike` for a heading or title, with the `#`
+  and list markers already blanked to spaces.
+
+```ts
+import { contractText, findUncontracted } from '@sonordev/contracts/voice'
+
+contractText('We do not ship on Sundays.')
+// "We don't ship on Sundays."
+
+findUncontracted('We do not ship on Sundays.')
+// [{ index: 3, length: 6, match: 'do not', suggestion: "don't" }]
+```
+
+### Known limits
+
+The rule is plain on purpose, and these are what it does today. Each one is
+pinned by a test, so changing it later is a visible change.
+
+- **"not" before "only".** Only "can not only" stays full. "You must not only
+  wait" becomes "You mustn't only wait", "will not only rise" becomes "won't
+  only rise", and "cannot only" becomes "can't only", which reads differently.
+- **"need" as a noun.** "The need not being met" becomes "The needn't being
+  met", and "must not" and "need not" contract wherever they appear.
+- **"let us" by position, not meaning.** "Let us look at your account, please"
+  becomes "Let's look at your account, please". "Let us try again", "let us
+  walk through the plan" and any sentence that opens with a bracket, a quote
+  or a dash ("(Let us look at it.)") stay full.
+- **Question detection is the first "." "!" or "?" on the line.** A decimal, a
+  domain or an initial hides the "?": "what is 3.5 percent?" becomes "what's
+  3.5 percent?". Only "what is" has a question guard: "Who is on the team?"
+  becomes "Who's on the team?". A question that wraps onto the next line isn't
+  seen.
+- **A line break ends a clause.** In a hard-wrapped paragraph, "we think it is"
+  at the end of a line stays full.
+- **A clause end is an inventory of characters.** ".", ",", ";", ":", "!", "?",
+  ")", "]", "}", a straight double quote, a curly closing double or single
+  quote, an ellipsis, an em dash, an en dash and "-" end a clause; a straight
+  apostrophe doesn't, so "Say 'it is' now." becomes "Say 'it's' now.", and a
+  hyphen inside a word counts ("it is-fine" stays full).
+- **A masked "]" reads as text that follows.** A link whose anchor text ends a
+  clause is contracted when you protect the whole "](destination)": "Meet [who
+  we are](/about)." becomes "Meet [who we're](/about).".
+- **Only spaces and tabs join the words of a pair.** A non-breaking space
+  between "do" and "not", or a line break, keeps the pair from matching.
+- **The other direction is plain suffix rules.** `findContracted` always
+  expands "'s" to "is" ("It's been" suggests "It is", not "It has"), "'d" to
+  "would" ("She'd left" suggests "She would", not "She had"), and "ain't"
+  like any other "n't" word ("ai not"). Only the first letter's case carries
+  over ("WHY IT'S" suggests "IT is"). Treat its suggestions as prompts for a
+  person, not as edits to apply.
+- **Case.** Only the first letter's case carries over: "IT IS FINE." becomes
+  "It's FINE.".
+- **The heading rule is first-on-the-line.** "What Is" keeps its form only
+  when nothing but spaces, "*", "_" and masked text comes before it on its
+  line, and only when `titleLike` is set and the markers are already blanked.
+  The check is on the "what is" pair in any case, so "what is local seo" is
+  kept too.
+- **"let us" opens a sentence after a full stop, "!", "?" or ":".** Spaces,
+  "*", "_" and masked text before it are skipped, so "Now: let us look at it."
+  contracts.
 
 ## Why it exists
 

package/dist/voice.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Stands in for every character that isn't prose (code, quotations, link
+ * destinations). It's neither whitespace nor a word character, so a masked
+ * span still separates words and no pattern can match it.
+ */
+export declare const VOICE_MASK = "\u2800";
+export interface VoiceHit {
+    /** UTF-16 offset into the whole string you passed in, never line-relative. */
+    readonly index: number;
+    /** Length of the span to replace. May include a run of spaces or tabs. */
+    readonly length: number;
+    /** The text at [index, index + length) of the string you passed in. */
+    readonly match: string;
+    /** What to put there, first-letter case preserved. Always a straight apostrophe. */
+    readonly suggestion: string;
+}
+export interface VoiceOptions {
+    /**
+     * The text is a heading or title, so one that opens with "What Is" keeps it.
+     * Applies to every line. Pass the heading text, not the Markdown line: `#`
+     * and list markers must already be blanked.
+     */
+    readonly titleLike?: boolean | undefined;
+    /**
+     * Half-open [start, end) UTF-16 ranges to leave alone, computed from the
+     * exact string passed in. Any order, overlaps and touching ranges allowed.
+     * Start is floored and clamped to 0 (so -Infinity means "from the start"),
+     * end is ceiled and clamped to the text length (so Infinity means "to the
+     * end"), and an empty or out-of-text range is ignored. Every protected
+     * character is masked except "\n" and "\r", which stay as they are (a
+     * protected line break still ends its line). A malformed range (NaN, a
+     * non-number, or start after end) or a truthy value that isn't an array
+     * protects the whole text: protection never fails open. A falsy value means
+     * no ranges.
+     */
+    readonly protectedRanges?: ReadonlyArray<readonly [number, number]> | undefined;
+}
+/**
+ * Full forms the house voice contracts ("do not" -> "don't"). Read one line at
+ * a time: split on "\n"; a "\r" right before it, or at the very end of the
+ * text, ends the line with it; any other "\r" is text.
+ * Sorted by index, never overlapping, [] for ''.
+ */
+export declare function findUncontracted(text: string, options?: VoiceOptions): VoiceHit[];
+/**
+ * `text` with every findUncontracted hit applied. Returns `text` itself when
+ * nothing applies, and for anything that isn't a string. Protected characters
+ * are never rewritten.
+ */
+export declare function contractText(text: string, options?: VoiceOptions): string;
+/**
+ * Contractions a question-form heading or FAQ question must expand
+ * ("What's" -> "What is"). Sorted by index, never overlapping. `titleLike` is
+ * not part of this direction.
+ */
+export declare function findContracted(text: string, options?: Pick<VoiceOptions, 'protectedRanges'>): VoiceHit[];

package/dist/voice.js

@@ -0,0 +1,200 @@
+'use strict';
+
+// src/contracts/voice.ts
+var VOICE_MASK = "\u2800";
+var TABLE = [
+  ["do not", "don't"],
+  ["does not", "doesn't"],
+  ["did not", "didn't"],
+  ["is not", "isn't"],
+  ["are not", "aren't"],
+  ["was not", "wasn't"],
+  ["were not", "weren't"],
+  ["cannot", "can't"],
+  ["can not", "can't"],
+  ["will not", "won't"],
+  ["would not", "wouldn't"],
+  ["should not", "shouldn't"],
+  ["could not", "couldn't"],
+  ["has not", "hasn't"],
+  ["have not", "haven't"],
+  ["had not", "hadn't"],
+  ["must not", "mustn't"],
+  ["need not", "needn't"],
+  ["it is", "it's"],
+  ["that is", "that's"],
+  ["there is", "there's"],
+  ["here is", "here's"],
+  ["who is", "who's"],
+  ["what is", "what's"],
+  ["you are", "you're"],
+  ["we are", "we're"],
+  ["they are", "they're"],
+  ["I am", "I'm"],
+  ["you will", "you'll"],
+  ["we will", "we'll"],
+  ["they will", "they'll"],
+  ["it will", "it'll"],
+  ["we would", "we'd"],
+  ["you would", "you'd"],
+  ["they would", "they'd"],
+  ["let us", "let's"]
+];
+var PAIRS = TABLE.map(([full, contracted]) => ({
+  full,
+  contracted,
+  negation: / not$|^cannot$/.test(full),
+  pattern: new RegExp(`\\b${full.replace(/ /g, "[ \\t]+")}\\b`, "gi")
+}));
+var CAN_NOT_ONLY = /[ \t]+only\b/iy;
+var CLAUSE_END = /[ \t]*(?:[.,;:!?)\]}"\u201d\u2019\u2026\u2014\u2013-]|\r?\n|\r?$)/y;
+var CONJUNCTION = /[ \t]+(?:and|or|but|nor)\b/iy;
+var LET_US_SUGGESTIONS = /[ \t]+(?:look|start|begin|consider|turn|see|review|compare|break|dig|recap|unpack|explore|examine|revisit|focus|go|talk|move|get started|step back|zoom out)\b/iy;
+var PROSE_GAP = /[\s*_\u2800]/;
+var preserveCase = (match, replacement) => match[0] === match[0].toUpperCase() && match[0] !== match[0].toLowerCase() ? replacement[0].toUpperCase() + replacement.slice(1) : replacement;
+var maskAll = (text) => text.replace(/[^\r\n]/g, VOICE_MASK);
+function maskProtected(text, ranges) {
+  if (!ranges) return text;
+  if (!Array.isArray(ranges)) return maskAll(text);
+  if (ranges.length === 0) return text;
+  const length = text.length;
+  const edges = new Int32Array(length + 1);
+  let any = false;
+  for (const range of ranges) {
+    const from = range?.[0];
+    const to = range?.[1];
+    if (typeof from !== "number" || typeof to !== "number" || Number.isNaN(from) || Number.isNaN(to) || from > to) return maskAll(text);
+    const start = Math.max(0, Math.floor(from));
+    const end = Math.min(length, Math.ceil(to));
+    if (end <= start) continue;
+    edges[start] += 1;
+    edges[end] -= 1;
+    any = true;
+  }
+  if (!any) return text;
+  const parts = [];
+  let depth = 0;
+  let runStart = 0;
+  let runProtected = false;
+  for (let i = 0; i <= length; i++) {
+    const isProtected = i < length && (depth += edges[i]) > 0;
+    if (i === length || isProtected !== runProtected) {
+      if (i > runStart) parts.push(runProtected ? maskAll(text.slice(runStart, i)) : text.slice(runStart, i));
+      runStart = i;
+      runProtected = isProtected;
+    }
+  }
+  return parts.join("");
+}
+function walkBackOverGap(text, start) {
+  let at = start;
+  while (at > 0 && text[at - 1] !== "\n" && PROSE_GAP.test(text[at - 1])) at--;
+  return at;
+}
+function firstStop(text, from) {
+  for (let i = from; i < text.length; i++) {
+    const code = text.charCodeAt(i);
+    if (code === 46 || code === 33 || code === 63 || code === 10) return i;
+  }
+  return text.length;
+}
+function mustStayFull(pair, text, titleLike, start, end, look) {
+  if (pair.full === "can not") {
+    CAN_NOT_ONLY.lastIndex = end;
+    return CAN_NOT_ONLY.test(text);
+  }
+  if (pair.negation) return false;
+  CLAUSE_END.lastIndex = end;
+  if (CLAUSE_END.test(text)) return true;
+  CONJUNCTION.lastIndex = end;
+  if (CONJUNCTION.test(text)) return true;
+  if (pair.full === "what is") {
+    if (look.stop < end) look.stop = firstStop(text, end);
+    if (text.charCodeAt(look.stop) === 63) return true;
+    if (titleLike) {
+      const at = walkBackOverGap(text, start);
+      if (at === 0 || text[at - 1] === "\n") return true;
+    }
+  }
+  if (pair.full === "let us") {
+    const at = walkBackOverGap(text, start);
+    if (at > 0 && !".!?:\n".includes(text[at - 1])) return true;
+    LET_US_SUGGESTIONS.lastIndex = end;
+    return !LET_US_SUGGESTIONS.test(text);
+  }
+  return false;
+}
+function scanUncontracted(text, masked, titleLike) {
+  if (masked.length < 4) return [];
+  const hits = [];
+  const claimed = new Uint8Array(masked.length);
+  for (const pair of PAIRS) {
+    const look = { stop: -1 };
+    for (const found of masked.matchAll(pair.pattern)) {
+      const start = found.index ?? 0;
+      const end = start + found[0].length;
+      let overlaps = false;
+      for (let i = start; i < end; i++) {
+        if (claimed[i] === 1) {
+          overlaps = true;
+          break;
+        }
+      }
+      if (overlaps || mustStayFull(pair, masked, titleLike, start, end, look)) continue;
+      claimed.fill(1, start, end);
+      const match = text.slice(start, end);
+      hits.push({ index: start, length: end - start, match, suggestion: preserveCase(match, pair.contracted) });
+    }
+  }
+  return hits.sort((a, b) => a.index - b.index);
+}
+function findUncontracted(text, options) {
+  if (typeof text !== "string" || !text) return [];
+  return scanUncontracted(text, maskProtected(text, options?.protectedRanges), options?.titleLike === true);
+}
+function contractText(text, options) {
+  const hits = findUncontracted(text, options);
+  if (hits.length === 0) return text;
+  let out = "";
+  let cursor = 0;
+  for (const hit of hits) {
+    out += text.slice(cursor, hit.index) + hit.suggestion;
+    cursor = hit.index + hit.length;
+  }
+  return out + text.slice(cursor);
+}
+var CONTRACTION = /\b(?:[A-Za-z]+n['\u2019]t|(?:it|that|what|there|here|who|where|how|when|why|let|he|she)['\u2019]s|(?:you|we|they|who|what)['\u2019]re|(?:i|you|we|they|it|that|who|there|what)['\u2019]ll|(?:i|you|we|they|who|could|would|should|might|must)['\u2019]ve|(?:i|you|we|they|he|she|it|that|who|there)['\u2019]d|i['\u2019]m)\b/gi;
+var IRREGULAR_EXPANSIONS = {
+  "can't": "cannot",
+  "won't": "will not",
+  "shan't": "shall not",
+  "let's": "let us",
+  "i'm": "I am"
+};
+var SUFFIX_EXPANSIONS = { s: "is", re: "are", ll: "will", ve: "have", d: "would", m: "am" };
+function expandContraction(contraction) {
+  const plain = contraction.replace(/\u2019/g, "'");
+  const lower = plain.toLowerCase();
+  let expanded = IRREGULAR_EXPANSIONS[lower];
+  if (!expanded && lower.endsWith("n't")) expanded = `${plain.slice(0, -3)} not`;
+  if (!expanded) {
+    const [word, suffix] = plain.split("'");
+    expanded = `${word} ${SUFFIX_EXPANSIONS[suffix.toLowerCase()] ?? suffix}`;
+  }
+  return preserveCase(plain, expanded);
+}
+function findContracted(text, options) {
+  if (typeof text !== "string" || !text) return [];
+  const hits = [];
+  for (const found of maskProtected(text, options?.protectedRanges).matchAll(CONTRACTION)) {
+    const index = found.index ?? 0;
+    const match = text.slice(index, index + found[0].length);
+    hits.push({ index, length: match.length, match, suggestion: expandContraction(match) });
+  }
+  return hits;
+}
+
+exports.VOICE_MASK = VOICE_MASK;
+exports.contractText = contractText;
+exports.findContracted = findContracted;
+exports.findUncontracted = findUncontracted;

package/dist/voice.mjs

@@ -0,0 +1,195 @@
+// src/contracts/voice.ts
+var VOICE_MASK = "\u2800";
+var TABLE = [
+  ["do not", "don't"],
+  ["does not", "doesn't"],
+  ["did not", "didn't"],
+  ["is not", "isn't"],
+  ["are not", "aren't"],
+  ["was not", "wasn't"],
+  ["were not", "weren't"],
+  ["cannot", "can't"],
+  ["can not", "can't"],
+  ["will not", "won't"],
+  ["would not", "wouldn't"],
+  ["should not", "shouldn't"],
+  ["could not", "couldn't"],
+  ["has not", "hasn't"],
+  ["have not", "haven't"],
+  ["had not", "hadn't"],
+  ["must not", "mustn't"],
+  ["need not", "needn't"],
+  ["it is", "it's"],
+  ["that is", "that's"],
+  ["there is", "there's"],
+  ["here is", "here's"],
+  ["who is", "who's"],
+  ["what is", "what's"],
+  ["you are", "you're"],
+  ["we are", "we're"],
+  ["they are", "they're"],
+  ["I am", "I'm"],
+  ["you will", "you'll"],
+  ["we will", "we'll"],
+  ["they will", "they'll"],
+  ["it will", "it'll"],
+  ["we would", "we'd"],
+  ["you would", "you'd"],
+  ["they would", "they'd"],
+  ["let us", "let's"]
+];
+var PAIRS = TABLE.map(([full, contracted]) => ({
+  full,
+  contracted,
+  negation: / not$|^cannot$/.test(full),
+  pattern: new RegExp(`\\b${full.replace(/ /g, "[ \\t]+")}\\b`, "gi")
+}));
+var CAN_NOT_ONLY = /[ \t]+only\b/iy;
+var CLAUSE_END = /[ \t]*(?:[.,;:!?)\]}"\u201d\u2019\u2026\u2014\u2013-]|\r?\n|\r?$)/y;
+var CONJUNCTION = /[ \t]+(?:and|or|but|nor)\b/iy;
+var LET_US_SUGGESTIONS = /[ \t]+(?:look|start|begin|consider|turn|see|review|compare|break|dig|recap|unpack|explore|examine|revisit|focus|go|talk|move|get started|step back|zoom out)\b/iy;
+var PROSE_GAP = /[\s*_\u2800]/;
+var preserveCase = (match, replacement) => match[0] === match[0].toUpperCase() && match[0] !== match[0].toLowerCase() ? replacement[0].toUpperCase() + replacement.slice(1) : replacement;
+var maskAll = (text) => text.replace(/[^\r\n]/g, VOICE_MASK);
+function maskProtected(text, ranges) {
+  if (!ranges) return text;
+  if (!Array.isArray(ranges)) return maskAll(text);
+  if (ranges.length === 0) return text;
+  const length = text.length;
+  const edges = new Int32Array(length + 1);
+  let any = false;
+  for (const range of ranges) {
+    const from = range?.[0];
+    const to = range?.[1];
+    if (typeof from !== "number" || typeof to !== "number" || Number.isNaN(from) || Number.isNaN(to) || from > to) return maskAll(text);
+    const start = Math.max(0, Math.floor(from));
+    const end = Math.min(length, Math.ceil(to));
+    if (end <= start) continue;
+    edges[start] += 1;
+    edges[end] -= 1;
+    any = true;
+  }
+  if (!any) return text;
+  const parts = [];
+  let depth = 0;
+  let runStart = 0;
+  let runProtected = false;
+  for (let i = 0; i <= length; i++) {
+    const isProtected = i < length && (depth += edges[i]) > 0;
+    if (i === length || isProtected !== runProtected) {
+      if (i > runStart) parts.push(runProtected ? maskAll(text.slice(runStart, i)) : text.slice(runStart, i));
+      runStart = i;
+      runProtected = isProtected;
+    }
+  }
+  return parts.join("");
+}
+function walkBackOverGap(text, start) {
+  let at = start;
+  while (at > 0 && text[at - 1] !== "\n" && PROSE_GAP.test(text[at - 1])) at--;
+  return at;
+}
+function firstStop(text, from) {
+  for (let i = from; i < text.length; i++) {
+    const code = text.charCodeAt(i);
+    if (code === 46 || code === 33 || code === 63 || code === 10) return i;
+  }
+  return text.length;
+}
+function mustStayFull(pair, text, titleLike, start, end, look) {
+  if (pair.full === "can not") {
+    CAN_NOT_ONLY.lastIndex = end;
+    return CAN_NOT_ONLY.test(text);
+  }
+  if (pair.negation) return false;
+  CLAUSE_END.lastIndex = end;
+  if (CLAUSE_END.test(text)) return true;
+  CONJUNCTION.lastIndex = end;
+  if (CONJUNCTION.test(text)) return true;
+  if (pair.full === "what is") {
+    if (look.stop < end) look.stop = firstStop(text, end);
+    if (text.charCodeAt(look.stop) === 63) return true;
+    if (titleLike) {
+      const at = walkBackOverGap(text, start);
+      if (at === 0 || text[at - 1] === "\n") return true;
+    }
+  }
+  if (pair.full === "let us") {
+    const at = walkBackOverGap(text, start);
+    if (at > 0 && !".!?:\n".includes(text[at - 1])) return true;
+    LET_US_SUGGESTIONS.lastIndex = end;
+    return !LET_US_SUGGESTIONS.test(text);
+  }
+  return false;
+}
+function scanUncontracted(text, masked, titleLike) {
+  if (masked.length < 4) return [];
+  const hits = [];
+  const claimed = new Uint8Array(masked.length);
+  for (const pair of PAIRS) {
+    const look = { stop: -1 };
+    for (const found of masked.matchAll(pair.pattern)) {
+      const start = found.index ?? 0;
+      const end = start + found[0].length;
+      let overlaps = false;
+      for (let i = start; i < end; i++) {
+        if (claimed[i] === 1) {
+          overlaps = true;
+          break;
+        }
+      }
+      if (overlaps || mustStayFull(pair, masked, titleLike, start, end, look)) continue;
+      claimed.fill(1, start, end);
+      const match = text.slice(start, end);
+      hits.push({ index: start, length: end - start, match, suggestion: preserveCase(match, pair.contracted) });
+    }
+  }
+  return hits.sort((a, b) => a.index - b.index);
+}
+function findUncontracted(text, options) {
+  if (typeof text !== "string" || !text) return [];
+  return scanUncontracted(text, maskProtected(text, options?.protectedRanges), options?.titleLike === true);
+}
+function contractText(text, options) {
+  const hits = findUncontracted(text, options);
+  if (hits.length === 0) return text;
+  let out = "";
+  let cursor = 0;
+  for (const hit of hits) {
+    out += text.slice(cursor, hit.index) + hit.suggestion;
+    cursor = hit.index + hit.length;
+  }
+  return out + text.slice(cursor);
+}
+var CONTRACTION = /\b(?:[A-Za-z]+n['\u2019]t|(?:it|that|what|there|here|who|where|how|when|why|let|he|she)['\u2019]s|(?:you|we|they|who|what)['\u2019]re|(?:i|you|we|they|it|that|who|there|what)['\u2019]ll|(?:i|you|we|they|who|could|would|should|might|must)['\u2019]ve|(?:i|you|we|they|he|she|it|that|who|there)['\u2019]d|i['\u2019]m)\b/gi;
+var IRREGULAR_EXPANSIONS = {
+  "can't": "cannot",
+  "won't": "will not",
+  "shan't": "shall not",
+  "let's": "let us",
+  "i'm": "I am"
+};
+var SUFFIX_EXPANSIONS = { s: "is", re: "are", ll: "will", ve: "have", d: "would", m: "am" };
+function expandContraction(contraction) {
+  const plain = contraction.replace(/\u2019/g, "'");
+  const lower = plain.toLowerCase();
+  let expanded = IRREGULAR_EXPANSIONS[lower];
+  if (!expanded && lower.endsWith("n't")) expanded = `${plain.slice(0, -3)} not`;
+  if (!expanded) {
+    const [word, suffix] = plain.split("'");
+    expanded = `${word} ${SUFFIX_EXPANSIONS[suffix.toLowerCase()] ?? suffix}`;
+  }
+  return preserveCase(plain, expanded);
+}
+function findContracted(text, options) {
+  if (typeof text !== "string" || !text) return [];
+  const hits = [];
+  for (const found of maskProtected(text, options?.protectedRanges).matchAll(CONTRACTION)) {
+    const index = found.index ?? 0;
+    const match = text.slice(index, index + found[0].length);
+    hits.push({ index, length: match.length, match, suggestion: expandContraction(match) });
+  }
+  return hits;
+}
+
+export { VOICE_MASK, contractText, findContracted, findUncontracted };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sonordev/contracts",
-  "version": "2.0.0",
-  "description": "The rules Sonor's sites, APIs and dashboard share: popup blocks and site design tokens, site hosts, SEO page identity, title quality, llms.txt sanitizers, the forms honeypot, fleet heartbeats, slot content and signing, site cache tags and portfolio metrics. Pure functions, no dependencies.",
+  "version": "2.1.0",
+  "description": "The rules Sonor's sites, APIs and dashboard share: popup blocks and site design tokens, site hosts, SEO page identity, title quality, llms.txt sanitizers, the forms honeypot, fleet heartbeats, slot content and signing, site cache tags, portfolio metrics and the house voice's contraction rule. Pure functions, no dependencies.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -80,6 +80,11 @@
       "import": "./dist/portfolio.mjs",
       "require": "./dist/portfolio.js"
     },
+    "./voice": {
+      "types": "./dist/voice.d.ts",
+      "import": "./dist/voice.mjs",
+      "require": "./dist/voice.js"
+    },
     "./package.json": "./package.json"
   },
   "typesVersions": {