@sonordev/contracts 2.8.0 → 2.9.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 2.9.0
+
+A minor release: three new entries, `@sonordev/contracts/page-titles`, `@sonordev/contracts/broadcast-layouts` and `@sonordev/contracts/publication-branding`. Every other entry is unchanged.
+
+- **New entry `@sonordev/contracts/page-titles`**: what a page is called when a list, a sitemap or a case study needs its own name and not its whole title, so every one of them reads the same.
+  - `titleHead(title)` returns the title without its trailing " | Brand". Stray pipes are repaired first (a run of pipes with only whitespace between them is one separator, and a leading or trailing pipe is dropped), then only the last " | " segment goes, using `seo-meta`'s `stripTitleSuffix`. "Roof Repair | | Example Roofing" is "Roof Repair".
+  - `slugLabel(input)` makes a readable label from a slug, a file name or a path when a page has no title: "ac-replacement" is "AC Replacement", "faq" is "FAQ", "smith-and-smith" is "Smith and Smith", "homes-in-ky" is "Homes in KY". It knows acronyms, US state codes, small words and part numbers, and never throws on a malformed %-escape. "mt" is read by position: last it's Montana ("billings-mt" is "Billings MT"), and before another word it's Mount ("mt-adams" is "Mt Adams").
+  - `isRoutePlaceholder(value)` says whether a value, or any "/"-separated segment of it, is a route placeholder such as `:slug`, `[slug]` or `[[...rest]]`, so a page's pattern never ends up as its name.
+- **New entry `@sonordev/contracts/broadcast-layouts`**: which Broadcast card compositions are drawn, and what a retired one draws as, so the API, its agents and the dashboard can't disagree.
+  - `CARD_LAYOUTS` is every layout ID a stored row may carry (`stacked`, `headline`, `split`, `anchor`) and `ARTICLE_COVER_LAYOUTS` is the two that are drawn: centered `headline` and low `anchor`. Nothing is top-aligned.
+  - `RETIRED_CARD_LAYOUTS` and `normalizeArticleCoverLayout` draw a stored `stacked` as `anchor` and `split` as `headline`. `isCardLayoutId`, `isArticleCoverLayoutId` and `isRetiredCardLayoutId` are the checks, and `CARD_LAYOUT_LABELS` and `CARD_LAYOUT_OPTIONS` the names.
+  - `PUBLICATION_CARD_LAYOUTS` is what a publication-branding change may choose and `SAVED_PUBLICATION_CARD_LAYOUTS` what a saved profile may still carry.
+  - `BROADCAST_STYLES` lists the shared Broadcast looks.
+  - `REVIEW_CARD_VARIATIONS` (Signature and Framed), `normalizeReviewCardVariation` (a retired `spotlight` draws as Signature) and `reviewCardVariationFromDigest`, which draws each review's composition from the SHA-256 of `reviewCompositionSeed(projectId, reviewId)` so it never moves.
+- **New entry `@sonordev/contracts/publication-branding`**: what a project's publication branding may hold and what a change may set.
+  - `createPublicationBrandingValidator({ isBlockedHost })` returns `validatePublicationBranding`, `validatePublicationBrandingPatch` and `mergePublicationBrandingPatch`, bound to the caller's own private-address guard. A change may only choose a card layout that's drawn today; a saved profile still reads a retired one.
+  - `PublicationBrandingValidationError` names the refused field.
+  - The editorial charter (`parsePublicationCharter`, `parseSiteCharters`, `publicationCharterFor`, `publicationCharterContext`), `safeFontStack`, `containsControlCharacters` and `EMAIL_SAFE_FONTS`, plus the profile's types, platforms and field lists.
+
 ## 2.8.0
 
 A minor release: two new entries, `@sonordev/contracts/business-claims` and `@sonordev/contracts/outreach`. Every other entry is unchanged.

package/README.md

@@ -34,6 +34,9 @@ pnpm add @sonordev/contracts
 | `@sonordev/contracts/knowledge` | Which Sonor records Signal reads into a project's knowledge, the address each one's knowledge is stored under (`portfolio://<id>`), and the limits of the call that tells Signal a site's pages changed | the Sonor API sends those calls and Signal answers them |
 | `@sonordev/contracts/business-claims` | What an outbound email or text may say about a business (`checkOutboundCopy`), the stored review of what it claimed and when that review is settled, and whether a sent email arrived intact (`readBackVerdict`) | the Sonor API checks again on the bytes it sends, Signal checks what its writers and agents file |
 | `@sonordev/contracts/outreach` | What a segment of outreach is (pitch, sending mailbox, prospect industry), who may turn one on, what a turned-on segment covers, and what a drip's ledger row means for its lead | Signal writes and reads segment grants, the Sonor API checks the same grant before it sends |
+| `@sonordev/contracts/page-titles` | A page's own name: its title without the brand (`titleHead`), a readable label from a slug (`slugLabel`), and whether a value is a route placeholder like `:slug` (`isRoutePlaceholder`) | Signal's site-architecture writer, the agency site kit's portfolio components |
+| `@sonordev/contracts/broadcast-layouts` | Which Broadcast card layouts are drawn (centered `headline`, low `anchor`), which retired IDs still read and what each draws as (`normalizeArticleCoverLayout`), the Broadcast styles, and the review compositions with the frozen draw that gives each review its own (`reviewCardVariationFromDigest`) | the Sonor API's card renderers and settings, Signal's agent tools, the dashboard's pickers |
+| `@sonordev/contracts/publication-branding` | What a publication's branding may hold and what a change may set (`createPublicationBrandingValidator`), how a change merges, the editorial charter, and safe font stacks | the Sonor API stores and resolves it, Signal checks an agent's change before filing it, the dashboard edits it |
 
 ## Schema placeholders
 
@@ -541,6 +544,195 @@ so they can't disagree about what a person turned on.
 `OUTREACH_CONTRACT_VERSION` is bumped when a grant's shape or the segment key
 changes incompatibly.
 
+## The page-titles contract
+
+A page's title is its own name followed by the brand: "AC Repair | Example
+HVAC". A list of pages, a sitemap or a case study wants the name alone, and
+the usual shortcuts get it wrong. Capitalizing each word of a slug turns
+"ac-replacement" into "Ac Replacement", "faq" into "Faq" and
+"smith-and-smith" into "Smith And Smith". A title with a stray second pipe
+ships as "Loans | | Brand". `titleHead`, `slugLabel` and `isRoutePlaceholder`
+are the one set of rules, so every list reads the same.
+
+```ts
+import { isRoutePlaceholder, slugLabel, titleHead } from '@sonordev/contracts/page-titles'
+
+titleHead('FHA Home Loans | | Example Mortgage') // 'FHA Home Loans'
+slugLabel('/services/hvac-repair/')              // 'HVAC Repair'
+isRoutePlaceholder('/floor-plans/:slug')         // true
+```
+
+- **`titleHead(title)`** is the title without its trailing " | Brand". Only
+  the last " | " segment is the brand, so "1 Bedroom | 1BR 1BA | Example
+  Apartments" is "1 Bedroom | 1BR 1BA". The cut is the one `seo-meta`'s
+  `stripTitleSuffix` makes.
+- **Stray pipes are repaired first.** A run of pipes with only whitespace
+  between them is one separator ("Roof Repair | | Example Roofing" reads as
+  "Roof Repair | Example Roofing"), and a leading or trailing pipe is dropped
+  ("Pricing |" is "Pricing"). Whitespace is trimmed and collapsed.
+- **No separator, no cut.** A title without one comes back as written. It
+  can't tell a brand from a name, so a title that's only a brand stays that
+  brand, and a dash ("AC Repair - Example HVAC") isn't a brand separator.
+  Empty, whitespace-only, `null` and `undefined` input give `""`.
+- **Apply it once.** A title with two or more separators loses one segment
+  per call, so the output of `titleHead` isn't a title to run it on again.
+- **`slugLabel(input)`** is for the rare label that has to come from a slug,
+  a file name or a path because the page has no title. Prefer `titleHead`:
+  a title is what the page was written with, and a slug is a guess at it.
+- **Which part it reads.** The last non-empty path segment, after dropping a
+  `https://host` origin, a query or a hash, and a trailing `.html`, `.htm`,
+  `.php` or `.aspx`. %-escapes are decoded without ever throwing: a malformed
+  one stays as written. Words split on `-`, `_`, `+` and whitespace.
+- **How each word is cased**, by the first rule that fits:
+  - an acronym is upper case: `ac`, `ai`, `aeo`, `api`, `cms`, `crm`, `faq`,
+    `fsbo`, `hvac`, `jl`, `llc`, `llp`, `mls`, `pdf`, `pllc`, `ppc`, `roi`,
+    `seo`, `ui`, `ux` and `usa`. The plural `faqs` is "FAQs";
+  - a stand-alone two-letter US state or DC code is upper case
+    ("covington-ky" is "Covington KY"). Codes that are ordinary words as
+    often as not stay words: `in`, `or`, `me`, `hi`, `id`, `la`, `ma`, `pa`,
+    `al`, `de` and `co`. `mt` goes by its position: as the last word it's
+    Montana ("billings-mt" is "Billings MT"), and with a word after it it's
+    Mount ("mt-adams" is "Mt Adams", "academy-of-mt-adams" is "Academy of Mt
+    Adams"). `us` isn't a state: "about-us" is "About Us";
+  - a word with a digit keeps its case, and gains a capital only when it
+    starts with a letter: "c1" is "C1", "075ct" and "1003" stay;
+  - a small word is lower case unless it's first: `a`, `an`, `and`, `at`,
+    `by`, `for`, `in`, `of`, `on`, `or`, `the`, `to`, `vs`, `with`;
+  - anything else gets a capital first letter and lower case after it.
+  The first word of a label is always capitalized, and an acronym stays upper
+  case there.
+- **Nothing to label gives `""`.** `""`, `"/"`, `"?x=1"` and a bare origin
+  all give an empty string. Naming the home page is the caller's job.
+- **Stable.** Running a label back through `slugLabel` gives the same label,
+  as long as its words follow the rules above. A brand's own capitalization
+  ("DeWalt") is the exception.
+- **`isRoutePlaceholder(value)`** is true when the value, or any
+  "/"-separated segment of it, is a framework route placeholder: `:slug`,
+  `:Slug`, `:id?`, `[slug]`, `[...rest]` or `[[...rest]]`. A placeholder is a
+  single token with no spaces, so ordinary text that contains a colon or a
+  bracket isn't one ("Update: new hours", "FAQ / [draft] notes"). Nullish and
+  empty values are false.
+
+Known limits. A slug carries no capitalization or punctuation, so "DeWalt"
+reads "Dewalt", "joes-pizza" reads "Joes Pizza", and an `index.html` reads
+"Index". A slug with `mt` anywhere but last reads it as Mount
+("billings-mt-homes" reads "Billings Mt Homes"), since position is all that
+tells Montana from Mount. A bare `[draft]` is a placeholder, because nothing
+tells it from `[slug]`. Only the pipe is a brand separator, the way
+`stripTitleSuffix` has it.
+
+## The broadcast-layouts contract
+
+A Broadcast post is centered or low, never top-aligned. The title-on-top
+composition was retired, but posts and settings saved before that still name
+it, so there are two lists: every ID a stored row may carry, and the IDs
+that are drawn. A retired ID keeps validating and draws as its replacement.
+
+```ts
+import { createHash } from 'node:crypto'
+import {
+  ARTICLE_COVER_LAYOUTS, CARD_LAYOUTS, isCardLayoutId, normalizeArticleCoverLayout,
+  normalizeReviewCardVariation, reviewCardVariationFromDigest, reviewCompositionSeed,
+} from '@sonordev/contracts/broadcast-layouts'
+
+CARD_LAYOUTS                                // ['stacked', 'headline', 'split', 'anchor']
+ARTICLE_COVER_LAYOUTS                       // ['headline', 'anchor']
+isCardLayoutId('stacked')                   // true: an old post still reads
+normalizeArticleCoverLayout('stacked')      // 'anchor'
+normalizeArticleCoverLayout('split')        // 'headline'
+normalizeReviewCardVariation('spotlight')   // 'signature'
+
+// On the server: a review's composition, stable for its identity.
+const digest = createHash('sha256').update(reviewCompositionSeed(projectId, reviewId)).digest()
+reviewCardVariationFromDigest(digest)       // 'signature' or 'frame'
+```
+
+- **`CARD_LAYOUTS`** is every layout ID a stored row, a saved setting or a
+  request may carry, retired ones included. **`ARTICLE_COVER_LAYOUTS`** is
+  what's drawn and offered. Both orders are part of the contract: rotation
+  picks by index, and a refusal lists the IDs in order.
+- **`RETIRED_CARD_LAYOUTS`** maps each retired ID to what it draws as
+  (`stacked` to `anchor`, `split` to `headline`).
+  **`normalizeArticleCoverLayout`** applies it and returns anything else as
+  it came, so a caller still checks `isCardLayoutId` (or passes `auto`)
+  before rendering. Only an own key of the map is retired, so `"toString"`
+  isn't.
+- **`CARD_LAYOUT_LABELS`** names the drawn layouts and
+  **`CARD_LAYOUT_OPTIONS`** serves them Anchor first.
+- **`PUBLICATION_CARD_LAYOUTS`** is what a publication-branding change may
+  choose (`auto` or a drawn layout). **`SAVED_PUBLICATION_CARD_LAYOUTS`** is
+  what a saved profile may carry (`auto` or any readable ID).
+- **`BROADCAST_STYLES`** is the shared look for article, review and generated
+  post artwork (`glass` by default).
+- **`REVIEW_CARD_VARIATIONS`** is the review compositions drawn, Signature
+  and Framed. **`normalizeReviewCardVariation`** draws a retired `spotlight`
+  as Signature and anything unknown as the default, Signature.
+  **`isReviewCardVariation`** is the strict check for a request that must
+  name a drawn one.
+- **A review's composition never moves.** It's drawn from the SHA-256 of
+  `reviewCompositionSeed(projectId, reviewId)`, never from anything a person
+  can edit. `reviewCardVariationFromDigest` reads the first four bytes
+  against the frozen v1 list (`REVIEW_CARD_VARIATION_V1_DRAW`); a review that
+  drew the retired Spotlight redraws between the drawn two from the next four
+  bytes, so no other review changes. The hash stays with the caller, so the
+  contract needs no `crypto`.
+
+Changing a list's order or the v1 draw list reshuffles stored posts, so treat
+both as a breaking change and bump `BROADCAST_LAYOUTS_CONTRACT_VERSION`.
+
+## The publication-branding contract
+
+A project's publication branding is one stored profile: identity (names,
+publisher, logos), colors, type, editorial direction (the Broadcast style,
+the card layout, the charter) and newsletter settings, each of which a
+channel (email, social, a single network) can override. The API that saves it
+and the agent tools that propose changes to it have to agree exactly on what's
+valid, so the validator lives here once.
+
+```ts
+import { createPublicationBrandingValidator } from '@sonordev/contracts/publication-branding'
+
+// Bind it once, to the server's own private-address guard.
+const branding = createPublicationBrandingValidator({ isBlockedHost })
+
+branding.validatePublicationBrandingPatch({ colors: { primary: '#ABC' } })
+// { colors: { primary: '#aabbcc' } }
+branding.validatePublicationBrandingPatch({ editorial: { cardLayout: 'stacked' } })
+// throws: publication_branding.editorial.cardLayout: choose auto, headline, anchor
+branding.mergePublicationBrandingPatch(saved, { identity: { logos: { dark: null } } })
+// saved, minus that one override
+```
+
+- **`createPublicationBrandingValidator({ isBlockedHost })`** returns the
+  validator. A URL leaf must be a public HTTPS URL without credentials;
+  whether its host is private (loopback, a LAN range, link-local,
+  `localhost`) is the caller's guard, because that check needs Node. It gets
+  `new URL(value).hostname`, so IPv6 keeps its brackets.
+- **`validatePublicationBranding`** reads a whole saved profile.
+  **`validatePublicationBrandingPatch`** reads a change: a leaf set to `null`
+  clears that override, and a card layout must be one that's drawn today.
+  A saved profile may still name a retired layout.
+- **`mergePublicationBrandingPatch(saved, change)`** applies a change leaf by
+  leaf and prunes containers it empties. No saved profile reads as
+  `{ version: 1 }`, and a change that sets nothing returns the profile as it
+  was. **`mergePublicationBrandingLayers`** is the same leaf-wise merge for
+  resolving layers.
+- **Refusals name the field.** A `PublicationBrandingValidationError` carries
+  the path (`publication_branding.platforms.email.colors.primary`) and says
+  what's allowed. A charter set on a channel override is a plain `Error`: a
+  charter belongs to the publication or a site.
+- **The editorial charter** (`parsePublicationCharter`, `parseSiteCharters`,
+  `publicationCharterFor`, `publicationCharterContext`) is data-only
+  direction: who the publication is for, what they're deciding, the proof it
+  holds itself to. It's never evidence of expertise.
+- **`safeFontStack`** keeps a font stack as data ("'Brand Display',serif"),
+  never a stylesheet fragment, and `EMAIL_SAFE_FONTS` is what an email
+  fallback may name.
+
+The stored shape's version is `PUBLICATION_BRANDING_VERSION`. Resolving a
+profile against a project's own colors and its measured site design stays in
+the Sonor API.
+
 ## Why it exists
 
 A rule that lives in several copies is how two of them end up disagreeing.

package/dist/broadcast-layouts.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Broadcast layouts: which compositions a Broadcast card draws, which retired
+ * IDs stay readable and what each one draws as, the Broadcast styles, and the
+ * review card variations with the frozen draw that gives each review its
+ * composition. Sonor's APIs and dashboard import it as
+ * `@sonordev/contracts/broadcast-layouts`.
+ *
+ * Why it exists: a post is centered (`headline`) or low (`anchor`), never
+ * top-aligned. Retiring the top-aligned compositions meant changing the same
+ * lists in three places (the Sonor API, Signal and the dashboard), and any one
+ * of them drifting would let an old ID reach a renderer or a picker. So the
+ * IDs, the retired-to-drawn map, the normalizers, the labels and the review
+ * draw live here once.
+ *
+ * Two lists, on purpose:
+ *  - CARD_LAYOUTS is every ID a stored row, a saved setting or a request may
+ *    carry. Retired IDs stay in it so old rows keep validating; they're
+ *    normalized on the way to a renderer.
+ *  - ARTICLE_COVER_LAYOUTS is what's drawn and offered. Nothing else is.
+ * Both orders are visible (rotation order and refusal messages), so they're
+ * part of the contract.
+ *
+ * Pure: no I/O, no Node built-ins. The review draw takes the SHA-256 digest
+ * of reviewCompositionSeed, which the caller hashes, so the hash stays with
+ * the server.
+ */
+/** Bumped when a stored ID here changes meaning. */
+export declare const BROADCAST_LAYOUTS_CONTRACT_VERSION = 1;
+/**
+ * Every composition ID a stored row, a saved setting or a request may carry.
+ *
+ * - `headline`: centered, the title set large.
+ * - `anchor`:   the background leads, the title sits low.
+ * - `stacked`:  retired 2026-10-14 (title pinned to the top, art below). Draws as `anchor`.
+ * - `split`:    retired (title and stage in columns). Draws as `headline`.
+ */
+export declare const CARD_LAYOUTS: readonly ['stacked', 'headline', 'split', 'anchor'];
+export type CardLayoutId = (typeof CARD_LAYOUTS)[number];
+/** The compositions Broadcast draws and offers: centered or low. Nothing is top-aligned. */
+export declare const ARTICLE_COVER_LAYOUTS: readonly ['headline', 'anchor'];
+export type ArticleCoverLayoutId = (typeof ARTICLE_COVER_LAYOUTS)[number];
+export type RetiredCardLayoutId = Exclude<CardLayoutId, ArticleCoverLayoutId>;
+/** Each retired layout ID, and the composition it draws as. */
+export declare const RETIRED_CARD_LAYOUTS: Readonly<Record<RetiredCardLayoutId, ArticleCoverLayoutId>>;
+/** A readable layout ID, retired ones included. The check every input boundary uses. */
+export declare const isCardLayoutId: (value: unknown) => value is CardLayoutId;
+/** A layout that's drawn and offered today. */
+export declare const isArticleCoverLayoutId: (value: unknown) => value is ArticleCoverLayoutId;
+/** A retired layout ID (an own key of RETIRED_CARD_LAYOUTS, never an inherited one). */
+export declare const isRetiredCardLayoutId: (value: unknown) => value is RetiredCardLayoutId;
+/**
+ * Which composition a layout ID draws. A retired ID becomes what it draws as;
+ * anything else is returned as it came, so callers check isCardLayoutId (or
+ * pass `auto` through) before rendering. Every renderer reads its layout
+ * through here, so a retired ID never reaches one.
+ */
+export declare function normalizeArticleCoverLayout(layout: CardLayoutId): ArticleCoverLayoutId;
+export declare function normalizeArticleCoverLayout<T>(layout: T): T | ArticleCoverLayoutId;
+/** What each drawn layout is called wherever a person picks one. */
+export declare const CARD_LAYOUT_LABELS: Readonly<Record<ArticleCoverLayoutId, string>>;
+/** The layout choices the API serves to pickers and agents, Anchor first. */
+export declare const CARD_LAYOUT_OPTIONS: ReadonlyArray<{
+    id: ArticleCoverLayoutId;
+    label: string;
+}>;
+/** A publication's card layout when it doesn't pin one: rotate. */
+export declare const AUTO_CARD_LAYOUT: 'auto';
+export type PublicationCardLayout = CardLayoutId | typeof AUTO_CARD_LAYOUT;
+/** What a publication-branding write may choose: rotate, or a drawn layout. */
+export declare const PUBLICATION_CARD_LAYOUTS: readonly ["auto", "headline", "anchor"];
+/** What a saved publication-branding profile may carry: a write's choices plus the retired IDs. */
+export declare const SAVED_PUBLICATION_CARD_LAYOUTS: readonly ["auto", "stacked", "headline", "split", "anchor"];
+/**
+ * The shared Broadcast look for article, review and generated post artwork.
+ * One choice per project (stored as `articleStyle`, its legacy wire name).
+ *
+ * - `glass`:     the background full bleed, the words on a frosted card.
+ * - `editorial`: paper, a serif headline, the image framed like a magazine plate.
+ * - `poster`:    one flat accent field, condensed type, big numbers.
+ * - `cinematic`: the image as a widescreen still over solid ground.
+ * - `blueprint`: a drawing sheet, with a grid, mono labels and a title block.
+ * - `focus`:     real project photos, a dark reading gradient and circular details.
+ */
+export declare const BROADCAST_STYLES: readonly ['glass', 'editorial', 'poster', 'cinematic', 'blueprint', 'focus'];
+export type BroadcastStyleId = (typeof BROADCAST_STYLES)[number];
+export declare const DEFAULT_BROADCAST_STYLE: BroadcastStyleId;
+export declare const isBroadcastStyleId: (value: unknown) => value is BroadcastStyleId;
+/**
+ * The review compositions Broadcast draws: `signature` (photo up top, the
+ * quote low) and `frame` (centered). Order matters: a review whose v1 draw
+ * was retired redraws by index into this list.
+ */
+export declare const REVIEW_CARD_VARIATIONS: readonly ['signature', 'frame'];
+export type ReviewCardVariation = (typeof REVIEW_CARD_VARIATIONS)[number];
+/** A review composition when none is chosen, or an unknown one is asked for. */
+export declare const DEFAULT_REVIEW_CARD_VARIATION: ReviewCardVariation;
+/** Each retired review variation, and what it draws as. `spotlight` pinned the quote to the top; retired 2026-10-14. */
+export declare const RETIRED_REVIEW_CARD_VARIATIONS: Readonly<Record<'spotlight', ReviewCardVariation>>;
+/** What each review variation is called wherever a person picks one. */
+export declare const REVIEW_CARD_VARIATION_LABELS: Readonly<Record<ReviewCardVariation, string>>;
+/** The review variation choices, in REVIEW_CARD_VARIATIONS order. */
+export declare const REVIEW_CARD_VARIATION_OPTIONS: ReadonlyArray<{
+    id: ReviewCardVariation;
+    label: string;
+}>;
+/** A review variation that's drawn today. Strict: a retired one isn't. */
+export declare const isReviewCardVariation: (value: unknown) => value is ReviewCardVariation;
+/**
+ * The review composition to draw for a stored or requested value: a drawn
+ * one as it is, a retired one as what it draws as, anything else (null, '',
+ * an unknown string) as the default.
+ */
+export declare function normalizeReviewCardVariation(value: unknown): ReviewCardVariation;
+/**
+ * The v1 draw list, frozen. A review's composition belongs to its immutable
+ * identity, so changing this list (or its order) would reshuffle every
+ * review's card. New compositions get a new seed version, never an edit here.
+ */
+export declare const REVIEW_CARD_VARIATION_V1_DRAW: readonly ['signature', 'spotlight', 'frame'];
+/**
+ * What a review's composition is drawn from: the project and the review, and
+ * nothing a person can edit (platform, artwork, copy and brand never move it).
+ * Hash this string with SHA-256 and pass the digest to
+ * reviewCardVariationFromDigest.
+ */
+export declare function reviewCompositionSeed(projectId: string, reviewId: string): string;
+/**
+ * The composition a review's digest draws. The first four bytes (big-endian)
+ * pick from the v1 list; a review that drew a retired composition redraws
+ * between the drawn ones from the next four, so no other review moves.
+ * `digest` is the SHA-256 of reviewCompositionSeed (a Node Buffer works).
+ */
+export declare function reviewCardVariationFromDigest(digest: ArrayLike<number>): ReviewCardVariation;

package/dist/broadcast-layouts.js

@@ -0,0 +1,83 @@
+'use strict';
+
+// src/contracts/broadcast-layouts.ts
+var BROADCAST_LAYOUTS_CONTRACT_VERSION = 1;
+var own = (record, key) => typeof key === "string" && Object.prototype.hasOwnProperty.call(record, key);
+var CARD_LAYOUTS = ["stacked", "headline", "split", "anchor"];
+var ARTICLE_COVER_LAYOUTS = ["headline", "anchor"];
+var RETIRED_CARD_LAYOUTS = {
+  stacked: "anchor",
+  split: "headline"
+};
+var isCardLayoutId = (value) => typeof value === "string" && CARD_LAYOUTS.includes(value);
+var isArticleCoverLayoutId = (value) => typeof value === "string" && ARTICLE_COVER_LAYOUTS.includes(value);
+var isRetiredCardLayoutId = (value) => own(RETIRED_CARD_LAYOUTS, value);
+function normalizeArticleCoverLayout(layout) {
+  return isRetiredCardLayoutId(layout) ? RETIRED_CARD_LAYOUTS[layout] : layout;
+}
+var CARD_LAYOUT_LABELS = {
+  headline: "Headline",
+  anchor: "Anchor"
+};
+var CARD_LAYOUT_OPTIONS = [
+  { id: "anchor", label: CARD_LAYOUT_LABELS.anchor },
+  { id: "headline", label: CARD_LAYOUT_LABELS.headline }
+];
+var AUTO_CARD_LAYOUT = "auto";
+var PUBLICATION_CARD_LAYOUTS = [AUTO_CARD_LAYOUT, ...ARTICLE_COVER_LAYOUTS];
+var SAVED_PUBLICATION_CARD_LAYOUTS = [AUTO_CARD_LAYOUT, ...CARD_LAYOUTS];
+var BROADCAST_STYLES = ["glass", "editorial", "poster", "cinematic", "blueprint", "focus"];
+var DEFAULT_BROADCAST_STYLE = "glass";
+var isBroadcastStyleId = (value) => typeof value === "string" && BROADCAST_STYLES.includes(value);
+var REVIEW_CARD_VARIATIONS = ["signature", "frame"];
+var DEFAULT_REVIEW_CARD_VARIATION = "signature";
+var RETIRED_REVIEW_CARD_VARIATIONS = {
+  spotlight: "signature"
+};
+var REVIEW_CARD_VARIATION_LABELS = {
+  signature: "Signature",
+  frame: "Framed"
+};
+var REVIEW_CARD_VARIATION_OPTIONS = REVIEW_CARD_VARIATIONS.map((id) => ({ id, label: REVIEW_CARD_VARIATION_LABELS[id] }));
+var isReviewCardVariation = (value) => typeof value === "string" && REVIEW_CARD_VARIATIONS.includes(value);
+function normalizeReviewCardVariation(value) {
+  if (isReviewCardVariation(value)) return value;
+  return own(RETIRED_REVIEW_CARD_VARIATIONS, value) ? RETIRED_REVIEW_CARD_VARIATIONS[value] : DEFAULT_REVIEW_CARD_VARIATION;
+}
+var REVIEW_CARD_VARIATION_V1_DRAW = ["signature", "spotlight", "frame"];
+function reviewCompositionSeed(projectId, reviewId) {
+  return JSON.stringify(["review-composition-v1", projectId, reviewId]);
+}
+var uint32BE = (bytes, offset) => (bytes[offset] << 24 | bytes[offset + 1] << 16 | bytes[offset + 2] << 8 | bytes[offset + 3]) >>> 0;
+function reviewCardVariationFromDigest(digest) {
+  if (!digest || digest.length < 8) throw new RangeError("A review composition digest needs at least 8 bytes");
+  const drawn = REVIEW_CARD_VARIATION_V1_DRAW[uint32BE(digest, 0) % REVIEW_CARD_VARIATION_V1_DRAW.length];
+  return isReviewCardVariation(drawn) ? drawn : REVIEW_CARD_VARIATIONS[uint32BE(digest, 4) % REVIEW_CARD_VARIATIONS.length];
+}
+
+exports.ARTICLE_COVER_LAYOUTS = ARTICLE_COVER_LAYOUTS;
+exports.AUTO_CARD_LAYOUT = AUTO_CARD_LAYOUT;
+exports.BROADCAST_LAYOUTS_CONTRACT_VERSION = BROADCAST_LAYOUTS_CONTRACT_VERSION;
+exports.BROADCAST_STYLES = BROADCAST_STYLES;
+exports.CARD_LAYOUTS = CARD_LAYOUTS;
+exports.CARD_LAYOUT_LABELS = CARD_LAYOUT_LABELS;
+exports.CARD_LAYOUT_OPTIONS = CARD_LAYOUT_OPTIONS;
+exports.DEFAULT_BROADCAST_STYLE = DEFAULT_BROADCAST_STYLE;
+exports.DEFAULT_REVIEW_CARD_VARIATION = DEFAULT_REVIEW_CARD_VARIATION;
+exports.PUBLICATION_CARD_LAYOUTS = PUBLICATION_CARD_LAYOUTS;
+exports.RETIRED_CARD_LAYOUTS = RETIRED_CARD_LAYOUTS;
+exports.RETIRED_REVIEW_CARD_VARIATIONS = RETIRED_REVIEW_CARD_VARIATIONS;
+exports.REVIEW_CARD_VARIATIONS = REVIEW_CARD_VARIATIONS;
+exports.REVIEW_CARD_VARIATION_LABELS = REVIEW_CARD_VARIATION_LABELS;
+exports.REVIEW_CARD_VARIATION_OPTIONS = REVIEW_CARD_VARIATION_OPTIONS;
+exports.REVIEW_CARD_VARIATION_V1_DRAW = REVIEW_CARD_VARIATION_V1_DRAW;
+exports.SAVED_PUBLICATION_CARD_LAYOUTS = SAVED_PUBLICATION_CARD_LAYOUTS;
+exports.isArticleCoverLayoutId = isArticleCoverLayoutId;
+exports.isBroadcastStyleId = isBroadcastStyleId;
+exports.isCardLayoutId = isCardLayoutId;
+exports.isRetiredCardLayoutId = isRetiredCardLayoutId;
+exports.isReviewCardVariation = isReviewCardVariation;
+exports.normalizeArticleCoverLayout = normalizeArticleCoverLayout;
+exports.normalizeReviewCardVariation = normalizeReviewCardVariation;
+exports.reviewCardVariationFromDigest = reviewCardVariationFromDigest;
+exports.reviewCompositionSeed = reviewCompositionSeed;

package/dist/broadcast-layouts.mjs

@@ -0,0 +1,56 @@
+// src/contracts/broadcast-layouts.ts
+var BROADCAST_LAYOUTS_CONTRACT_VERSION = 1;
+var own = (record, key) => typeof key === "string" && Object.prototype.hasOwnProperty.call(record, key);
+var CARD_LAYOUTS = ["stacked", "headline", "split", "anchor"];
+var ARTICLE_COVER_LAYOUTS = ["headline", "anchor"];
+var RETIRED_CARD_LAYOUTS = {
+  stacked: "anchor",
+  split: "headline"
+};
+var isCardLayoutId = (value) => typeof value === "string" && CARD_LAYOUTS.includes(value);
+var isArticleCoverLayoutId = (value) => typeof value === "string" && ARTICLE_COVER_LAYOUTS.includes(value);
+var isRetiredCardLayoutId = (value) => own(RETIRED_CARD_LAYOUTS, value);
+function normalizeArticleCoverLayout(layout) {
+  return isRetiredCardLayoutId(layout) ? RETIRED_CARD_LAYOUTS[layout] : layout;
+}
+var CARD_LAYOUT_LABELS = {
+  headline: "Headline",
+  anchor: "Anchor"
+};
+var CARD_LAYOUT_OPTIONS = [
+  { id: "anchor", label: CARD_LAYOUT_LABELS.anchor },
+  { id: "headline", label: CARD_LAYOUT_LABELS.headline }
+];
+var AUTO_CARD_LAYOUT = "auto";
+var PUBLICATION_CARD_LAYOUTS = [AUTO_CARD_LAYOUT, ...ARTICLE_COVER_LAYOUTS];
+var SAVED_PUBLICATION_CARD_LAYOUTS = [AUTO_CARD_LAYOUT, ...CARD_LAYOUTS];
+var BROADCAST_STYLES = ["glass", "editorial", "poster", "cinematic", "blueprint", "focus"];
+var DEFAULT_BROADCAST_STYLE = "glass";
+var isBroadcastStyleId = (value) => typeof value === "string" && BROADCAST_STYLES.includes(value);
+var REVIEW_CARD_VARIATIONS = ["signature", "frame"];
+var DEFAULT_REVIEW_CARD_VARIATION = "signature";
+var RETIRED_REVIEW_CARD_VARIATIONS = {
+  spotlight: "signature"
+};
+var REVIEW_CARD_VARIATION_LABELS = {
+  signature: "Signature",
+  frame: "Framed"
+};
+var REVIEW_CARD_VARIATION_OPTIONS = REVIEW_CARD_VARIATIONS.map((id) => ({ id, label: REVIEW_CARD_VARIATION_LABELS[id] }));
+var isReviewCardVariation = (value) => typeof value === "string" && REVIEW_CARD_VARIATIONS.includes(value);
+function normalizeReviewCardVariation(value) {
+  if (isReviewCardVariation(value)) return value;
+  return own(RETIRED_REVIEW_CARD_VARIATIONS, value) ? RETIRED_REVIEW_CARD_VARIATIONS[value] : DEFAULT_REVIEW_CARD_VARIATION;
+}
+var REVIEW_CARD_VARIATION_V1_DRAW = ["signature", "spotlight", "frame"];
+function reviewCompositionSeed(projectId, reviewId) {
+  return JSON.stringify(["review-composition-v1", projectId, reviewId]);
+}
+var uint32BE = (bytes, offset) => (bytes[offset] << 24 | bytes[offset + 1] << 16 | bytes[offset + 2] << 8 | bytes[offset + 3]) >>> 0;
+function reviewCardVariationFromDigest(digest) {
+  if (!digest || digest.length < 8) throw new RangeError("A review composition digest needs at least 8 bytes");
+  const drawn = REVIEW_CARD_VARIATION_V1_DRAW[uint32BE(digest, 0) % REVIEW_CARD_VARIATION_V1_DRAW.length];
+  return isReviewCardVariation(drawn) ? drawn : REVIEW_CARD_VARIATIONS[uint32BE(digest, 4) % REVIEW_CARD_VARIATIONS.length];
+}
+
+export { ARTICLE_COVER_LAYOUTS, AUTO_CARD_LAYOUT, BROADCAST_LAYOUTS_CONTRACT_VERSION, BROADCAST_STYLES, CARD_LAYOUTS, CARD_LAYOUT_LABELS, CARD_LAYOUT_OPTIONS, DEFAULT_BROADCAST_STYLE, DEFAULT_REVIEW_CARD_VARIATION, PUBLICATION_CARD_LAYOUTS, RETIRED_CARD_LAYOUTS, RETIRED_REVIEW_CARD_VARIATIONS, REVIEW_CARD_VARIATIONS, REVIEW_CARD_VARIATION_LABELS, REVIEW_CARD_VARIATION_OPTIONS, REVIEW_CARD_VARIATION_V1_DRAW, SAVED_PUBLICATION_CARD_LAYOUTS, isArticleCoverLayoutId, isBroadcastStyleId, isCardLayoutId, isRetiredCardLayoutId, isReviewCardVariation, normalizeArticleCoverLayout, normalizeReviewCardVariation, reviewCardVariationFromDigest, reviewCompositionSeed };

package/dist/page-titles.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Page-titles contract: what a page is called when a list, a sitemap or a
+ * case study needs its own name and not its whole <title>. The Sonor APIs and
+ * the agency site kit import it as `@sonordev/contracts/page-titles`.
+ *
+ * Why it exists: three places each turned a stored title or a URL slug into a
+ * label with their own logic, and they disagreed. "ac-replacement" became "Ac
+ * Replacement", "faq" became "Faq", "smith-and-smith" became "Smith And
+ * Smith", and a title with a stray second pipe shipped as "Loans | | Brand".
+ * There's one rule now:
+ *
+ *  - `titleHead` is the page's own name: the title without its trailing
+ *    " | Brand" segment. Prefer it. A page's title is the label it was
+ *    written with, so it beats anything guessed from a URL.
+ *  - `slugLabel` is for the rare case a label has to come from a slug, a file
+ *    name or a path, because the page has no title at all.
+ *  - `isRoutePlaceholder` says whether a value is a framework route
+ *    placeholder (":slug", "[slug]", "[...rest]") and not a page's name.
+ *
+ * Pure string logic: no I/O, no Node built-ins. The brand split is
+ * seo-meta's `stripTitleSuffix`, imported, never copied: only the LAST
+ * " | " segment of a title is its brand.
+ */
+/**
+ * The page's own name: the title without its trailing " | Brand" segment.
+ *
+ * Whitespace is collapsed first. Stray pipes are repaired before the brand is
+ * cut, so "Loans | | Brand" reads as "Loans | Brand" (a run of pipes with
+ * only whitespace between them is one separator) and a leading or trailing
+ * pipe is dropped ("Pricing |" is "Pricing"). Then the last " | " segment is
+ * the brand and goes; anything before it stays, pipes and all:
+ * "1 Bedroom | 1BR 1BA | Example Apartments" is "1 Bedroom | 1BR 1BA".
+ *
+ * Apply it once to a stored title. A title with two or more separators
+ * loses one segment per call, so its own output isn't a fixed point.
+ *
+ * A title with no separator comes back as written (trimmed): this can't tell
+ * a brand from a name, so a title that's only a brand stays that brand.
+ * Empty, whitespace-only, non-string, null and undefined input give "".
+ */
+export declare function titleHead(title: string | null | undefined): string;
+/**
+ * A readable label for a slug, a file name or a path: "ac-replacement" is
+ * "AC Replacement", "/services/hvac-repair/" is "HVAC Repair".
+ *
+ * Reach for it only when the page has no title (`titleHead` is the page's own
+ * name). It reads the last non-empty path segment of the input, after
+ * dropping a "https://host" origin, a query or a hash, and decodes %-escapes
+ * without ever throwing. A trailing .html, .htm, .php or .aspx is dropped. The
+ * words split on "-", "_", "+" and whitespace.
+ *
+ * Each word is cased by the first rule that fits:
+ *  - an acronym is upper case ("ac", "ai", "cms", "faq", "hvac", "seo",
+ *    "llc", "mls", ...), and "faqs" is "FAQs";
+ *  - a two-letter US state or DC code is upper case ("ky" is "KY"), apart
+ *    from the codes that are ordinary words as often as not ("in", "or",
+ *    "me", "hi", "id", "la", "ma", "pa", "al", "de", "co"). "mt" goes by its
+ *    position: last, it's Montana ("billings-mt" is "Billings MT"); with a
+ *    word after it, it's Mount ("mt-adams" is "Mt Adams"). "us" isn't a
+ *    state: "about-us" is "About Us";
+ *  - a word with a digit keeps its case and only gains a leading capital
+ *    when it starts with a letter ("c1" is "C1", "075ct" stays);
+ *  - a small word ("a", "an", "and", "at", "by", "for", "in", "of", "on",
+ *    "or", "the", "to", "vs", "with") is lower case, unless it's first;
+ *  - anything else is capitalized with the rest lower case.
+ *
+ * Nothing left to label ("", "/", "?x=1") gives "". The home page is the
+ * caller's to name. A label isn't a title: "index" isn't special-cased,
+ * and a brand's own capitalization ("DeWalt") isn't recoverable from a slug.
+ */
+export declare function slugLabel(input: string): string;
+/**
+ * True when the value, or any "/"-separated segment of it, is a framework
+ * route placeholder: a page's pattern leaked into its name ("/floor-plans/:slug",
+ * ":Slug", "[...rest]"). A placeholder is one token with no spaces, so
+ * ordinary text that contains a colon or a bracket isn't one ("Update: new
+ * hours", "FAQ / [draft] notes"). Nullish, empty and non-string values are
+ * false.
+ */
+export declare function isRoutePlaceholder(value: string | null | undefined): boolean;