@sonordev/contracts 2.8.0 → 2.10.0

package/dist/page-titles.d.ts

@@ -0,0 +1,140 @@
+/**
+ * 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.
+ *  - `isPageAddress` says whether a value is a page's address (a path, a
+ *    URL, a route pattern, or the page's own path without its slashes) and
+ *    not its name. It's the one "is this title really a path" rule, so the
+ *    writer of a page list and the reader that prints it can't disagree.
+ *  - `isPageName` says whether a stored title is a name: something is left
+ *    once the pipes are set aside, and no piece between them is an address.
+ *    It's the one rule for a title that gets printed whole, so the writer
+ *    that stores a name and the reader that prints it can't disagree about
+ *    a path, a URL or a placeholder behind a pipe.
+ *
+ * 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;
+/**
+ * Whether `value` is a page's address and not its name: what a page's title
+ * becomes when nothing better was stored (the old sitemap writers saved the
+ * path there), or a pattern that leaked out of the router. True for:
+ *
+ *  - a path, or anything starting with a slash ("/services/ac-repair",
+ *    "//example.com/services");
+ *  - an absolute URL ("https://example.com/services");
+ *  - a host and a path with no scheme ("example.com/services");
+ *  - a route placeholder, as `isRoutePlaceholder` reads it ("/floor-plans/:slug",
+ *    ":Slug", "[slug]");
+ *  - the page's own path written without its slashes. Given `path`, the
+ *    comparison drops leading and trailing slashes from both sides, so for
+ *    "/services/ac-repair" the values "services/ac-repair" and
+ *    "services/ac-repair/" are the address, and for "/faq" the value "faq" is.
+ *    It compares the whole path and it's case-sensitive: "ac-repair" isn't
+ *    the address of "/services/ac-repair", and "Pricing" for "/pricing" is a
+ *    name where "pricing" is the path.
+ *
+ * The value is trimmed first. Empty, whitespace-only, nullish and non-string
+ * values give false: they aren't an address, they're nothing, and the caller
+ * decides what an empty title means. `path` is optional; without it only the
+ * checks that don't need the page's own path run.
+ *
+ * It judges one string. A title with a " | Brand" tail is `titleHead`'s to
+ * cut, and the caller asks about the head: `isPageAddress(titleHead(title), path)`.
+ * Pure string logic, linear in the length of the input.
+ */
+export declare function isPageAddress(value: string | null | undefined, path?: string | null): boolean;
+/**
+ * Whether a stored title is a real name for the page at `path`: something is
+ * left once the pipes are set aside, and none of its pieces is a page's
+ * address (`isPageAddress`, given the page's path). It's the one rule for a
+ * title that gets printed whole, so whoever stores a name and whoever prints
+ * it can't disagree.
+ *
+ * Every piece is judged, the first and the last included, because a title
+ * with a pipe in it prints with its pipes: ":slug | Example Apartments" (a
+ * placeholder in front of a brand tail) and "Floor Plans | /floor-plans/x" (a
+ * path behind the name) are both refused, and so is the unspaced
+ * "Floor Plans|/floor-plans/x". A name with a pipe in it stays a name while
+ * every piece is text ("1 Bedroom | 1BR 1BA"). A title that's only pipes has
+ * no piece and isn't a name. Empty, whitespace-only, nullish and non-string
+ * values aren't names either.
+ *
+ * It judges the title it is given, brand tail and all. A writer cuts the tail
+ * first and asks about what it stores: `isPageName(titleHead(title), path)`.
+ * `path` is optional, as it is for `isPageAddress`. Pure string logic, linear
+ * in the length of the input.
+ */
+export declare function isPageName(title: string | null | undefined, path?: string | null): boolean;

package/dist/page-titles.js

@@ -0,0 +1,157 @@
+'use strict';
+
+// src/contracts/seo-meta.ts
+var TITLE_SEPARATOR = " | ";
+function stripTitleSuffix(title) {
+  const t = title.trim();
+  const i = t.lastIndexOf(TITLE_SEPARATOR);
+  return i > 0 ? t.slice(0, i).trim() : t;
+}
+
+// src/contracts/page-titles.ts
+var PIPE_RUN = /\|(?:\s*\|)+/g;
+var EDGE_PIPES = /^[\s|]+|[\s|]+$/g;
+function titleHead(title) {
+  if (typeof title !== "string") return "";
+  const tidy = title.replace(/\s+/g, " ").replace(PIPE_RUN, " | ").replace(EDGE_PIPES, "").replace(/\s+/g, " ");
+  return tidy ? stripTitleSuffix(tidy) : "";
+}
+var ACRONYMS = /* @__PURE__ */ new Map([
+  ["ac", "AC"],
+  ["ai", "AI"],
+  ["aeo", "AEO"],
+  ["api", "API"],
+  ["cms", "CMS"],
+  ["crm", "CRM"],
+  ["faq", "FAQ"],
+  ["faqs", "FAQs"],
+  ["fsbo", "FSBO"],
+  ["hvac", "HVAC"],
+  ["jl", "JL"],
+  ["llc", "LLC"],
+  ["llp", "LLP"],
+  ["mls", "MLS"],
+  ["pdf", "PDF"],
+  ["pllc", "PLLC"],
+  ["ppc", "PPC"],
+  ["roi", "ROI"],
+  ["seo", "SEO"],
+  ["ui", "UI"],
+  ["usa", "USA"],
+  ["ux", "UX"]
+]);
+var STATE_CODES = new Set(
+  "al ak az ar ca co ct de dc fl ga hi id il in ia ks ky la me md ma mi mn ms mo mt ne nv nh nj nm ny nc nd oh ok or pa ri sc sd tn tx ut vt va wa wv wi wy".split(" ")
+);
+var WORD_STATE_CODES = /* @__PURE__ */ new Set([
+  "in",
+  "or",
+  "me",
+  "hi",
+  "id",
+  "la",
+  "ma",
+  "pa",
+  "al",
+  "de",
+  "co"
+]);
+var TRAILING_STATE_CODES = /* @__PURE__ */ new Set(["mt"]);
+function isStateCode(lower, isLast) {
+  if (!STATE_CODES.has(lower) || WORD_STATE_CODES.has(lower)) return false;
+  return TRAILING_STATE_CODES.has(lower) ? isLast : true;
+}
+var SMALL_WORDS = /* @__PURE__ */ new Set([
+  "a",
+  "an",
+  "and",
+  "at",
+  "by",
+  "for",
+  "in",
+  "of",
+  "on",
+  "or",
+  "the",
+  "to",
+  "vs",
+  "with"
+]);
+var PAGE_EXTENSION = /\.(?:html?|php|aspx)$/i;
+var URL_ORIGIN = /^[a-z][a-z0-9+.-]*:\/\/[^/\\]*/i;
+var PERCENT_RUN = /(?:%[0-9a-f]{2})+/gi;
+function decodeEscapes(value) {
+  return value.replace(PERCENT_RUN, (run) => {
+    try {
+      return decodeURIComponent(run);
+    } catch {
+      return run;
+    }
+  });
+}
+function capitalizeFirst(word) {
+  const code = word.codePointAt(0);
+  if (code === void 0) return word;
+  const first = String.fromCodePoint(code);
+  return first.toUpperCase() + word.slice(first.length);
+}
+function labelWord(token, isFirst, isLast) {
+  const lower = token.toLowerCase();
+  const acronym = ACRONYMS.get(lower);
+  if (acronym) return acronym;
+  if (isStateCode(lower, isLast)) return lower.toUpperCase();
+  if (/\p{N}/u.test(token)) return /^\p{L}/u.test(token) ? capitalizeFirst(token) : token;
+  if (!isFirst && SMALL_WORDS.has(lower)) return lower;
+  return capitalizeFirst(lower);
+}
+function slugLabel(input) {
+  if (typeof input !== "string") return "";
+  const path = input.split(/[?#]/, 1)[0].replace(URL_ORIGIN, "");
+  const segment = path.split(/[/\\]/).filter((s) => s.trim() !== "").pop();
+  if (!segment) return "";
+  const name = decodeEscapes(segment).replace(PAGE_EXTENSION, "");
+  const tokens = name.split(/[-_+\s]+/).filter(Boolean);
+  return tokens.map((token, i) => labelWord(token, i === 0, i === tokens.length - 1)).join(" ");
+}
+var PLACEHOLDER_TOKEN = /^(?::[A-Za-z_][\w-]*[?*+]?|\[\[\.\.\.[A-Za-z_][\w-]*\]\]|\[(?:\.\.\.)?[A-Za-z_][\w-]*\])$/;
+function isRoutePlaceholder(value) {
+  if (typeof value !== "string") return false;
+  return value.split("/").some((segment) => PLACEHOLDER_TOKEN.test(segment.trim()));
+}
+var ABSOLUTE_URL = /^[a-z][a-z0-9+.-]*:\/\//i;
+var HOST_NAME = /^(?:[a-z0-9-]+\.)+[a-z]{2,}(?::\d{1,5})?$/i;
+function withoutOuterSlashes(value) {
+  let start = 0;
+  let end = value.length;
+  while (start < end && value[start] === "/") start++;
+  while (end > start && value[end - 1] === "/") end--;
+  return value.slice(start, end);
+}
+function isHostPath(value) {
+  const slash = value.indexOf("/");
+  if (slash < 0 || /\s/.test(value)) return false;
+  return HOST_NAME.test(value.slice(0, slash));
+}
+function isPageAddress(value, path) {
+  if (typeof value !== "string") return false;
+  const given = value.trim();
+  if (!given) return false;
+  if (given.startsWith("/") || ABSOLUTE_URL.test(given) || isHostPath(given) || isRoutePlaceholder(given)) return true;
+  if (typeof path !== "string") return false;
+  const own = withoutOuterSlashes(path.trim());
+  return withoutOuterSlashes(given) === own;
+}
+function pipePieces(title) {
+  return title.split("|").map((piece) => piece.trim()).filter(Boolean);
+}
+function isPageName(title, path) {
+  if (typeof title !== "string") return false;
+  const pieces = pipePieces(title);
+  return pieces.length > 0 && pieces.every((piece) => !isPageAddress(piece, path));
+}
+
+exports.isPageAddress = isPageAddress;
+exports.isPageName = isPageName;
+exports.isRoutePlaceholder = isRoutePlaceholder;
+exports.slugLabel = slugLabel;
+exports.titleHead = titleHead;

package/dist/page-titles.mjs

@@ -0,0 +1,151 @@
+// src/contracts/seo-meta.ts
+var TITLE_SEPARATOR = " | ";
+function stripTitleSuffix(title) {
+  const t = title.trim();
+  const i = t.lastIndexOf(TITLE_SEPARATOR);
+  return i > 0 ? t.slice(0, i).trim() : t;
+}
+
+// src/contracts/page-titles.ts
+var PIPE_RUN = /\|(?:\s*\|)+/g;
+var EDGE_PIPES = /^[\s|]+|[\s|]+$/g;
+function titleHead(title) {
+  if (typeof title !== "string") return "";
+  const tidy = title.replace(/\s+/g, " ").replace(PIPE_RUN, " | ").replace(EDGE_PIPES, "").replace(/\s+/g, " ");
+  return tidy ? stripTitleSuffix(tidy) : "";
+}
+var ACRONYMS = /* @__PURE__ */ new Map([
+  ["ac", "AC"],
+  ["ai", "AI"],
+  ["aeo", "AEO"],
+  ["api", "API"],
+  ["cms", "CMS"],
+  ["crm", "CRM"],
+  ["faq", "FAQ"],
+  ["faqs", "FAQs"],
+  ["fsbo", "FSBO"],
+  ["hvac", "HVAC"],
+  ["jl", "JL"],
+  ["llc", "LLC"],
+  ["llp", "LLP"],
+  ["mls", "MLS"],
+  ["pdf", "PDF"],
+  ["pllc", "PLLC"],
+  ["ppc", "PPC"],
+  ["roi", "ROI"],
+  ["seo", "SEO"],
+  ["ui", "UI"],
+  ["usa", "USA"],
+  ["ux", "UX"]
+]);
+var STATE_CODES = new Set(
+  "al ak az ar ca co ct de dc fl ga hi id il in ia ks ky la me md ma mi mn ms mo mt ne nv nh nj nm ny nc nd oh ok or pa ri sc sd tn tx ut vt va wa wv wi wy".split(" ")
+);
+var WORD_STATE_CODES = /* @__PURE__ */ new Set([
+  "in",
+  "or",
+  "me",
+  "hi",
+  "id",
+  "la",
+  "ma",
+  "pa",
+  "al",
+  "de",
+  "co"
+]);
+var TRAILING_STATE_CODES = /* @__PURE__ */ new Set(["mt"]);
+function isStateCode(lower, isLast) {
+  if (!STATE_CODES.has(lower) || WORD_STATE_CODES.has(lower)) return false;
+  return TRAILING_STATE_CODES.has(lower) ? isLast : true;
+}
+var SMALL_WORDS = /* @__PURE__ */ new Set([
+  "a",
+  "an",
+  "and",
+  "at",
+  "by",
+  "for",
+  "in",
+  "of",
+  "on",
+  "or",
+  "the",
+  "to",
+  "vs",
+  "with"
+]);
+var PAGE_EXTENSION = /\.(?:html?|php|aspx)$/i;
+var URL_ORIGIN = /^[a-z][a-z0-9+.-]*:\/\/[^/\\]*/i;
+var PERCENT_RUN = /(?:%[0-9a-f]{2})+/gi;
+function decodeEscapes(value) {
+  return value.replace(PERCENT_RUN, (run) => {
+    try {
+      return decodeURIComponent(run);
+    } catch {
+      return run;
+    }
+  });
+}
+function capitalizeFirst(word) {
+  const code = word.codePointAt(0);
+  if (code === void 0) return word;
+  const first = String.fromCodePoint(code);
+  return first.toUpperCase() + word.slice(first.length);
+}
+function labelWord(token, isFirst, isLast) {
+  const lower = token.toLowerCase();
+  const acronym = ACRONYMS.get(lower);
+  if (acronym) return acronym;
+  if (isStateCode(lower, isLast)) return lower.toUpperCase();
+  if (/\p{N}/u.test(token)) return /^\p{L}/u.test(token) ? capitalizeFirst(token) : token;
+  if (!isFirst && SMALL_WORDS.has(lower)) return lower;
+  return capitalizeFirst(lower);
+}
+function slugLabel(input) {
+  if (typeof input !== "string") return "";
+  const path = input.split(/[?#]/, 1)[0].replace(URL_ORIGIN, "");
+  const segment = path.split(/[/\\]/).filter((s) => s.trim() !== "").pop();
+  if (!segment) return "";
+  const name = decodeEscapes(segment).replace(PAGE_EXTENSION, "");
+  const tokens = name.split(/[-_+\s]+/).filter(Boolean);
+  return tokens.map((token, i) => labelWord(token, i === 0, i === tokens.length - 1)).join(" ");
+}
+var PLACEHOLDER_TOKEN = /^(?::[A-Za-z_][\w-]*[?*+]?|\[\[\.\.\.[A-Za-z_][\w-]*\]\]|\[(?:\.\.\.)?[A-Za-z_][\w-]*\])$/;
+function isRoutePlaceholder(value) {
+  if (typeof value !== "string") return false;
+  return value.split("/").some((segment) => PLACEHOLDER_TOKEN.test(segment.trim()));
+}
+var ABSOLUTE_URL = /^[a-z][a-z0-9+.-]*:\/\//i;
+var HOST_NAME = /^(?:[a-z0-9-]+\.)+[a-z]{2,}(?::\d{1,5})?$/i;
+function withoutOuterSlashes(value) {
+  let start = 0;
+  let end = value.length;
+  while (start < end && value[start] === "/") start++;
+  while (end > start && value[end - 1] === "/") end--;
+  return value.slice(start, end);
+}
+function isHostPath(value) {
+  const slash = value.indexOf("/");
+  if (slash < 0 || /\s/.test(value)) return false;
+  return HOST_NAME.test(value.slice(0, slash));
+}
+function isPageAddress(value, path) {
+  if (typeof value !== "string") return false;
+  const given = value.trim();
+  if (!given) return false;
+  if (given.startsWith("/") || ABSOLUTE_URL.test(given) || isHostPath(given) || isRoutePlaceholder(given)) return true;
+  if (typeof path !== "string") return false;
+  const own = withoutOuterSlashes(path.trim());
+  return withoutOuterSlashes(given) === own;
+}
+function pipePieces(title) {
+  return title.split("|").map((piece) => piece.trim()).filter(Boolean);
+}
+function isPageName(title, path) {
+  if (typeof title !== "string") return false;
+  const pieces = pipePieces(title);
+  return pieces.length > 0 && pieces.every((piece) => !isPageAddress(piece, path));
+}
+
+export { isPageAddress, isPageName, isRoutePlaceholder, slugLabel, titleHead };

package/dist/publication-branding.d.ts

@@ -0,0 +1,143 @@
+import { type BroadcastStyleId, type PublicationCardLayout } from './broadcast-layouts';
+import { type PublicationCharter } from './publication-charter';
+export { PUBLICATION_CHARTER_FIELDS, parsePublicationCharter, parseSiteCharters, publicationCharterContext, publicationCharterFor, type PublicationCharter, } from './publication-charter';
+/** The stored profile's version. A breaking change to the shape bumps it. */
+export declare const PUBLICATION_BRANDING_VERSION: 1;
+/** Where a publication appears. `social` overrides every social network; each network can override again. */
+export declare const PUBLICATION_PLATFORMS: readonly ['publication', 'email', 'social', 'instagram', 'facebook', 'linkedin', 'gbp'];
+export type PublicationPlatform = (typeof PUBLICATION_PLATFORMS)[number];
+/** The sections of a profile and of each platform override, in the order they're read. */
+export declare const PUBLICATION_BRANDING_SECTIONS: readonly ['identity', 'colors', 'typography', 'editorial', 'newsletter'];
+export type PublicationBrandingSection = (typeof PUBLICATION_BRANDING_SECTIONS)[number];
+export declare const PUBLICATION_IDENTITY_FIELDS: readonly ['publicationName', 'wordmark', 'tagline', 'publisherName', 'publisherUrl', 'publisherLogoUrl', 'logos'];
+export declare const PUBLICATION_LOGO_VARIANTS: readonly ['default', 'light', 'dark'];
+export declare const PUBLICATION_COLOR_FIELDS: readonly ['primary', 'secondary', 'accent', 'background', 'surface', 'text', 'muted', 'border'];
+export declare const PUBLICATION_TYPOGRAPHY_FIELDS: readonly ['heading', 'body', 'mono', 'emailHeadingFallback', 'emailBodyFallback'];
+export declare const PUBLICATION_EDITORIAL_FIELDS: readonly ['articleStyle', 'cardLayout', 'charter', 'siteCharters'];
+export declare const PUBLICATION_NEWSLETTER_FIELDS: readonly ['name', 'tagline', 'layout', 'maxWidth'];
+/** Fonts every email client has, the only families an email fallback may name. Lowercase. */
+export declare const EMAIL_SAFE_FONTS: ReadonlySet<string>;
+/** CSS generic families: written bare and lowercase in a font stack, never quoted. */
+export declare const GENERIC_FONT_FAMILIES: ReadonlySet<string>;
+export interface PublicationIdentity {
+    publicationName?: string;
+    wordmark?: string;
+    tagline?: string;
+    publisherName?: string;
+    publisherUrl?: string;
+    /** The publisher's attribution mark, separate from the publication masthead. */
+    publisherLogoUrl?: string;
+    logos?: {
+        default?: string;
+        light?: string;
+        dark?: string;
+    };
+}
+export interface PublicationColors {
+    primary?: string;
+    secondary?: string;
+    accent?: string;
+    background?: string;
+    surface?: string;
+    text?: string;
+    muted?: string;
+    border?: string;
+}
+export interface PublicationTypography {
+    heading?: string;
+    body?: string;
+    mono?: string;
+    emailHeadingFallback?: string;
+    emailBodyFallback?: string;
+}
+export interface PublicationEditorial {
+    charter?: PublicationCharter;
+    siteCharters?: Record<string, PublicationCharter>;
+    /** Shared Broadcast style for articles, reviews and generated posts; portfolio is excluded. Legacy wire name. */
+    articleStyle?: BroadcastStyleId;
+    cardLayout?: PublicationCardLayout;
+}
+export interface PublicationNewsletter {
+    name?: string;
+    tagline?: string;
+    layout?: 'editorial';
+    maxWidth?: 600 | 640;
+}
+export interface PublicationBrandingSections {
+    identity?: PublicationIdentity;
+    colors?: PublicationColors;
+    typography?: PublicationTypography;
+    editorial?: PublicationEditorial;
+    newsletter?: PublicationNewsletter;
+}
+/** Exactly the object stored in projects.settings.publication_branding. */
+export interface PublicationBranding extends PublicationBrandingSections {
+    version: typeof PUBLICATION_BRANDING_VERSION;
+    platforms?: Partial<Record<PublicationPlatform, PublicationBrandingSections>>;
+}
+export type PublicationBrandingProfile = PublicationBranding;
+type LeafPatch<T> = {
+    [K in keyof T]?: NonNullable<T[K]> extends object ? LeafPatch<NonNullable<T[K]>> : T[K] | null;
+};
+export type PublicationBrandingSectionsPatch = LeafPatch<PublicationBrandingSections>;
+/** A change: any leaf set to a value, or to null to clear that override. */
+export interface PublicationBrandingPatch extends PublicationBrandingSectionsPatch {
+    version?: typeof PUBLICATION_BRANDING_VERSION;
+    platforms?: Partial<Record<PublicationPlatform, PublicationBrandingSectionsPatch>>;
+}
+/**
+ * A refusal, naming the field: `publication_branding.colors.primary: use a
+ * valid opaque color`. One case throws a plain Error instead: a charter set on
+ * a channel override, which belongs to the publication or a site.
+ */
+export declare class PublicationBrandingValidationError extends Error {
+    readonly path: string;
+    constructor(path: string, reason: string);
+}
+/** True for a control character (U+0000-U+001F, U+007F) anywhere in the text. */
+export declare function containsControlCharacters(value: string): boolean;
+/**
+ * A CSS font stack as data, never a stylesheet fragment: quoted family names
+ * and lowercase generic families joined by commas ("'Brand Display',serif"),
+ * or undefined when the value carries rules, variables, url() or anything
+ * that isn't a family name. The theme aliases heading, body and mono drop out.
+ */
+export declare function safeFontStack(value: unknown): string | undefined;
+export interface PublicationBrandingValidatorOptions {
+    /**
+     * True when a URL's hostname must never be stored as a logo or publisher
+     * URL: loopback, private and link-local ranges, `localhost` and the like.
+     * Each API passes its own server-side SSRF host guard. It receives
+     * `new URL(value).hostname`, so IPv6 keeps its brackets.
+     */
+    isBlockedHost: (hostname: string) => boolean;
+}
+export interface PublicationBrandingValidator {
+    /** A whole saved profile. Retired card layouts still read. */
+    validatePublicationBranding(value: unknown): PublicationBranding;
+    /** A change. Leaves may be null (clear that override); a card layout must be one drawn today. */
+    validatePublicationBrandingPatch(value: unknown): PublicationBrandingPatch;
+    /** The sections of a profile or a platform override, at `path`. */
+    validatePublicationBrandingSections(input: unknown, path: string, patch: boolean): PublicationBrandingSections | PublicationBrandingSectionsPatch;
+    /**
+     * The saved profile with the change applied: a null leaf clears just that
+     * override and empty containers are pruned. No profile yet reads as
+     * `{ version: 1 }`; a change that sets nothing returns the profile as it was.
+     */
+    mergePublicationBrandingPatch(current: unknown, patch: unknown): PublicationBranding;
+    /** One text leaf: trimmed, 1 to max characters (0 when empty is allowed), no control characters. */
+    text(value: unknown, path: string, max: number, empty?: boolean): string;
+    /** One URL leaf: a public HTTPS URL without credentials, normalized. */
+    url(value: unknown, path: string): string;
+    /** One font leaf, normalized by safeFontStack; email fallbacks may name only EMAIL_SAFE_FONTS. */
+    font(value: unknown, path: string, emailSafe?: boolean): string;
+}
+/**
+ * Leaf-wise merge of a validated change into a profile layer: a null leaf
+ * deletes that key, an object merges recursively, and a container left empty
+ * is removed. The inputs are never mutated. The Sonor API layers resolved
+ * branding with the same merge.
+ */
+export declare function mergePublicationBrandingLayers(current: Record<string, unknown>, patch: Record<string, unknown>): Record<string, unknown>;
+/** Single source of truth for publication-branding validation, bound to the caller's host guard. */
+export declare function createPublicationBrandingValidator(options: PublicationBrandingValidatorOptions): PublicationBrandingValidator;