@sonordev/contracts 2.0.0 → 2.1.1

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # Changelog
 
+## 2.1.1
+
+- Docs only: the README names the Sonor API and the dashboard where it named internal repositories. No code changes.
+
+## 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.
@@ -21,7 +73,7 @@ A major for one entry, `slots`, plus three new entries; every other entry is unc
   `slots` re-exports all of it.
 - **New entry `@sonordev/contracts/site-cache`**: how Sonor refreshes a
   site's cached pages. `SITE_CACHE_TAGS` (the tag names site-kit's fetches
-  carry and sonor-api expires), `SITE_REVALIDATE_PATH`, the webhook payload
+  carry and the Sonor API expires), `SITE_REVALIDATE_PATH`, the webhook payload
   and its `ping`, and `isSiteRevalidatePong`.
 - **New entry `@sonordev/contracts/site-edit`**: Sonor's Edit on page. The
   messages between a framed site and the dashboard, which origins may drive
@@ -32,5 +84,5 @@ A major for one entry, `slots`, plus three new entries; every other entry is unc
 
 First release. The rules site-kit 6.x published as `@sonordev/site-kit/*/contract`
 (website, color, sites, seo-pages, seo-meta, llms, forms, fleet, slots,
-portfolio), as a dependency-free package, so sonor-api, signal-api and the
-dashboard import them instead of keeping mirrors.
+portfolio), as a dependency-free package, so the Sonor APIs and the
+dashboard import them instead of keeping copies.

package/README.md

@@ -9,26 +9,136 @@ pnpm add @sonordev/contracts
 
 | Entry | What it decides | Who reads it |
 |---|---|---|
-| `@sonordev/contracts/website` | A site's design tokens and what a popup is made of (blocks, limits, the text sanitizer) | site-kit renders them, sonor-api validates every write, the dashboard previews them, Signal's agents send them |
+| `@sonordev/contracts/website` | A site's design tokens and what a popup is made of (blocks, limits, the text sanitizer) | site-kit renders them, the Sonor API validates every write, the dashboard previews them, Signal's agents send them |
 | `@sonordev/contracts/color` | Reading a CSS color, WCAG luminance and contrast | `website`, site-kit's brand extraction |
 | `@sonordev/contracts/sites` | The canonical shape of a site host (the multi-site `site` dimension) | every ingest and read that filters by site |
-| `@sonordev/contracts/seo-pages` | Which `seo_pages` row a path resolves to on a multi-site project | sonor-api, Signal, site-kit's sitemap sync |
+| `@sonordev/contracts/seo-pages` | Which `seo_pages` row a path resolves to on a multi-site project | the Sonor API, Signal, site-kit's sitemap sync |
 | `@sonordev/contracts/seo-meta` | Whether a title or description is fit to ship | site-kit, Signal's SEO gate |
-| `@sonordev/contracts/llms` | llms.txt sanitizers and contract version | site-kit, sonor-api, Signal's schema validation |
-| `@sonordev/contracts/forms` | The honeypot policy | site-kit forms, sonor-api intake |
-| `@sonordev/contracts/fleet` | The fleet heartbeat's wire shape | site-kit, sonor-api |
-| `@sonordev/contracts/slots` | Slot payload signing, contract v2 (HMAC; Node only). Signs and verifies v1 for older site-kit releases | sonor-api, site-kit on the server |
-| `@sonordev/contracts/slot-content` | What a slot of each kind may hold (`normalizeSlotValue`), safe links, the rich-text parser. No `crypto`, so browsers can import it | sonor-api, site-kit, the dashboard editor |
-| `@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/llms` | llms.txt sanitizers and contract version | site-kit, the Sonor API, Signal's schema validation |
+| `@sonordev/contracts/forms` | The honeypot policy | site-kit forms, the Sonor API's form intake |
+| `@sonordev/contracts/fleet` | The fleet heartbeat's wire shape | site-kit, the Sonor API |
+| `@sonordev/contracts/slots` | Slot payload signing, contract v2 (HMAC; Node only). Signs and verifies v1 for older site-kit releases | the Sonor API, site-kit on the server |
+| `@sonordev/contracts/slot-content` | What a slot of each kind may hold (`normalizeSlotValue`), safe links, the rich-text parser. No `crypto`, so browsers can import it | the Sonor API, site-kit, the dashboard editor |
+| `@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, the 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/portfolio` | Where a portfolio number comes from and which may headline; the live-frame message | the 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
 
-Before this package, each API kept a byte-identical copy of the rules it
-shared with site-kit, plus a drift test to catch the copies diverging. Ten
-parallel copies of a rule is how two of them end up disagreeing. Now there's
-one: the source is `src/contracts/` in the site-kit repo, site-kit bundles it
+A rule that lives in several copies is how two of them end up disagreeing.
+This package means there's one: the source is `src/contracts/` in the site-kit repo, site-kit bundles it
 into its own `*/contract` entries, and this package publishes the same files
 for everyone else.
 

package/dist/fleet.d.ts

@@ -2,13 +2,13 @@
  * @sonordev/contracts/fleet — Fleet heartbeat wire contract (v1)
  *
  * Single source of truth for the heartbeat payload shape, shared by site-kit
- * (send side, `@sonordev/site-kit/fleet/contract`) and sonor-api (ingest
+ * (send side, `@sonordev/site-kit/fleet/contract`) and the Sonor API (ingest
  * side: its DTO is type-checked against FleetHeartbeatPayload).
  *
- * Why it exists: ~24+ client sites run site-kit at wildly drifted versions and
- * the platform could not answer "which version / modules / key state is each
- * site running" without shelling into every local repo. The heartbeat answers
- * that from live traffic. It is fire-and-forget, deferred to idle (never in the
+ * Why it exists: sites run whatever site-kit version they last deployed, and
+ * Sonor should be able to answer "which version / modules / key state is each
+ * site running" without anyone opening each repo. The heartbeat answers that
+ * from live traffic. It is fire-and-forget, deferred to idle (never in the
  * hydration path), and carries NO visitor data — only the site's own build
  * fingerprint. Project identity is resolved server-side from the x-api-key
  * header, exactly like every other /api/public/* endpoint; sites never send
@@ -56,7 +56,7 @@ export interface FleetHeartbeatPayload {
     next_version?: string | null;
     /** Client-observable active modules — deduped, validated, canonical order. */
     modules: FleetModule[];
-    /** Normalized lowercase host (multi-site sub-dimension; see CLAUDE.md). */
+    /** Normalized lowercase host (multi-site sub-dimension). */
     site?: string | null;
     /** 'client' (runtime boot) or 'build' (CI/build step). Default 'client'. */
     source?: FleetHeartbeatSource;
@@ -77,9 +77,9 @@ export declare function normalizeFleetModules(input: unknown): FleetModule[];
 export declare function sanitizeFleetVersion(raw: unknown): string | null;
 /**
  * Light client-side site normalization to the canonical host shape (lowercase,
- * no protocol/path/port). sonor-api's IngestService.normalizeSite is the
- * AUTHORITATIVE normalizer and re-runs on ingest — this just avoids sending
- * obvious noise. Keep the two shapes aligned (see CLAUDE.md "site" convention).
+ * no protocol/path/port). The Sonor API's normalizer is AUTHORITATIVE and
+ * re-runs on ingest; this just avoids sending obvious noise. Keep the two
+ * shapes aligned.
  */
 export declare function normalizeFleetSite(raw: unknown): string | null;
 /**

package/dist/forms.d.ts

@@ -1,17 +1,11 @@
 /**
  * @sonordev/contracts/forms — managed-form honeypot policy (v1)
  *
- * Single source of truth for the honeypot trap-field naming + server-side
- * detection policy, shared by the client (site-kit emits the trap field) and
- * the server (sonor-api names the trap in the form config it returns AND
- * detects hits on intake). Both import this: site-kit as
- * `@sonordev/site-kit/forms/contract`, sonor-api through
- * `src/modules/forms/honeypot-contract.ts`.
+ * Single source of truth for the honeypot field's naming, shared by site-kit
+ * (which renders the field, as `@sonordev/site-kit/forms/contract`) and Sonor.
  *
- * The default field name (`_sk_hp_url`) is deliberately obscure: a common name
- * like "website" collides with real form fields and flags genuine submissions
- * as spam, so generic names are only trusted when they DON'T match a real
- * field of the form (see `resolveHoneypotFieldNames`).
+ * The default field name is deliberately unlike a real field's, so it never
+ * collides with a form's own fields (see `resolveHoneypotFieldNames`).
  */
 /** Bump on breaking changes to the honeypot policy. */
 export declare const FORMS_HONEYPOT_CONTRACT_VERSION: 1;

package/dist/llms.d.ts

@@ -14,7 +14,7 @@ export declare const LLMS_PUBLIC_SUMMARY_MAX_LENGTH = 400;
 /** Max length for optional llms.txt blockquote disclaimer line. */
 export declare const LLMS_DISCLAIMER_MAX_LENGTH = 280;
 /**
- * Optional keys we allow inside managed_llm_schema JSON from Portal.
+ * Optional keys we allow inside managed_llm_schema JSON from Sonor.
  * Values outside this set should not be relied on by consumers; strip unknown keys when emitting JSON-LD.
  */
 export declare const MANAGED_LLM_SCHEMA_KNOWN_KEYS: Set<string>;

package/dist/portfolio.d.ts

@@ -2,13 +2,9 @@
  * @sonordev/contracts/portfolio — portfolio proof display policy (v1)
  *
  * Single source of truth for the Lighthouse-KPI collapse policy shared by the
- * content side (signal-api generation) and the render side (agency-site-kit
- * display):
- *  - agency-site-kit imports it (`@sonordev/site-kit/portfolio/contract`)
- *    from `src/portfolio/curate-proof.ts`, which keeps the render-only
- *    primitives that bind to its section types.
- *  - signal-api imports it through
- *    `src/modules/skills/portfolio/portfolio-kpi-policy.util.ts`.
+ * content side (Signal's case-study generation) and the render side
+ * (agency-site-kit, which imports it as `@sonordev/site-kit/portfolio/contract`
+ * and keeps the render-only primitives that bind to its section types).
  *
  * Why it exists: generated case studies arrived with four "100/100 Lighthouse X"
  * KPIs repeated across hero, results cards, and a Performance section. One
@@ -17,8 +13,8 @@
  *
  * It is also the single source of truth for METRIC PROVENANCE (below): the
  * three sources a portfolio number can have, what a client-reported number
- * must carry, and which numbers may headline. sonor-api imports those
- * through `src/modules/portfolio/portfolio-metric-source.util.ts`.
+ * must carry, and which numbers may headline. The Sonor API applies the same
+ * rules.
  */
 /** The message a cross-origin-framed site-kit page posts to its embedder once it has painted. */
 export declare const FRAME_READY_MESSAGE: 'sonor:frame-ready';
@@ -109,11 +105,11 @@ export declare const METRIC_SOURCES: readonly ['measured', 'reported', 'estimate
 export type MetricSource = (typeof METRIC_SOURCES)[number];
 /** Who stands behind a client-reported number. */
 export interface MetricAttribution {
-    /** The person, e.g. "Scott Mann". */
+    /** The person, e.g. "Dana Reyes". */
     name: string;
-    /** Their title, e.g. "Director of Business Development". */
+    /** Their title, e.g. "Director of Operations". */
     role?: string;
-    /** Where they work: almost always the client, e.g. "True Power Systems". */
+    /** Where they work: almost always the client, e.g. "Northwind Engineering". */
     organization: string;
     /** The day they reported it, YYYY-MM-DD. */
     date: string;
@@ -140,12 +136,12 @@ export declare function isHeadlineMetric(metric: SourcedMetric): boolean;
 /** The badge a display shows, or null for a missing or unknown source (show nothing rather than guess). */
 export declare function metricSourceLabel(source: unknown): string | null;
 /**
- * The full credit: "Reported by Scott Mann, Director of Business Development,
- * True Power Systems, September 25, 2026". The date is read as a plain day,
+ * The full credit: "Reported by Dana Reyes, Director of Operations, Northwind
+ * Engineering, September 25, 2026". The date is read as a plain day,
  * never through a time zone, so it can't slip to the day before.
  */
 export declare function formatAttribution(by: MetricAttribution): string;
-/** The credit for a tight space (a card, a carousel tile): "per True Power Systems". */
+/** The credit for a tight space (a card, a carousel tile): "per Northwind Engineering". */
 export declare function shortAttribution(by: Pick<MetricAttribution, 'organization'>): string;
 /**
  * Carry a person's reported numbers through a regeneration. The generator can

package/dist/seo-meta.d.ts

@@ -4,17 +4,16 @@
  * Single source of truth for "is this machine-generated seo_pages.managed_title
  * / managed_meta_description fit to ship?". site-kit applies it at render time
  * (getManagedMetadata falls back to the page's own title/description), and
- * signal-api imports it (`src/shared/utils/seo-meta-quality.util.ts`) to gate
- * every generated title before it's written, so the two can't disagree.
+ * Signal applies it to every generated title before it's written, so the two
+ * can't disagree.
  *
- * Why it exists (2026-09-15): Signal's meta generator used the raw domain as
- * the brand whenever it could not resolve one, so ~500 managed titles across
- * 20+ projects shipped as "Apartments for Rent | abbeyglenapts.com", were
- * hard-cut at 60 chars ("… | reinhartheatingandcooli"), lost the suffix to a
- * word-boundary cut ("Contact Reinhart Heating and Cooling |"), or had the
- * model rebuild a brand out of the domain ("About SSO Shkosh Apartments | SSO
- * Shkosh" for ssoshkoshapts.com — the brand is SS Oshkosh Apartments). Sites
- * rendered them verbatim.
+ * Why it exists: a meta generator that uses the raw domain as the brand when it
+ * can't resolve one ships titles like "Apartments for Rent |
+ * maplecourtapts.com", hard-cuts them at 60 chars ("… |
+ * brightsideheatingandcooli"), loses the suffix to a word-boundary cut
+ * ("Contact Brightside Heating and Cooling |"), or rebuilds a brand out of the
+ * domain ("About BBE Llis Apartments | BBE Llis" for bbellisapts.com, when the
+ * brand is BB Ellis Apartments). Sites render them verbatim.
  *
  * Every rule derives from the site's own identity (its hosts and brand), so
  * there is no list of bad strings to maintain. Pure string logic — no I/O, no
@@ -24,7 +23,7 @@
 export declare const SEO_META_CONTRACT_VERSION: 1;
 /** Who the site is. Hosts come from the project/site config, the brand from the resolved business name — never from the domain. */
 export interface MetaIdentity {
-    /** The site's brand, e.g. "SS Oshkosh Apartments". */
+    /** The site's brand, e.g. "BB Ellis Apartments". */
     brand?: string | null;
     /** Other correct spellings of the brand. */
     brandAliases?: Array<string | null | undefined>;
@@ -34,7 +33,7 @@ export interface MetaIdentity {
 export type TitleProblem = 'empty' | 'placeholder' | 'dangling-separator' | 'hostname' | 'mangled-brand';
 export type DescriptionProblem = 'empty' | 'hostname' | 'mangled-brand' | 'truncated';
 export type SuffixProblem = 'hostname' | 'mangled-brand';
-/** "https://www.AbbeyGlenApts.com:443/x" → "abbeyglenapts.com". Null for anything that isn't a host (no dot, or words). */
+/** "https://www.MapleCourtApts.com:443/x" → "maplecourtapts.com". Null for anything that isn't a host (no dot, or words). */
 export declare function metaHost(value: string | null | undefined): string | null;
 /** True when the text names the brand (an alias, or either one's core) word for word. */
 export declare function namesBrand(text: string, id: MetaIdentity): boolean;

package/dist/seo-pages.d.ts

@@ -3,13 +3,10 @@
  *
  * Single source of truth for choosing ONE seo_pages row when a (project_id,
  * path/url) lookup matches several, and for scoping a project's rows to one
- * host. site-kit (`@sonordev/site-kit/seo/pages/contract`), sonor-api
- * (`src/modules/seo/seo-page-resolve.util.ts`) and signal-api
- * (`src/shared/utils/seo-page-pick.util.ts`) all import this; none keeps a
- * copy.
+ * host. site-kit (`@sonordev/site-kit/seo/pages/contract`) and both Sonor
+ * APIs import this; none keeps a copy.
  *
- * seo_pages identity became (project_id, site, url) in sonor-api migration
- * 20260702150000_seo_pages_per_site_identity.sql: a multi-site project (one
+ * seo_pages identity is (project_id, site, url): a multi-site project (one
  * Sonor project hosting many domains) keeps one row PER SUB-SITE HOST for
  * shared paths like `/` or `/contact`. Any path/url lookup can therefore match
  * several rows — `.single()`/`.maybeSingle()` error on them (PGRST116) — so
@@ -26,11 +23,9 @@ export declare const SEO_PAGES_CONTRACT_VERSION: 1;
  *
  * Retired pages are kept as tombstones (status='removed') so their history and
  * redirects survive, which means every public read has to opt out of them
- * explicitly. Three reads in llms-content.service.ts never did, and the sitemap
- * sync's removal flag was write-only for as long as the code existed: on
- * 2026-09-20 upforge.io's llms.txt — the file handed straight to AI crawlers —
- * was 32% dead URLs, advertising service areas in Atlanta, Detroit and Tampa
- * that the business has never served.
+ * explicitly. A read that forgets serves dead URLs: an llms.txt, the file
+ * handed straight to AI crawlers, ends up advertising pages the business
+ * retired long ago.
  *
  * Null-safe by design: `status` is nullable with an 'active' default, so a row
  * whose status was explicitly nulled stays live rather than vanishing from the
@@ -80,13 +75,12 @@ export declare function matchSitemapEntryRow<T extends SeoPageRowLike>(candidate
  * that belongs to `site`, keeping at most one row per path.
  *
  * Why this exists: a multi-site project (one Sonor project hosting many
- * domains — bd-aec.com plus 48 sibling domains, truepowersystems.com plus its
- * state microsites) holds one row PER HOST for shared paths like `/` and
- * `/terms`. Any project-wide read that dedupes by path alone therefore keeps an
- * ARBITRARY host's row. Observed 2026-08-25: bd-aec.com's llms.txt described
- * `/` with soqwriters.com's homepage copy and `/terms` with bd-charlotte.com's,
- * and which sibling won changed every time a neighbour rebuilt, because the tie
- * among same-path rows is broken by whatever order Postgres returns.
+ * domains, e.g. example.com plus dozens of city microsites) holds one row PER
+ * HOST for shared paths like `/` and `/terms`. Any project-wide read that
+ * dedupes by path alone therefore keeps an ARBITRARY host's row: example.com's
+ * llms.txt can describe `/` with a sibling's homepage copy, and which sibling
+ * wins changes every time a neighbour rebuilds, because the tie among
+ * same-path rows is broken by whatever order Postgres returns.
  *
  * Rules, per path, via `matchSitemapEntryRow`:
  *  - this host's row wins outright

package/dist/site-cache.d.ts

@@ -2,11 +2,11 @@
  * How Sonor refreshes a site's cached pages when content changes.
  *
  * A site serves cached pages and caches every fetch from Sonor. When someone
- * edits content in Sonor, sonor-api POSTs the paths and cache tags that
+ * edits content in Sonor, Sonor POSTs the paths and cache tags that
  * changed to the site's revalidation route, authenticated with the project's
  * API key, and the site regenerates just those. site-kit tags its fetches with
  * these names and serves the route (`@sonordev/site-kit/revalidate`);
- * sonor-api sends them. Single source of truth for the names on both sides:
+ * Sonor sends them. Single source of truth for the names on both sides:
  * never spell a tag as a string literal in either.
  */
 /** Where the revalidation route lives on every site. */
@@ -29,7 +29,7 @@ export declare const SITE_CACHE_TAGS: {
     readonly portfolio: 'portfolio';
 };
 export type SiteCacheTag = (typeof SITE_CACHE_TAGS)[keyof typeof SITE_CACHE_TAGS];
-/** The body sonor-api POSTs to the revalidation route. */
+/** The body Sonor POSTs to the revalidation route. */
 export interface SiteRevalidatePayload {
     /** Local paths to regenerate, e.g. `['/services/roofing']`. */
     paths?: string[];
@@ -39,7 +39,7 @@ export interface SiteRevalidatePayload {
     revalidateAll?: boolean;
     /**
      * Only check that the route is installed and the key matches; nothing is
-     * regenerated. sonor-api pings after it registers a site's route, so it
+     * regenerated. Sonor pings after it registers a site's route, so it
      * knows whether an edit goes live in seconds or waits for the cache to age out.
      */
     ping?: boolean;

package/dist/sites-normalize.d.ts

@@ -14,9 +14,7 @@
  * pushed those entries over their bundle budgets.
  *
  * `./sites` re-exports this, so `@sonordev/contracts/sites` (and site-kit's
- * `sites/contract`) carry it too. The Nest APIs import it from there
- * (sonor-api `src/common/utils/site-host.ts`, signal-api
- * `src/shared/utils/seo-page-pick.util.ts`).
+ * `sites/contract`) carry it too. The Sonor APIs import it from there.
  *
  * Pure string logic only (no Node built-ins) so it is safe in the browser.
  */
@@ -24,7 +22,7 @@
  * normalizeSiteHost — canonical normalizer for a sub-site host value before it
  * is persisted or used as a filter.
  *
- *   `https://OhioPowerStudies.com:3000/path` → `ohiopowerstudies.com`
+ *   `https://Ohio.Example.com:3000/path` → `ohio.example.com`
  *
  * Lowercases, strips protocol, keeps host only (drops path + query), strips
  * port (rollups span dev/prod) and the FQDN root dot. Returns null for

package/dist/sites.d.ts

@@ -2,10 +2,8 @@
  * @sonordev/contracts/sites — Multi-site "site" dimension host contract (v1)
  *
  * Single source of truth for normalizing and comparing sub-site host values
- * (the multi-site `site` dimension, see CLAUDE.md). site-kit, sonor-api
- * (`src/common/utils/site-host.ts`) and signal-api
- * (`src/shared/utils/seo-page-pick.util.ts`) all import it, so there's no
- * copy to drift.
+ * (the multi-site `site` dimension). site-kit and both Sonor APIs import it,
+ * so there's no copy to drift.
  *
  * Pure string logic only (no Node built-ins) so it is safe in the browser:
  * site-kit itself normalizes `__SITE_KIT_SITE__` with `normalizeSiteHost`.
@@ -28,7 +26,7 @@ export declare function stripWww(host: string): string;
  */
 export declare function sameSite(a: string | null | undefined, b: string | null | undefined): boolean;
 /**
- * Host of a full URL ("https://ohiopowerstudies.com/x" → "ohiopowerstudies.com"),
+ * Host of a full URL ("https://ohio.example.com/x" → "ohio.example.com"),
  * null for site-relative paths ("/services") and unparseable input.
  */
 export declare function hostFromUrl(value: string | null | undefined): string | null;

package/dist/slot-content.d.ts

@@ -4,7 +4,7 @@
  * The pure half of the slots contract: content types, value validation
  * (normalizeSlotValue), safe links, and the rich-text subset parser. No
  * crypto, so the dashboard can import it in the browser to validate and
- * preview exactly what sonor-api will accept and site-kit will render.
+ * preview exactly what the Sonor API will accept and site-kit will render.
  * `@sonordev/contracts/slots` re-exports all of it next to the signing.
  */
 /**
@@ -66,7 +66,7 @@ export type SlotValueResult = {
 /**
  * Validate and normalize what an editor (or Signal) submits for a slot of
  * `type`, returning the canonical `content` + `value` to store and sign.
- * The single rule for "what a valid slot of this type is": sonor-api runs it
+ * The single rule for "what a valid slot of this type is": the Sonor API runs it
  * on every write and verifySlotContent re-runs it on every read.
  */
 export declare function normalizeSlotValue(type: SlotContentType, input: {

package/dist/slots.d.ts

@@ -3,23 +3,23 @@
  *
  * Single source of truth for the slot payload shape, value validation, the
  * rich-text subset, and content signing, shared by site-kit (verify + render),
- * sonor-api (validate + sign) and the dashboard (preview). Node only: it signs
+ * the Sonor API (validate + sign) and the dashboard (preview). Node only: it signs
  * with `crypto`.
  *
  * Security model: every SlotContent is HMAC-signed with the project API key.
  * site-kit verifies before rendering and falls back to the developer's static
  * content on any mismatch, so platform-originated content carries provenance
- * end to end. See docs/SITE-KIT-3.0-SPEC-SLOTS.md and docs/WEBSITE-CMS.md.
+ * end to end.
  *
  * v1 (site-kit ≤ 7.0) is plain text only. v2 adds rich text, links and lists,
- * and signs the structured value too. sonor-api serves both: a v1 request gets
+ * and signs the structured value too. Sonor serves both: a v1 request gets
  * text slots signed the v1 way and null for everything else.
  */
 import { type SlotContentType, type SlotValue } from './slot-content';
 export * from './slot-content';
 /** The version this package speaks. Bump on breaking payload changes. */
 export declare const SLOTS_CONTRACT_VERSION = 2;
-/** Versions sonor-api still serves. */
+/** Versions Sonor still serves. */
 export declare const SUPPORTED_SLOTS_CONTRACT_VERSIONS: readonly number[];
 export interface SlotContent {
     slot_id: string;
@@ -63,7 +63,7 @@ export interface SlotResolveRequestEntry {
 export interface SlotsResolveRequest {
     contract_version: number;
     slots: SlotResolveRequestEntry[];
-    /** Multi-site sub-dimension: normalized lowercase host (see CLAUDE.md "site" convention). */
+    /** Multi-site sub-dimension: normalized lowercase host. */
     site?: string;
 }
 export interface SlotsResolveResponse {
@@ -83,7 +83,7 @@ type Signable = Pick<SlotContent, 'slot_id' | 'type' | 'content'> & {
  */
 export declare function slotSigningPayload(content: Signable, version?: number): string;
 /**
- * Sign slot content with the project API key (sonor-api side).
+ * Sign slot content with the project API key (Sonor's side).
  * Returns the hex HMAC-SHA256 signature.
  */
 export declare function signSlotContent(content: Signable, apiKey: string, version?: number): string;

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/dist/website.d.ts

@@ -5,14 +5,14 @@
  * SINGLE SOURCE OF TRUTH shared by every side of the Website module's popups:
  *  - the site (site-kit measures its own rendered design and reports it,
  *    publishes it as `--sk-site-*` CSS variables, and renders popup blocks),
- *  - sonor-api (validates the design report and every popup write with these
+ *  - the Sonor API (validates the design report and every popup write with these
  *    normalizers, so a popup can't be saved in a shape the site can't draw),
  *  - the dashboard (the builder's preview reads the same tokens through the
  *    same CSS-variable mapping, so it looks like the site),
  *  - Signal's agents (the block shapes an MCP `propose_site_popup` sends).
  *
  * All four import it: site-kit as `@sonordev/site-kit/website/contract`,
- * sonor-api and the dashboard as `@sonordev/contracts/website`.
+ * the API and the dashboard as `@sonordev/contracts/website`.
  *
  * Why popups carry blocks and the site carries tokens: a popup should look
  * like the site it's on. It says WHAT (a heading, some formatted text, an

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.1",
+  "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": {